npm - @ultimat3/render - Versions diffs - 1.2.0 → 2.0.0 - Mend

@ultimat3/render 1.2.0 → 2.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 (25) hide show

package/CLAUDE.md ADDED Viewed

@@ -0,0 +1,74 @@
+# @ultimat3/render — boundary
+Owns: the `route` primitive, the five render modes, the route table, the surface boundary,
+islands + budgets, hydration directives, the vendored client router, `<head>` merge, **the server
+JSX runtime and the two Bun loaders that make an app's `.tsx` and `.scss` runnable**.
+`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`.
+Tier 4. May import tiers 0–3: `core`, `schema`, `i18n`, `money`, `time`, `cache`, `seo`,
+`entity`, `policy`, `http`, `action`, `query`. **Never** `pwa`, `mcp`, `ai`, `manifest`
+(sideways), never `ui`/`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`. |
+| 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. |
+| 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. |
+| 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. |
+| 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/` → `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. |
+| 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)`. |
+| 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. |
+| Route truth | `registry.ts`. Never keep a second route list anywhere. |
+| 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. |
+| 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. |
+| 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. |
+| 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`. |
+| 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. |
+| 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. |
+| 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 5, upward), 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. |
+| `<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. |
+Cross-package: `@ultimat3/pwa` consumes route descriptors as **data**, never by import.
+Keep `RouteDescriptor` additive — removing a field breaks `sw.js` generation.
+```
+bun test                          # from packages/render
+bun run typecheck
+bun run --cwd ../.. verify        # the contract
+```

package/README.md CHANGED Viewed

@@ -18,17 +18,54 @@ export const config = defineRoute({
   offline:    'precache',             // precache | runtime | network-only
   hydrate:    'visible',              // idle | visible | interaction | never
   budget:     { js: '40kb', lcp: 2000 },
-  meta:       ({ post }) => ({ title: post.title, description: post.excerpt,
-                               og: { image: post.cover }, ld: ld.Article(post) }),
+  load:       ({ params }) => db.posts.bySlug(params.slug),   // once per render
+  meta:       ({ data, url }) => ({ title: data.title, description: data.excerpt,
+                                    og: { image: data.cover }, alternates: { canonical: url },
+                                    ld: ld.Article(data) }),
 });
+export function Page(props: { data: Post }) { /* the SAME object meta was given */ }
+```
+## `load` is the one server-side data seam
+Optional, and the only way a page gets data. It runs **once per render** and the result is handed
+to both `meta` and the page component — the same object, never two resolutions, because a `<title>`
+describing content the body does not contain is the failure this seam exists to prevent.
+`meta` receives a context, not the bare data: `{ data, params, url, t }`. All four are needed for a
+real `<head>` — the data for the content, `url` for the canonical, `t` because no user-facing
+string may be hardcoded. A route that declares no `load` still gets `params` and `url` under the
+same names it always had, so nothing that shipped has to change.
+`As of 2026-07`, omitting `load` means the context IS the data: `meta` may read only what the
+context supplies, and anything richer is a compile error naming the missing `load`.
+```text
+defineRoute({ /* … */ meta: ({ data }) => ({ title: data.post.title }) });
+// Property 'load' is missing in type … but required in type '{ readonly load: RouteLoadFn<…> }'
 ```
-## `offline`, `hydrate` and `meta` are required by the type
+A `text` fence, not a `ts` one, because it is the one example in this file that must **not**
+compile — that is the whole claim. Without the rule the route compiled and rendered `undefined`
+in a `<title>`.
+A loader that throws is `X_ROUTE_LOAD_FAILED`, naming the path to fix — unless it threw an
+`UltimateError` of its own, which passes through untouched: a policy denial or a missing row
+already carries a better code and a better fix than any wrapper could. Membership is the framework's
+brand, not a `code` property: an `ENOENT` is an `Error` with a string `code` too, and it gets
+wrapped like any other loader failure.
+## `offline` and `meta` are required by the type
 Not by a lint rule, not by a doc — by `RouteDefinition`. Axiom 3 lives in the type system:
 a route that forgets its offline strategy or its `<head>` does not compile. `defineRoute`
