@ultimat3/render 2.0.0 → 4.0.0

package/CLAUDE.md

@@ -33,6 +33,9 @@ Tier 4. May import tiers 0–3: `core`, `schema`, `i18n`, `money`, `time`, `cach
 | 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/` → `4kb`, `app/` → `18kb` (`DEFAULT_ISLAND_JS_BYTES` above `jsBaselineBytes`). 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 `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-weighs a declared island. |
 | 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. |
+| 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. |
+| 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. |
 | Island bytes | `routeJsBytes` unions `entry.islands` with the rendered directives' `moduleId`s. Reading either alone is a budget that counts the runtime and not the chunk. |
 | 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)`. |
@@ -44,18 +47,22 @@ Tier 4. May import tiers 0–3: `core`, `schema`, `i18n`, `money`, `time`, `cach
 | 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. |
 | 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. |
 | 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. `decodeURIComponent('%zz')` is a bare `URIError` — a 500 for a typo — and `@ultimat3/http`'s router already answers "this branch does not match" for the same input. A literal route matching the same text still wins. |
+| An undecodable path segment | not a match, never a throw, on BOTH sides — `decodeSegment` in `registry.ts` is the one reader, imported by `router-client.ts`. The client half interpolated `decodeURIComponent` raw until 2026-08, and `resolve()` runs from the signal initialiser, from `navigate`, from a `<Link>` prefetch's `mouseenter` and from the popstate handler: `/blog/%zz` failed the SPA at BOOT where the server answers 404. `decodeURIComponent('%zz')` is a bare `URIError` — a 500 for a typo — and `@ultimat3/http`'s router already answers "this branch does not match" for the same input. A literal route matching the same text still wins. |
 | 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. 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. |
 | 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 fresh-and-gated, `spa` is a gated shell. |
 | Responses | return `RenderResult`. `@ultimat3/http` builds the `Response`. |
 | Solid | no `solid-js` import anywhere in this package — `type-pins.tsx` satisfies its `JSX.Element` structurally, through `jsxImportSource`, and never names it. Inject primitives. The JSX factory in `jsx.ts` builds inert nodes — it is not a Solid renderer and must never become one. |
 | The loaders | `module-loader.ts` installs them at `index.ts` module scope, once. 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. |
 | `<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. A second escaper is how one of them ends up missing a character, and a missing character in an attribute is an injection. `head.ts` and `hydrate.ts` each had a private copy; both now import. |
+| 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), `render-spa.ts` (`lang`, `dir`, `buildId`, `rootId`, every chunk url) and `head.ts`'s `themeScript` (`storageKey`/`attribute` as JS string LITERALS). All author-controlled today — the identical status `emitIslandAttributes` had before the last sweep. `lang` is safe on the framework's own path (`currentLocale()` normalises against the configured `supported` list) and is escaped anyway, because `renderSpaShell` is a public export and a caller supplies it directly. A second escaper is how one of them ends up missing a character, and a missing character in an attribute is an injection. `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` and served **inlined** per surface. `sass` is this package's only third-party dependency and its only reason to exist here. |

package/README.md

@@ -101,7 +101,7 @@ a hydrating `site/` route below.
 | Mode | Invariant | Error if violated |
 |---|---|---|
 | `static` | no per-request state — no `policy`, no `revalidate` | `X_ROUTE_MODE_INVALID` |
-| `isr` | needs a trigger: `revalidate.tags` or `revalidate.ttl` | `X_ROUTE_MODE_INVALID` |
+| `isr` | needs a trigger: `revalidate.tags` or `revalidate.ttl`; **no `policy`** — one cached document per URL cannot answer two actors | `X_ROUTE_MODE_INVALID` |
 | `ssr` | cannot be prerendered | `X_ROUTE_MODE_INVALID` |
 | `stream` | at least one `<Suspense>` boundary | `X_ROUTE_MODE_INVALID` |
 | `spa` | requires a `policy` (authed dashboards only) | `X_ROUTE_MODE_INVALID` |

package/package.json

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

package/src/css-modules.ts

@@ -7,6 +7,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 { PrerenderFailedError } from './errors';
 import { contentHash } from './render-static';
