@ultimat3/render 19.1.2 → 19.2.0

package/CLAUDE.md

@@ -50,7 +50,7 @@ for the mirror-image reason, keeping `render → pwa` refused. Never `cli` (upwa
 | 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. |
+| 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. |
@@ -97,7 +97,7 @@ for the mirror-image reason, keeping `render → pwa` refused. Never `cli` (upwa
 | 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` and served **inlined** per surface. `sass` is this package's only third-party dependency and its only reason to exist here. |
+| 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. |
 | Colours | tokens and `data-theme` only. No hex in `head.ts` or any emitted script. |

package/README.md

@@ -270,13 +270,85 @@ else is `X_ISLAND_INVALID`, and the fix is the `git mv`.
 |---|---|
 | every prop is declared in `props: [...]` | `X_ISLAND_PROPS_INVALID`, naming each undeclared key |
 | every value is JSON — no function, `Date`, class instance, `bigint`, `undefined`, cycle | `X_ISLAND_PROPS_INVALID`, naming the path and the type |
-| serialized props ≤ `ISLAND_PROPS_MAX_BYTES` (4096) | `X_ISLAND_PROPS_INVALID`, naming the measured size |
+| serialized props ≤ `ISLAND_PROPS_MAX_BYTES` (16,384 B) | `X_ISLAND_PROPS_INVALID`, naming the heaviest props with their bytes |
 
 `<ContactModal {...post} />` fails and names `email`, `passwordHash` — every column the spread
 would have shipped. The type refuses it first (`type-pins.tsx` pins that); the render refuses it
 second, which for `static` and `isr` is build time. `children` are the server-rendered shell and
 are never serialized.
 
+`X_ISLAND_PROPS_INVALID` is a **declared 500** in `@ultimat3/http`'s status table `As of 2026-09-05`.
+It is the author's fault and never the caller's, so 500 is the class — but until it had a row it
+was an *unclassified* 500, and `problem+json` blanks the cause of one of those outside dev. A
+34-row catalog over the cap took a page down with a document that said "the details are in this
+process's logs" about an error whose whole value is the sentence naming the prop and its bytes.
+
+### Large data rides over a query endpoint, after mount
+
+The props bag is inlined **verbatim** in the document, as `<script type="application/json">`, on
+every request — and `x verify`'s `budgets` step counts a JSON-typed script as data, not JS, so
+`budget.js` never sees a byte of it. `ISLAND_PROPS_MAX_BYTES` is the only ceiling on that channel.
+It is **16 KiB** `As of 2026-09-05` (it was 4 KiB, and a 34-model catalog at 8,812 B was a 500): a bag
+comparable in size to the island's own code (`DEFAULT_ISLAND_JS_BYTES` derives 20 KiB for `site/`,
+34 KiB for `app/`), ~3-4 KiB gzipped, under 100 ms on a 3G-class link. The constant's own comment
+carries the arithmetic.
+
+A list that is the same on every request is not a prop — it is a **dataset**, and under the cap
+or over it the page is the wrong place for it: it renders into every document, is cached with
+none of them, and is parsed before first paint. The props are what the island needs to draw its
+first frame — an id, a count, and the URL of the read that answers the rest:
+
+```ts
+// page.tsx — the props are the id and the endpoint, never the rows
+import { derivePath } from '@ultimat3/query';
+import { island } from '@ultimat3/render';
+
+const Dispatch = island({
+  src: './dispatch.island.tsx',
+  props: ['hostId', 'models', 'modelsEndpoint'],
+});
+
+export const DispatchFor = (host: { readonly id: string }) =>
+  Dispatch({ hostId: host.id, models: [], modelsEndpoint: `${derivePath('modelList')}?limit=100` });
+```
+
+```tsx
+// dispatch.island.tsx — one GET after mount, cached by the browser like any read
+import { createSignal } from 'solid-js';
+import { render } from 'solid-js/web';
+
+type Model = { readonly id: string; readonly label: string };
+type DispatchProps = {
+  readonly hostId: string;
+  readonly models: readonly Model[];
+  readonly modelsEndpoint?: string;
+};
+const Picker = (props: { readonly models: readonly Model[] }) => <ul>{props.models.length}</ul>;
+
+export function mount(el: HTMLElement, props: DispatchProps): void {
+  const [models, setModels] = createSignal<readonly Model[]>(props.models);
+  if (props.modelsEndpoint !== undefined) {
+    fetch(props.modelsEndpoint, { credentials: 'same-origin' })
+      .then((response) => response.json())
+      .then((rows: readonly Model[]) => setModels(rows));
+  }
+  render(() => <Picker models={models()} />, el);
+}
+```
+
+`models: []` keeps the island's first frame honest (an empty picker, not a missing one) and
+`derivePath` is the same derivation the typed `client()` uses, so the URL cannot drift from the
+route. The `fix:` line of an over-cap `X_ISLAND_PROPS_INVALID` names exactly this edit, with the
+heaviest prop's own name in it.
+
+At **verify** time the overflow is a finding, not a runtime surprise: an `app/` page with an
+island derives a budget, the `budgets` step's build renders every budgeted route to weigh it, and
+a render that throws `X_ISLAND_PROPS_INVALID` is reported under that code — the island, the prop,
+its bytes — rather than as an `X_BUDGET_UNMEASURED` whose fix is to go and read the build's list.
+A prop that only exists per request (the row behind `[id]`) is still measured at the route's
+pattern with empty params, so a static over-cap prop is caught, and a per-request one is caught
+by the request that carries it.
+
 ### It counts against the route's budget
 
 ```ts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/render",
-  "version": "19.1.2",
+  "version": "19.2.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": "19.1.2",
-    "@ultimat3/core": "19.1.2",
-    "@ultimat3/i18n": "19.1.2",
-    "@ultimat3/seo": "19.1.2",
+    "@ultimat3/cache": "19.2.0",
+    "@ultimat3/core": "19.2.0",
+    "@ultimat3/i18n": "19.2.0",
+    "@ultimat3/seo": "19.2.0",
     "sass": "1.102.0"
   }
 }