-re-checks the same three at runtime (`X_ROUTE_OFFLINE_MISSING`, `X_ROUTE_META_MISSING`) for
-JS callers and generators.
+re-checks both at runtime (`X_ROUTE_OFFLINE_MISSING`, `X_ROUTE_META_MISSING`) for JS callers
+and generators.
+`hydrate` was the third, and is not, `As of 2026-08`. It is the one key the framework can work
+out from the page's own declarations — see the island section — and requiring a value it already
+knows is not enforcement, it is a second place to get one thing wrong.
 ## `defineRoute` returns a descriptor, not the object you passed
@@ -36,12 +73,22 @@ Two fields come back narrower than they went in, so nothing downstream branches
 | Field | The declaration accepts | The descriptor always is |
 |---|---|---|
-| `meta` | `(data) => RouteMeta \| Promise<RouteMeta>` | `(data) => Promise<RouteMeta>` |
+| `meta` | `(ctx: RouteMetaContext) => RouteMeta \| Promise<RouteMeta>` | `(ctx) => Promise<RouteMeta>` |
 | `budget` | omitted, or a `RouteBudget` | a `RouteBudget` — `{}` when undeclared |
+| `hydrate` | omitted, or a `HydrateStrategy` | a `HydrateStrategy` — derived from the islands |
+| `islands` | never written | the `IslandSpec`s this module declared, in order |
+`meta` takes the **context**, never the bare data — the same `{ data, params, url, t }` the
+declaration receives, all four required:
 ```ts
-const meta = await config.meta({ post });   // always. sync or async declaration, one call
-const js = config.budget.js ?? null;        // never config.budget?.js
+import type { RouteConfig, RouteMetaContext } from '@ultimat3/render';
+declare const config: RouteConfig<Post>;
+declare const ctx: RouteMetaContext<Post>;   // { data, params, url, t }
+const meta = await config.meta(ctx);   // always. sync or async declaration, one call
+const js = config.budget.js ?? null;   // never config.budget?.js
 ```
 No author is forced to write `async`, and a `meta` that throws synchronously comes back as
@@ -111,11 +158,127 @@ The import that costs you is three hops from the file anyone reviewed, so
 at build time and therefore never carry the boundary. `shared/` is a leaf; `app/ → api/` is
 types-only.
