npm - @ultimat3/render - Versions diffs - 21.0.0 → 22.0.0 - Mend

@ultimat3/render 21.0.0 → 22.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (16) hide show

package/CLAUDE.md CHANGED Viewed

@@ -4,110 +4,102 @@ Owns: the `route` primitive, the four render modes, the route table, the surface
 islands + budgets, hydration directives, `<head>` merge, **the server JSX runtime and the two Bun
 loaders that make an app's `.tsx` and `.scss` runnable**.
-**Two entry points, disjoint, split 2026-08-22** — the same `"."` / `"./server"` shape
-`@ultimat3/realtime` took, for the same reason. `"."` (`index.ts`) is the CLIENT half and BUNDLES
-for the browser; `"./server"` (`server.ts`) is the build-time half — `css-modules`,
-`module-loader`, `render-html`, `render-isr`, `render-ssr`, `render-static`, `render-stream` — and
-does not. `css-modules.ts` imports `fileURLToPath`/`pathToFileURL` from `node:url`, which Bun's
-browser polyfill exports NEITHER of, so the single barrel was not a fat bundle, it was a
-`bun build --target=browser` that FAILED at link time on any app entry that reached this package.
-Measured: no `sideEffects` value repairs it (`false`, `[]`, an array naming only `errors.ts` — all
-fail identically), which is where this split differs from realtime's, where the array alone was
-enough. Only not importing the module does. Never re-export a name from both barrels: disjointness
-is what makes "which half does this live in" a mechanical fact, and `index.test.ts` asserts both
-the empty name intersection AND that `index.ts`'s transitive runtime import graph reaches none of
-the seven modules above. `scripts/browser-barrel.test.ts` holds the end property, both directions.
+**Two entry points, disjoint.** `"."` (`index.ts`) is the CLIENT half and bundles for the browser;
+`"./server"` (`server.ts`) is the build-time half — `css-modules`, `module-loader`, `render-html`,
+`render-isr`, `render-ssr`, `render-static`, `render-stream` — and does not (`css-modules.ts` needs
+`node:url`, which a browser build cannot link; no `sideEffects` value repairs that). Never re-export
+a name from both barrels: `index.test.ts` asserts the empty name intersection and that `index.ts`'s
+runtime import graph reaches none of those seven modules; `scripts/browser-barrel.test.ts` holds
+the end property.
-`island()` is a **factory over the route's own `hydrate`**, not a ninth primitive and not a
-second render mode — the same rule `llm()` and `backfill()` follow. It adds no key to
-`defineRoute`.
+`island()` is a **factory over the route's own `hydrate`**, not a ninth primitive and not a second
+render mode. It adds no key to `defineRoute`.
 Tier 4. May import tiers 0–3: `core`, `schema`, `i18n`, `money`, `time`, `cache`, `seo`,
-`entity`, `policy`, `http`, `action`, `query`. **Never** `pwa`, `mcp`, `ai`, `manifest`, `ui`
-— all tier 4, so **sideways**, and an undeclared sideways edge is a build error. `ui` moved 5 → 4
-in 2026-08 and is held level with this package deliberately (`FLOOR_ABOVE` in
-`scripts/lib/tiers.ts`), so `render → ui` stays refused; this package sits above its own floor of 2
-for the mirror-image reason, keeping `render → pwa` refused. Never `cli` (upward).
+`entity`, `policy`, `http`, `action`, `query`. **Never** `pwa`, `mcp`, `ai`, `manifest`, `ui` — all
+tier 4, so sideways. This package sits above its floor of 2 so `render → pwa` stays refused, and
+`ui` is held level with it so `render → ui` stays refused (`FLOOR_ABOVE` in `scripts/lib/tiers.ts`;
+axiom 6). Never `cli` (upward).
 | Rule | Detail |
 |---|---|
 | `offline`, `meta` | required by `RouteDefinition`. Never make them optional. |
-| `hydrate` | **optional since 1.2.0, derived from `island()`** — `'interaction'` when the module declared one, `'never'` when it did not. Declaring it still wins and is the only way to reach `idle` / `visible`. Not a widening of the contract: it is the one key the declaration above it already answers, and requiring it meant two failures (`X_ISLAND_NOT_HYDRATED`, and a `site/` route refused for a missing `budget.js`) for one omission. Never give the island its own strategy instead — `RouteDescriptor.hydrate` is read by `sw.js`, the web manifest and `x routes`, and two islands wanting different timings would leave it with no true answer. |
-| `defineRoute` shape | exactly the contract's 9 keys. New route *metadata* still goes inside `meta` — `load` is not metadata, it is the data `meta` already took a parameter for. |
-| `load` | optional, and the ONE server-side data seam. Resolved once per render by `routeDataFor()` and handed to **both** `meta` and the page component. Two resolutions is a `<title>` describing content the body does not contain. Absent `load`, the context IS the data (`{ params, url }`), which is what `meta` received before the key existed — so no consumer branches on whether a route declared one. |
-| `load` is required when the context cannot supply the data | `LoadRequirement<TData>` in `defineRoute`'s parameter — `unknown` when `RouteContext` satisfies `TData`, a required `load` when it does not. That is what makes the no-`load` fallback true rather than asserted: it was `ctx as unknown as TData`, so a `meta` reading `data.post` off a route that loads nothing type-checked and rendered `undefined` in a `<title>`. `RouteContext` is a type ALIAS for the same reason — only an alias carries the implicit index signature that makes it a `RouteData`; as an `interface` the compiler cannot see it and the cast comes back. |
-| A loader's own error | rethrown only when `isUltimateError` says so — core's brand, never a `code` property. Every `ENOENT` is an `Error` with a string `code`, and the duck-type that preceded this let all of them out of `routeDataFor` unwrapped: no `X_ROUTE_LOAD_FAILED`, no fix line, no route named. A tier-0 error (`@ultimat3/schema` cannot import core) is branded, not a subclass — never narrow this to `instanceof UltimateError`. |
-| A loader's own STATUS | `withStatus(status, data)` in `route-status.ts` — the ONE way a page answers 404 (or 410, or 503) while still rendering its own component inside the app's shell. Measured in ai-maxxing 2026-09-07: the only route to a status was a throw, which is the framework's error page OUTSIDE the shell, so `/fleet/nope` rendered the right page and answered 200. The status rides on the data by IDENTITY, in a `WeakMap` — the same object comes back, so `load`'s type, `routeDataFor`'s signature and every consumer that never asks are untouched, and a frozen or class-instance result is never written into. Never a `RouteContext` method: every builder of a context (`x dev`, the prerenderer, the SEO scan, both scaffold templates) would have to supply it, and an optional method is a second way. `routeStatusOf(data)` is the reader, TOTAL, 200 when nothing asked. A 3xx is `X_ROUTE_STATUS_INVALID` — a redirect is a `Location` and no body — and the range is `finiteStatus`'s. A 4xx/5xx is `robots.index = false` BY CONSTRUCTION in `defineRoute`'s `meta` wrapper, the one function every `<head>` renderer calls; a 200 hands the author's `meta` object back by reference. The response status itself is minted by `@ultimat3/cli`'s `dev-render.ts` (`resultFor`), which reads `routeStatusOf(data)` once and hands it to the mode — this package owns the seam, never the `Response`. |
-| Type claims | `type-pins.tsx`, never a `.test.ts` — `tsconfig.json` excludes tests, so `tsc` never reads one. `.tsx` since 1.2.0: the island-as-JSX claim is only decidable by writing the JSX an author writes, checked against the same `solid-js` `JSX.Element` a page is. |
+| `hydrate` | optional, **derived from `island()`** — `'interaction'` when the module declared one, `'never'` when not. Declaring it still wins and is the only way to reach `idle` / `visible`. Never give an island its own strategy: `RouteDescriptor.hydrate` is read by `sw.js`, the web manifest and `x routes`. |
+| `defineRoute` shape | exactly the contract's 9 keys. New route *metadata* goes inside `meta`. |
+| `load` | optional, and the ONE server-side data seam. Resolved once per render by `routeDataFor()` and handed to **both** `meta` and the page component. Absent `load`, the context IS the data (`{ params, url }`). |
+| `load` is required when the context cannot supply the data | `LoadRequirement<TData>` in `defineRoute`'s parameter. `RouteContext` is a type ALIAS on purpose — only an alias carries the implicit index signature that makes it a `RouteData`. |
+| A loader's own error | rethrown only when `isUltimateError` says so (core's brand), never a `code` property and never `instanceof UltimateError` — a tier-0 error is branded, not a subclass. Everything else is `X_ROUTE_LOAD_FAILED`. |
+| A loader's own STATUS | `withStatus(status, data)` (`route-status.ts`) — the ONE way a page answers 404/410/503 while rendering its own component in the app's shell. The status rides on the data by IDENTITY in a `WeakMap`; `routeStatusOf(data)` is the total reader (200 by default). A 3xx is `X_ROUTE_STATUS_INVALID`. A 4xx/5xx is `robots.index = false` by construction in `defineRoute`'s `meta` wrapper. The `Response` status is minted by `@ultimat3/cli`'s `dev-render.ts`. |
+| Type claims | `type-pins.tsx`, never a `.test.ts` — `tsconfig.json` excludes tests. `.tsx` so the island-as-JSX claim is checked against the JSX an author writes. |
 | Descriptor `meta` / `load` | always `(x) => Promise<…>`. Authors may declare either sync; consumers never branch. |
