npm - @ultimat3/render - Versions diffs - 5.0.1 → 7.0.0 - Mend

@ultimat3/render 5.0.1 → 7.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 (14) hide show

package/CLAUDE.md CHANGED Viewed

@@ -1,8 +1,8 @@
 # @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**.
+Owns: the `route` primitive, the four render modes, the route table, the surface boundary,
+islands + budgets, hydration directives, `<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
@@ -24,13 +24,13 @@ Tier 4. May import tiers 0–3: `core`, `schema`, `i18n`, `money`, `time`, `cach
 | 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. |
+| Mode invariants | `modes.ts` only. Never inline a mode check in a render-\* file. **Four modes, and every one renders the route's component** — `spa` did not, and `renderSpa` never read `entry.component`, so a `spa` route served `<div id="x-root"></div>` in every app that ever declared one. A gated page is `ssr`; a body that belongs in the browser is an `island({ src })`. A fifth mode has to name the function that renders it. |
 | Island declaration | `island({ src })` — a **specifier**, never an import. That is the whole boundary: a string has no scope to close over and no edge for a bundler or `checkSurfaceBoundary` to follow, so a `static` page's graph cannot grow the island's dependencies. Never add an overload that takes a component. |
 | Island filename | `*.island.tsx`, `ISLAND_EXTENSION` — one spelling, same rule as `page.tsx`: a module ships to the browser iff its name says so. Never widen it to accept a second, and never make it optional. |
 | Island timing | the route's `hydrate` and nothing else — derived from the declaration, never declared on the island. An island declaring its own strategy would be a second way to say "this route hydrates" (axiom 1) and a second thing `budget.js` would have to chase. `hydrate: 'never'` + an island is still `X_ISLAND_NOT_HYDRATED`, and so is an `island()` call *below* the `defineRoute` that drains it. The `fix:` names exactly ONE of the two edits — `islandNeverDrained(spec)` tells the causes apart at the throw site, and a message offering both makes half the instruction wrong for every reader. |
 | Island node shape | a **branded array** (`IslandNode extends Array<never>`), and every walker tests `isIslandNode` BEFORE `Array.isArray`. An app types JSX with `jsxImportSource: solid-js`, whose `JSX.Element` is a type ALIAS — unaugmentable — and whose only object-shaped member is `ArrayElement`; a plain object was TS2786 at every `<Island />`, so the feature only worked through `h(Island, …)`, which is what render's own tests used. The array stays empty; the shell is `props.children`. Never satisfy this by importing solid's union. |
 | Island declaration order | `island()` above `defineRoute`, drained by it (`drainDeclaredIslands`). Package-internal — reachable from `./island`, never re-exported by `src/index.ts`: an app calling the drain between its `island()` and its `defineRoute` would silently un-declare the islands the route derives everything from, and a public export is semver-locked the moment it ships. Ambient, and NOT the thing the collector refuses to be: that one is per RENDER, where two requests would bill each other; this one is per MODULE, evaluated once, before any request — and `src` is resolved relative to the route file, so an `island()` call is route-module-local by construction. |
-| Derived budget | `registry.ts`, not `defineRoute`: a ceiling is only meaningful against a surface baseline, and the surface is a fact of the file path the route table already reads. `site/` → `4kb`, `app/` → `18kb` (`DEFAULT_ISLAND_JS_BYTES` above `jsBaselineBytes`). A declared `budget.js` wins; a `'never'` route gets none, so the contradiction stays visible. |
+| 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 `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. |
@@ -40,6 +40,8 @@ Tier 4. May import tiers 0–3: `core`, `schema`, `i18n`, `money`, `time`, `cach
 | 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. |
+| Island mount markers | `data-x-mounted=""` when `mount()` RESOLVED, `data-x-failed="<message>"` when it rejected — set by the runtime, never by `emitIslandAttributes`, because the server does not know the answer. `el.__x` alone cannot carry this: it is assigned when `import()` is CALLED, so a chunk still downloading and one whose `mount()` threw were the same observable, and telling those apart is what `x shot` gates on. Two attributes rather than two values of one, so `[data-x-mounted]` never counts a failure as a success. The rejection handler RETHROWS — swallowing it resolves `el.__x` and the interaction runtime flushes its replay queue into an island that never mounted, which is the row above reintroduced one layer out. Costs 129 B of shared prelude: `idle` 744, `visible` 816, `interaction` 1,010 (`As of 2026-08-21`, the numbers `DEFAULT_ISLAND_JS_BYTES` is derived from). |
+| `idle`'s deadline | `IDLE_HYDRATE_TIMEOUT_MS`, interpolated INTO the runtime string. Exported because a second reader has to agree — `x shot` waits before it photographs, and a settle shorter than this deadline reports an unhydrated page for one that hydrates perfectly. A constant the emitted string restates instead of reading is worse than no constant. |
 | Route truth | `registry.ts`. Never keep a second route list anywhere. |
 | 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. |
@@ -52,17 +54,18 @@ Tier 4. May import tiers 0–3: `core`, `schema`, `i18n`, `money`, `time`, `cach
 | `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, 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. |
+| An undecodable path segment | not a match, never a throw — `decodeSegment` in `registry.ts` is the one reader. `decodeURIComponent('%zz')` is a bare `URIError`, so a typo in a path segment was a 500 where `@ultimat3/http`'s router already answers "this branch does not match". A literal route matching the same text still wins. `router-client.ts` was the second reader and went with `createRouter`. |
 | ISR registration | reconciled against `store.paths()` after every generation (`forgetEvictedPaths`). The store is bounded and evicts silently; `registered` and the cache graph behind it only ever grew, one edge per slug ever requested. Never a store callback — a custom `IsrStore` has none. |
 | Stream hole deadline | `DEFAULT_HOLE_TIMEOUT_MS` (15s), `holeTimeoutMs: null` to opt out. 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. |
+| A gated route is never a cached one | `modes.ts` refuses `policy` on BOTH `static` and `isr` (`X_ROUTE_MODE_INVALID`, `modes.test.ts`). `isr` was not refused until 2026-08 and `dev-render.ts` keys the cache on `url.pathname` alone — no actor, no query string — so a gated ISR route rendered the first actor's document and served it to every later actor who passed the same policy. Keying on more is a trap, not a fix: the key would have to enumerate everything a `policy` and a `load` can read. `ssr` is the one gated mode there is. |
 | 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. |