+## One interactive component on a static page
+`island()` — a marketing page with a contact modal, a docs page with a search box, a pricing page
+with a plan toggle. The page stays `render: 'static'`; the modal is the only JavaScript on it.
+```tsx
+const ContactModal = island({ src: './contact-modal.island.tsx', props: ['subject'] });
+export const config = defineRoute({
+  render: 'static', offline: 'precache',
+  meta: ({ t }) => ({ title: t('pricing.title'), description: t('pricing.description') }),
+});
+export function Page() {
+  return <main><h1>Pricing</h1>
+    <ContactModal subject="pricing"><button>Contact us</button></ContactModal>
+  </main>;
+}
+```
+### Declaring the island is the whole declaration
+That route says `render` and `meta` and nothing else, and it is the same route that used to spell
+out three things. `hydrate` and `budget.js` are **derived from `island()`**, `As of 2026-08`:
+| Omitted | Derived | Overridden by |
+|---|---|---|
+| `hydrate` | `'interaction'` when the module declared an island, `'never'` when it did not | stating `hydrate` — the only way to say `idle` or `visible` |
+| `budget.js` | the surface baseline + 4kb (`site/` → `4kb`, `app/` → `18kb`) | stating `budget: { js }` |
+Both were required and both were punished: an island on a route still at `'never'` is
+`X_ISLAND_NOT_HYDRATED`, and a `site/` route off `'never'` with no `budget.js` is refused at
+registration. Two failures for one omission the `island()` call above had already answered.
+4kb because the reference app's real island is 875 B of chunk plus a 1,019 B runtime — room for a
+second small island, not enough to hide a library. It is a ceiling, not a pass: exceeding it is
+`X_BUDGET_EXCEEDED`, naming the island.
+`island()` goes **above** `defineRoute`, where JavaScript already puts a `const` the page uses:
+`defineRoute` drains the declarations made before it. Below it, the route resolves to `'never'` and
+the render fails loudly with `X_ISLAND_NOT_HYDRATED`, whose fix names both repairs.
+An island still declares no strategy of its own. One spelling for "this route hydrates" — the
+route's — because two islands wanting different timings would leave `RouteDescriptor.hydrate`, which
+`sw.js`, the web manifest and `x routes` all read, with no single true answer.
+| The route says | The island says |
+|---|---|
+| `hydrate` — WHEN it wakes, once, for the whole route, and only when the default is wrong | `src` — WHICH module, and `props` — what it may receive |
+| `budget.js` — how many bytes that is allowed to cost, when 4kb is not the number | `tag`, `events`, `rootMargin` — how the wrapper behaves |
+### An island node is a JSX child
+`island()` returns a component, and `<ContactModal />` is an ordinary element call. That took work:
+an app types its JSX with `jsxImportSource: solid-js`, whose `JSX.Element` is a type **alias** —
+unaugmentable — and whose only object-shaped member is `ArrayElement`. `IslandNode` is therefore a
+branded (empty) array, which is what makes it assignable. Until `As of 2026-08` it was a plain
+object and every `<ContactModal />` in an app was **TS2786**, so the feature was reachable only
+through `h(ContactModal, …)` — which is exactly what the framework's own tests used, and why
+nobody saw it. `type-pins.tsx` holds the claim now: it writes the JSX an author writes, and `tsc`
+reads it.
+### Declared by specifier, never by import
+`src` is a string. The page never imports the client module, so:
+- **there is no import edge** for the bundler or `checkSurfaceBoundary()` to follow from
+  `page.tsx` into the island — the static page's graph cannot grow the island's dependencies;
+- **the component cannot close over anything.** A string does not capture a database handle,
+  a request, an actor or a row. There is no scope to leak.
+`.island.tsx` is the one spelling, for the reason `page.tsx` is: a file ships to the browser if
+and only if its name says so, decidable by `grep` and by the bundler without opening it. Anything
+else is `X_ISLAND_INVALID`, and the fix is the `git mv`.
+### Props are the only channel, and they are checked
+| Rule | Failure |
+|---|---|
+| 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 |
+`<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.
+### It counts against the route's budget
+```ts
+const collector = createIslandCollector({ file, hydrate: config.hydrate, resolve });
+const html = await renderToHtml(page, { islands: collector });
+document.body += hydrateRuntime(collector.directives);   // the one thing left to remember
+assertBudget(entry, measuredIslands, collector.directives);
+```
+`routeJsBytes` reads **both** sources — what registration declared in `entry.islands` and what the
+render actually pulled in. Reading only the first is how a page could be charged for the hydration
+runtime and not for the chunk it boots: a budget that counts the wrapper and not the code.
+`entry.islands` is filled from `config.islands` at registration and from nothing else, so a declared
+island is weighed even on a route no render has touched. It was `input.islands ?? []` and nothing
+ever passed `islands`, which left that half of the union reading nothing at all; `RegisterRouteInput`
+no longer carries the key, because the only thing a caller could do with it was un-weigh a
+declaration.
+An island on a route that resolves to `hydrate: 'never'`, or rendered with no collector, is
+`X_ISLAND_NOT_HYDRATED` — inert markup either way. With `hydrate` derived it means one of exactly
+two things, and the `fix:` names **the one that is yours**: the route stated `'never'` next to an
+island (remove it), or the `island()` call sits below the `defineRoute` that would have drained it
+(move it up). The throw site tells them apart by asking whether that declaration is still waiting to
+be drained. A `'never'` route is also left with no derived budget, deliberately — a ceiling there
+would paper over the contradiction.
 ## Public API
 | Export | Owns |
 |---|---|
 | `defineRoute` | the `route` primitive |
+| `island`, `createIslandCollector` | one interactive component on a static page |
 | `MODE_SPECS`, `assertModeShape`, `assertModeInvariants` | the mode invariant table |
 | `registerRoute`, `describeRoutes`, `matchRoute`, `routePathFromFile` | the route table |
 | `checkSurfaceBoundary`, `assertSurfaceBoundary`, `surfaceOf` | the hard boundary |
@@ -135,14 +298,19 @@ types-only.
   `action({ cache: { invalidates: [tag.post] } })` reaches ISR in the same hop as memo,
   LRU, Redis and the CDN, and regenerates exactly the dependent pages — nobody lists
   pages by hand, so nobody forgets one. `controller.attach()` installs it as the
-  framework's `Revalidator`.
+  framework's `Revalidator`, and the function it returns releases **both** halves — the
+  dependents and the revalidator slot, the latter only while it is still this controller's.
+  The default store (`memoryIsrStore`) is capped at `DEFAULT_ISR_MAX_ENTRIES` (1,000) pages,
+  least recently generated evicted first.
 - **`stream`** flushes the shell first, then reveals holes in completion order with a
-  ~200-byte inline script. Solid's compiled templates and signals mean the shell costs zero
+  ~200-byte inline script. A client that disconnects mid-stream cancels it: `StreamHole.resolve`
+  is handed an `AbortSignal` so the work stops, and nothing more is enqueued. Solid's compiled templates and signals mean the shell costs zero
   hydration work, so streaming buys TTFB *and* TBT here, not just TTFB.
 - **`hydrate: 'interaction'`** replays the event that woke the island; without replay the
   first click on a cold island is silently lost.
 - **`hydrate: 'never'`** emits no attributes beyond the marker and no runtime — the `site/`
-  0kb default is mechanical, not aspirational.
+  0kb default is mechanical, not aspirational. A page that renders an island anyway is
+  `X_ISLAND_NOT_HYDRATED`, not a silently dead button.
 - **The client router is vendored** rather than depending on a moving SolidStart alpha. It
   imports no `solid-js`: reactive primitives and the DOM host are injected.
 - `@ultimat3/http`'s `html()` / `stream()` turn a `RenderResult` into a `Response`; render

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/render",
-  "version": "1.2.0",
+  "version": "2.0.0",
   "description": "The route primitive and the five render modes: static, isr, ssr, stream, spa.",
   "license": "MIT",
   "type": "module",
@@ -19,6 +19,7 @@
   "files": [
     "src",
     "!src/**/*.test.ts",
+    "CLAUDE.md",
     "README.md",
     "LICENSE"
   ],
@@ -30,8 +31,10 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/cache": "1.2.0",
-    "@ultimat3/core": "1.2.0",
-    "@ultimat3/seo": "1.2.0"
+    "@ultimat3/cache": "2.0.0",
+    "@ultimat3/core": "2.0.0",
+    "@ultimat3/i18n": "2.0.0",
+    "@ultimat3/seo": "2.0.0",
+    "sass": "1.102.0"
   }
 }

package/src/css-modules.ts ADDED Viewed

@@ -0,0 +1,138 @@
+/**
+ * SCSS → CSS, plus the scoped class-name map every `import styles from './x.module.scss'` already
+ * assumes exists. Scoping is content-addressed, so the same source compiles to the same class names
+ * on every machine and the output diffs across deploys the way the HTML does.
+ */
+import { existsSync } from 'node:fs';
+import { basename, dirname, resolve } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import * as sass from 'sass';
+import { PrerenderFailedError } from './errors';
+import { contentHash } from './render-static';
+export interface CompiledStylesheet {
+  readonly css: string;
+  /** `hero` → `hero_1f2e3d4c`. Empty for a plain (non-module) stylesheet. */
+  readonly classes: Readonly<Record<string, string>>;
+}
+/** A file is a CSS module when its name says so — one spelling, per the `.module.scss` convention. */
+export function isCssModule(file: string): boolean {
+  return file.endsWith('.module.scss') || file.endsWith('.module.css');
+}
+/**
+ * The complement, named rather than spelled `!isCssModule(…)` at the call site, because the
+ * registry ORDERS on it: a plain stylesheet is the global layer — the `:root` custom properties
+ * every module rule reads through `var(--…)`, and the element reset — and it has to reach the
+ * document before the modules do. A cascade rule that only exists as a negation at one call site
+ * is a cascade rule the next reader inverts by accident.
+ */
+export function isGlobalStylesheet(file: string): boolean {
+  return !isCssModule(file);
+}
+/**
+ * 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'> => ({
+  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
+    // a package entry point resolves and every partial it forwards does not.
+    const base =
+      context.containingUrl === undefined || context.containingUrl === null
+        ? from
+        : dirname(fileURLToPath(context.containingUrl));
+    const local = partialCandidates(resolve(base, url)).find((candidate) => existsSync(candidate));
+    if (local !== undefined) return pathToFileURL(local);
+    try {
+      return pathToFileURL(Bun.resolveSync(url, base));
+    } catch {
+      return null;
+    }
+  },
+});
+/** Sass's own load order for a bare name: the file, its partial, then the directory's index. */
+const partialCandidates = (target: string): readonly string[] => {
+  const dir = dirname(target);
+  const name = basename(target);
+  return [
+    `${dir}/${name}.scss`,
+    `${dir}/_${name}.scss`,
+    `${target}/_index.scss`,
+    `${target}/index.scss`,
+    `${dir}/${name}.css`,
+  ];
+};
+/** Strings and `url()` payloads may contain a `.` that is not a class selector. */
+const PROTECTED = /"(?:[^"\\]|\\.)*"|'(?:[^'\\]|\\.)*'|url\([^)]*\)/g;
+/** A class selector: a dot followed by an identifier start. `0.5rem` cannot match — `5` is not one. */
+const CLASS_SELECTOR = /\.(-?[A-Za-z_][\w-]*)/g;
+/**
+ * The mask delimiter. NUL is the one byte CSS cannot contain, so the restore pass cannot mistake
+ * a real declaration for a placeholder — a bare numeric marker would collide with `flex:1 1 0`.
+ */
+const NUL = '\u0000';
+const MASKED = new RegExp(`${NUL}(\\d+)${NUL}`, 'g');
+/**
+ * Rewrite every class selector to its scoped name and report the map. Done on the compiled CSS
+ * rather than the SCSS source so mixins, `@extend` and interpolation have already produced their
+ * final selectors — a rewrite before Sass runs would miss every class a mixin generates.
+ */
+export function scopeClasses(
+  css: string,
+  suffix: string,
+): { readonly css: string; readonly classes: Record<string, string> } {
+  const classes: Record<string, string> = {};
+  const literals: string[] = [];
+  const masked = css.replace(PROTECTED, (match) => {
+    literals.push(match);
+    return `${NUL}${literals.length - 1}${NUL}`;
+  });
+  const scoped = masked.replace(CLASS_SELECTOR, (_match, name: string) => {
+    const local = `${name}_${suffix}`;
+    classes[name] = local;
+    return `.${local}`;
+  });
+  const restored = scoped.replace(
+    MASKED,
+    // The mask is dense and index-addressed, so a miss is impossible; `??` only keeps
+    // `noUncheckedIndexedAccess` honest.
+    (_match, index: string) => literals[Number(index)] ?? '',
+  );
+  return { css: restored, classes };
+}
+/** The fix line for a stylesheet that names tokens `@ultimat3/ui/tokens` does not export. */
+const TOKEN_FIX =
+  "@ultimat3/ui/tokens exports functions and mixins — space(4), radius(md), role('surface-raised'), " +
+  'text(sm) — and no $variables';
+export function compileStylesheet(file: string, source: string): CompiledStylesheet {
+  let css: string;
+  try {
+    css = sass.compileString(source, {
+      url: pathToFileURL(file),
+      loadPaths: [dirname(file)],
+      importers: [packageImporter(dirname(file))],
+      style: 'compressed',
+    }).css;
+  } catch (error) {
+    const first = error instanceof Error ? error.message.split('\n')[0] : String(error);
+    throw new PrerenderFailedError(
+      `${file} did not compile: ${first}`,
+      `edit ${file}: ${TOKEN_FIX}`,
+    );
+  }
+  if (!isCssModule(file)) return { css, classes: {} };
+  // Content-addressed, not path-addressed: a checkout at a different absolute path must produce
+  // byte-identical CSS, which a hash over the absolute filename would not.
+  const scoped = scopeClasses(css, contentHash(`${file.split('/').pop() ?? file} ${source}`));
+  return { css: scoped.css, classes: scoped.classes };
+}

package/src/errors.ts CHANGED Viewed

@@ -12,9 +12,18 @@ export const RENDER_ERROR_CODES = [
   'X_ROUTE_UNNORMALIZED',
   'X_ROUTE_DUPLICATE',
   'X_ROUTE_FILE_INVALID',
+  'X_ROUTE_LOAD_INVALID',
+  'X_ROUTE_LOAD_FAILED',
   'X_SURFACE_BOUNDARY',
   'X_BUDGET_EXCEEDED',
   'X_PRERENDER_FAILED',
+  'X_ISLAND_INVALID',
+  'X_ISLAND_PROPS_INVALID',
+  'X_ISLAND_NOT_HYDRATED',
+  // Render's, not the CLI's, for the same reason X_BUDGET_EXCEEDED is: this package owns the
+  // stylesheet registry and `stylesFor`, so "the CSS a document on this surface carries" is a fact
+  // about render's own output. `x verify` is only the surface that reports it.
+  'X_STYLES_GLOBAL_MISSING',
 ] as const;
 export type RenderErrorCode = (typeof RENDER_ERROR_CODES)[number];
@@ -26,9 +35,16 @@ export const RENDER_ERROR_TITLES: Readonly<Record<RenderErrorCode, string>> = {
   X_ROUTE_UNNORMALIZED: 'a route was registered without defineRoute',
   X_ROUTE_DUPLICATE: 'two route files resolve to one URL',
   X_ROUTE_FILE_INVALID: 'a route file is not named for its surface',
+  X_ROUTE_LOAD_INVALID: 'a route declared a load that is not a function',
+  X_ROUTE_LOAD_FAILED: "a route's load threw while resolving its data",
   X_SURFACE_BOUNDARY: 'a surface imported across the hard boundary',
   X_BUDGET_EXCEEDED: 'a route blew its JS or LCP budget',
   X_PRERENDER_FAILED: 'a prerendered path threw during build',
+  X_ISLAND_INVALID: 'an island declaration cannot become a client entry',
+  X_ISLAND_PROPS_INVALID: 'an island was passed props it cannot carry to the browser',
+  X_ISLAND_NOT_HYDRATED: 'a page renders an island that nothing would ever boot',
+  X_STYLES_GLOBAL_MISSING:
+    'a surface renders documents whose CSS defines no :root custom properties',
 };
 // Titles must be registered for `format()` to render the contract's first line. Every code above is
@@ -165,3 +181,85 @@ export class PrerenderFailedError extends UltimateError {
     });
   }
 }
+/** `load` is optional, so this catches a value that is present and not callable. */
+export class RouteLoadInvalidError extends UltimateError {
+  static readonly code = 'X_ROUTE_LOAD_INVALID' as const;
+  constructor(cause: string, fix: string) {
+    super({
+      code: RouteLoadInvalidError.code,
+      cause,
+      fix,
+      docs: docsFor(RouteLoadInvalidError.code),
+    });
+  }
+}
+/**
+ * The declaration itself cannot become a client entry: no `src`, a remote URL, a name that is not
+ * `*.island.tsx`, or two islands on one page claiming one id. Thrown where `island()` is written,
+ * so the failure lands in the file the author is editing.
+ */
+export class IslandInvalidError extends UltimateError {
+  static readonly code = 'X_ISLAND_INVALID' as const;
+  constructor(cause: string, fix: string) {
+    super({
+      code: IslandInvalidError.code,
+      cause,
+      fix,
+      docs: docsFor(IslandInvalidError.code),
+    });
+  }
+}
+/**
+ * An island is named by specifier, so it can close over nothing — its props are the only channel
+ * from the server, and this is what keeps that channel to declared, JSON-safe, budgeted values.
+ * The failure it exists for is `<Modal {...row} />`: a spread that ships a column nobody meant to.
+ */
+export class IslandPropsInvalidError extends UltimateError {
+  static readonly code = 'X_ISLAND_PROPS_INVALID' as const;
+  constructor(cause: string, fix: string) {
+    super({
+      code: IslandPropsInvalidError.code,
+      cause,
+      fix,
+      docs: docsFor(IslandPropsInvalidError.code),
+    });
+  }
+}
+/**
+ * The page renders an island nothing would boot: the route says `hydrate: 'never'`, or the render
+ * collected no islands so no runtime is emitted. Both ship inert markup — and `hydrate: 'never'`
+ * is exactly what excuses a `site/` route from declaring `budget.js`, so silence here is how the
+ * budget stops meaning anything.
+ */
+export class IslandNotHydratedError extends UltimateError {
+  static readonly code = 'X_ISLAND_NOT_HYDRATED' as const;
+  constructor(cause: string, fix: string) {
+    super({
+      code: IslandNotHydratedError.code,
+      cause,
+      fix,
+      docs: docsFor(IslandNotHydratedError.code),
+    });
+  }
+}
+/**
+ * A loader threw. Named separately from whatever it threw because the useful fact is WHICH route
+ * failed to load — a bare rejection surfaces the repo's own stack and not the URL an author has
+ * to go and fix.
+ */
+export class RouteLoadFailedError extends UltimateError {
+  static readonly code = 'X_ROUTE_LOAD_FAILED' as const;
+  constructor(cause: string, fix: string) {
+    super({
+      code: RouteLoadFailedError.code,
+      cause,
+      fix,
+      docs: docsFor(RouteLoadFailedError.code),
+    });
+  }
+}