package/src/island-props.ts

@@ -20,8 +20,30 @@ export type IslandProps = Readonly<Record<string, JsonValue>>;
 /**
  * Props ship inside the HTML of every response, so they are page weight the `budget` never sees
  * as JS. A cap turns "I passed the whole row" into a number and a fix instead of a slow page.
+ *
+ * What the cap protects. `hydrateRuntime` inlines the bag VERBATIM as
+ * `<script type="application/json" data-x-props>` in the document, and `measureDocumentJs` counts
+ * a JSON-typed script as data — zero JS — so `budget.js` never sees a byte of it. This constant is
+ * the only ceiling on that channel. Every byte of it is parsed before first paint, on every
+ * request, on every page that renders the island, and cannot be cached apart from the page.
+ *
+ * Why 16 KiB and not 4. It was 4096 until 2026-09-05, and a page carrying a 34-row catalog
+ * (8,812 B) answered 500 at RUNTIME — a legitimate medium-sized bag, a page down. What 16 KiB
+ * costs, measured against the budgets the route table derives (`DEFAULT_ISLAND_JS_BYTES`:
+ * `site/` 20 KiB, `app/` 34 KiB of JS): the ceiling is a bag comparable in size to the island's
+ * OWN code, and never more than it. On the wire, JSON with repeated keys gzips 4-6x, so a full
+ * bag is ~3-4 KiB compressed — under 100 ms on a 3G-class link (~50 KB/s), ~1 ms of `JSON.parse`
+ * on a phone. Uncompressed (a dev server, a proxy that skips `text/html`) it is ~320 ms on that
+ * link, which is why the ceiling stays a ceiling and not a warning.
+ *
+ * Why a catalog is still the wrong thing to inline, even under the cap. A list that is the same
+ * on every request is a DATASET, not a prop: behind a query route it is one `GET`, cached by the
+ * browser and by the CDN, fetched once per session instead of rendered into every page. The prop
+ * is the id, the initial count, the endpoint — what the island needs to draw its first frame.
+ * `README.md` ("large data rides over a query endpoint") is the pattern, and the `fix:` below
+ * names it.
  */
-export const ISLAND_PROPS_MAX_BYTES = 4096;
+export const ISLAND_PROPS_MAX_BYTES = 16_384;
 
 /** JSX keys that are markup, not data: they stay on the server and never serialize. */
 const SERVER_ONLY_KEYS = new Set(['children']);
@@ -142,15 +164,39 @@ export function checkIslandProps(
     put(bag, key, assertJsonSafe(props[key], `props.${key}`, seen, file));
   }
 