-| Descriptor `budget` | always an object, `{}` when undeclared. Its *fields* stay optional — `budget.js === undefined` is the site/ hydration failure. |
-| `RouteBudget` keys | **`js` and `lcp`, and every key is PROJECTED** (`As of 2026-08-24`). `css`, `cls` and `tbt` were declared on the contract, flattened away by `registerRoute` — the descriptor carries `budgetJs` + `budgetLcp` and nothing else — and read by NOTHING: `x verify`'s `budgets` step, `x.manifest.json`, `x routes` and the dev dashboard all read those two. So `budget: { cls: 0.1 }` was accepted, normalised, stored and ignored while the gate that exists to enforce budgets reported green — the shape `jobs.driver` and `realtime.tier` had one declaration surface over. **Deleted, not wired**, for `PwaConfig.installPrompt`'s reason: the measuring half does not exist either. `type-pins.tsx` derives the allowed set from `RouteDescriptor`'s own `budget*` keys, so a key added here without a projection is a build error; `scripts/declaration-readers.ts` is the rule that finds the class across every declaration. **Breaking**: three keys are gone from `RouteBudget`. |
-| No `describe()` on a route | `describeRoutes()` is the one route list. A per-route projection would be a second one. |
-| Mode invariants | `modes.ts` only. Never inline a mode check in a render-\* file. **Four modes, and every one renders the route's component** — `spa` did not, and `renderSpa` never read `entry.component`, so a `spa` route served `<div id="x-root"></div>` in every app that ever declared one. A gated page is `ssr`; a body that belongs in the browser is an `island({ src })`. A fifth mode has to name the function that renders it. |
-| Island declaration | `island({ src })` — a **specifier**, never an import. That is the whole boundary: a string has no scope to close over and no edge for a bundler or `checkSurfaceBoundary` to follow, so a `static` page's graph cannot grow the island's dependencies. Never add an overload that takes a component. |
-| Island filename | `*.island.tsx`, `ISLAND_EXTENSION` — one spelling, same rule as `page.tsx`: a module ships to the browser iff its name says so. Never widen it to accept a second, and never make it optional. |
-| Island timing | the route's `hydrate` and nothing else — derived from the declaration, never declared on the island. An island declaring its own strategy would be a second way to say "this route hydrates" (axiom 1) and a second thing `budget.js` would have to chase. `hydrate: 'never'` + an island is still `X_ISLAND_NOT_HYDRATED`, and so is an `island()` call *below* the `defineRoute` that drains it. The `fix:` names exactly ONE of the two edits — `islandNeverDrained(spec)` tells the causes apart at the throw site, and a message offering both makes half the instruction wrong for every reader. |
-| Island node shape | a **branded array** (`IslandNode extends Array<never>`), and every walker tests `isIslandNode` BEFORE `Array.isArray`. An app types JSX with `jsxImportSource: solid-js`, whose `JSX.Element` is a type ALIAS — unaugmentable — and whose only object-shaped member is `ArrayElement`; a plain object was TS2786 at every `<Island />`, so the feature only worked through `h(Island, …)`, which is what render's own tests used. The array stays empty; the shell is `props.children`. Never satisfy this by importing solid's union. |
-| Island declaration order | `island()` above `defineRoute`, drained by it (`drainDeclaredIslands`). Package-internal — reachable from `./island`, never re-exported by `src/index.ts`: an app calling the drain between its `island()` and its `defineRoute` would silently un-declare the islands the route derives everything from, and a public export is semver-locked the moment it ships. Ambient, and NOT the thing the collector refuses to be: that one is per RENDER, where two requests would bill each other; this one is per MODULE, evaluated once, before any request — and `src` is resolved relative to the route file, so an `island()` call is route-module-local by construction. |
-| Derived budget | `registry.ts`, not `defineRoute`: a ceiling is only meaningful against a surface baseline, and the surface is a fact of the file path the route table already reads. `site/` → `20kb`, `app/` → `34kb` (`DEFAULT_ISLAND_JS_BYTES` above `jsBaselineBytes`). **Calibrated on a Solid island** `As of 2026-08`: it was `4kb`, sized from `contact-sales.island.tsx`, which imports no `solid-js` at all — and `render(() => <p>hello</p>, el)` measures 12,588 B, so the default sat a factor of three below the floor of every island that uses the JSX runtime, on every surface. A declared `budget.js` wins; a `'never'` route gets none, so the contradiction stays visible. |
-| `RouteEntry.islands` | filled from `config.islands` at registration, and from nothing else — `RegisterRouteInput` has no `islands` key. It was `input.islands ?? []`, undocumented and passed by nothing, so the now-deleted `routeJsBytes`'s "what registration declared" half read `[]` on every route in the framework's history; keeping it as a fallback would be a second answer to one question that can only ever weaken it, since a caller passing `[]` un-declares an island. The field survives its one former reader: it is the only record a build has of an island a page declared but did not render on a given pass. |
-| Island props | declared, JSON-safe, under `ISLAND_PROPS_MAX_BYTES` — `island-props.ts` is the one gate. A structural walk, never a `JSON.stringify` round trip: stringify drops a function and an `undefined` silently, which is the footgun rather than the check. The cap is **16 KiB** `As of 2026-09-05` (was 4; a 34-row catalog at 8,812 B was a runtime 500) and its doc comment carries the arithmetic — the bag is inlined as a JSON script `measureDocumentJs` counts as zero JS, so this constant is the only ceiling on it. Over the cap, the cause names the **heaviest props with their bytes** and the fix names the endpoint pattern (`models: []` + `modelsEndpoint`), never "raise the cap". `X_ISLAND_PROPS_INVALID` has a **row** in `@ultimat3/http`'s table (500): unclassified, `problem+json` blanked the one sentence that is the instruction. |
-| A prop lands via `Object.defineProperty` | never `out[key] = v`. For exactly one name — `__proto__`, which `JSON.parse` mints as a real OWN key off any request body — the assignment runs `Object.prototype`'s setter: the prop was DROPPED from the browser payload (the footgun the walk exists to prevent), the record handed back as `IslandProps` carried a prototype built from request data, so a later `bag.row.isAdmin` on the SERVER read attacker-chosen values, and `ISLAND_PROPS_MAX_BYTES` under-counted because `JSON.stringify` could not see it. Same shape `@ultimat3/mcp`'s `validate-args.ts` uses for the same class. |
-| An attribute alias is a `Map` | never a record — an object lookup walks the prototype chain, so `<div {...row} />` with a column named `toString` resolved the alias to a FUNCTION and `attribute.toLowerCase()` threw a bare `TypeError`: no code, no fix, the whole page 500s off a `load()` result. Same reason `MODE_SPECS[config.render]` in `modes.ts` is guarded by `Object.hasOwn`, where `render: 'constructor'` returned a frozen descriptor for a mode nothing implements. |
-| An attribute NAME is validated too | `ATTRIBUTE_NAME` in `html.ts` — `/^[A-Za-z_:][-A-Za-z0-9_:.]*$/`, refused as `null`. A name is emitted VERBATIM before the `=` and is escaped nowhere, so `{ 'q onmouseover=alert(1) r': 'ok' }` shipped a live event handler out of an object KEY. The handler check on the line under it folds case for the same reason: it was `name.startsWith('on')` while the two checks below it lowercased, so `ONERROR="alert(1)"` went out on the wire. Both are reachable by `<div {...row} />` over a JSON body or a JSONB column. `head.ts`'s `renderTag` is the package's OTHER attribute sink and shares the predicate (`isAttributeName`) — it emitted `<meta name="q" r onmouseover=alert(1) s="ok">` from an `attrs` key. One predicate, never two. |
-| Which attributes take a URL | `URL_BEARING_ATTRIBUTES` in `html.ts` — core's four (`href`, `src`, `action`, `formaction`) plus `data`, `poster`, `ping` and `xlink:href`, each of which a browser FOLLOWS. `srcdoc` is refused outright: its value is entity-decoded and THEN parsed as HTML, so `escapeAttribute`'s `&lt;script&gt;` becomes a live `<script>` on this origin — escaping cannot make markup inert, so the attribute is never emitted, the same way `innerHTML` stays the one explicit escape hatch. |
-| Island collection | per render, passed as `renderToHtml(tree, { islands })`. Never module-global and never on an ambient context — two concurrent requests would bill one page for the other's JS, and `assertNoPerRequestState` refuses a live context under `static` anyway. |
-| A byte count in a message | `formatBytes` from `@ultimat3/core`, never a local one. This package's copy stopped at `kb`, so a 5 MB route read `5120kb` in `X_BUDGET_EXCEEDED` while `@ultimat3/pwa`'s own copy said `5mb` for the same bytes — two halves of one build disagreeing about the size of one artifact. Still on this barrel, because `@ultimat3/cli`'s budget reporter reads it beside the route table. |
-| Island bytes | **not this package's**, `As of 2026-08-23`. `routeJsBytes`, `graphFor`, `checkBudget`, `checkBudgets`, `assertBudget` and the `Island` / `BundleGraph` / `RouteBytes` / `BudgetReport` types were exported from the barrel and called by NOTHING outside this package's own tests — the near-miss is `@ultimat3/cli`'s own `checkBudgets` in `packages/cli/src/budgets.ts`, which measures the EMITTED document and is the gate that runs. Deleted rather than wired, because two answers to "what does this route weigh" — one of them never asked — is axiom 1, and a build error nothing calls is not a build error. What survives here is the budget GRAMMAR (`parseByteBudget`, which the CLI does import) and `defaultIslandBudget`, which `registerRoute` reaches. **Breaking**: the six functions and five types are gone from the public API. |
-| The hydration runtime's CSP | `HYDRATE_RUNTIME_BODIES` — every body `hydrateRuntime` can emit, one per non-empty subset of the three strategies, seven in all. It is emitted INLINE in every document carrying an island, and `@ultimat3/http`'s `script-src` is `'self' 'wasm-unsafe-eval'`, so under the enforced policy a container serves (`dev: false`) **no island ever booted** — invisible in `x dev`, where the policy is report-only. `@ultimat3/cli`'s `script-csp.ts` hashes this list at boot, the mirror of `style-csp.ts`. Hashes and not a nonce, for `cspHashSource`'s own reason: a `render: 'static'` page is a file on disk. Never restate the concatenation — `runtimeBody` is the one place the served text and the hashed text are the same string. **Still uncovered**: `render-stream.ts`'s per-hole `<script>$X("id")</script>`, whose body is per-response and cannot be hashed. Unreachable today (`dev-render.ts` passes `holes: []`), and the first real hole needs a nonce, not a hash. |
-| Island markup | the props `<script>` is emitted INSIDE the wrapper by `render-html.ts`, so a document assembler has exactly one thing left to remember: `hydrateRuntime(directives)`. |
-| Island boot | `el.__x` holds the boot PROMISE, never a boolean. As a flag, a second interaction while the chunk was still loading got a resolved promise back and the replay queue flushed into an island that had not mounted — the events went nowhere and the listeners were already removed. |
-| Island mount markers | `data-x-mounted=""` when `mount()` RESOLVED, `data-x-failed="<message>"` when it rejected — set by the runtime, never by `emitIslandAttributes`, because the server does not know the answer. `el.__x` alone cannot carry this: it is assigned when `import()` is CALLED, so a chunk still downloading and one whose `mount()` threw were the same observable, and telling those apart is what `x shot` gates on. Two attributes rather than two values of one, so `[data-x-mounted]` never counts a failure as a success. The rejection handler RETHROWS — swallowing it resolves `el.__x` and the interaction runtime flushes its replay queue into an island that never mounted, which is the row above reintroduced one layer out. Costs 129 B of shared prelude: `idle` 1,744, `visible` 846, `interaction` 1,629 (`As of 2026-09-22`, the numbers `DEFAULT_ISLAND_JS_BYTES` is derived from — `idle` moved 774 -> 1,744 and `interaction` 1,251 -> 1,629 when both began sharing `catchUp` and aiming by path, the rows below). |
-| A runtime that calls `boot` | TERMINATES the chain, because `boot` rethrows. `idle` and `visible` end in `.catch(hush)`; `interaction` passes `off` as the rejection arm of its `then`. A bare `boot(el)` produced a fresh rejected promise per call — one unhandled rejection per user event on an island whose `mount()` threw — and, on `interaction`, left `done` false, the listeners attached and the queue growing by one retained `Event` (each with a live `target`) per click, for an island that will never mount. Nothing is lost by swallowing here: the DOM already carries the failure as `data-x-failed`, which is the row above and the documented observable. `hydrate-runtime.test.ts` runs all three against a real module; Bun's runner fails a test on an unhandled rejection, so the omission reds the suite by itself. |
-| `idle` replays too | An `idle` island is pressable for the idle wait plus its chunk's download, and a press in that window reached a node with no handler: every app's first click could vanish. `idle` and `interaction` share ONE `catchUp(el)` in `hydrate.ts` — capture listeners for `data-x-events` (default `click`), a queue, `aim`, one flush — which answers `go`: a caught event calls it (so a press wakes an `idle` island early), and `idle` calls it again from `requestIdleCallback`. Every `go` chains on the same `el.__x` and the first flush sets `done`, so each event replays once and an untouched island still drops its listeners at mount. Emitted once when either strategy is on the page; a `visible`-only page pays nothing. `hydrate-replay.test.ts`'s idle block holds it. |
-| Where `interaction` replays | `aim(el, ev)` in `hydrate.ts`, never `ev.target`. Every island's `mount` opens with `el.textContent = ''` — the documented idiom, and what `settings`, `feed` and `like` all do — so the node the visitor pressed is DETACHED by the time the replay runs and `ev.target.dispatchEvent(c)` reached nothing: the first press did nothing and the second worked, which reads as a slow network and is never filed as a bug. `examples/dummy/apps/web/app/posts/[id]/page.tsx` declares `hydrate: 'idle'` in writing to avoid it. The runtime CAN tell the two mounts apart — `el.contains(ev.target)` AFTER the mount is the exact question — so this is a repair and not a refusal: refusing the pairing would delete a strategy that works today for a takeover-style island (`contact-sales.island.tsx` attaches to the server's own form and replaces nothing). Kept → the original target. Replaced → `document.elementFromPoint(ev.clientX, ev.clientY)`, which is where the event would land had the visitor pressed a moment later. The island ROOT is the last resort and never the repair: Solid's delegated listener sits on `document` and walks UP from the target (`solid-js/web`'s `eventHandler`), so a handler on a CHILD of the root is never visited and dispatching at the root fixes nothing for the canonical island. A hit landing outside this island falls back to the root too — synthesizing a click on an element the visitor never pressed is worse than losing the replay. `typeof ev.clientX === 'number'`, never `ev.clientX || ev.clientY`: (0, 0) is a coordinate — unless `ev.detail === 0`, a keyboard-activated or scripted `click()`, which fires at (0, 0) and names no point. Between the hit test and the root sits the STRUCTURAL answer: `path(el, target)` records the child-element indices and tag when the event is caught, and the replay walks them in the mounted tree — same tag at the same place is the island's render of the pressed control; a different tag falls to the root. `hydrate-replay.test.ts` holds it, and it is a separate file because `hydrate-runtime.test.ts`'s element is BOTH the island root and every event's target — the two answers are the same node there, which is how this survived. |
-| `idle`'s deadline | `IDLE_HYDRATE_TIMEOUT_MS`, interpolated INTO the runtime string. Exported because a second reader has to agree — `x shot` waits before it photographs, and a settle shorter than this deadline reports an unhydrated page for one that hydrates perfectly. A constant the emitted string restates instead of reading is worse than no constant. |
-| Route truth | `registry.ts`. Never keep a second route list anywhere, and never a second *matcher*: this package's `matchRoute` was deleted in 2026-08 with zero consumers, because `@ultimat3/http`'s trie (`stages.ts`) is the one that serves requests and two matchers with different precedence rules is two answers to "which route is this?". `routeFor` is an exact-path `Map` lookup, not a pattern matcher. |
-| Route filename | `page.tsx` under `site/`/`app/`, `route.ts` under `api/` — `ROUTE_FILENAME`, one per surface. The URL is the directory path. Anything else is `X_ROUTE_FILE_INVALID`; never widen the table to accept a second spelling. |
-| Registry input | descriptors only. `registerRoute` refuses a raw declaration with `X_ROUTE_UNNORMALIZED` — `defineRoute` is the one normalizer of everything the declaration alone decides, and every reader downstream assumes it ran. The registry fills in exactly one value on top: the island budget, which needs the surface, which is a fact of the file path only the route table reads. |
-| Descriptors | `describeRoutes()` must stay JSON-safe, sorted by path, deterministic. |
-| Every string order in this package | `byCodeUnit` (`code-unit-order.ts`), never `localeCompare`. With no locale argument `localeCompare` answers from the runtime's ICU **default locale** and **collation version**: `'/A'` sorted after `'/a'` on one machine and before it on the next, and `'/zoo'` before `'/ärzte'` under `sv-SE` but after it under `en-US` — for the same route table. Three sites shipped it: `routeEntries()` (so `describeRoutes()`, and with it `x.manifest.json`, the sitemap and `sw.js`'s rule table), `checkSurfaceBoundary`'s report, and `pageComponentOf`'s fallback, whose own comment promised "the same one on every machine". Package-internal on purpose — a comparator is not public API. Same rule `@ultimat3/pwa`'s `precache.ts` and `service-worker.ts` state for the artifact they emit. |
+| Descriptor `budget` | always an object, `{}` when undeclared. `budget.js === undefined` is the site/ hydration failure. |
+| `RouteBudget` keys | **`js` and `lcp` only, and every key is PROJECTED** (`budgetJs`, `budgetLcp`). `type-pins.tsx` derives the allowed set from `RouteDescriptor`'s `budget*` keys, so an unprojected key is a build error; `scripts/declaration-readers.ts` finds the class across every declaration. |
+| No `describe()` on a route | `describeRoutes()` is the one route list. |
+| Mode invariants | `modes.ts` only; never inline a mode check in a render-\* file. **Four modes, and every one renders the route's component.** A fifth mode has to name the function that renders it. |
+| Island declaration | `island({ src })` — a **specifier**, never an import, so a `static` page's graph cannot grow the island's dependencies. Never add an overload that takes a component. |
+| Island filename | `*.island.tsx`, `ISLAND_EXTENSION` — one spelling. Never widen it. |
+| Island timing | the route's `hydrate` and nothing else. `hydrate: 'never'` + an island, or an `island()` call below the `defineRoute` that drains it, is `X_ISLAND_NOT_HYDRATED`; `islandNeverDrained(spec)` tells the two causes apart so the `fix:` names exactly one edit. |
+| Island node shape | a **branded array** (`IslandNode extends Array<never>`); every walker tests `isIslandNode` BEFORE `Array.isArray`. Solid's `JSX.Element` is an unaugmentable alias whose only object member is `ArrayElement`. Never import solid's union. |
+| Island declaration order | `island()` above `defineRoute`, drained by it (`drainDeclaredIslands`), reachable from `./island` and never from `src/index.ts`. Per MODULE (evaluated once), unlike the per-render collector. |
+| Derived budget | `registry.ts`, from the surface: `site/` → `20kb`, `app/` → `34kb` (`DEFAULT_ISLAND_JS_BYTES` above `jsBaselineBytes`), calibrated on a Solid island. A declared `budget.js` wins; a `'never'` route gets none. |
+| `RouteEntry.islands` | filled from `config.islands` at registration and nothing else — `RegisterRouteInput` has no `islands` key. |
+| Island props | declared, JSON-safe, under `ISLAND_PROPS_MAX_BYTES` (16 KiB; the doc comment carries the arithmetic) — `island-props.ts` is the one gate, a structural walk, never a `JSON.stringify` round trip. Over the cap the cause names the heaviest props and the fix names the endpoint pattern, never "raise the cap". `X_ISLAND_PROPS_INVALID` has a row in `@ultimat3/http`'s table (500). |
+| A prop lands via `Object.defineProperty` | never `out[key] = v` — `__proto__` (a real own key off `JSON.parse`) would run the prototype setter. |
+| An attribute alias is a `Map` | never a record (`toString` resolved to a function). `MODE_SPECS[config.render]` is guarded by `Object.hasOwn` for the same reason. |
+| An attribute NAME is validated too | `ATTRIBUTE_NAME` in `html.ts` (`/^[A-Za-z_:][-A-Za-z0-9_:.]*$/`), refused as `null`; the `on*` handler check folds case. `head.ts`'s `renderTag` shares the predicate (`isAttributeName`). One predicate, never two. |
+| Which attributes take a URL | `URL_BEARING_ATTRIBUTES` in `html.ts` — core's four plus `data`, `poster`, `ping`, `xlink:href`. `srcdoc` is refused outright (entity-decoded, then parsed as HTML). |
+| Island collection | per render, `renderToHtml(tree, { islands })`. Never module-global and never on an ambient context. |
+| A byte count in a message | `formatBytes` from `@ultimat3/core`, never a local one. |
+| Island bytes | **not this package's**: `@ultimat3/cli`'s `packages/cli/src/budgets.ts` measures the EMITTED document and is the gate. What stays here is the budget grammar (`parseByteBudget`) and `defaultIslandBudget`. |
+| The hydration runtime's CSP | `HYDRATE_RUNTIME_BODIES` — every body `hydrateRuntime` can emit (seven subsets). It is inline in every document with an island and `@ultimat3/http`'s `script-src` is `'self' 'wasm-unsafe-eval'`, so `@ultimat3/cli`'s `script-csp.ts` hashes this list at boot. `runtimeBody` is the one place the served and hashed text are one string. **Uncovered**: `render-stream.ts`'s per-hole `<script>$X("id")</script>` (unreachable today; the first real hole needs a nonce). |
+| Island markup | the props `<script>` is emitted INSIDE the wrapper by `render-html.ts`; an assembler only adds `hydrateRuntime(directives)`. |
+| Island boot | `el.__x` holds the boot PROMISE, never a boolean. |
+| Island mount markers | `data-x-mounted=""` when `mount()` resolved, `data-x-failed="<message>"` when it rejected — set by the runtime, never by `emitIslandAttributes`. The rejection handler RETHROWS. Prelude sizes `As of 2026-09-22`: `idle` 1,744, `visible` 846, `interaction` 1,629 B (what `DEFAULT_ISLAND_JS_BYTES` derives from). |
+| A runtime that calls `boot` | TERMINATES the chain: `idle`/`visible` end in `.catch(hush)`, `interaction` passes `off` as the rejection arm. `hydrate-runtime.test.ts` reds on an unhandled rejection. |
+| `idle` replays too | `idle` and `interaction` share ONE `catchUp(el)` in `hydrate.ts` (capture listeners for `data-x-events`, default `click`; a queue; `aim`; one flush). A caught event wakes an `idle` island early; each event replays once. `hydrate-replay.test.ts`. |
+| Where `interaction` replays | `aim(el, ev)`, never `ev.target` — `mount` usually clears the root, detaching the pressed node. Kept → original target; replaced → `path(el, target)`'s structural walk (same tag, same place), then `document.elementFromPoint(ev.clientX, ev.clientY)` (unless `ev.detail === 0`), then the island root. A hit outside the island falls back to the root. `hydrate-replay.test.ts`. |
+| `idle`'s deadline | `IDLE_HYDRATE_TIMEOUT_MS`, interpolated INTO the runtime string and exported for `x shot`'s settle. |
+| Route truth | `registry.ts`. Never a second route list and never a second matcher — `@ultimat3/http`'s trie (`stages.ts`) serves requests. `routeFor` is an exact-path `Map` lookup. |
+| Route filename | `page.tsx` under `site/`/`app/`, `route.ts` under `api/` — `ROUTE_FILENAME`. Anything else is `X_ROUTE_FILE_INVALID`. |
+| Registry input | descriptors only. `registerRoute` refuses a raw declaration with `X_ROUTE_UNNORMALIZED`; it fills in only the island budget. |
+| Descriptors | `describeRoutes()` stays JSON-safe, sorted by path, deterministic. |
+| Every string order | `byCodeUnit` (`code-unit-order.ts`), never `localeCompare` (ICU default locale and collation version vary by machine). |
 | Boundary | `surfaces.ts` throws; it never warns. Type-only edges are not violations. |