@@ -124,7 +125,10 @@ export function compileStylesheet(file: string, source: string): CompiledStylesh
       style: 'compressed',
     }).css;
   } catch (error) {
-    const first = error instanceof Error ? error.message.split('\n')[0] : String(error);
+    // `renderThrowable`, never `.message`/`String()`: an importer, a plugin or a future Sass
+    // release can throw a value whose own read raises, and this frame is what turns a failed
+    // compile into `X_PRERENDER_FAILED` naming the file — a laundered read leaves it a bare one.
+    const first = renderThrowable(error).split('\n')[0];
     throw new PrerenderFailedError(
       `${file} did not compile: ${first}`,
       `edit ${file}: ${TOKEN_FIX}`,

package/src/duration.ts

@@ -0,0 +1,27 @@
+/**
+ * The one reader of a TTL string. It sits below both `modes.ts` (which asks "is this a TTL at
+ * all?" when it refuses an `isr` route with no regeneration trigger) and `render-isr.ts` (which
+ * asks "how many ms?"), because a second answer is what let `revalidate: { ttl: '5 minutes' }`
+ * pass registration and then parse to `null` — a page generated once and served for the life of
+ * 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,
+};
+
+/** `'5m'` → 300000. Numbers pass through as milliseconds. */
+export function parseTtlMs(ttl: string | number | null | undefined): number | null {
+  if (ttl === null || ttl === undefined) return null;
+  if (typeof ttl === 'number') return Number.isFinite(ttl) && ttl > 0 ? ttl : null;
+  const match = /^(\d+(?:\.\d+)?)(ms|s|m|h|d)$/.exec(ttl.trim());
+  const amount = match?.[1];
+  const unit = match?.[2];
+  if (amount === undefined || unit === undefined) return null;
+  const factor = DURATION_UNITS[unit];
+  return factor === undefined ? null : Number(amount) * factor;
+}

package/src/head.ts

@@ -134,10 +134,20 @@ function contentOf(tag: HeadTag, raw: string): string {
   return carriesJson(tag) ? escapeJsonContent(raw) : escapeRawTextContent(raw);
 }
 
-/** `application/ld+json`, `application/json`, any `…+json`: the body is data, not code. */
+/**
+ * `application/ld+json`, `application/json`, any `…+json`: the body is data, not code.
+ *
+ * The MIME parameter is cut before the suffix test, because a real document writes
+ * `type="application/ld+json; charset=utf-8"` and that does not end in `json` — so the block built
+ * from route data, which is the path attacker text takes, silently took the raw-text escaper
+ * instead of the total one. `</` is escaped either way, so this was a weakened boundary rather than
+ * a break-out; the JSON rule is total on purpose, and a `charset` is not a reason to leave it.
+ */
 function carriesJson(tag: HeadTag): boolean {
-  const type = tag.attrs?.['type'];
-  return typeof type === 'string' && type.trim().toLowerCase().endsWith('json');
+  const declared = tag.attrs?.['type'];
+  if (typeof declared !== 'string') return false;
+  const [type = ''] = declared.split(';');
+  return type.trim().toLowerCase().endsWith('json');
 }
 
 export interface ThemeScriptOptions {
@@ -158,10 +168,14 @@ export const THEME_SCRIPT_MAX_BYTES = 512;
 export function themeScript(options: ThemeScriptOptions = {}): HeadTag {
   const attribute = options.attribute ?? 'data-theme';
   const storageKey = options.storageKey ?? 'x-theme';
+  // `JSON.stringify`, never a value pasted between two quotes: both options land INSIDE a JS
+  // string in a `<script>` body, where one `"` ends the string and the rest is code the page runs.
+  // Author-supplied today — the same status every `emitIslandAttributes` value had before it was
+  // routed through `html.ts`. The element's own raw-text rule is applied by `renderTag` below.
   const source =
-    `try{var t=localStorage.getItem("${storageKey}")||` +
+    `try{var t=localStorage.getItem(${JSON.stringify(storageKey)})||` +
     `(matchMedia("(prefers-color-scheme: dark)").matches?"dark":"light");` +
-    `document.documentElement.setAttribute("${attribute}",t)}catch(e){}`;
+    `document.documentElement.setAttribute(${JSON.stringify(attribute)},t)}catch(e){}`;
 
   const bytes = new TextEncoder().encode(source).byteLength;
   const cap = options.maxBytes ?? THEME_SCRIPT_MAX_BYTES;

package/src/html.ts

@@ -72,11 +72,15 @@ export function escapeJsonContent(json: string): string {
  * JSX prop name → attribute name. Solid authors write the HTML spelling (`class`, `for`), but the
  * React spellings compile too, and an author who writes one and gets no attribute has a bug with
  * no error message.
+ *
+ * A `Map` like the two sets above, 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 the URL
+ * check below called `.toLowerCase()` on it — a bare TypeError, no code, no fix, and the page 500s.
  */
-const ATTRIBUTE_ALIASES: Readonly<Record<string, string>> = {
-  className: 'class',
-  htmlFor: 'for',
-};
+const ATTRIBUTE_ALIASES: ReadonlyMap<string, string> = new Map([
+  ['className', 'class'],
+  ['htmlFor', 'for'],
+]);
 
 /** Props the tree consumes rather than emits. `innerHTML` is emitted as content, not an attribute. */
 const NON_ATTRIBUTES: ReadonlySet<string> = new Set([
@@ -87,6 +91,30 @@ const NON_ATTRIBUTES: ReadonlySet<string> = new Set([
   'textContent',
 ]);
 
+/**
+ * Attributes a browser FOLLOWS, beyond the four `@ultimat3/core` names for the anchor case. Kept
+ * here rather than in `safe-url.ts` only because that file is another package's; the scheme check
+ * is one rule and every attribute a scheme can execute from belongs under it. `data` is
+ * `<object data>`, `poster` is `<video poster>`, `xlink:href` executes on click inside inline SVG,
+ * and `ping` is a URL the browser POSTs to on activation.
+ */
+const URL_BEARING_ATTRIBUTES: ReadonlySet<string> = new Set([
+  ...URL_ATTRIBUTES,
+  'data',
+  'ping',
+  'poster',
+  'xlink:href',
+]);
+
+/**
+ * Attributes that carry MARKUP, not text or a URL, and are therefore never emitted. `srcdoc` is
+ * entity-DECODED and then parsed as HTML, so `escapeAttribute`'s `&lt;script&gt;` becomes a live
+ * `<script>` inside the iframe — on this origin, with this session's cookie. Escaping cannot make
+ * it inert, so the attribute is refused instead, the same way `innerHTML` above stays the one
+ * explicit escape hatch rather than a prop anyone can spread in from a row.
+ */
+const REFUSED_ATTRIBUTES: ReadonlySet<string> = new Set(['srcdoc']);
+
 const cssProperty = (name: string): string =>
   name.startsWith('--') ? name : name.replace(/[A-Z]/g, (letter) => `-${letter.toLowerCase()}`);
 
@@ -111,7 +139,8 @@ export function attributePair(name: string, value: unknown): string | null {
   if (typeof value === 'function') return null;
   if (name.startsWith('on') && name.length > 2) return null;
 
-  const attribute = ATTRIBUTE_ALIASES[name] ?? name;
+  const attribute = ATTRIBUTE_ALIASES.get(name) ?? name;
+  if (REFUSED_ATTRIBUTES.has(attribute.toLowerCase())) return null;
   if (value === true) return attribute;
   if (attribute === 'style') {
     const style = styleValue(value);
@@ -123,7 +152,7 @@ export function attributePair(name: string, value: unknown): string | null {
   // module is the single place injection is prevented and an href off a database row is the shape
   // every app writes. A refused URL emits no attribute at all — an anchor with no `href` is inert
   // and still renders its text, where a blanked one is a live link nobody checked.
-  if (URL_ATTRIBUTES.includes(attribute.toLowerCase())) {
+  if (URL_BEARING_ATTRIBUTES.has(attribute.toLowerCase())) {
     const url = safeUrl(text, attribute.toLowerCase());
     if (url === null) return null;
     return `${attribute}="${escapeAttribute(url)}"`;

package/src/hydrate.ts

@@ -5,7 +5,7 @@
  * answered instead of swallowed.
  */
 
-import { escapeJsonContent } from './html';
+import { escapeAttribute, escapeJsonContent } from './html';
 import type { HydrateStrategy } from './route';
 
 export interface IslandDirective {
@@ -34,14 +34,22 @@ export const DEFAULT_REPLAY_EVENTS = ['click', 'input', 'change', 'submit', 'key
  * runtime below is never emitted for that island.
  */
 export function emitIslandAttributes(directive: IslandDirective): string {
-  const attrs = [`data-x-island="${directive.islandId}"`, `data-x-hydrate="${directive.strategy}"`];
+  // `html.ts`'s escaper, not raw interpolation: a `"` in any of these values closes the attribute
+  // and the rest of the string is markup. Author-controlled today — which is why it costs nothing
+  // to route through the ONE escaper now, rather than after a build id or a prop-derived margin
+  // starts carrying something the author did not type.
+  const attr = (name: string, value: string): string => `${name}="${escapeAttribute(value)}"`;
+  const attrs = [
+    attr('data-x-island', directive.islandId),
+    attr('data-x-hydrate', directive.strategy),
+  ];
   if (directive.strategy !== 'never') {
-    attrs.push(`data-x-entry="${directive.entry}"`);
+    attrs.push(attr('data-x-entry', directive.entry));
     if (directive.rootMargin !== undefined) {
-      attrs.push(`data-x-margin="${directive.rootMargin}"`);
+      attrs.push(attr('data-x-margin', directive.rootMargin));
     }
     if (directive.events !== undefined && directive.events.length > 0) {
-      attrs.push(`data-x-events="${directive.events.join(' ')}"`);
+      attrs.push(attr('data-x-events', directive.events.join(' ')));
     }
   }
   return attrs.join(' ');

package/src/index.ts

@@ -11,6 +11,7 @@ installRenderLoader();
 
 export type { CompiledStylesheet } from './css-modules';
 export { compileStylesheet, isCssModule, isGlobalStylesheet, scopeClasses } from './css-modules';
+export { parseTtlMs } from './duration';
 export type { RenderErrorCode } from './errors';
 export {
   BudgetExceededError,
@@ -134,8 +135,8 @@ export {
   createIsrController,
   DEFAULT_ISR_MAX_ENTRIES,
   invalidateAndRevalidate,
+  isrKey,
   memoryIsrStore,
-  parseTtlMs,
 } from './render-isr';
 export type { SpaShell, SpaShellInput } from './render-spa';
 export { renderSpa, renderSpaShell, SPA_ROOT_ID } from './render-spa';

package/src/island-props.ts

@@ -68,7 +68,7 @@ function assertJsonSafe(value: unknown, path: string, seen: Set<object>, file: s
     guardCycle(value, path, seen, file);
     const out: Record<string, JsonValue> = {};
     for (const [key, item] of Object.entries(value)) {
-      out[key] = assertJsonSafe(item, `${path}.${key}`, seen, file);
+      put(out, key, assertJsonSafe(item, `${path}.${key}`, seen, file));
     }
     seen.delete(value);
     return out;
@@ -82,6 +82,18 @@ function assertJsonSafe(value: unknown, path: string, seen: Set<object>, file: s
   );
 }
 
+/**
+ * One walked value onto the bag. `out[key] = value` is not an assignment for exactly one name:
+ * `__proto__` runs `Object.prototype`'s setter and REPLACES the prototype instead of adding a key,
+ * so the prop never reaches the browser — the exact footgun the walk above exists to prevent — and
+ * the record the server keeps reading answers whatever the request body chose. `JSON.parse` mints a
+ * real own `__proto__` key, so a row off the wire is enough. Same shape as `validate-args.ts`'s
+ * `put` in `@ultimat3/mcp`; `defineProperty` writes a plain own data property whatever the name is.
+ */
+function put(out: Record<string, JsonValue>, key: string, value: JsonValue): void {
+  Object.defineProperty(out, key, { value, writable: true, enumerable: true, configurable: true });
+}
+
 function isPlainObject(value: unknown): value is Record<string, unknown> {
   if (typeof value !== 'object' || value === null) return false;
   const proto: unknown = Object.getPrototypeOf(value);
@@ -127,7 +139,7 @@ export function checkIslandProps(
   const bag: Record<string, JsonValue> = {};
   const seen = new Set<object>();
   for (const key of passed) {
-    bag[key] = assertJsonSafe(props[key], `props.${key}`, seen, file);
+    put(bag, key, assertJsonSafe(props[key], `props.${key}`, seen, file));
   }
 
   const bytes = new TextEncoder().encode(JSON.stringify(bag)).byteLength;

package/src/modes.ts

@@ -5,6 +5,7 @@
  * invariant is only documented is a mode that silently degrades in production.
  */
 
+import { parseTtlMs } from './duration';
 import { RouteModeInvalidError } from './errors';
 import type { HydrateStrategy, RenderMode, RouteConfig } from './route';
 import { HYDRATE_STRATEGIES } from './route';
@@ -89,8 +90,12 @@ export const MODE_SPECS: Readonly<Record<RenderMode, ModeSpec>> = Object.freeze(
 
 /** Mode-local checks that need nothing but the config. Called by `defineRoute`. */
 export function assertModeShape(config: RouteShape): void {
-  // Widened on purpose: JS callers reach `defineRoute` with unvalidated strings.
-  const spec: ModeSpec | undefined = MODE_SPECS[config.render];
+  // Widened on purpose: JS callers reach `defineRoute` with unvalidated strings — and an object
+  // lookup walks the prototype chain, so `render: 'constructor'` used to find a `ModeSpec` that
+  // does not exist and hand back a frozen descriptor for a mode nothing implements.
+  const spec: ModeSpec | undefined = Object.hasOwn(MODE_SPECS, config.render)
+    ? MODE_SPECS[config.render]
+    : undefined;
   if (spec === undefined) {
     throw new RouteModeInvalidError(
       `render: ${JSON.stringify(config.render)} is not a render mode`,
@@ -121,6 +126,19 @@ export function assertModeShape(config: RouteShape): void {
     );
   }
 
+  // isr: a CACHED document, so it may not be gated. The symmetry with `static` above is the
+  // point — an ISR route resolves `load` with the request's own `Ctx`, renders that actor's
+  // document, and the cache stores it under the pathname alone. Every later actor who passes the
+  // same policy is then served the first actor's HTML. Keying the cache on more is a trap, not a
+  // fix: the key would have to enumerate everything a policy and a `load` can read.
+  if (config.render === 'isr' && config.policy !== undefined) {
+    throw new RouteModeInvalidError(
+      "render: 'isr' caches one document per URL and cannot be gated, but a `policy` was " +
+        `declared (${config.policy.permission} varies the answer per actor)`,
+      "change render to 'ssr' (fresh, gated) or 'spa' (gated shell), or drop the policy",
+    );
+  }
+
   // isr: needs a trigger, otherwise it is `static` wearing a costume.
   if (config.render === 'isr' && !hasRevalidateTrigger(config)) {
     throw new RouteModeInvalidError(
@@ -150,7 +168,10 @@ function hasRevalidateTrigger(config: RouteShape): boolean {
   const revalidate = config.revalidate;
   if (revalidate === undefined) return false;
   const hasTags = revalidate.tags !== undefined && revalidate.tags.length > 0;
-  const hasTtl = revalidate.ttl !== undefined && revalidate.ttl !== '';
+  // `parseTtlMs`, never "a non-empty string": the ISR clock is the one that has to read this value,
+  // and `ttl: '5 minutes'` passed here and parsed to `null` there — a page generated once and
+  // served for the life of the process, which is the exact costume this check refuses below.
+  const hasTtl = parseTtlMs(revalidate.ttl) !== null;
   return hasTags || hasTtl;
 }
 

package/src/module-loader.ts

@@ -4,6 +4,7 @@
  * `bun test` all load a component the same way and there is no separate "bundled" behaviour.
  */
 
+import { renderThrowable } from '@ultimat3/core';
 import { compileStylesheet, isGlobalStylesheet } from './css-modules';
 import { PrerenderFailedError } from './errors';
 import type { Surface } from './surfaces';
@@ -134,7 +135,10 @@ export function installRenderLoader(): void {
         } catch (error) {
           if (error instanceof PrerenderFailedError) throw error;
           throw new PrerenderFailedError(
-            `${path} could not be loaded: ${error instanceof Error ? error.message : String(error)}`,
+            // `renderThrowable` from core, never `.message`/`String()`: this catch is the loader's
+            // last frame, and a value that fights being read would replace the coded failure with
+            // a bare throw out of a Bun plugin — where no route and no file name survives.
+            `${path} could not be loaded: ${renderThrowable(error)}`,
             `open ${path} and fix the stylesheet it @use-s`,
           );
         }

package/src/registry.ts

@@ -369,8 +369,12 @@ export function matchRoute(pathname: string): RouteMatch | null {
  * `undefined` for a malformed percent-escape. A pathname is whatever the client typed, and
  * `decodeURIComponent('%zz')` throws a bare `URIError` — no code, no fix line — which escaped
  * `matchRoute` as a 500 and an error-monitor page for somebody's typo.
+ *
+ * Exported for `router-client.ts`, which answers the same question about the same pathname on the
+ * other side of the wire: two decoders is how the client throws out of a popstate listener for an
+ * address the server 404s.
  */
-function decodeSegment(value: string): string | undefined {
+export function decodeSegment(value: string): string | undefined {
   try {
     return decodeURIComponent(value);
   } catch {

package/src/render-html.ts

@@ -4,6 +4,7 @@
  * component — `static` at build time, `ssr`/`stream` per request, all through `renderToHtml`.
  */
 
+import { renderThrowable } from '@ultimat3/core';
 import {
   IslandInvalidError,
   IslandNotHydratedError,
@@ -30,9 +31,6 @@ export interface RenderHtmlOptions {
   readonly islands?: IslandCollector;
 }
 
-const describe = (error: unknown): string =>
-  error instanceof Error ? error.message : String(error);
-
 /**
  * A thunk is called, not stringified. Solid's reactive reads are accessors (`count()`), and a
  * `children` prop is routinely a function — evaluating it once is exactly the server's job.
@@ -142,7 +140,10 @@ export async function renderComponent(
     if (error instanceof IslandPropsInvalidError) throw error;
     if (error instanceof IslandNotHydratedError) throw error;
     throw new PrerenderFailedError(
-      `rendering the component in ${file} threw: ${describe(error)}`,
+      // `renderThrowable`, never `.message`/`String()`: a component is app code and may throw a
+      // null-prototype object (`String()` raises) or an Error whose `message` getter does — and
+      // this frame is the last thing between that and a build failure with no code at all.
+      `rendering the component in ${file} threw: ${renderThrowable(error)}`,
       `run \`bun test ${file.replace(/\.tsx?$/, '.test.ts')}\` to reproduce, then fix ${file}`,
     );
   }

package/src/render-isr.ts

@@ -13,7 +13,8 @@ import {
   registerRevalidator,
   unregisterDependent,
 } from '@ultimat3/cache';
-import { logger } from '@ultimat3/core';
+import { logger, renderThrowable } from '@ultimat3/core';
+import { parseTtlMs } from './duration';
 import type { RouteDescriptor } from './registry';
 import { describeRoutes } from './registry';
 import { contentHash, staticHeaders } from './render-static';
@@ -22,6 +23,11 @@ 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;
@@ -74,24 +80,35 @@ export function memoryIsrStore(options: MemoryIsrStoreOptions = {}): IsrStore {
   };
 }
 
-const DURATION_UNITS: Readonly<Record<string, number>> = {
-  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 {
-  if (ttl === null || ttl === undefined) return null;
-  if (typeof ttl === 'number') return Number.isFinite(ttl) && ttl > 0 ? ttl : null;
-  const match = /^(\d+(?:\.\d+)?)(ms|s|m|h|d)$/.exec(ttl.trim());
-  const amount = match?.[1];
-  const unit = match?.[2];
-  if (amount === undefined || unit === undefined) return null;
-  const factor = DURATION_UNITS[unit];
-  return factor === undefined ? null : Number(amount) * factor;
+/**
+ * The ISR store key for one request URL: pathname plus the query, **params sorted**.
+ *
+ * Exported because deriving it is the caller's job and there may only be ONE derivation — a
+ * server that keyed on `url.pathname` while the store believed it held a whole URL is the shape
+ * of #171. Sorting makes `?a=1&b=2` and `?b=2&a=1` one entry rather than two renders of one page.
+ *
+ * A query-carrying URL therefore gets its own entry, which is correct and is not free: a crawler
+ * appending `?utm_source=…` mints one entry per value. That is bounded, not unbounded —
+ * `DEFAULT_ISR_MAX_ENTRIES` evicts least-recently-generated first — and a bounded cache that
+ * thrashes is the right failure next to an unbounded one that answers the wrong document.
+ */
+export function isrKey(url: URL): string {
+  if (url.search === '') return url.pathname;
+  const params = new URLSearchParams(url.search);
+  params.sort();
+  return `${url.pathname}?${params.toString()}`;
+}
+
+/**
+ * The route pattern a key belongs to. Every lookup that asks the ROUTE TABLE a question — the
+ * descriptor, and therefore the TTL — has to strip the query first: `descriptorFor('/blog?page=2')`
+ * matches no route, so the entry would silently fall back to `ttlMs: null` and a declared
+ * `revalidate: { ttl: '5m' }` would become tag-only. Keying without this split is a half-fix that
+ * trades a leak for a wrong TTL.
+ */
+function routePathOf(key: string): string {
+  const query = key.indexOf('?');
+  return query === -1 ? key : key.slice(0, query);
 }
 
 export type IsrRenderFn = (path: string) => string | Promise<string>;
@@ -150,7 +167,8 @@ export function createIsrController(options: IsrControllerOptions = {}): IsrCont
   const pending = new Map<string, Promise<IsrEntry>>();
   const registered = new Set<string>();
 
-  function descriptorFor(path: string): RouteDescriptor | undefined {
+  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));
   }
@@ -248,10 +266,10 @@ export function createIsrController(options: IsrControllerOptions = {}): IsrCont
       // stale-while-revalidate: answer from the stale copy now, refresh behind the request.
       const already = pending.has(path);
       void regenerate(path, render).catch((error: unknown) => {
-        logger.warn('isr.regenerate.failed', {
-          path,
-          error: error instanceof Error ? error.message : String(error),
-        });
+        // `renderThrowable`, never `.message`/`String()`: this `.catch` is the last frame under a
+        // route's own render function, and `String()` raises on a null-prototype object — the
+        // handler that exists to REPORT the failure became a second, unhandled rejection.
+        logger.warn('isr.regenerate.failed', { path, error: renderThrowable(error) });
       });
       return {
         state: 'stale',

package/src/render-spa.ts

@@ -6,6 +6,7 @@
  */
 
 import { RouteModeInvalidError } from './errors';
+import { escapeAttribute } from './html';
 import type { RouteEntry } from './registry';
 import { contentHash } from './render-static';
 import type { RenderResult } from './route';
@@ -37,18 +38,22 @@ export function renderSpaShell(input: SpaShellInput): SpaShell {
     );
   }
 
-  const rootId = input.rootId ?? SPA_ROOT_ID;
+  // Every attribute value through `html.ts`'s ONE escaper — the package's own escaping rule, and
+  // the same repair `emitIslandAttributes` took. `head` is the exception by construction: it is
+  // already-merged markup from `head.ts`, which escaped it on the way in.
+  const rootId = escapeAttribute(input.rootId ?? SPA_ROOT_ID);
   const preloads = input.chunks
-    .map((chunk) => `<link rel="modulepreload" href="${chunk}">`)
+    .map((chunk) => `<link rel="modulepreload" href="${escapeAttribute(chunk)}">`)
     .join('');
   const scripts = input.chunks
-    .map((chunk) => `<script type="module" src="${chunk}"></script>`)
+    .map((chunk) => `<script type="module" src="${escapeAttribute(chunk)}"></script>`)
     .join('');
 
   const html =
-    `<!doctype html><html lang="${input.lang}" dir="${input.dir ?? 'ltr'}">` +
+    `<!doctype html><html lang="${escapeAttribute(input.lang)}" ` +
+    `dir="${escapeAttribute(input.dir ?? 'ltr')}">` +
     `<head>${input.head}${preloads}` +
-    `<meta name="x-ultimate-build" content="${input.buildId}">` +
+    `<meta name="x-ultimate-build" content="${escapeAttribute(input.buildId)}">` +
     `</head><body><div id="${rootId}"></div>${scripts}</body></html>`;
 
   return { html, hash: contentHash(html) };

package/src/render-static.ts

@@ -4,7 +4,7 @@
  * the precache revision in `sw.js`, and the asset filename suffix.
  */
 
-import { useContext } from '@ultimat3/core';
+import { renderThrowable, useContext } from '@ultimat3/core';
 import { PrerenderFailedError, RouteModeInvalidError } from './errors';
 import type { RouteEntry } from './registry';
 import type { RenderResult, RouteParams } from './route';
@@ -69,7 +69,9 @@ export async function enumeratePrerender(entry: RouteEntry): Promise<readonly Ro
     produced = await prerender();
   } catch (error) {
     throw new PrerenderFailedError(
-      `prerender() for ${entry.path} threw: ${describe(error)}`,
+      // `renderThrowable`, never `.message`/`String()`: `prerender` is app code and may throw a
+      // value whose read raises in turn — this frame is what makes the build failure a coded one.
+      `prerender() for ${entry.path} threw: ${renderThrowable(error)}`,
       `fix prerender in ${entry.file} — it runs at build time with no request context`,
     );
   }
@@ -119,8 +121,8 @@ export async function renderStatic(
       html = await render({ path, params });
     } catch (error) {
       throw new PrerenderFailedError(
-        `rendering ${path} failed: ${describe(error)}`,
-        `run \`x build --route ${path}\` to reproduce, then fix ${entry.file}`,
+        `rendering ${path} failed: ${renderThrowable(error)}`,
+        `x build --target static --json   # reproduces ${path}, then fix ${entry.file}`,
       );
     }
     const hash = contentHash(html);
@@ -164,7 +166,3 @@ export function fillPath(pattern: string, params: RouteParams): string {
       .replace(/\/+$/, '') || '/'
   );
 }
-
-function describe(error: unknown): string {
-  return error instanceof Error ? error.message : String(error);
-}

package/src/render-stream.ts

@@ -11,7 +11,8 @@
  * contains no interactive island costs literally zero JS.
  */
 
-import { logger } from '@ultimat3/core';
+import { logger, renderThrowable } from '@ultimat3/core';
+import { escapeAttribute, escapeRawTextContent } from './html';
 import type { RenderResult } from './route';
 
 export interface StreamHole {
@@ -42,9 +43,16 @@ export function holeId(id: string): string {
   return `${HOLE_PREFIX}${id}`;
 }
 
-/** The placeholder that sits in the first flush, holding the fallback markup. */
+/**
+ * The placeholder that sits in the first flush, holding the fallback markup.
+ *
+ * `html.ts`'s escaper, not raw interpolation, for the reason `emitIslandAttributes` states: a `"`
+ * in the id closes the attribute and the rest is markup. Author-controlled today — which is why it
+ * costs nothing to route through the ONE escaper now, rather than after an id starts being derived
+ * from a param. `fallback` is already-rendered HTML and stays verbatim.
+ */
 export function holeMarker(id: string, fallback: string): string {
-  return `<x-hole id="${holeId(id)}">${fallback}</x-hole>`;
+  return `<x-hole id="${escapeAttribute(holeId(id))}">${fallback}</x-hole>`;
 }
 
 /**
@@ -57,7 +65,15 @@ export const REVEAL_SCRIPT =
 
 export function revealChunk(id: string, html: string): string {
   const key = holeId(id);
-  return `<template data-x-hole="${key}">${html}</template><script>$X("${key}")</script>`;
+  // 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));
+  return (
+    `<template data-x-hole="${escapeAttribute(key)}">${html}</template>` +
+    `<script>$X(${argument})</script>`
+  );
 }
 
 /**
@@ -166,9 +182,10 @@ export function renderStreamHtml(
             reveal(html);
           },
           (error: unknown) => {
-            logger.warn(
-              `stream hole ${hole.id} rejected: ${error instanceof Error ? error.message : String(error)}`,
-            );
+            // `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)}`);
             reveal(errorFallback(hole.id));
           },
         );

package/src/route-data.ts

@@ -5,7 +5,7 @@
  * the body does not contain.
  */
 
-import { isUltimateError } from '@ultimat3/core';
+import { isUltimateError, renderThrowable } from '@ultimat3/core';
 import { useI18n } from '@ultimat3/i18n';
 import { RouteLoadFailedError } from './errors';
 import type { RouteConfig, RouteContext, RouteData, RouteMetaContext } from './route';
@@ -26,6 +26,11 @@ export async function routeDataFor<TData = RouteData>(
   // `RouteContext` satisfies `TData` on this line. One narrowing assertion backed by a build
   // error, in place of the `as unknown as` that used to hand back any shape a caller named.
   if (config.load === undefined) return ctx as RouteContext & TData;
+  // Read BEFORE the try, and never inside the catch: `new URL('/posts/7')` is a bare `TypeError`,
+  // and `ctx.url` is relative on every path that builds one by hand — a prerender pass, `x build`,
+  // a test harness. Computing it in the catch replaced `X_ROUTE_LOAD_FAILED` with that TypeError
+  // on the ONE path whose job is to produce a coded error.
+  const path = pathnameOf(ctx.url);
   try {
     return await config.load(ctx);
   } catch (cause) {
@@ -35,14 +40,29 @@ export async function routeDataFor<TData = RouteData>(
     // `code` property: an ENOENT off `Bun.file` carries `code: 'ENOENT'`, and the duck-type let
     // every one of them out of here unwrapped — no fix line, and no mention of the route to fix.
     if (isUltimateError(cause)) throw cause;
-    const detail = cause instanceof Error ? cause.message : String(cause);
+    // `renderThrowable`, not `.message`/`String()`: `load` is app code and may throw a value
+    // whose `message` getter or `toString` throws in turn — this frame is the last thing between
+    // that and a page with no error at all.
+    const detail = renderThrowable(cause);
     throw new RouteLoadFailedError(
-      `load() threw while rendering ${new URL(ctx.url).pathname}: ${detail}`,
-      `fix the load function for ${new URL(ctx.url).pathname}, or return a fallback so the page can render`,
+      `load() threw while rendering ${path}: ${detail}`,
+      `fix the load function for ${path}, or return a fallback so the page can render`,
     );
   }
 }
 
+/**
+ * The pathname of a route URL, absolute or relative, and never a throw: this value only ever
+ * appears in an error message, so a reader that raises would cost the caller the whole error.
+ */
+function pathnameOf(url: string): string {
+  try {
+    return new URL(url).pathname;
+  } catch {
+    return url.split(/[?#]/)[0] ?? url;
+  }
+}
+
 /**
  * The argument `meta` is called with. Built here rather than at each call site so `x dev` and the
  * build's prerenderer cannot disagree about what `meta` receives — two builders is a `<title>`

package/src/router-client.ts

@@ -7,7 +7,7 @@
  */
 
 import type { CompiledPattern } from './registry';
-import { compilePattern } from './registry';
+import { compilePattern, decodeSegment } from './registry';
 import type { RouteParams } from './route';
 
 export interface RouterRoute {
@@ -108,10 +108,21 @@ export function createRouter(options: RouterOptions): Router {
       const match = candidate.pattern.regex.exec(rawPath);
       if (match === null) continue;
       const params: Record<string, string> = {};
+      let undecodable = false;
       candidate.pattern.keys.forEach((key, index) => {
         const value = match[index + 1];
-        if (value !== undefined) params[key] = decodeURIComponent(value);
+        if (value === undefined) return;
+        // `decodeSegment`, the server router's own reader: `decodeURIComponent('%zz')` is a bare
+        // `URIError`, and `resolve` is called from the signal initialiser, from `navigate`, from a
+        // `mouseenter` prefetch and from the popstate handler — so a typo in the address bar took
+        // the whole SPA down at boot instead of failing this one branch.
+        const decoded = decodeSegment(value);
+        if (decoded === undefined) undecodable = true;
+        else params[key] = decoded;
       });
+      // Fails only the branch that would have decoded it, exactly as `matchRoute` answers: a
+      // literal route matching the same text still wins, and an unclaimed pathname is a non-match.
+      if (undecodable) continue;
       return {
         route: candidate.route,
         params,