-  const bytes = new TextEncoder().encode(JSON.stringify(bag)).byteLength;
+  const bytes = utf8Bytes(JSON.stringify(bag));
   if (bytes > ISLAND_PROPS_MAX_BYTES) {
+    const heaviest = propBytes(bag).slice(0, HEAVIEST_NAMED);
+    const first = heaviest[0]?.[0] ?? 'rows';
     throw new IslandPropsInvalidError(
-      `the ${moduleId} island in ${file} carries ${bytes} bytes of props (cap ` +
-        `${ISLAND_PROPS_MAX_BYTES}), and every one of them ships inside the HTML on every request`,
-      `pass an id in ${file} and fetch the rest inside the island, or raise the cap deliberately ` +
-        'by splitting the island',
+      `the ${moduleId} island in ${file} carries ${bytes} B of props (cap ${ISLAND_PROPS_MAX_BYTES} B), ` +
+        'and every one of them ships inside the HTML on every request — ' +
+        heaviest.map(([key, size]) => `props.${key} is ${size} B of the ${bytes}`).join(', '),
+      `in ${file}, pass ${heaviest.map(([key]) => `\`${key}: []\``).join(' and ')} beside ` +
+        `\`${first}Endpoint: derivePath('<queryName>')\` (@ultimat3/query) and fetch the rows inside ` +
+        'the island after mount — a list that is the same on every request is a dataset, not a ' +
+        'prop; an id, a count and a URL are',
     );
   }
 
   return bag;
 }
+
+const utf8Bytes = (text: string): number => new TextEncoder().encode(text).byteLength;
+
+/**
+ * Which keys carry the weight, heaviest first — so the finding names the prop to move, not the
+ * bag. A page with `models` at 8,812 B beside `hostId` at 12 B gets one instruction, and the
+ * instruction names `models`. Per-key bytes are the value's serialisation plus its `"key":`.
+ */
+function propBytes(bag: Record<string, JsonValue>): readonly (readonly [string, number])[] {
+  return Object.entries(bag)
+    .map(([key, value]): readonly [string, number] => [
+      key,
+      utf8Bytes(JSON.stringify(key)) + 1 + utf8Bytes(JSON.stringify(value)),
+    ])
+    .sort((a, b) => b[1] - a[1]);
+}
+
+/** At most two: one prop is the usual answer, two names a split, and a third is the whole bag. */
+const HEAVIEST_NAMED = 2;

package/src/module-loader.ts

@@ -80,12 +80,30 @@ export interface Stylesheet {
 
 const stylesheets = new Map<string, Stylesheet>();
 
+/**
+ * Bumped whenever the registry's CONTENT changes — a sheet arriving, a sheet's rules changing, the
+ * whole map being cleared. It exists so a caller can cache something derived from `stylesFor` (the
+ * CLI content-addresses the surface stylesheet and serves it as a file) without re-deriving it per
+ * request, and without a cache that goes stale the moment `x dev` rebuilds an island: island CSS
+ * registers through this same `loadStylesheet`, on every `Bun.build`.
+ *
+ * A re-registration with IDENTICAL css does not bump it. `buildIslands` re-runs its plugins on
+ * every watcher tick, so counting registrations rather than changes would mint a new stylesheet
+ * URL on every save of an unrelated file — the immutable-cache miss this counter exists to avoid.
+ */
+let revision = 0;
+
+export function stylesheetsRevision(): number {
+  return revision;
+}
+
 export function registeredStylesheets(): readonly Stylesheet[] {
   return [...stylesheets.values()];
 }
 
 /** Test seam: the registry is process-global because the module cache it mirrors is too. */
 export function clearStylesheets(): void {
+  if (stylesheets.size > 0) revision += 1;
   stylesheets.clear();
 }
 
@@ -133,6 +151,7 @@ export function transformTsx(source: string): string {
 export function loadStylesheet(path: string, source: string): string {
   const compiled = compileStylesheet(path, source);
   if (compiled.css.length > 0) {
+    if (stylesheets.get(path)?.css !== compiled.css) revision += 1;
     stylesheets.set(path, {
       file: path,
       surface: surfaceOf(path),

package/src/server.ts

@@ -25,6 +25,7 @@ export {
   loadStylesheet,
   registeredStylesheets,
   stylesFor,
+  stylesheetsRevision,
   transformTsx,
 } from './module-loader';
 // ---- the render pipeline: one entry point per mode ----------------------------------------------