-| Stream cancellation | the underlying source has a `cancel()`, and `write` is guarded on it. A client that disconnects mid-stream aborts `StreamHole.resolve(signal)` and every later `write`/`close` is a no-op — `settle()` on a cancelled controller threw out of a `void`ed promise, one unhandled rejection per response, while the resolved holes kept doing their database work with nowhere to write. |
-| ISR detach | `attach()`'s returned function clears the revalidator as well as the dependents — and only if the slot is still its own, tracked in `installedRevalidator` because `@ultimat3/cache` holds ONE and offers no read back. Left installed, a detached controller and its whole store stayed reachable and kept receiving revalidations while the live one's pages never went stale. |
-| "Is this a TTL?" has one reader | `parseTtlMs` in `duration.ts`, below both `modes.ts` and `render-isr.ts` (importing the latter from the former is a cycle through `registry.ts`). `hasRevalidateTrigger` accepted any non-empty string, so `revalidate: { ttl: '5 minutes' }` passed registration and parsed to `null` at serve time: generated ONCE, served for the life of the process, while the CDN was told `s-maxage=60` — the exact costume the `isr`-needs-a-trigger check refuses. |
-| A build-time frame reads a throw with `renderThrowable` | `render-html.ts`, `render-static.ts`, `css-modules.ts`, `module-loader.ts`, `route-data.ts` — never `error instanceof Error ? error.message : String(error)`. A component that throws `Object.create(null)` escaped as a bare `TypeError` and one whose `message` getter throws as a bare `Error`, where `X_PRERENDER_FAILED` naming the file belongs. `bun run error-render` does NOT see this shape: it follows a direct interpolation, not a value laundered through a file-local `describe()` helper. |
-| `X_ROUTE_LOAD_FAILED` computes its pathname BEFORE the try | `new URL(ctx.url)` inside the catch made a relative `ctx.url` — what a prerender pass, `x build` and every test harness hand in — throw a bare `TypeError` on the one path whose job is a coded error. `pathnameOf` never throws. |
-| The ISR key | `isrKey(url, locale)` — pathname, the negotiated LOCALE in the reserved `__x_locale` parameter, then the query, params sorted. The locale is a REQUIRED argument, so every call site has to answer: a document is rendered with `<html lang>` and every `t()` in the request's own locale, so one entry per path served visitor 2 the document negotiated for visitor 1 — for the whole TTL, and `s-maxage` told the CDN to do the same. `examples/dummy` ships en + es and three `isr` routes, so it was all three. A parameter and not a prefix because `routePathOf` splits a key at its `?`: a `es:/blog` key matches no route, so `descriptorFor` answers `undefined` and a declared `ttl` silently becomes tag-only. The time zone is deliberately NOT a dimension — unbounded where a locale set is declared — so a date on an `isr` page belongs in a zone the page itself names. `toResult` emits `vary: accept-language` for the CDN half; the rest of the shared key is added by `@ultimat3/http`'s `cache-headers` stage, which sees the actor this function cannot. |
-| A bust that lands MID-render | fenced with `@ultimat3/cache`'s `sampleFence({ key, tags })`, taken before `render()` and asked before `store.set` — the same mechanism `CacheStack`'s read-through fill uses, never a second one grown here. `regenerate` rendered and then wrote `{ stale: false }` unconditionally, so a `markStale` arriving in between was ERASED by HTML built from pre-write rows; for a tag-only route `isFresh` is then true forever and the process serves it for the rest of its life. `registerPath` runs BEFORE the render for the other half: `revalidateByTags` reads the graph, so a bust could not see a cold path whose first render was still in flight. |
-| Marking a page stale | `IsrStore.markStale(path)`, in place — never `set({ ...entry, stale: true })`. `set` means "this page was just generated" and the default store orders eviction by exactly that, so the read-modify-write made the STALEST page the newest: a tag bust protected the pages that most needed regenerating and evicted the freshest one instead. **Breaking**: `markStale` is a required member of `IsrStore`. |
-| ISR store bound | `memoryIsrStore()` caps at `DEFAULT_ISR_MAX_ENTRIES` (1,000), least recently generated first — a route table supports `:params` and `*`, so `/blog/:slug` retains one full HTML string per slug ever requested, 404-shaped ones included. |
-| A `RenderResult.status` | `finiteStatus(subject, status)` in `finite-status.ts`, at every site that takes one from a caller (`renderSsr`'s `options.status`, `streamResult`'s third argument, `withStatus`'s first, and an `IsrRenderFn` answering `{ html, status }` at generation — `isRenderStatus`, the same range as a predicate, is the TOTAL read of a stored `IsrEntry.status` on the request path, because a custom store may JSON-round-trip one and a throw there is a 500 for the page's whole TTL) — 200–599, whole. It reaches `new Response(body, { status })`, which answers a bare `RangeError` for anything else: `NaN` arrives there as `The status provided (-9223372036854775808)`, no code, no fix, and the render fails two frames above the route that set it. The screen is NARROWER than the boundary on purpose — `new Response` also takes `101`, and no rendered document is a protocol switch. The name carries `finite` because `bun run finite-bounds` recognises a repair by the shape of the CALL; spelled `renderStatus` it read as no screen at all. |
-| `IsrEntry.ttlMs` off a store | normalised by `entryTtlMs`, TOTAL, never a throw — a ttl that is not a POSITIVE FINITE number of ms is the tag-only `null` `parseTtlMs` would have answered. `IsrStore` is a driver seam, and one backed by Redis round-trips the entry through JSON where a `ttlMs` nobody wrote reads back as `undefined`, so `entry.ttlMs === null` is false. Two failures, neither raising: `now - generatedAt < NaN` is false so the page is NEVER fresh and every request regenerates it, and the CDN is handed `s-maxage=NaN` — a directive a conforming cache IGNORES, dropping the page to heuristic caching. Read on the request path, so a refusal would turn a bad stored entry into a 500; the `isr.entry_ttl_invalid` warning is what keeps it from being silent. |
-| Route path from file | ONE reader of the surface segment: `locateSurface()` answers which surface AND where it starts. `registry.ts` sliced at `indexOf('app/')` instead, which matched inside `myapp/`, so every route under `apps/myapp/app/` served at `/app/…`. Never re-derive the offset from the surface NAME. |
-| An undecodable path segment | not a match, never a throw — `decodeSegment` in `registry.ts` is the one reader. `decodeURIComponent('%zz')` is a bare `URIError`, so a typo in a path segment was a 500 where `@ultimat3/http`'s router already answers "this branch does not match". A literal route matching the same text still wins. `router-client.ts` was the second reader and went with `createRouter`. |
-| ISR registration | reconciled against `store.paths()` after every generation (`forgetEvictedPaths`). The store is bounded and evicts silently; `registered` and the cache graph behind it only ever grew, one edge per slug ever requested. Never a store callback — a custom `IsrStore` has none. |
-| Stream hole deadline | `DEFAULT_HOLE_TIMEOUT_MS` (15s), `holeTimeoutMs: null` to opt out, and a declared one is a whole number of at least **1** — a deadline is the bound a non-finite value does not disable but MOVES: `setTimeout(fn, NaN)` is `setTimeout(fn, 0)`, so every hole misses a deadline nobody set and the document is all fallbacks. There is no spelling of `holeTimeoutMs` that means "immediately". A hole is app code the framework `await`s and nothing else bounds it; one that never settles held the response and its whole closure open for the life of the process. A hole reveals exactly once — its promise, its rejection, or its deadline, whichever lands first. |
+| Stream cancellation | the source has a `cancel()` and `write` is guarded on it; a disconnect aborts `StreamHole.resolve(signal)`. |
+| ISR detach | `attach()`'s returned function clears the revalidator too — only if the slot is still its own (`installedRevalidator`). |
+| "Is this a TTL?" has one reader | `parseTtlMs` in `duration.ts`, below `modes.ts` and `render-isr.ts`. |
+| A build-time frame reads a throw with `renderThrowable` | `render-html.ts`, `render-static.ts`, `css-modules.ts`, `module-loader.ts`, `route-data.ts`. `bun run error-render` cannot see a value laundered through a local helper. |
+| `X_ROUTE_LOAD_FAILED` computes its pathname BEFORE the try | `pathnameOf` never throws on a relative `ctx.url`. |
+| The ISR key | `isrKey(url, locale)` — pathname, the negotiated locale in the reserved `__x_locale` parameter, then the sorted query. The locale is REQUIRED. The time zone is deliberately not a dimension. `toResult` emits `vary: accept-language`; the rest of the shared key is `@ultimat3/http`'s `cache-headers` stage. |
+| A bust that lands MID-render | fenced with `@ultimat3/cache`'s `sampleFence({ key, tags })`, taken before `render()` and asked before `store.set`. `registerPath` runs BEFORE the render. |
+| Marking a page stale | `IsrStore.markStale(path)`, in place — never `set({ ...entry, stale: true })` (`set` means "just generated" and orders eviction). |
+| ISR store bound | `memoryIsrStore()` caps at `DEFAULT_ISR_MAX_ENTRIES` (1,000), least recently generated first. |
+| A `RenderResult.status` | `finiteStatus(subject, status)` (`finite-status.ts`), 200–599 whole, at every site that takes one from a caller; `isRenderStatus` is the TOTAL read of a stored `IsrEntry.status`. The name carries `finite` so `bun run finite-bounds` recognises it. |
+| `IsrEntry.ttlMs` off a store | normalised by `entryTtlMs`, TOTAL — anything not positive-finite is tag-only `null`, with an `isr.entry_ttl_invalid` warning. |
+| Route path from file | `locateSurface()` answers which surface AND where it starts. Never re-derive the offset from the surface name. |
+| An undecodable path segment | not a match, never a throw — `decodeSegment` in `registry.ts`. |
+| ISR registration | reconciled against `store.paths()` after every generation (`forgetEvictedPaths`). |
+| Stream hole deadline | `DEFAULT_HOLE_TIMEOUT_MS` (15 s), `holeTimeoutMs: null` to opt out, otherwise a whole number ≥ 1. A hole reveals exactly once — promise, rejection or deadline. |
 | Errors | `errors.ts` subclasses only. Never a bare `Error`, never a bare `TODO`. |
 | Policy | render checks *presence* only. Evaluation belongs to `@ultimat3/policy`. |