+| Solid | no `solid-js` import anywhere in this package — `type-pins.tsx` satisfies its `JSX.Element` structurally, through `jsxImportSource`, and never names it. The JSX factory in `jsx.ts` builds inert nodes — it is not a Solid renderer and must never become one. The client half runs in an island chunk, which `@ultimat3/cli`'s `solid-loader.ts` compiles with `babel-preset-solid`: Solid's reactivity is a COMPILE-time contract, so nothing this package could inject would substitute for it. `router-client.ts` was the one file built on that premise ("inject primitives") and it never had a caller. |
+| Root element | `ROOT_ELEMENT_ID` (`render-html.ts`), the id every document's body wraps its component in. It was `SPA_ROOT_ID` in `render-spa.ts`, naming a mode that never used it and that no longer exists. |
 | The loaders | `module-loader.ts` installs them at `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, 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. |
+| 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. `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 CHANGED Viewed

@@ -1,6 +1,6 @@
 # 🖼 @ultimat3/render
-The `route` primitive and the five render modes.
+The `route` primitive and the four render modes.
 | Mode | Behavior | Use |
 |---|---|---|
@@ -8,11 +8,10 @@ The `route` primitive and the five render modes.
 | `isr` | static + background regen on tag/TTL | catalogs, profiles |
 | `ssr` | per-request full render | fresh SEO pages |
 | `stream` | static shell flushed instantly, holes streamed | **default for app pages** |
-| `spa` | shell only, client fetches | dashboards behind auth |
 ```ts
 export const config = defineRoute({
-  render:     'isr',                  // static | isr | ssr | stream | spa
+  render:     'isr',                  // static | isr | ssr | stream
   revalidate: { tags: [tag.post] },
   prerender:  () => db.posts.slugs(),
   offline:    'precache',             // precache | runtime | network-only
@@ -104,9 +103,8 @@ a hydrating `site/` route below.
 | `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` |
-Plus surface rules: `site/` allows `static | isr | ssr`, `app/` allows `stream | spa | ssr`,
+Plus surface rules: `site/` allows `static | isr | ssr`, `app/` allows `stream | ssr`,
 `api/` renders nothing, and a `site/` route that opts into hydration without a `budget.js`
 is a build error.
@@ -186,15 +184,45 @@ out three things. `hydrate` and `budget.js` are **derived from `island()`**, `As
 | 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 }` |
+| `budget.js` | the surface baseline + 20kb (`site/` → `20kb`, `app/` → `34kb`) | 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.
+20kb because a Solid island cannot cost less. Measured through `buildIslands`, minified, against
+production Solid, `As of 2026-08`:
+| Island | Bytes |
+|---|---|
+| `render(() => <p>hello</p>, el)` — the floor, before an author writes a line | 12,588 |
+| a signal, a button and reactive text | 13,663 |
+| `settings.island.tsx`, the heaviest island this repo ships | 17,797 |
+| one directive's hydration runtime at `hydrate: 'idle'` | 615 |
+| the same at `'interaction'`, which is what an island route declaring no `hydrate` gets | 881 |
+17,797 + 881 = **18,678** — the heaviest island this repo ships, plus the runtime an app pays
+without writing a number down. `DEFAULT_ISLAND_HYDRATE` is `'interaction'`
+([`route.ts:33`](src/route.ts)), applied at `:253` to any island route that states no `hydrate`, so
+`idle`'s 615 is the cheaper case and not the one a budget has to clear.
+The default is **20,480** (20kb), which is not that number rounded: the next whole kilobyte above
+it is 19,456, and clearing today's worst island by 778 bytes is a ceiling the next line anyone
+writes breaks. 20kb leaves 1,802 B, and stays under 2× 18,678 — so a route that bundles the same
+island twice is still refused. All three clauses are assertions in
+[`modes.test.ts`](src/modes.test.ts)'s `DEFAULT_ISLAND_JS_BYTES` block, against the measured
+table above; a default that stopped clearing the floor, or stopped being a ceiling, is red.
+It was **4kb** until `As of 2026-08`, sized from `contact-sales.island.tsx` — 875 B of chunk, and
+no `solid-js` import anywhere in it. Calibrating a JSX budget on the one island shape that does not
+pay the JSX runtime put the default a factor of three below the floor of every island that does:
+no `budget.js` under 4096 was reachable on any surface, because the allowance is measured ABOVE the
+baseline and not against it. (Its second number was wrong too — one directive's hydration runtime
+is 615 B at `idle` and 881 B at `interaction`, never 1,019.)
+Still a ceiling and not a pass: exceeding it is `X_BUDGET_EXCEEDED`, naming the island. An island
+that pulls a design system in — `@ultimat3/ui`'s `<Switch>` measures 36,335 B — writes its own
+number down, which is the point of the field.
 `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
@@ -207,7 +235,7 @@ route's — because two islands wanting different timings would leave `RouteDesc
 | 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 |
+| `budget.js` — how many bytes that is allowed to cost, when 20kb is not the number | `tag`, `events`, `rootMargin` — how the wrapper behaves |
 ### An island node is a JSX child
@@ -273,6 +301,26 @@ island (remove it), or the `island()` call sits below the `defineRoute` that wou
 be drained. A `'never'` route is also left with no derived budget, deliberately — a ceiling there
 would paper over the contradiction.
