GeezerVison

Copy link

Copy Markdown

Collaborator

JosunLP marked this pull request as ready for review September 20, 2026 12:55

JosunLP commented Sep 20, 2026

View reviewed changes

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.

Base automatically changed from fix/219-exports-map to dev September 21, 2026 08:05

27 checks passed

JosunLP deleted the feat/218-publint-attw branch September 21, 2026 08:23

…wrong (#236)

Co-authored-by: Claude Opus 5 <[email protected]>
Closes #218

Both postbuild rewriters skipped comment text by splitting the source into
lines and matching each one on its own. `SPECIFIER` matches `\s*`/`\s+`
between the keyword and the quote, so a wrapped specifier —

    export type X = import(
      './css'
    ).Css;

only matches against the whole text. Per line it matched nothing, so the
extension was never added and the `.d.ts`/`.d.cts` shipped an unresolvable
import with the build still green. A rewrite that fails silently is worse
than one that over-reaches.

The guard now records the offsets of comment lines up front and the match
runs over the whole source, checking each hit's index against those ranges.
Comment text is still skipped, wrapped specifiers are rewritten again.

No multiline specifier is in the current `dist/` output, so nothing shipped
broken — but `postbuild-types.mjs` has carried this since #236 and
`prettier`'s print width decides when it stops being latent.

Co-Authored-By: Claude Opus 5 <[email protected]>
Claude-Session: https://claude.ai/code/session_01Y2dPuUeGeK7mJvar9uLqKz

## Summary

- Release PR for **1.17.0**, cutting everything on `dev` since `1.16.1`
into `main`.
- Feature release for `server` and `security`, plus the packaging fixes
that make the published tarball resolve correctly for the first time.
- **One user-visible break:** `dist/full.umd.js` no longer exists.
Details under [Upgrading](#upgrading).

> **You asked for 1.7.0.** `v1.7.0` is already tagged and the package is
on `1.16.1`, so that number would be a downgrade. Cut as **1.17.0** per
your confirmation.

## Motivation

`dev` is 14 commits ahead of `main` and carries four new features, one
lifecycle change, one reactive fix and the packaging work. Closes the
release cycle for #210, #211, #212, #213, #215, #216, #218, #219, #220,
#222, #223 and #229 — all twelve issues are closed and their PRs merged.

## What this PR's diff actually contains

> **Correction, kept in place.** This section originally read "No source
changes. The diff is 8 files plus the new release-notes page." That was
true of the release commit alone and has not been true of the PR for
some time. Left standing rather than quietly deleted, because the same
staleness is what the note below guards against.

The PR targets `main`, so GitHub shows the **whole `1.16.1 → 1.17.0`
delta: 73 files, +9985/−555** — all of `serveStatic`, `rateLimit`, both
sanitizer backends, the reactive scheduler and the packaging work.
Review it as a feature release, not as a version bump.

Measured against `dev`, the delta is **35 files, +1766/−258**: the
version bump, the release notes, and eleven source fixes pushed onto
this branch during review that are **not on `dev`**:

| Commit | Change |
| --- | --- |
| `1c6b5fb` | SSR validates tag and attribute names at every
serialization site — **this is the CodeQL `js/xss-through-dom` fix** |
| `f0c64b5` | `rateLimit` keys on the rightmost (proxy-added)
`X-Forwarded-For` hop |
| `407a6c5` | `trustProxy` reads one proxy-controlled header instead of
whichever turns up |
| `9e02000` | `postbuild-cts`/`postbuild-types` keep rewriting
specifiers that wrap across lines |
| `e668d14` | One text-extraction rule across both sanitizer backends;
the HTML-sink path escapes |
| `29dbcbf` | `serveStatic` can revalidate a precompressed asset, and
ranks encodings by q-value |
| `1192a87` | Limiters sharing a `SessionStore` serialize against each
other |
| `786bd4d` | A trailing slash no longer closes an element HTML will not
let close itself; entities decode on the DOM text-only path |
| `4d10b5e` | Character references decode by the tokenizer's rules
(case, `;`, legacy prefixes, attribute rule) from an HTML 4.01 + ASCII +
legacy table; **raises five bundle budgets by ~1.8 kB** |
| `4c269a4` | A precompressed sidecar's `ETag`/`Last-Modified` come from
the sidecar; its `304` no longer offers ranges |
| `0fc9849` | The workflow branch guard fails on unreadable triggers
even when it has no branch list |

## Version and metadata

- `package.json`: `1.16.1` → `1.17.0`.
- `AGENT.md`, `llms.txt`, `.cursorrules`, `.clinerules`,
`.github/copilot-instructions.md`: version baseline and a new highlights
section each. `bun run check:ai-guidance` enforces these and passes.

**Changelog**

- `## [Unreleased]` → `## [1.17.0] - 2026-09-21`, section headings and
the table of contents renamed to match.
- **Three Changed entries added that were missing**, plus a Fixed entry
per review-round fix. See the note below.

**Docs**

- New `docs/release-notes/1.17.md` — the release process requires a page
per minor.
- Row added to `docs/release-notes/index.md`.

## The changelog gap I had to close first

The `Unreleased` block on `dev` covered only #205, #210, #222, #223 and
#229. The packaging work had merged with **no changelog entry at all**:

| Merged | Missing from the changelog |
| --- | --- |
| #219 (PR #234) | `dist/full.umd.js` → `.cjs`, CDN fields →
`full.iife.js`, `require()` fixed, `types` first, `./package.json`
export, `.d.cts` tree |
| #218 (PR #236) | Extensionless declaration imports fixed (315 ×
`TS2834` → 0) |
| #220 (PR #235) | JS source maps dropped from the tarball |

The first row is this release's only breaking change. A release that
ships a 404 for pinned CDN URLs without a changelog line is how users
find out the hard way, so those three entries are now written up under
`### Changed (1.17.0)`.

The remaining merged work (#211, #212, #213, #215, #216, #243, #244) is
CI and repo tooling with no effect on consumers, so it stays out of the
changelog by design.

## Validation

Against `0fc9849`:

- [x] `bun run lint` — clean
- [x] `bun run build`
- [x] `bun test` — **3518 pass, 1 skip, 0 fail**
- [x] `npx tsc --noEmit` — clean

| Gate | Result |
| --- | --- |
| `check:ai-guidance` | in sync at 1.17.0 |
| `check` (full-bundle, stability, doc-exports, theme-links,
workflow-branches) | pass |
| `format:check` | pass |
| `check:package` | 1.38 MB packed / 5.39 MB unpacked / 1240 files |
| `check:size` | 25/25 within budget, largest `./full` at 133.4 kB
gzipped |
| `check:publish` | publint + attw exit 0 |
| `check:coverage` | 89.27% lines / 87.88% functions |
| `build:docs` | VitePress builds with the new release-notes page |

The entity decoder was also checked outside the test suite:
differential-tested against Chromium's `DOMParser` on 60,046 generated
text and attribute inputs, with 0 differences outside names the table
deliberately leaves out (the previous decoder differed on 9,240).

**One unexplained result, recorded rather than rounded off.** An earlier
full-suite run reported `3497 pass / 1 fail`. It has not recurred in 23
further full-suite runs or 25 targeted runs of the changed files, every
test file passes in isolation, and the output gave only the counts — so
I do not have the name of the test that failed. Calling it a flake would
be a guess; it is listed here because an unreproduced failure is worth a
reviewer knowing about.

## Checklist

- [x] I followed the contributing guidelines.
- [x] I added or updated tests where behavior changed.
- [x] I updated documentation when public behavior or developer workflow
changed.
- [x] I confirmed the change does not introduce security-sensitive
regressions.

## Upgrading

Package specifiers (`@bquery/bquery`, `@bquery/bquery/*`) are unaffected
and resolve better than before. One path changed:

| Before | After |
| --- | --- |
| `dist/full.umd.js` | `dist/full.umd.cjs` |
| `unpkg` / `jsdelivr` → UMD build | → `dist/full.iife.js` |

A pinned `unpkg.com/@bquery/bquery@1/dist/full.umd.js` will **404**.
`full.iife.js` sets the same `window.bQuery` global.

Behaviour changes worth checking:

- `app.use()` middleware now runs for requests matching no route.
- `batch()` runs effects only after derivations settle, so code relying
on observing an intermediate state inside a batch sees the settled
state.
- SSR drops attribute and tag names outside the validated ASCII
patterns, so a non-ASCII name such as `<div é="x">` is no longer
serialized.
- **In the browser**, `stripTags()` no longer surfaces
`<script>`/`<style>` source as text —
`stripTags('<script>alert(1)</script>')` is now `''` rather than
`'alert(1)'`, matching the server.
- **In the browser**, `sanitizeHtml(html, { stripAllTags: true })` now
escapes its output. It is branded `SanitizedHtml` and callers assign it
to HTML sinks, so returning entity-decoded text raw handed back live
markup. `stripTags()` is unaffected and still returns raw plain text.
- The sanitizer decodes character references like a browser:
`caf&eacute;` is `café` on the server and on the browser's text-only
path, names are case-sensitive, and `href="?a=1&copy=2"` is left intact.
HTML5-only names outside the table (e.g. `&star;`) stay literal on the
string backend. Every entry that sanitizes (`core`, `component`,
`security`, `view`, `storybook`, and the umbrella entries) grows by
about **1.8 kB gzipped**.

## Notes for reviewers

**Why 1.17.0 and not 2.0.0.** There is a defensible major case, and it
got slightly stronger during review: the UMD path removal, the
`app.use()` lifecycle change, the `batch()` ordering change and now two
browser-visible sanitizer changes are all observable. I still read them
as minor because no exported API was removed or changed shape, the UMD
break is a deep file path rather than a package specifier, the sanitizer
changes remove a leak rather than alter a contract, and #242
deliberately kept `'sync'` the default scheduler for all of 1.x
precisely to avoid forcing a major. If you weigh the CDN path break
higher, say so and I will recut as 2.0.0 — it is a re-run of the same
mechanical edits.

**The entity table is a size trade-off you may want to overrule.** It is
every HTML 4.01 name plus every ASCII-valued and legacy-prefixed name:
~1.3 kB of the ~1.8 kB. The full HTML5 table would be ~7.4 kB; dropping
the Greek and math symbols would save ~0.6 kB at the cost of `&alpha;`,
`&le;`, `&infin;` and friends diverging between backends. Either
direction is a small follow-up.

**Branch choice, and why the back-merge is mandatory.** This is
`release/1.17.0` off `dev` rather than `dev → main` directly, so `dev`
stays at `1.16.1` if you defer the release. That was the only cost when
this PR opened. It is not any more: the eleven fixes listed above live
**only on this branch**. Merging to `main` without back-merging `main`
into `dev` would leave `dev` without the CodeQL fix, both rate-limiter
hardening commits, the shared-store lock and the sanitizer fixes — and
the next release cut from `dev` would reintroduce all of them as
regressions. So after merge, either back-merge `main` into `dev`, or say
the word and I will redo this as a straight `dev → main` PR, which
removes the follow-up entirely.

**`main` has one commit `dev` does not** (`fe51cb5`, the squash of
#208). The merge is conflict-free — verified with `git merge-tree` — but
that squash is why `dev` and `main` diverge rather than fast-forward.
Note also that `dev`'s squash-merges carry different SHAs than the same
content on this branch, so compare the two by content (`git diff
origin/dev origin/release/1.17.0`), not by commit list.

**Not yet done, deliberately:** no git tag and no `npm publish`. Tagging
`v1.17.0` belongs on the merge commit, and publishing is maintainer-only
per the release process.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

https://claude.ai/code/session_01Y2dPuUeGeK7mJvar9uLqKz

---
_Generated by [Claude
Code](https://claude.ai/code/session_01Y2dPuUeGeK7mJvar9uLqKz)_

<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit

* **New Features**
* Added static file serving with caching, range requests, compressed
assets, directory indexes, and traversal protection.
* Added fixed-window rate limiting with standard headers and `429`
responses; a key function is required unless trusted proxy headers are
used.
  * Added DOM-free HTML sanitization with configurable backends.
* Added opt-in batched reactive scheduling, scheduler configuration, and
synchronous flushing.
  * Global middleware now runs for unmatched routes.

* **Changed**
* Renamed the CommonJS bundle from `full.umd.js` to `full.umd.cjs`;
browser scripts use `full.iife.js`.
  * Improved package type declarations and source-map handling.
  * Reactive updates now settle derived values before effects run.

* **Bug Fixes**
* Hardened server-rendered HTML by rejecting invalid tag and attribute
names.
* Improved compressed-asset revalidation and sanitizer handling of HTML
entities.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->

---------

Co-authored-by: Claude Opus 5 <[email protected]>