-| A gated route is never a cached one | `modes.ts` refuses `policy` on BOTH `static` and `isr` (`X_ROUTE_MODE_INVALID`, `modes.test.ts`). `isr` was not refused until 2026-08 and `dev-render.ts` keys the cache on `url.pathname` alone — no actor, no query string — so a gated ISR route rendered the first actor's document and served it to every later actor who passed the same policy. Keying on more is a trap, not a fix: the key would have to enumerate everything a `policy` and a `load` can read. `ssr` is the one gated mode there is. |
+| A gated route is never a cached one | `modes.ts` refuses `policy` on both `static` and `isr` (`X_ROUTE_MODE_INVALID`, `modes.test.ts`). `ssr` is the one gated mode. |
 | Responses | return `RenderResult`. `@ultimat3/http` builds the `Response`. |
-| Who owns `cache-control` | a render mode states the MODE's intent; `@ultimat3/http`'s `cache-headers` stage makes the final answer and may overrule it. `ssrHeaders` writes `s-maxage=30` for any route without a `policy` — and `meta.auth` is `'public' \| 'required'`, so the page that greets a signed-in visitor by name is a `'public'` route whose own header offered it to a CDN. This package cannot see the actor and must never try: the fix is not a second actor check here. |
-| Solid | no `solid-js` import anywhere in this package — `type-pins.tsx` satisfies its `JSX.Element` structurally, through `jsxImportSource`, and never names it. The JSX factory in `jsx.ts` builds inert nodes — it is not a Solid renderer and must never become one. The client half runs in an island chunk, which `@ultimat3/cli`'s `solid-loader.ts` compiles with `babel-preset-solid`: Solid's reactivity is a COMPILE-time contract, so nothing this package could inject would substitute for it. `router-client.ts` was the one file built on that premise ("inject primitives") and it never had a caller. |
-| Root element | `ROOT_ELEMENT_ID` (`render-html.ts`), the id every document's body wraps its component in. It was `SPA_ROOT_ID` in `render-spa.ts`, naming a mode that never used it and that no longer exists. |
-| The loaders | `module-loader.ts` installs them at **`server.ts`** module scope, once — `index.ts` until the barrel split, and it cannot be there again: the client barrel would carry `sass` and `node:url`. A plugin only affects modules loaded after it, so a second install point is a page that renders in one entry point and not another. Anything that loads an app's `.tsx` reaches `@ultimat3/render/server` first, which is why `packages/cli/src/app-load.ts` imports it for the side effect and nothing else. |
-| Client sync tags | `client-sync-tags.ts` — `ultimate-sync` (the socket URL: `/_x/sync` or a declared `wss://…`), `ultimate-build` (the build id a script cannot read off `x-ultimate-build`) and `ultimate-sync-worker` (absent when no worker was built). Principal-free, so every document carries them. The three names are literals here until core or realtime owns constants a reader imports. `As of 2026-09-22`. |
-| Client scope tag | `client-scope-tag.ts` — `<meta name="ultimate-scope" content="<opaque>">`, read once by core's `pageClient()` (plan 101). `documentCarriesScope(headers)` is the ONE rule for which documents may carry it: `cache-control` says `private` — a gated `ssr` page and every `stream`. A `static`/`isr`/ungated-`ssr` document is shareable and carries NO tag; absent means "not rendered for anyone", never `''` (anonymous). The literal `ultimate-scope` is duplicated in core's reader because core cannot import this package — the pin is owed once core exports its constant. `As of 2026-09-22`. |
-| `<head>` baseline | `documentBaseline()` in `head.ts` — charset, viewport, `color-scheme` — merged FIRST so a route can still override any of them. Absent until `As of 2026-08`, and the missing `viewport` is why every deployed app rendered zoomed-out on a phone whatever its CSS said. |
-| Escaping | `html.ts` only, and that now includes `render-stream.ts` (`holeMarker`'s attribute, and `revealChunk`'s `$X(...)` argument via `JSON.stringify` — an id containing `")` closed the call and ran the rest) and `head.ts`'s `themeScript` (`storageKey`/`attribute` as JS string LITERALS). All author-controlled today — the identical status `emitIslandAttributes` had before the last sweep. `render-spa.ts` was the third entry here and went with the mode. A second escaper is how one of them ends up missing a character, and a missing character in an attribute is an injection. `escapeAttribute` itself is `@ultimat3/seo`'s (tier 1), re-exported by `html.ts` rather than reimplemented — the copy that lived here was the second escaper this row forbids, and `pwa/CLAUDE.md` already named seo's as the one. `head.ts` and `hydrate.ts` each had a private copy; both now import — `escapeAttribute` for every attribute value (`emitIslandAttributes` interpolated all five of its own raw until 2026-08, while this row already claimed otherwise) and `escapeJsonContent` for a JSON script body. |
-| Script and style CONTENT | never emitted raw. Three rules, one choice: HTML text (`escapeText`), raw text for code (`escapeRawTextContent`: `</` → `<\/`, `<!--` → `<\!--`), and the total JSON rule for a `type` ending in `json` (`escapeJsonContent`: `<`, `>`, `&`, U+2028/9 → `\uXXXX`, still valid JSON). `meta.ld` is built from route data, and it was emitted VERBATIM until `As of 2026-08` — a title could close the element. Never HTML-escape a script body: a character reference is not decoded there, so `&lt;` corrupts the code AND leaves the hole. |
-| Which export is the page | `route-component.ts`, one precedence: `Page` → a single `…Page` → a single capitalised function. Never a per-generator name table. |
-| Stylesheets | compiled by `css-modules.ts`, still grouped per surface, and served by the CLI as **one content-hashed file per surface** (`@ultimat3/cli`'s `style-bundle.ts`) rather than inlined — measured 2026-09-06, the inline block was 156,738 bytes inside a `no-store` document, re-sent on every navigation. `stylesFor` is unchanged and is what that file is built from. `sass` is this package's only third-party dependency and its only reason to exist here. |
-| CSS order | `stylesFor` sorts **globals before modules** (`isGlobalStylesheet`), never plain insertion order — the reset styles bare elements at the lowest specificity there is, so whichever page loaded first must not decide who wins a tie. `shared/` is carried by both graphs, like a package sheet: it is where an app's own global layer lives, and filtering it out is what made every deployed app render token-less. |
-| The global layer | this package may not import `@ultimat3/ui` (tier 4, the same tier — sideways, not upward: `ui` moved 5 → 4 in 2026-08 and `render → ui` stays forbidden because a same-tier edge has to be declared in `scripts/lib/tiers.ts`, and this one deliberately is not — the static bundle graph may not reach the design system, axiom 6), so the app's source graph carries it: one `shared/global.scss` that `@use`s `@ultimat3/ui/global.scss`, side-effect-imported by `shared/global.ts`. One file, because each stylesheet is its own Sass compilation — a token file `@use`d per module duplicates its `:root` block per module. `x verify` fails with `X_STYLES_GLOBAL_MISSING` when a surface's document defines none. |
+| Who owns `cache-control` | a mode states intent; `@ultimat3/http`'s `cache-headers` stage decides and may overrule. This package cannot see the actor and never tries. |
+| Solid | no `solid-js` import anywhere in this package; `type-pins.tsx` satisfies `JSX.Element` structurally. `jsx.ts` builds inert nodes. Islands are compiled by `@ultimat3/cli`'s `solid-loader.ts` with `babel-preset-solid`. |
+| Root element | `ROOT_ELEMENT_ID` (`render-html.ts`). |
+| The loaders | `module-loader.ts` installs them at **`server.ts`** module scope, once. `packages/cli/src/app-load.ts` imports `@ultimat3/render/server` for that side effect. |
+| Client sync tags | `client-sync-tags.ts` — `ultimate-sync`, `ultimate-build`, `ultimate-sync-worker`. Principal-free, on every document. |
+| Client scope tag | `client-scope-tag.ts` — `<meta name="ultimate-scope">`, read by core's `pageClient()`. `documentCarriesScope(headers)` is the one rule: only a `private` document carries it; absent means "not rendered for anyone". The literal is duplicated in core until core exports a constant. |
+| `<head>` baseline | `documentBaseline()` in `head.ts` — charset, viewport, `color-scheme` — merged FIRST so a route can override any of them. |
+| Escaping | `html.ts` only — including `render-stream.ts`'s `holeMarker` and `revealChunk` (`JSON.stringify`), and `head.ts`'s `themeScript`. `escapeAttribute` is `@ultimat3/seo`'s, re-exported by `html.ts`. |
+| Script and style CONTENT | never raw: `escapeText`, `escapeRawTextContent` (`</` → `<\/`, `<!--` → `<\!--`), or `escapeJsonContent` for a `type` ending in `json`. Never HTML-escape a script body. |
+| Which export is the page | `route-component.ts`: `Page` → a single `…Page` → a single capitalised function. |
+| Stylesheets | compiled by `css-modules.ts`, grouped per surface, served by the CLI as one content-hashed file per surface (`@ultimat3/cli`'s `style-bundle.ts`) from `stylesFor`. `sass` is this package's only third-party dependency. |
+| CSS order | `stylesFor` sorts **globals before modules** (`isGlobalStylesheet`). `shared/` is carried by both graphs. |
+| The global layer | the app's `shared/global.scss` `@use`s `@ultimat3/ui/global.scss`, side-effect-imported by `shared/global.ts` (this package may not import `ui`). `x verify` fails with `X_STYLES_GLOBAL_MISSING` when a surface's document defines none. |
 | Colours | tokens and `data-theme` only. No hex in `head.ts` or any emitted script. |
-| An island's `mount` | may return `() => void`, its disposer — `return render(…)`. The runtime resolves `el.__x` with it and never calls it; `@ultimat3/testing`'s `mountIsland` does, on dispose. |
-| `<head>` binding | `head.ts` stays injection-only (testable with no catalog); `head-seo.ts` is the ONE binding of `HeadRenderers` to `@ultimat3/seo`. A caller writing its own converter is the drift this file prevents. |
+| An island's `mount` | may return `() => void`, its disposer; the runtime never calls it, `@ultimat3/testing`'s `mountIsland` does. |
+| `<head>` binding | `head.ts` stays injection-only; `head-seo.ts` is the ONE binding of `HeadRenderers` to `@ultimat3/seo`. |
 Cross-package: `@ultimat3/pwa` consumes route descriptors as **data**, never by import.
 Keep `RouteDescriptor` additive — removing a field breaks `sw.js` generation.
@@ -117,3 +109,5 @@ bun test                          # from packages/render
 bun run typecheck
 bun run --cwd ../.. verify        # the contract
 ```
+Why each rule above is shaped the way it is: [`docs/history/render.md`](../../docs/history/render.md).

package/README.md CHANGED Viewed

@@ -433,6 +433,28 @@ does.
 side effect. Anything that loads an app's source — `x dev`, `x build`, `server.ts`, a test that
 `await import()`s a `page.tsx` — reaches it before the module it loads.
+## Error classes
+Every error class `src/index.ts` exports, for `instanceof` inside one process. Across a wire or
+a job boundary the class is gone and the `code` is what survives — match on that.
+| Class | Code | Declared in |
+|---|---|---|
+| `BudgetExceededError` | `X_BUDGET_EXCEEDED` | `src/errors.ts` |
+| `IslandInvalidError` | `X_ISLAND_INVALID` | `src/errors.ts` |
+| `IslandNotHydratedError` | `X_ISLAND_NOT_HYDRATED` | `src/errors.ts` |
+| `IslandPropsInvalidError` | `X_ISLAND_PROPS_INVALID` | `src/errors.ts` |
+| `PrerenderFailedError` | `X_PRERENDER_FAILED` | `src/errors.ts` |
+| `RouteDuplicateError` | `X_ROUTE_DUPLICATE` | `src/errors.ts` |
+| `RouteFileInvalidError` | `X_ROUTE_FILE_INVALID` | `src/errors.ts` |
+| `RouteLoadFailedError` | `X_ROUTE_LOAD_FAILED` | `src/errors.ts` |
+| `RouteLoadInvalidError` | `X_ROUTE_LOAD_INVALID` | `src/errors.ts` |
+| `RouteMetaMissingError` | `X_ROUTE_META_MISSING` | `src/errors.ts` |
+| `RouteModeInvalidError` | `X_ROUTE_MODE_INVALID` | `src/errors.ts` |
+| `RouteOfflineMissingError` | `X_ROUTE_OFFLINE_MISSING` | `src/errors.ts` |
+| `RouteStatusInvalidError` | `X_ROUTE_STATUS_INVALID` | `src/errors.ts` |
+| `SurfaceBoundaryError` | `X_SURFACE_BOUNDARY` | `src/errors.ts` |
 ## Public API
 `†` marks a name on `@ultimat3/render/server`.

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/render",
-  "version": "21.0.0",
+  "version": "22.0.0",
   "description": "The route primitive and the five render modes: static, isr, ssr, stream, spa.",
   "license": "MIT",
   "type": "module",
@@ -36,10 +36,10 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/cache": "21.0.0",
-    "@ultimat3/core": "21.0.0",
-    "@ultimat3/i18n": "21.0.0",
-    "@ultimat3/seo": "21.0.0",
+    "@ultimat3/cache": "22.0.0",
+    "@ultimat3/core": "22.0.0",
+    "@ultimat3/i18n": "22.0.0",
+    "@ultimat3/seo": "22.0.0",
     "sass": "1.104.0"
   }
 }

package/src/css-modules.ts CHANGED Viewed

@@ -8,7 +8,7 @@ import { existsSync } from 'node:fs';
 import { basename, dirname, resolve } from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 import { renderThrowable } from '@ultimat3/core';
-import * as sass from 'sass';
+import type * as Sass from 'sass';
 import { PrerenderFailedError } from './errors';
 import { contentHash } from './render-static';
@@ -38,7 +38,7 @@ export function isGlobalStylesheet(file: string): boolean {
  * Sass resolves relative `@use` itself; a bare specifier is Bun's job, because `@ultimat3/ui/tokens`
  * is an `exports` entry and only the module resolver knows where that lands.
  */
-const packageImporter = (from: string): sass.FileImporter<'sync'> => ({
+const packageImporter = (from: string): Sass.FileImporter<'sync'> => ({
   findFileUrl(url: string, context: { readonly containingUrl?: URL | null }): URL | null {
     // Sass routes every load inside a file THIS importer supplied back to this importer, including
     // `_index.scss`'s own relative `@forward`s — so the filesystem lookup has to live here too, or
@@ -185,11 +185,24 @@ export function stripCharset(css: string): string {
   return css.replace(CHARSET_HEAD, '');
 }
+let loadedSass: typeof Sass | undefined;
+/**
+ * Dart Sass, loaded on the first compile and never at import: it is ~290ms of module evaluation,
+ * measured, and every process importing `@ultimat3/render/server` paid it — `x --help`, `x doctor`,
+ * a container role that renders no stylesheet. `require` and not `import()` because this function
+ * is synchronous: Bun's loader-plugin `onLoad` path in `module-loader.ts` calls it inline.
+ */
+const sassCompiler = (): typeof Sass => {
+  loadedSass ??= require('sass') as typeof Sass;
+  return loadedSass;
+};
 export function compileStylesheet(file: string, source: string): CompiledStylesheet {
   let css: string;
   try {
     css = stripCharset(
-      sass.compileString(source, {
+      sassCompiler().compileString(source, {
         url: pathToFileURL(file),
         loadPaths: [dirname(file)],
         importers: [packageImporter(dirname(file))],

package/src/duration.ts CHANGED Viewed

@@ -6,13 +6,14 @@
  * the process while the CDN was told `s-maxage=60`.
  */
-const DURATION_UNITS: Readonly<Record<string, number>> = {
-  ms: 1,
-  s: 1_000,
-  m: 60_000,
-  h: 3_600_000,
-  d: 86_400_000,
-};
+/** A `Map`, never an object literal: a unit is read by a string key, and a `Map` has no prototype chain to answer for it. */
+const DURATION_UNITS: ReadonlyMap<string, number> = new Map([
+  ['ms', 1],
+  ['s', 1_000],
+  ['m', 60_000],
+  ['h', 3_600_000],
+  ['d', 86_400_000],
+]);
 /** `'5m'` → 300000. Numbers pass through as milliseconds. */
 export function parseTtlMs(ttl: string | number | null | undefined): number | null {
@@ -22,6 +23,6 @@ export function parseTtlMs(ttl: string | number | null | undefined): number | nu
   const amount = match?.[1];
   const unit = match?.[2];
   if (amount === undefined || unit === undefined) return null;
-  const factor = DURATION_UNITS[unit];
+  const factor = DURATION_UNITS.get(unit);
   return factor === undefined ? null : Number(amount) * factor;
 }

package/src/index.ts CHANGED Viewed

@@ -67,15 +67,13 @@ export {
   headFromMeta,
   mergeHead,
   renderHead,
-  THEME_SCRIPT_MAX_BYTES,
   THEME_STORAGE_KEY,
   themeScript,
   themeScriptBody,
 } from './head';
-export { headTagKey, seoRenderers, toHeadTag } from './head-seo';
+export { seoRenderers } from './head-seo';
 export type { IslandDirective } from './hydrate';
 export {
-  DEFAULT_REPLAY_EVENTS,
   emitIslandAttributes,
   emitIslandProps,
   HYDRATE_RUNTIME_BODIES,
@@ -84,13 +82,10 @@ export {
   IDLE_HYDRATE_TIMEOUT_MS,
   ISLAND_FAILED_ATTRIBUTE,
   ISLAND_MOUNTED_ATTRIBUTE,
-  requiredStrategies,
 } from './hydrate';
 export type { IslandComponent, IslandDeclaration, IslandNode, IslandSpec } from './island';
 export {
   ISLAND_EXTENSION,
-  ISLAND_NODE,
-  isEmittableSpecifier,
   isIslandNode,
   island,
   islandModuleId,
@@ -98,7 +93,7 @@ export {
 export type { IslandCollector, IslandCollectorInput } from './island-collector';
 export { createIslandCollector, islandModuleIds } from './island-collector';
 export type { IslandProps, JsonValue } from './island-props';
-export { checkIslandProps, ISLAND_PROPS_MAX_BYTES } from './island-props';
+export { ISLAND_PROPS_MAX_BYTES } from './island-props';
 export { parseByteBudget } from './islands';
 export type { JsxComponent, JsxNode, JsxProps } from './jsx';
 export { Fragment, h, isJsxNode, JSX_NODE } from './jsx';
@@ -123,7 +118,6 @@ export {
   describeRoutes,
   ROUTE_FILENAME,
   registerRoute,
-  routeCount,
   routeEntries,
   routeFor,
   routePathFromFile,
@@ -150,7 +144,8 @@ export { DEFAULT_ISLAND_HYDRATE, defineRoute, isRouteConfig, tagKeys } from './r
 export type { RouteComponent } from './route-component';
 export { pageComponentOf } from './route-component';
 export { metaContextFor, routeDataFor } from './route-data';
-export { DEFAULT_ROUTE_STATUS, isErrorStatus, routeStatusOf, withStatus } from './route-status';
+export { routeStatusOf, withStatus } from './route-status';
+export { STREAM_REVEAL_BODIES } from './stream-scripts';
 export type {
   BoundaryRule,
   BoundaryViolation,

package/src/module-loader.ts CHANGED Viewed

@@ -152,6 +152,9 @@ export function transformTsx(source: string): string {
  */
 export function loadStylesheet(path: string, source: string): string {
   const compiled = compileStylesheet(path, source);
+  // An EMPTY compile unregisters: under `x dev` an edit that deleted every rule left the old entry
+  // in place, serving rules the file no longer had until the process restarted.
+  if (compiled.css.length === 0 && stylesheets.delete(path)) revision += 1;
   if (compiled.css.length > 0) {
     if (stylesheets.get(path)?.css !== compiled.css) revision += 1;
     stylesheets.set(path, {

package/src/registry.ts CHANGED Viewed

@@ -211,6 +211,8 @@ export function compilePattern(path: string): CompiledPattern {
 }
 const routes = new Map<string, RouteEntry>();
+/** The table `describeRoutes()` last built, dropped whenever a route registers or the registry clears. */
+let described: readonly RouteDescriptor[] | undefined;
 export interface RegisterRouteInput<TData = RouteData> {
   readonly file: string;
@@ -290,6 +292,7 @@ export function registerRoute<TData = RouteData>(
     ...(input.component === undefined ? {} : { component: input.component }),
   };
   routes.set(path, entry as RouteEntry);
+  described = undefined;
   return entry;
 }
@@ -316,6 +319,7 @@ function withIslandBudget<TData>(config: RouteConfig<TData>, surface: Surface):
 export function clearRoutes(): void {
   routes.clear();
+  described = undefined;
 }
 export function routeCount(): number {
@@ -337,6 +341,14 @@ export function routeFor(path: string): RouteEntry | undefined {
  * Determinism matters because `sw.js` and the sitemap are diffed across deploys.
  */
 export function describeRoutes(): readonly RouteDescriptor[] {
+  // Built once per registry change and handed out as the SAME frozen array: an ISR regeneration
+  // looked its route up through this on every request, re-sorting the whole table each time, and
+  // a stable identity is what lets `render-isr.ts` compile its matchers once per table.
+  described ??= Object.freeze(buildDescriptors());
+  return described;
+}
+function buildDescriptors(): RouteDescriptor[] {
   return routeEntries().map((entry) => ({
     path: entry.path,
     file: entry.file,

package/src/render-isr-store.ts ADDED Viewed

@@ -0,0 +1,93 @@
+/**
+ * The ISR store: what an entry is, the driver seam an app may back with its own storage, and the
+ * bounded in-memory default. Split from `render-isr.ts`, which is the controller that reads it.
+ */
+import { finiteCount } from '@ultimat3/core';
+export type IsrState = 'miss' | 'hit' | 'stale';
+export interface IsrEntry {
+  /**
+   * The store key: the request's pathname AND its query, params sorted. Not the route's pattern
+   * and not the bare pathname — `/blog?page=2` and `/blog?page=3` render different documents, and
+   * keying both as `/blog` served the second visitor the first one's HTML (#171).
+   */
+  readonly path: string;
+  readonly html: string;
+  readonly hash: string;
+  readonly generatedAt: number;
+  readonly ttlMs: number | null;
+  /** Set by a tag invalidation; independent of the TTL clock. */
+  readonly stale: boolean;
+  /**
+   * What the page answers, 200–599. Optional because an entry can come back from an app's own
+   * store, written before this field existed or JSON-round-tripped without it; absent reads as
+   * 200, the only status an entry ever had until `withStatus`.
+   */
+  readonly status?: number;
+}
+export interface IsrStore {
+  get(path: string): IsrEntry | undefined;
+  set(entry: IsrEntry): void;
+  /**
+   * Mark a held page stale IN PLACE — `false` when the store does not hold it. Its own method and
+   * not `set({ ...entry, stale: true })`, because `set` means "this page was just generated" and a
+   * store is entitled to order its eviction by that: the read-modify-write made the STALEST page
+   * the newest, so a tag bust protected exactly the pages that most needed regenerating.
+   */
+  markStale(path: string): boolean;
+  delete(path: string): void;
+  paths(): readonly string[];
+}
+/**
+ * How many rendered pages the default store holds. A route table supports `:params` and `*`, so
+ `/blog/:slug` has as many ISR paths as the blog has slugs — 404-shaped ones that still render
+ * included. Unbounded, a crawler over 100k slugs is 100k HTML strings resident for the life of
+ * the process.
+ */
+export const DEFAULT_ISR_MAX_ENTRIES = 1_000;
+export interface MemoryIsrStoreOptions {
+  /** Pages retained. The least recently generated goes first. */
+  readonly maxEntries?: number;
+}
+export function memoryIsrStore(options: MemoryIsrStoreOptions = {}): IsrStore {
+  // `map.size > NaN` is false for every size, so a cap that arrived non-finite is not a bigger
+  // cap — it is no cap, and this store is the one thing bounding a crawler over 100k slugs.
+  const maxEntries = finiteCount(
+    'memoryIsrStore',
+    'maxEntries',
+    options.maxEntries ?? DEFAULT_ISR_MAX_ENTRIES,
+  );
+  const map = new Map<string, IsrEntry>();
+  return {
+    get: (path) => map.get(path),
+    set: (entry) => {
+      // Re-inserted rather than overwritten, so the Map's iteration order IS generation order and
+      // the first key is the least recently generated page.
+      map.delete(entry.path);
+      map.set(entry.path, entry);
+      while (map.size > maxEntries) {
+        const oldest = map.keys().next();
+        if (oldest.done === true) break;
+        map.delete(oldest.value);
+      }
+    },
+    // In place: `map.set` on a key the Map already holds keeps its position, and that position is
+    // the eviction order. Never `delete` + `set` here — that is the bug this method exists to fix.
+    markStale: (path) => {
+      const entry = map.get(path);
+      if (entry === undefined) return false;
+      map.set(path, { ...entry, stale: true });
+      return true;
+    },
+    delete: (path) => {
+      map.delete(path);
+    },
+    paths: () => [...map.keys()].sort(),
+  };
+}

package/src/render-isr.ts CHANGED Viewed

@@ -15,101 +15,16 @@ import {
   sampleFence,
   unregisterDependent,
 } from '@ultimat3/cache';
-import { finiteCount, logger, renderThrowable } from '@ultimat3/core';
+import { logger, renderThrowable } from '@ultimat3/core';
 import { parseTtlMs } from './duration';
 import { finiteStatus, isRenderStatus } from './finite-status';
 import type { RouteDescriptor } from './registry';
 import { describeRoutes } from './registry';
+import type { IsrEntry, IsrState, IsrStore } from './render-isr-store';
+import { memoryIsrStore } from './render-isr-store';
 import { contentHash, staticHeaders } from './render-static';
 import type { RenderResult } from './route';
-export type IsrState = 'miss' | 'hit' | 'stale';
-export interface IsrEntry {
-  /**
-   * The store key: the request's pathname AND its query, params sorted. Not the route's pattern
-   * and not the bare pathname — `/blog?page=2` and `/blog?page=3` render different documents, and
-   * keying both as `/blog` served the second visitor the first one's HTML (#171).
-   */
-  readonly path: string;
-  readonly html: string;
-  readonly hash: string;
-  readonly generatedAt: number;
-  readonly ttlMs: number | null;
-  /** Set by a tag invalidation; independent of the TTL clock. */
-  readonly stale: boolean;
-  /**
-   * What the page answers, 200–599. Optional because an entry can come back from an app's own
-   * store, written before this field existed or JSON-round-tripped without it; absent reads as
-   * 200, the only status an entry ever had until `withStatus`.
-   */
-  readonly status?: number;
-}
-export interface IsrStore {
-  get(path: string): IsrEntry | undefined;
-  set(entry: IsrEntry): void;
-  /**
-   * Mark a held page stale IN PLACE — `false` when the store does not hold it. Its own method and
-   * not `set({ ...entry, stale: true })`, because `set` means "this page was just generated" and a
-   * store is entitled to order its eviction by that: the read-modify-write made the STALEST page
-   * the newest, so a tag bust protected exactly the pages that most needed regenerating.
-   */
-  markStale(path: string): boolean;
-  delete(path: string): void;
-  paths(): readonly string[];
-}
-/**
- * How many rendered pages the default store holds. A route table supports `:params` and `*`, so
- `/blog/:slug` has as many ISR paths as the blog has slugs — 404-shaped ones that still render
- * included. Unbounded, a crawler over 100k slugs is 100k HTML strings resident for the life of
- * the process.
- */
-export const DEFAULT_ISR_MAX_ENTRIES = 1_000;
-export interface MemoryIsrStoreOptions {
-  /** Pages retained. The least recently generated goes first. */
-  readonly maxEntries?: number;
-}
-export function memoryIsrStore(options: MemoryIsrStoreOptions = {}): IsrStore {
-  // `map.size > NaN` is false for every size, so a cap that arrived non-finite is not a bigger
-  // cap — it is no cap, and this store is the one thing bounding a crawler over 100k slugs.
-  const maxEntries = finiteCount(
-    'memoryIsrStore',
-    'maxEntries',
-    options.maxEntries ?? DEFAULT_ISR_MAX_ENTRIES,
-  );
-  const map = new Map<string, IsrEntry>();
-  return {
-    get: (path) => map.get(path),
-    set: (entry) => {
-      // Re-inserted rather than overwritten, so the Map's iteration order IS generation order and
-      // the first key is the least recently generated page.
-      map.delete(entry.path);
-      map.set(entry.path, entry);
-      while (map.size > maxEntries) {
-        const oldest = map.keys().next();
-        if (oldest.done === true) break;
-        map.delete(oldest.value);
-      }
-    },
-    // In place: `map.set` on a key the Map already holds keeps its position, and that position is
-    // the eviction order. Never `delete` + `set` here — that is the bug this method exists to fix.
-    markStale: (path) => {
-      const entry = map.get(path);
-      if (entry === undefined) return false;
-      map.set(path, { ...entry, stale: true });
-      return true;
-    },
-    delete: (path) => {
-      map.delete(path);
-    },
-    paths: () => [...map.keys()].sort(),
-  };
-}
 /**
  * The reserved query parameter the negotiated locale rides in. A parameter and not a prefix
  * because `routePathOf` splits a key at its `?`: a `es:/blog` key would match no route, so
@@ -231,7 +146,7 @@ export function createIsrController(options: IsrControllerOptions = {}): IsrCont
   function descriptorFor(key: string): RouteDescriptor | undefined {
     const path = routePathOf(key);
     const table = routes();
-    return table.find((r) => r.path === path) ?? table.find((r) => matchesRoute(path, r.path));
+    return table.find((r) => r.path === path) ?? matchersOf(table).find((m) => m.test(path))?.route;
   }
   /**
@@ -413,11 +328,27 @@ function parseWireTag(wire: string): CacheTag {
   return { entity: wire.slice(0, split), id: wire.slice(split + 1) };
 }
+interface RouteMatcher {
+  readonly route: RouteDescriptor;
+  test(storedPath: string): boolean;
+}
+/** One compiled set per route TABLE — `describeRoutes()` hands out one array per registry change. */
+const compiledTables = new WeakMap<readonly RouteDescriptor[], readonly RouteMatcher[]>();
 /** A stored path belongs to a route when the route's pattern matches it. */
-function matchesRoute(storedPath: string, routePath: string): boolean {
-  if (!routePath.includes(':') && !routePath.includes('*')) return storedPath === routePath;
-  const parts = routePath.split('/').map(segmentPattern);
-  return new RegExp(`^${parts.join('/')}/?$`).test(storedPath);
+function matchersOf(table: readonly RouteDescriptor[]): readonly RouteMatcher[] {
+  const cached = compiledTables.get(table);
+  if (cached !== undefined) return cached;
+  const compiled = table.map((route): RouteMatcher => {
+    if (!route.path.includes(':') && !route.path.includes('*')) {
+      return { route, test: (storedPath) => storedPath === route.path };
+    }
+    const pattern = new RegExp(`^${route.path.split('/').map(segmentPattern).join('/')}/?$`);
+    return { route, test: (storedPath) => pattern.test(storedPath) };
+  });
+  compiledTables.set(table, compiled);
+  return compiled;
 }
 function segmentPattern(segment: string): string {

package/src/render-static.ts CHANGED Viewed

@@ -8,12 +8,13 @@ import { renderThrowable, useContext } from '@ultimat3/core';
 import { PrerenderFailedError, RouteModeInvalidError } from './errors';
 import type { RouteEntry } from './registry';
 import type { RenderResult, RouteParams } from './route';
+import { filePathOf, filledSegments, urlPathOf } from './static-path';
 export interface StaticArtifact {
   readonly path: string;
   readonly params: RouteParams;
   readonly html: string;
-  /** FNV-1a of the HTML. Stable across machines and across Bun versions. */
+  /** `contentHash` (xxHash32) of the HTML. Stable across machines and across Bun versions. */
   readonly hash: string;
   /** Where the file lands on disk, relative to the build output root. */
   readonly outputPath: string;
@@ -25,14 +26,15 @@ export type StaticRenderFn = (input: {
   readonly params: RouteParams;
 }) => string | Promise<string>;
-/** Deterministic, dependency-free 32-bit FNV-1a, hex. */
+/**
+ * xxHash32 (seed 0) of the UTF-8 bytes, 8 hex characters. Native: FNV-1a in JS measured 134 µs on a
+ * 96 kB document against 21 µs here, and every static page, ISR regeneration and CSS module hashes
+ * through it. xxHash32 is a SPECIFIED algorithm — the test pins its reference vectors — so the value
+ * is stable across machines and Bun versions, as the FNV one was. Switching was a one-time cache
+ * bust: every ETag and every scoped CSS class name changed once, in 22.0.0.
+ */
 export function contentHash(input: string): string {
-  let hash = 0x811c9dc5;
-  for (let i = 0; i < input.length; i += 1) {
-    hash ^= input.charCodeAt(i);
-    hash = Math.imul(hash, 0x01000193) >>> 0;
-  }
-  return hash.toString(16).padStart(8, '0');
+  return Bun.hash.xxHash32(input).toString(16).padStart(8, '0');
 }
 /**
@@ -115,7 +117,8 @@ export async function renderStatic(
   const artifacts: StaticArtifact[] = [];
   for (const params of paramSets) {
-    const path = fillPath(entry.pattern.source, params);
+    const segments = filledSegments(entry.pattern.source, params);
+    const path = urlPathOf(segments);
     let html: string;
     try {
       html = await render({ path, params });
@@ -131,7 +134,7 @@ export async function renderStatic(
       params,
       html,
       hash,
-      outputPath: `${path === '/' ? '' : path}/${indexFile}`.replace(/^\/+/, ''),
+      outputPath: filePathOf(segments, indexFile),
       headers: staticHeaders(hash, options.buildId),
     });
   }
@@ -152,17 +155,11 @@ export function staticResult(artifact: StaticArtifact): RenderResult {
   return { status: 200, headers: artifact.headers, body: artifact.html };
 }
-/** `/blog/:slug` + `{ slug: 'hello' }` → `/blog/hello`. */
+/**
+ * `/blog/:slug` + `{ slug: 'hello' }` → `/blog/hello`, each segment percent-encoded. A missing
+ * param, a dot segment, a separator inside a `:param`, NUL, `?` and `#` are `X_PRERENDER_FAILED`
+ * (`static-path.ts`) — they wrote a `:slug` directory, or a file outside the build output.
+ */
 export function fillPath(pattern: string, params: RouteParams): string {
-  return (
-    pattern
-      .split('/')
-      .map((segment) => {
-        if (segment.startsWith(':')) return params[segment.slice(1)] ?? segment;
-        if (segment.startsWith('*')) return params[segment.slice(1)] ?? '';
-        return segment;
-      })
-      .join('/')
-      .replace(/\/+$/, '') || '/'
-  );
+  return urlPathOf(filledSegments(pattern, params));
 }

package/src/render-stream.ts CHANGED Viewed

@@ -13,8 +13,9 @@
 import { finiteCount, logger, renderThrowable } from '@ultimat3/core';
 import { finiteStatus } from './finite-status';
-import { escapeAttribute, escapeRawTextContent } from './html';
+import { escapeAttribute } from './html';
 import type { RenderResult } from './route';
+import { REVEAL_BODY, REVEAL_CALL } from './stream-scripts';
 export interface StreamHole {
   /** Stable within a response; becomes the DOM id, so keep it short. */
@@ -60,20 +61,14 @@ export function holeMarker(id: string, fallback: string): string {
  * The entire client half of out-of-order streaming. Inline, uncompressed, ~200 bytes; it
  * moves a late `<template>`'s content into the placeholder that is already on screen.
  */
-export const REVEAL_SCRIPT =
-  "<script>window.$X=function(i){var t=document.querySelector('template[data-x-hole=\"'+i+'\"]')," +
-  's=document.getElementById(i);if(t&&s){s.replaceWith(t.content);t.remove()}}</script>';
+export const REVEAL_SCRIPT = `<script>${REVEAL_BODY}</script>`;
 export function revealChunk(id: string, html: string): string {
-  const key = holeId(id);
-  // Two contexts, two encoders — the attribute takes `escapeAttribute`, and the script argument is
-  // built by `JSON.stringify` so the id is a JS string LITERAL rather than text pasted between two
-  // quotes: `a");alert(1);//` closed the call and ran on the page's own origin. `</script` inside
-  // it would still end the element, so the raw-text rule applies over the top, as `html.ts` says.
-  const argument = escapeRawTextContent(JSON.stringify(key));
+  // The id reaches markup ONLY through `escapeAttribute` — never a script — so a quote in it
+  // cannot close anything, and no per-hole body exists for a CSP to fail to list.
   return (
-    `<template data-x-hole="${escapeAttribute(key)}">${html}</template>` +
-    `<script>$X(${argument})</script>`
+    `<template data-x-hole="${escapeAttribute(holeId(id))}">${html}</template>` +
+    `<script>${REVEAL_CALL}</script>`
   );
 }
@@ -186,7 +181,7 @@ export function renderStreamHtml(
           timeoutMs === null
             ? undefined
             : setTimeout(() => {
-                logger.warn(`stream hole ${hole.id} missed its ${timeoutMs}ms deadline`);
+                logger.warn('render.stream.hole_deadline', { hole: hole.id, timeoutMs });
                 reveal(errorFallback(hole.id));
               }, timeoutMs);
         // A response nobody is reading must not hold the process open until its deadline.
@@ -200,7 +195,12 @@ export function renderStreamHtml(
             // `renderThrowable`, never `.message`/`String()`: the value is whatever the hole threw,
             // and a read that raises here skips the `reveal` below — the hole never fills and the
             // response is held to its deadline for a failure that was already handled.
-            logger.warn(`stream hole ${hole.id} rejected: ${renderThrowable(error)}`);
+            // A FIELD, never the message: `logger` redacts fields and never `msg`, so a hole's
+            // failure text interpolated into the message reached the log past every redactor.
+            logger.warn('render.stream.hole_rejected', {
+              hole: hole.id,
+              error: renderThrowable(error),
+            });
             reveal(errorFallback(hole.id));
           },
         );

package/src/server.ts CHANGED Viewed

@@ -40,22 +40,18 @@ export { ROOT_ELEMENT_ID, renderComponent, renderToHtml } from './render-html';
 export type {
   IsrController,
   IsrControllerOptions,
-  IsrEntry,
   IsrRendered,
   IsrRenderFn,
   IsrServeResult,
-  IsrState,
-  IsrStore,
-  MemoryIsrStoreOptions,
 } from './render-isr';
 export {
   createIsrController,
-  DEFAULT_ISR_MAX_ENTRIES,
   ISR_LOCALE_PARAM,
   invalidateAndRevalidate,
   isrKey,
-  memoryIsrStore,
 } from './render-isr';
+export type { IsrEntry, IsrState, IsrStore, MemoryIsrStoreOptions } from './render-isr-store';
+export { DEFAULT_ISR_MAX_ENTRIES, memoryIsrStore } from './render-isr-store';
 export type { SsrOptions, SsrRenderFn, SsrRenderInput } from './render-ssr';
 export { renderSsr, ssrHeaders } from './render-ssr';
 export type { StaticArtifact, StaticBuildOptions, StaticRenderFn } from './render-static';

package/src/static-path.ts ADDED Viewed

@@ -0,0 +1,77 @@
+// Single responsibility: a route pattern plus `prerender()` params, as the segments a static build
+// writes. `prerender()` returns APP data, and each value becomes a directory on disk: a raw `..`
+// wrote outside the build output, and a missing param wrote a directory literally named `:slug`.
+import { renderCauseValue } from '@ultimat3/core';
+import { PrerenderFailedError } from './errors';
+import type { RouteParams } from './route';
+/** Anything a single path segment may not carry: separators, `?` and `#` (controls: `hasControl`). */
+const UNSAFE = /[/\\?#]/;
+/** NUL and every C0 control, plus DEL — by code point, so no control character sits in a regex. */
+const hasControl = (text: string): boolean => {
+  for (const char of text) {
+    const code = char.codePointAt(0) ?? 0;
+    if (code < 0x20 || code === 0x7f) return true;
+  }
+  return false;
+};
+const refuse = (pattern: string, param: string, value: unknown, why: string): never => {
+  throw new PrerenderFailedError(
+    `prerender() gave ${pattern} the ${param} ${renderCauseValue(value)}, which ${why}`,
+    `return a value for every param of ${pattern} from prerender(), each one plain path text — slugify it (lowercase, [a-z0-9-]) where it comes from a title or a user`,
+  );
+};
+const checked = (pattern: string, param: string, segment: string): string => {
+  if (segment === '.' || segment === '..') {
+    return refuse(pattern, param, segment, 'is a dot segment — it would write outside its route');
+  }
+  if (UNSAFE.test(segment) || hasControl(segment)) {
+    return refuse(pattern, param, segment, 'carries a separator, a control character, ? or #');
+  }
+  return segment;
+};
+/**
+ * The raw (decoded) segments, validated. `:name` must be present and one segment; `*name` may span
+ * several (`a/b`) and may be absent, but none of its parts may be a dot segment or unsafe.
+ */
+export function filledSegments(pattern: string, params: RouteParams): readonly string[] {
+  const out: string[] = [];
+  for (const segment of pattern.split('/')) {
+    if (segment === '') continue;
+    if (segment.startsWith(':')) {
+      const name = segment.slice(1);
+      const value = Object.hasOwn(params, name) ? params[name] : undefined;
+      if (value === undefined || value === '') {
+        return refuse(
+          pattern,
+          name,
+          value,
+          'is missing — the file would be named after the pattern',
+        );
+      }
+      out.push(checked(pattern, name, value));
+      continue;
+    }
+    if (segment.startsWith('*')) {
+      const name = segment.slice(1);
+      const value = Object.hasOwn(params, name) ? (params[name] ?? '') : '';
+      for (const part of value.split('/')) if (part !== '') out.push(checked(pattern, name, part));
+      continue;
+    }
+    out.push(segment);
+  }
+  return out;
+}
+/** The URL form: each segment percent-encoded, as a browser's `pathname` spells it. */
+export const urlPathOf = (segments: readonly string[]): string =>
+  segments.length === 0 ? '/' : `/${segments.map(encodeURIComponent).join('/')}`;
+/** The file form: the DECODED segments, which is what a static server maps a URL back onto. */
+export const filePathOf = (segments: readonly string[], indexFile: string): string =>
+  [...segments, indexFile].join('/');

package/src/stream-scripts.ts ADDED Viewed

@@ -0,0 +1,18 @@
+// Single responsibility: the inline script bodies out-of-order streaming emits, as constants. Its own
+// module so a CSP builder can import the list without importing the stream renderer and its logger.
+export const REVEAL_BODY =
+  "window.$X=function(){document.querySelectorAll('template[data-x-hole]').forEach(function(t){" +
+  "var s=document.getElementById(t.getAttribute('data-x-hole'));if(s){s.replaceWith(t.content);t.remove()}})}";
+/** The one call every reveal makes. Constant, so a hash-based CSP can admit it. */
+export const REVEAL_CALL = '$X()';
+/**
+ * Every inline script body a streamed document can carry — two, whatever the holes. A production
+ * policy admits inline script by HASH (a `render: 'stream'` response gets no nonce), and the reveal
+ * used to be one `$X("<id>")` per hole: a body per id that no policy could list, so every reveal
+ * was blocked. The id now rides only in the escaped `data-x-hole` attribute, and `$X()` reveals
+ * every template that has arrived.
+ */
+export const STREAM_REVEAL_BODIES: readonly string[] = Object.freeze([REVEAL_BODY, REVEAL_CALL]);

package/src/surfaces.ts CHANGED Viewed

@@ -47,7 +47,10 @@ export const SURFACE_SPECS = Object.freeze<Record<Surface, SurfaceSpec>>({
     defaultMode: null,
     allowedModes: [],
     jsBaselineBytes: 0,
-    mayImport: ['shared'],
+    // `app` too, measured the day this table became the rule: both tracked apps' `api/index.ts`
+    // and `api/tasks.ts` import the app slices' actions and jobs to register them. Both surfaces
+    // are server-only, so no browser bundle pays for the edge; `site` stays out.
+    mayImport: ['shared', 'app'],
     mayImportTypes: ['shared'],
   },
   shared: {
@@ -118,7 +121,11 @@ export function importGraph(
   return graph;
 }
-export type BoundaryRule = 'site-imports-app' | 'shared-is-a-leaf' | 'app-imports-api-at-runtime';
+export type BoundaryRule =
+  | 'site-imports-app'
+  | 'shared-is-a-leaf'
+  | 'app-imports-api-at-runtime'
+  | 'surface-imports-surface';
 export interface BoundaryViolation {
   readonly rule: BoundaryRule;
@@ -210,50 +217,57 @@ interface ClassifyInput {
   readonly chain: readonly string[];
 }
+/**
+ * One edge against `SURFACE_SPECS` — the table IS the rule. `mayImport` and `mayImportTypes` were
+ * read by nothing, so an `api → site`, `site → api` or `app → site` value import classified as no
+ * violation at all. The three pairs that had rules of their own keep them (and their codes); every
+ * other crossing the table does not allow is `surface-imports-surface`.
+ */
 function classify(i: ClassifyInput): BoundaryViolation | null {
   const chainText = i.chain.join(' → ');
+  const base = { entry: i.entry, importer: i.importer, imported: i.imported, chain: i.chain };
+  // Transitive, from the ENTRY: a site page reaching app/ through any number of hops.
   if (i.entrySurface === 'site' && i.importedSurface === 'app' && !i.typeOnly) {
     return {
+      ...base,
       rule: 'site-imports-app',
-      entry: i.entry,
-      importer: i.importer,
-      imported: i.imported,
-      chain: i.chain,
       cause: chainText,
       fix: `x fix boundary ${i.entry}   (or move ${i.imported} out of the shared graph)`,
     };
   }
-  if (
-    i.importerSurface === 'shared' &&
-    (i.importedSurface === 'app' || i.importedSurface === 'site') &&
-    !i.typeOnly
-  ) {
+  const from = i.importerSurface;
+  const to = i.importedSurface;
+  if (from === null || to === null || from === to) return null;
+  const spec = SURFACE_SPECS[from];
+  if (spec.mayImport.includes(to)) return null;
+  if (i.typeOnly && spec.mayImportTypes.includes(to)) return null;
+  // Reported above, from the site entry that reaches it — one crossing, one finding.
+  if (from === 'site' && to === 'app' && !i.typeOnly) return null;
+  if (from === 'shared' && !i.typeOnly) {
     return {
+      ...base,
       rule: 'shared-is-a-leaf',
-      entry: i.entry,
-      importer: i.importer,
-      imported: i.imported,
-      chain: i.chain,
       cause: `${chainText}  (shared/ is a leaf — it may not import a surface)`,
       fix: `move the shared part of ${i.imported} into shared/ and import it from ${i.importer}`,
     };
   }
-  if (i.importerSurface === 'app' && i.importedSurface === 'api' && !i.typeOnly) {
+  if (from === 'app' && to === 'api' && !i.typeOnly) {
     return {
+      ...base,
       rule: 'app-imports-api-at-runtime',
-      entry: i.entry,
-      importer: i.importer,
-      imported: i.imported,
-      chain: i.chain,
       cause: `${chainText}  (app/ → api/ is types-only)`,
       fix: `change to \`import type\` in ${i.importer} and call the typed client instead`,
     };
   }
-  return null;
+  const field = i.typeOnly ? 'mayImportTypes' : 'mayImport';
+  return {
+    ...base,
+    rule: 'surface-imports-surface',
+    cause: `${chainText}  (${from}/ may not import ${to}/${i.typeOnly ? ', even as a type' : ''}: SURFACE_SPECS.${from}.${field} is [${spec[field].join(', ')}])`,
+    fix: `move what ${i.importer} needs from ${i.imported} into shared/ and import it from there`,
+  };
 }
 /** Build-time gate. `x verify` and the dev server both call this. */