+### "Booted" and "mounted" are different facts, and the DOM says which
+| In the DOM | Means |
+|---|---|
+| `data-x-island`, `data-x-hydrate` | **declared** — emitted for every island, `'never'` included |
+| `el.__x` set, neither marker | **importing** — the chunk was requested, `mount()` has not settled |
+| `data-x-mounted=""` | **running** — `mount()` resolved |
+| `data-x-failed="<message>"` | **threw** — `mount()` rejected, and this is why |
+`el.__x` is assigned when `import()` is *called*, so on its own it cannot tell a chunk still
+downloading from one whose `mount()` threw — and the second is the half that gates a deploy. Both
+markers are set by the runtime, never by `emitIslandAttributes`: the server does not know the
+answer. A rejection still rethrows, so `el.__x` stays rejected and the `interaction` replay queue is
+never flushed into an island that did not mount. `ISLAND_MOUNTED_ATTRIBUTE` and
+`ISLAND_FAILED_ATTRIBUTE` are exported so a reader (`x shot`, an app's own test) names them once.
+`IDLE_HYDRATE_TIMEOUT_MS` (2000) is the `requestIdleCallback` deadline the `idle` runtime is built
+from, exported for the same reason: anything waiting for hydration has to wait at least this long,
+and a second copy of the number is a settle that shoots early and calls a healthy page broken.
 ## Public API
 | Export | Owns |
@@ -284,10 +332,10 @@ would paper over the contradiction.
 | `checkSurfaceBoundary`, `assertSurfaceBoundary`, `surfaceOf` | the hard boundary |
 | `renderStatic`, `enumeratePrerender` | build-time render, content hashing |
 | `createIsrController`, `invalidateAndRevalidate` | SWR + single-flight + tag triggers |
-| `renderSsr`, `streamResult`, `renderSpa` | the per-request modes |
+| `renderSsr`, `streamResult` | the per-request modes |
 | `emitIslandAttributes`, `hydrateRuntime` | the four hydration strategies |
+| `ISLAND_MOUNTED_ATTRIBUTE`, `ISLAND_FAILED_ATTRIBUTE`, `IDLE_HYDRATE_TIMEOUT_MS` | what hydration looks like from outside the page |
 | `graphFor`, `checkBudget`, `assertBudget` | two bundle graphs, per-route budgets |
-| `createRouter` | the vendored client router |
 | `mergeHead`, `renderHead`, `themeScript` | `<head>` merge + the one inlined script |
 ## Notes
@@ -311,7 +359,11 @@ would paper over the contradiction.
 - **`hydrate: 'never'`** emits no attributes beyond the marker and no runtime — the `site/`
   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.
+- **A gated page is `ssr`**, never a client-rendered shell. `spa` and `createRouter` were
+  deleted `As of 2026-08-20`: `renderSpa` never read the route's component and no build ever produced the
+  `chunks` it preloaded, so every `spa` route served an empty `<div id="x-root">`, and the router
+  that shell would have needed had no caller in the framework or in either tracked app. A page
+  whose body belongs in the browser declares `island({ src })` — one interactivity model, one
+  bundler entry point, one budget measured against real bytes.
 - `@ultimat3/http`'s `html()` / `stream()` turn a `RenderResult` into a `Response`; render
   never constructs one.

package/package.json CHANGED Viewed

@@ -1,9 +1,13 @@
 {
   "name": "@ultimat3/render",
-  "version": "5.0.1",
+  "version": "7.0.0",
   "description": "The route primitive and the five render modes: static, isr, ssr, stream, spa.",
   "license": "MIT",
   "type": "module",
+  "sideEffects": [
+    "./src/errors.ts",
+    "./src/index.ts"
+  ],
   "repository": {
     "type": "git",
     "url": "git+https://github.com/developerz-ai/ultimate.git",
@@ -31,10 +35,10 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/cache": "5.0.1",
-    "@ultimat3/core": "5.0.1",
-    "@ultimat3/i18n": "5.0.1",
-    "@ultimat3/seo": "5.0.1",
+    "@ultimat3/cache": "7.0.0",
+    "@ultimat3/core": "7.0.0",
+    "@ultimat3/i18n": "7.0.0",
+    "@ultimat3/seo": "7.0.0",
     "sass": "1.102.0"
   }
 }

package/src/hydrate.ts CHANGED Viewed

@@ -5,8 +5,8 @@
  * answered instead of swallowed.
  */
+import type { HydrateStrategy } from '@ultimat3/core';
 import { escapeAttribute, escapeJsonContent } from './html';
-import type { HydrateStrategy } from './route';
 export interface IslandDirective {
   /** Unique per INSTANCE: two of the same island on a page need two prop bags to find. */
@@ -29,6 +29,28 @@ export interface IslandDirective {
 export const DEFAULT_REPLAY_EVENTS = ['click', 'input', 'change', 'submit', 'keydown'] as const;
+/**
+ * How long `idle` waits before hydrating anyway. Exported because a second reader exists and it
+ * has to agree: `x shot` leaves the page alone for this long before it photographs it, and a
+ * settle shorter than this timeout reports an unhydrated page for one that hydrates perfectly.
+ * The runtime string below interpolates it — two copies of one number is the drift axiom 2 refuses.
+ */
+export const IDLE_HYDRATE_TIMEOUT_MS = 2_000;
+/**
+ * Set by the runtime when the island's `mount()` RESOLVED. `el.__x` is set when `import()` is
+ * called, so it answers "the chunk was requested" and nothing more — three facts (declared,
+ * importing, running) had two observables between them, and the missing one is the half that gates.
+ */
+export const ISLAND_MOUNTED_ATTRIBUTE = 'data-x-mounted';
+/**
+ * Set by the runtime when `mount()` REJECTED, to the error's message. A failed island and one still
+ * loading are the two states an agent most needs to tell apart, and with a success marker alone
+ * they are the same absence.
+ */
+export const ISLAND_FAILED_ATTRIBUTE = 'data-x-failed';
 /**
  * The island's markup wrapper. `never` gets attributes only, so the HTML is inert and the
  * runtime below is never emitted for that island.
@@ -84,20 +106,28 @@ export function requiredStrategies(
 // resolved promise. As a flag, a second click during the chunk's load short-circuited to
 // `Promise.resolve()`, and the interaction runtime flushed its replay queue into an island that
 // had not mounted — the events went to nothing and the listeners were already removed.
+//
+// The mount markers are what make the boot promise's OUTCOME readable from the DOM — by `x shot`,
+// by an app's own test, by a human in devtools. `el.__x` exists from the moment `import()` is
+// called, so it cannot tell a chunk that is still downloading from one whose `mount()` threw.
+// The rejection handler rethrows: swallowing it would resolve `el.__x`, and the interaction
+// runtime below would then flush its replay queue into an island that never mounted — the bug
+// `el.__x`-as-a-promise was introduced to fix, reintroduced one layer further out.
 const RUNTIME_PRELUDE = `
-var Q={};
 function boot(el){var e=el.getAttribute('data-x-entry');
 if(!e)return Promise.resolve();if(el.__x)return el.__x;
 var p=document.querySelector('script[data-x-props="'+el.getAttribute('data-x-island')+'"]');
 var props=p?JSON.parse(p.textContent||'{}'):{};
-return el.__x=import(e).then(function(m){return m.mount(el,props)})}
+return el.__x=import(e).then(function(m){return m.mount(el,props)}).then(
+function(r){el.setAttribute('${ISLAND_MOUNTED_ATTRIBUTE}','');return r},
+function(x){el.setAttribute('${ISLAND_FAILED_ATTRIBUTE}',x&&x.message||'1');throw x})}
 function each(s,f){Array.prototype.forEach.call(document.querySelectorAll(s),f)}
 `.trim();
 const RUNTIME_IDLE = `
 each('[data-x-hydrate="idle"]',function(el){
 var go=function(){boot(el)};
-if('requestIdleCallback'in window)requestIdleCallback(go,{timeout:2000});else setTimeout(go,1)})
+if('requestIdleCallback'in window)requestIdleCallback(go,{timeout:${IDLE_HYDRATE_TIMEOUT_MS}});else setTimeout(go,1)})
 `.trim();
 const RUNTIME_VISIBLE = `

package/src/index.ts CHANGED Viewed

@@ -9,6 +9,15 @@ import { installRenderLoader } from './module-loader';
 // places one fact can be wrong instead of none.
 installRenderLoader();
+/**
+ * The route vocabulary is declared once, at tier 0 (`@ultimat3/core`), and re-exported here
+ * because `defineRoute`, `MODE_SPECS`, `surfaceAllows` and `RouteDescriptor` all take these types
+ * in their signatures: a consumer calling this package's API should not need a second import to
+ * name its arguments. A re-export is not a declaration — `scripts/render-modes.test.ts` refuses a
+ * second declaration, which is what makes re-exporting safe where copying was not.
+ */
+export type { HydrateStrategy, OfflineStrategy, RenderMode } from '@ultimat3/core';
+export { HYDRATE_STRATEGIES, OFFLINE_STRATEGIES, RENDER_MODES } from '@ultimat3/core';
 export type { CompiledStylesheet } from './css-modules';
 export { compileStylesheet, isCssModule, isGlobalStylesheet, scopeClasses } from './css-modules';
 export { parseTtlMs } from './duration';
@@ -54,6 +63,9 @@ export {
   emitIslandProps,
   hydrateRuntime,
   hydrateRuntimeBytes,
+  IDLE_HYDRATE_TIMEOUT_MS,
+  ISLAND_FAILED_ATTRIBUTE,
+  ISLAND_MOUNTED_ATTRIBUTE,
   requiredStrategies,
 } from './hydrate';
 export type { IslandComponent, IslandDeclaration, IslandNode, IslandSpec } from './island';
@@ -89,7 +101,6 @@ export {
   defaultHydrate,
   defaultIslandBudget,
   MODE_SPECS,
-  RENDER_MODES,
 } from './modes';
 export type { Stylesheet } from './module-loader';
 export {
@@ -120,7 +131,7 @@ export {
   routePathFromFile,
 } from './registry';
 export type { RenderHtmlOptions } from './render-html';
-export { renderComponent, renderToHtml } from './render-html';
+export { ROOT_ELEMENT_ID, renderComponent, renderToHtml } from './render-html';
 export type {
   IsrController,
   IsrControllerOptions,
@@ -138,8 +149,6 @@ export {
   isrKey,
   memoryIsrStore,
 } from './render-isr';
-export type { SpaShell, SpaShellInput } from './render-spa';
-export { renderSpa, renderSpaShell, SPA_ROOT_ID } from './render-spa';
 export type { SsrOptions, SsrRenderFn, SsrRenderInput } from './render-ssr';
 export { renderSsr, ssrHeaders } from './render-ssr';
 export type { StaticArtifact, StaticBuildOptions, StaticRenderFn } from './render-static';
@@ -164,11 +173,8 @@ export {
   streamResult,
 } from './render-stream';
 export type {
-  HydrateStrategy,
   LoadRequirement,
-  OfflineStrategy,
   PrerenderFn,
-  RenderMode,
   RenderResult,
   RevalidateConfig,
   RouteBudget,
@@ -184,30 +190,10 @@ export type {
   RouteMetaFn,
   RouteParams,
 } from './route';
-export {
-  DEFAULT_ISLAND_HYDRATE,
-  defineRoute,
-  HYDRATE_STRATEGIES,
-  isRouteConfig,
-  OFFLINE_STRATEGIES,
-  tagKeys,
-} from './route';
+export { DEFAULT_ISLAND_HYDRATE, defineRoute, isRouteConfig, tagKeys } from './route';
 export type { RouteComponent } from './route-component';
 export { pageComponentOf } from './route-component';
 export { metaContextFor, routeDataFor } from './route-data';
-export type {
-  NavigateOptions,
-  NavigationGuard,
-  PrefetchContainer,
-  PrefetchLink,
-  ReactivePrimitives,
-  ResolvedRoute,
-  Router,
-  RouterHost,
-  RouterOptions,
-  RouterRoute,
-} from './router-client';
-export { createRouter } from './router-client';
 export type {
   BoundaryRule,
   BoundaryViolation,

package/src/island-collector.ts CHANGED Viewed

@@ -4,6 +4,7 @@
  * one place a route says it ships JavaScript, and the directives stay a per-render fact.
  */
+import type { HydrateStrategy } from '@ultimat3/core';
 import { IslandInvalidError, IslandNotHydratedError } from './errors';
 import type { IslandDirective } from './hydrate';
 import { DEFAULT_REPLAY_EVENTS } from './hydrate';
@@ -12,7 +13,6 @@ import { isEmittableSpecifier, islandNeverDrained } from './island';
 import type { IslandProps } from './island-props';
 import { checkIslandProps } from './island-props';
 import type { JsxProps } from './jsx';
-import type { HydrateStrategy } from './route';
 /** The distinct client entries a rendered page pulled in — one per module, however many instances. */
 export function islandModuleIds(directives: readonly IslandDirective[]): readonly string[] {

package/src/islands.ts CHANGED Viewed

@@ -5,11 +5,11 @@
  * opt-in, budgeted island.
  */
+import type { HydrateStrategy } from '@ultimat3/core';
 import { BudgetExceededError } from './errors';
 import type { IslandDirective } from './hydrate';
 import { hydrateRuntimeBytes } from './hydrate';
 import type { RouteEntry } from './registry';
-import type { HydrateStrategy } from './route';
 import type { Surface } from './surfaces';
 import { SURFACE_SPECS } from './surfaces';

package/src/modes.ts CHANGED Viewed

@@ -1,19 +1,18 @@
 /**
- * The five render modes as a table of invariants, checked at registration.
+ * The four render modes as a table of invariants, checked at registration.
  * Each mode has properties the framework can rely on; a config that contradicts one is
  * rejected with `X_ROUTE_MODE_INVALID` and the exact edit that fixes it. A mode whose
  * invariant is only documented is a mode that silently degrades in production.
  */
+import type { HydrateStrategy, RenderMode } from '@ultimat3/core';
+import { HYDRATE_STRATEGIES, RENDER_MODES } from '@ultimat3/core';
 import { parseTtlMs } from './duration';
 import { RouteModeInvalidError } from './errors';
-import type { HydrateStrategy, RenderMode, RouteConfig } from './route';
-import { HYDRATE_STRATEGIES } from './route';
+import type { RouteConfig } from './route';
 import type { Surface } from './surfaces';
 import { SURFACE_SPECS, surfaceAllows } from './surfaces';
-export const RENDER_MODES = ['static', 'isr', 'ssr', 'stream', 'spa'] as const;
 /**
  * Everything about a route except the two keys carrying its data generic. Mode invariants never
  * read metadata and never load anything, and omitting both keeps these checks free of `TData`.
@@ -35,19 +34,18 @@ export interface ModeSpec {
   readonly needsRevalidate: boolean;
   /** Does the mode need at least one `<Suspense>` boundary to mean anything? */
   readonly needsSuspense: boolean;
-  /** Does the mode need a `policy` (it renders no data, so the shell must be gated)? */
-  readonly needsPolicy: boolean;
   readonly description: string;
 }
-export const MODE_SPECS: Readonly<Record<RenderMode, ModeSpec>> = Object.freeze({
+/** Keyed with an explicit type argument for the reason `MODE_STRATEGY` in `@ultimat3/pwa`
+ * gives: a `const X: Record<…> = Object.freeze({…})` accepts an extra key in silence. */
+export const MODE_SPECS = Object.freeze<Record<RenderMode, ModeSpec>>({
   static: {
     mode: 'static',
     perRequestState: false,
     prerenderable: true,
     needsRevalidate: false,
     needsSuspense: false,
-    needsPolicy: false,
     description: 'built once, served as a file',
   },
   isr: {
@@ -56,7 +54,6 @@ export const MODE_SPECS: Readonly<Record<RenderMode, ModeSpec>> = Object.freeze(
     prerenderable: true,
     needsRevalidate: true,
     needsSuspense: false,
-    needsPolicy: false,
     description: 'static + background regen on tag/TTL',
   },
   ssr: {
@@ -65,7 +62,6 @@ export const MODE_SPECS: Readonly<Record<RenderMode, ModeSpec>> = Object.freeze(
     prerenderable: false,
     needsRevalidate: false,
     needsSuspense: false,
-    needsPolicy: false,
     description: 'per-request full render',
   },
   stream: {
@@ -74,18 +70,8 @@ export const MODE_SPECS: Readonly<Record<RenderMode, ModeSpec>> = Object.freeze(
     prerenderable: false,
     needsRevalidate: false,
     needsSuspense: true,
-    needsPolicy: false,
     description: 'static shell flushed instantly, holes streamed',
   },
-  spa: {
-    mode: 'spa',
-    perRequestState: false,
-    prerenderable: true,
-    needsRevalidate: false,
-    needsSuspense: false,
-    needsPolicy: true,
-    description: 'shell only, client fetches',
-  },
 });
 /** Mode-local checks that need nothing but the config. Called by `defineRoute`. */
@@ -116,7 +102,7 @@ export function assertModeShape(config: RouteShape): void {
     throw new RouteModeInvalidError(
       "render: 'static' cannot read per-request state, but a `policy` was declared " +
         `(${config.policy.permission} needs an actor)`,
-      "change render to 'ssr' (fresh, gated) or 'spa' (gated shell), or drop the policy",
+      "change render to 'ssr' — per-request and gated — or drop the policy",
     );
   }
   if (config.render === 'static' && config.revalidate !== undefined) {
@@ -135,7 +121,7 @@ export function assertModeShape(config: RouteShape): void {
     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",
+      "change render to 'ssr' — per-request and gated — or drop the policy",
     );
   }
@@ -154,14 +140,6 @@ export function assertModeShape(config: RouteShape): void {
       "change render to 'isr' to prerender and regenerate, or remove prerender",
     );
   }
-  // spa: the shell carries no data, so authz has to live on the route itself.
-  if (config.render === 'spa' && config.policy === undefined) {
-    throw new RouteModeInvalidError(
-      "render: 'spa' ships a shell with no server-rendered data and requires a `policy`",
-      "add policy: can('dashboard:read') — or use 'stream' for a public page",
-    );
-  }
 }
 function hasRevalidateTrigger(config: RouteShape): boolean {
@@ -234,14 +212,42 @@ export function defaultHydrate(surface: Surface): HydrateStrategy {
 }
 /**
- * What an island route may spend ABOVE its surface's baseline when it declares no `budget.js`.
+ * What an island route may spend ABOVE its surface's baseline when it declares no `budget.js` —
+ * the island chunk plus the hydration runtime, which is what `routeJsBytes` adds to the baseline.
+ *
+ * **20kb, and it is calibrated on a Solid island** (`As of 2026-08-21`). It was 4096, justified in
+ * this comment as "twice what the reference app's real island costs (875 B of chunk plus a 1,019 B
+ * runtime)" — and that island, `contact-sales.island.tsx`, imports no `solid-js` at all. Calibrating
+ * a JSX budget on the one island shape that does not pay the JSX runtime made the default
+ * unreachable for every island that does: measured with `buildIslands`, minified, production Solid,
+ * `render(() => <p>hello</p>, el)` is **12,588 B** — the floor, before an author writes anything —
+ * a signal + a button + reactive text is 13,663 B, and the reference app's real Solid island
+ * (`settings.island.tsx`) is 17,797 B. No `budget.js` under 4096 was reachable by any of them, on
+ * any surface, because the allowance is measured above the baseline and not against it.
+ *
+ * The number: 17,797 (the heaviest island this repo actually ships) + 1,010 (`hydrateRuntimeBytes`
+ * for one directive at `DEFAULT_ISLAND_HYDRATE`, which is `'interaction'` — `route.ts:33`, applied
+ * at `:253` to any island route declaring no `hydrate`) = **18,807**. That is the worst case an
+ * app reaches without writing a number down. 20,480 is NOT that rounded up — the next whole
+ * kilobyte above it is 19,456 — it is one whole kB further, leaving 1,673 B of headroom and still
+ * under 2x 18,807, so a route bundling the same island twice is refused. `island-budget.test.ts`
+ * asserts all three. `idle` costs 744 and `visible` 816, so an island route that declares its
+ * strategy pays less; the default is what the budget has to clear.
+ *
+ * All three grew by 129 B on 2026-08-21 (from 881 / 615 / 687), when the prelude learned to mark a
+ * mount's OUTCOME so `x shot` can tell an island that RAN from one that only started loading. The
+ * headroom absorbed it and the conclusion is unchanged — which is the point of stating the
+ * arithmetic here rather than the answer alone. It is not
+ * derived from Solid's own size on purpose — this package may not import or name `solid-js`
+ * (`CLAUDE.md`), so a constant tracking the runtime's version would be a dependency in a comment.
  *
- * A number, not "unlimited", because the guard means nothing otherwise — and 4kb because that is
- * roughly twice what the reference app's real island costs (875 B of chunk plus a 1,019 B runtime),
- * which is enough for a second small island and not enough to hide a library. A declared
- * `budget.js` still wins, and exceeding this one still fails with the island named.
+ * Still a real ceiling, still real bytes on disk: an island that pulls a design system in
+ * (`@ultimat3/ui`'s `<Switch>` measures 36,335 B) or ships an engine twice must write its own
+ * number down, which is the whole point. Two defaults keyed on "does the graph reach Solid?" is
+ * not an option even setting axiom 1 aside: `registry.ts` reads this at REGISTRATION, before any
+ * bundle exists, so the answer is not available where the constant is used.
  */
-export const DEFAULT_ISLAND_JS_BYTES = 4096;
+export const DEFAULT_ISLAND_JS_BYTES = 20_480;
 /**
  * The derived ceiling for a route whose hydration came from an island. Relative to the surface

package/src/registry.ts CHANGED Viewed

@@ -5,6 +5,7 @@
  * from. Nothing downstream may keep its own list of routes.
  */
+import type { HydrateStrategy, OfflineStrategy, RenderMode } from '@ultimat3/core';
 import {
   RouteDuplicateError,
   RouteFileInvalidError,
@@ -12,24 +13,22 @@ import {
   SurfaceBoundaryError,
 } from './errors';
 import { assertModeInvariants, defaultIslandBudget } from './modes';
-import type {
-  HydrateStrategy,
-  OfflineStrategy,
-  RenderMode,
-  RouteConfig,
-  RouteData,
-  RouteParams,
-} from './route';
+import type { RouteConfig, RouteData, RouteParams } from './route';
 import { isRouteConfig, tagKeys } from './route';
 import type { RouteComponent } from './route-component';
 import type { Surface } from './surfaces';
 import { locateSurface } from './surfaces';
 /**
- * The one filename a route may carry, per surface. `shared/` is absent on purpose: it is a leaf
- * of helpers with no URL, so a route file there has nowhere to resolve to.
+ * The one filename a route may carry, per surface. `shared/` is `Exclude`d rather than merely
+ * absent: it is a leaf of helpers with no URL, so a route file there has nowhere to resolve to —
+ * and stating that in the key type makes the other three MANDATORY. `Partial<Record<Surface, …>>`
+ * said the same thing about `shared` and let any of the three go missing, which only three
+ * registration tests would have caught. A dropped `api` row is not a crash: `assertRouteFilename`
+ * reads `undefined` as "this file is under shared/", so every `api/` route author would have been
+ * told their file is a leaf of helpers.
  */
-export const ROUTE_FILENAME: Readonly<Partial<Record<Surface, string>>> = Object.freeze({
+export const ROUTE_FILENAME = Object.freeze<Record<Exclude<Surface, 'shared'>, string>>({
   site: 'page.tsx',
   app: 'page.tsx',
   api: 'route.ts',
@@ -137,7 +136,9 @@ const shellQuote = (value: string): string => `'${value.replaceAll("'", "'\\''")
  * author already meant, plus the one filename that surface accepts.
  */
 function assertRouteFilename(file: string, surface: Surface, basename: string | undefined): void {
-  const expected = ROUTE_FILENAME[surface];
+  // `shared` is the one surface with no filename, and the key type now says so — which is why
+  // this is a comparison rather than an `undefined` check on the lookup.
+  const expected = surface === 'shared' ? undefined : ROUTE_FILENAME[surface];
   if (expected === undefined) {
     throw new RouteFileInvalidError(
       `${file} is under shared/, which is a leaf of helpers with no URL — a route cannot live there`,
@@ -370,9 +371,9 @@ export function matchRoute(pathname: string): RouteMatch | null {
  * `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.
+ * Still exported after `router-client.ts` went with `createRouter`: it is the one answer to "is
+ * this segment decodable?" on this side of the wire, and a second copy of it is how one of the two
+ * ends up throwing where the other 404s.
  */
 export function decodeSegment(value: string): string | undefined {
   try {

package/src/render-html.ts CHANGED Viewed

@@ -20,6 +20,13 @@ import { islandWithoutCollector } from './island-collector';
 import type { JsxComponent, JsxProps } from './jsx';
 import { isJsxNode } from './jsx';
+/**
+ * The id of the element every document wraps its route component in — one name, because a service
+ * worker, a test and a client entry all address the same element. It was `SPA_ROOT_ID` in
+ * `render-spa.ts` and named a mode that no longer exists, while every mode has always used it.
+ */
+export const ROOT_ELEMENT_ID = 'x-root';
 /** Depth is bounded so a component that renders itself fails with a cause instead of a stack trace. */
 const MAX_DEPTH = 500;

package/src/route.ts CHANGED Viewed

@@ -14,6 +14,8 @@
 import type { CacheTag } from '@ultimat3/cache';
 import { serializeTags } from '@ultimat3/cache';
+import type { HydrateStrategy, OfflineStrategy, RenderMode } from '@ultimat3/core';
+import { OFFLINE_STRATEGIES } from '@ultimat3/core';
 import type { Translator } from '@ultimat3/i18n';
 import type { RouteMeta } from '@ultimat3/seo';
 import { RouteLoadInvalidError, RouteMetaMissingError, RouteOfflineMissingError } from './errors';
@@ -21,13 +23,6 @@ import type { IslandSpec } from './island';
 import { drainDeclaredIslands } from './island';
 import { assertModeShape } from './modes';
-export type RenderMode = 'static' | 'isr' | 'ssr' | 'stream' | 'spa';
-export type OfflineStrategy = 'precache' | 'runtime' | 'network-only';
-export type HydrateStrategy = 'idle' | 'visible' | 'interaction' | 'never';
-export const OFFLINE_STRATEGIES = ['precache', 'runtime', 'network-only'] as const;
-export const HYDRATE_STRATEGIES = ['idle', 'visible', 'interaction', 'never'] as const;
 /**
  * What a page that declares an island hydrates as when it says nothing. The most conservative of
  * the three that ship JavaScript: nothing runs until the visitor acts, and `interaction` is the

package/src/surfaces.ts CHANGED Viewed

@@ -5,8 +5,8 @@
  * aspirational. Violations are build errors, resolved through the whole chain.
  */
+import type { RenderMode } from '@ultimat3/core';
 import { SurfaceBoundaryError } from './errors';
-import type { RenderMode } from './route';
 export type Surface = 'site' | 'app' | 'api' | 'shared';
@@ -24,7 +24,7 @@ export interface SurfaceSpec {
   readonly mayImportTypes: readonly Surface[];
 }
-export const SURFACE_SPECS: Readonly<Record<Surface, SurfaceSpec>> = Object.freeze({
+export const SURFACE_SPECS = Object.freeze<Record<Surface, SurfaceSpec>>({
   site: {
     surface: 'site',
     defaultMode: 'static',
@@ -36,7 +36,7 @@ export const SURFACE_SPECS: Readonly<Record<Surface, SurfaceSpec>> = Object.free
   app: {
     surface: 'app',
     defaultMode: 'stream',
-    allowedModes: ['stream', 'spa', 'ssr'],
+    allowedModes: ['stream', 'ssr'],
     jsBaselineBytes: 14_336,
     mayImport: ['shared'],
     mayImportTypes: ['shared', 'api'],

package/src/render-spa.ts DELETED Viewed

@@ -1,79 +0,0 @@
-/**
- * `spa` — shell only, client fetches everything. For dashboards behind auth, where the
- * shell is identical for every actor and therefore cacheable, and the data is not.
- * `modes.ts` requires a `policy` on this mode: nothing is server-rendered, so the route
- * itself is the only place authz can live.
- */
-import { RouteModeInvalidError } from './errors';
-import { escapeAttribute } from './html';
-import type { RouteEntry } from './registry';
-import { contentHash } from './render-static';
-import type { RenderResult } from './route';
-export const SPA_ROOT_ID = 'x-root';
-export interface SpaShellInput {
-  readonly entry: RouteEntry;
-  readonly buildId: string;
-  /** Everything inside `<head>`, already merged by `head.ts`. */
-  readonly head: string;
-  /** Build-id-immutable chunk URLs to preload; order is preserved for determinism. */
-  readonly chunks: readonly string[];
-  readonly rootId?: string;
-  readonly lang: string;
-  readonly dir?: 'ltr' | 'rtl';
-}
-export interface SpaShell {
-  readonly html: string;
-  readonly hash: string;
-}
-export function renderSpaShell(input: SpaShellInput): SpaShell {
-  if (input.entry.config.policy === undefined) {
-    throw new RouteModeInvalidError(
-      `${input.entry.file} declares render: 'spa' with no policy, so the shell would be public`,
-      `add policy: can('…') to ${input.entry.file}`,
-    );
-  }
-  // 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="${escapeAttribute(chunk)}">`)
-    .join('');
-  const scripts = input.chunks
-    .map((chunk) => `<script type="module" src="${escapeAttribute(chunk)}"></script>`)
-    .join('');
-  const html =
-    `<!doctype html><html lang="${escapeAttribute(input.lang)}" ` +
-    `dir="${escapeAttribute(input.dir ?? 'ltr')}">` +
-    `<head>${input.head}${preloads}` +
-    `<meta name="x-ultimate-build" content="${escapeAttribute(input.buildId)}">` +
-    `</head><body><div id="${rootId}"></div>${scripts}</body></html>`;
-  return { html, hash: contentHash(html) };
-}
-/**
- * The shell is identical for every actor, so it is cache-first in `sw.js` and
- * revalidate-on-navigation over HTTP. The build id in the document is what
- * `@ultimat3/pwa`'s skew detection compares against the server's.
- */
-export function renderSpa(input: SpaShellInput): RenderResult {
-  const shell = renderSpaShell(input);
-  return {
-    status: 200,
-    headers: {
-      'content-type': 'text/html; charset=utf-8',
-      'cache-control': 'private, max-age=0, must-revalidate',
-      etag: `"${shell.hash}"`,
-      'x-ultimate-build': input.buildId,
-    },
-    body: shell.html,
-  };
-}

package/src/router-client.ts DELETED Viewed

@@ -1,236 +0,0 @@
-/**
- * The minimal client router. Vendored on purpose: the router is load-bearing for every
- * app page, and a moving SolidStart alpha is not something a framework should depend on.
- *
- * No `solid-js` import — reactive primitives and the DOM are injected, so this file runs
- * under `bun test` with no DOM and no framework runtime.
- */
-import type { CompiledPattern } from './registry';
-import { compilePattern, decodeSegment } from './registry';
-import type { RouteParams } from './route';
-export interface RouterRoute {
-  readonly path: string;
-  /** Module URL for the route chunk; used by `prefetch`. */
-  readonly chunk?: string;
-}
-export interface ResolvedRoute {
-  readonly route: RouterRoute;
-  readonly params: RouteParams;
-  readonly pathname: string;
-  readonly search: string;
-}
-/** Injected instead of imported so there is no framework runtime dependency here. */
-export interface ReactivePrimitives {
-  createSignal<T>(initial: T): readonly [() => T, (next: T) => void];
-}
-export interface RouterHost {
-  readonly pathname: () => string;
-  readonly search: () => string;
-  readonly pushState: (url: string) => void;
-  readonly replaceState: (url: string) => void;
-  readonly onPopState: (handler: () => void) => void;
-  readonly scrollTo: (x: number, y: number) => void;
-  readonly scrollY: () => number;
-  /** `document.startViewTransition` when present; falls back to running the update. */
-  readonly viewTransition?: (update: () => void) => void;
-  /** Warm a chunk. Defaults to a no-op host in tests. */
-  readonly preload?: (chunk: string) => void;
-}
-export type NavigationGuard = (
-  to: ResolvedRoute,
-  from: ResolvedRoute | null,
-) => boolean | Promise<boolean>;
-export interface RouterOptions {
-  readonly routes: readonly RouterRoute[];
-  readonly host: RouterHost;
-  readonly primitives: ReactivePrimitives;
-  /** Hover dwell before prefetching, ms. */
-  readonly prefetchDelayMs?: number;
-}
-export interface NavigateOptions {
-  readonly replace?: boolean;
-  readonly scroll?: boolean;
-}
-export interface Router {
-  readonly current: () => ResolvedRoute | null;
-  readonly navigate: (to: string, options?: NavigateOptions) => Promise<boolean>;
-  readonly resolve: (url: string) => ResolvedRoute | null;
-  readonly prefetch: (to: string) => void;
-  readonly guard: (guard: NavigationGuard) => () => void;
-  /** Attach hover/visible prefetch + scroll restoration to a container element. */
-  readonly attach: (container: PrefetchContainer) => () => void;
-}
-/** Structural view of the DOM bits the router touches, so tests can fake them. */
-export type DomEventHandler = (event: { target: unknown }) => void;
-export interface PrefetchContainer {
-  querySelectorAll(selector: string): Iterable<PrefetchLink>;
-  addEventListener(type: string, handler: DomEventHandler, options?: unknown): void;
-  removeEventListener(type: string, handler: DomEventHandler, options?: unknown): void;
-}
-export interface PrefetchLink {
-  getAttribute(name: string): string | null;
-}
-interface CompiledRoute {
-  readonly route: RouterRoute;
-  readonly pattern: CompiledPattern;
-}
-export function createRouter(options: RouterOptions): Router {
-  const compiled: readonly CompiledRoute[] = options.routes
-    .map((route) => ({ route, pattern: compilePattern(route.path) }))
-    .sort((a, b) => b.pattern.specificity - a.pattern.specificity);
-  const guards = new Set<NavigationGuard>();
-  const scrollPositions = new Map<string, number>();
-  const prefetched = new Set<string>();
-  const host = options.host;
-  const [current, setCurrent] = options.primitives.createSignal<ResolvedRoute | null>(
-    resolve(`${host.pathname()}${host.search()}`),
-  );
-  function resolve(url: string): ResolvedRoute | null {
-    const [rawPath = '/', rawSearch = ''] = splitUrl(url);
-    for (const candidate of compiled) {
-      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) 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,
-        pathname: rawPath,
-        search: rawSearch === '' ? '' : `?${rawSearch}`,
-      };
-    }
-    return null;
-  }
-  async function navigate(to: string, navOptions: NavigateOptions = {}): Promise<boolean> {
-    const next = resolve(to);
-    if (next === null) return false;
-    const from = current();
-    for (const guard of guards) {
-      // A guard that says no is a hard stop: no history entry, no scroll change.
-      if (!(await guard(next, from))) return false;
-    }
-    if (from !== null) scrollPositions.set(keyOf(from), host.scrollY());
-    const commit = (): void => {
-      if (navOptions.replace === true) host.replaceState(to);
-      else host.pushState(to);
-      setCurrent(next);
-      if (navOptions.scroll !== false) restoreScroll(next);
-    };
-    if (host.viewTransition !== undefined) host.viewTransition(commit);
-    else commit();
-    return true;
-  }
-  function restoreScroll(route: ResolvedRoute): void {
-    host.scrollTo(0, scrollPositions.get(keyOf(route)) ?? 0);
-  }
-  function prefetch(to: string): void {
-    const target = resolve(to);
-    const chunk = target?.route.chunk;
-    if (chunk === undefined || prefetched.has(chunk)) return;
-    prefetched.add(chunk);
-    host.preload?.(chunk);
-  }
-  host.onPopState(() => {
-    const next = resolve(`${host.pathname()}${host.search()}`);
-    if (next !== null) {
-      setCurrent(next);
-      restoreScroll(next);
-    }
-  });
-  return {
-    current,
-    navigate,
-    resolve,
-    prefetch,
-    guard(guard) {
-      guards.add(guard);
-      return () => guards.delete(guard);
-    },
-    attach(container) {
-      let timer: ReturnType<typeof setTimeout> | null = null;
-      const onEnter = (event: { target: unknown }): void => {
-        const href = hrefOf(event.target);
-        if (href === null) return;
-        if (timer !== null) clearTimeout(timer);
-        timer = setTimeout(() => prefetch(href), options.prefetchDelayMs ?? 80);
-      };
-      const onLeave = (): void => {
-        if (timer !== null) clearTimeout(timer);
-        timer = null;
-      };
-      container.addEventListener('mouseenter', onEnter, true);
-      container.addEventListener('mouseleave', onLeave, true);
-      // Visible prefetch: everything explicitly marked, warmed once it is on screen.
-      for (const link of container.querySelectorAll('a[data-prefetch="visible"]')) {
-        const href = link.getAttribute('href');
-        if (href !== null) prefetch(href);
-      }
-      return () => {
-        container.removeEventListener('mouseenter', onEnter, true);
-        container.removeEventListener('mouseleave', onLeave, true);
-        onLeave();
-      };
-    },
-  };
-}
-function keyOf(route: ResolvedRoute): string {
-  return `${route.pathname}${route.search}`;
-}
-function splitUrl(url: string): readonly [string, string] {
-  const hashless = url.split('#')[0] ?? '/';
-  const index = hashless.indexOf('?');
-  if (index === -1) return [hashless === '' ? '/' : hashless, ''];
-  return [hashless.slice(0, index) || '/', hashless.slice(index + 1)];
-}
-function hrefOf(target: unknown): string | null {
-  if (typeof target !== 'object' || target === null) return null;
-  if (!('getAttribute' in target)) return null;
-  const link = target as PrefetchLink;
-  return link.getAttribute('href');
-}