@ultimat3/render 6.0.0 → 7.0.0

package/CLAUDE.md

@@ -30,7 +30,7 @@ Tier 4. May import tiers 0–3: `core`, `schema`, `i18n`, `money`, `time`, `cach
 | 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. |

package/README.md

@@ -184,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
@@ -205,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
 
@@ -271,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,6 +334,7 @@ would paper over the contradiction.
 | `createIsrController`, `invalidateAndRevalidate` | SWR + single-flight + tag triggers |
 | `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 |
 | `mergeHead`, `renderHead`, `themeScript` | `<head>` merge + the one inlined script |
 

package/package.json

@@ -1,9 +1,13 @@
 {
   "name": "@ultimat3/render",
-  "version": "6.0.0",
+  "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": "6.0.0",
-    "@ultimat3/core": "6.0.0",
-    "@ultimat3/i18n": "6.0.0",
-    "@ultimat3/seo": "6.0.0",
+    "@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

@@ -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

@@ -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 {
@@ -162,11 +173,8 @@ export {
   streamResult,
 } from './render-stream';
 export type {
-  HydrateStrategy,
   LoadRequirement,
-  OfflineStrategy,
   PrerenderFn,
-  RenderMode,
   RenderResult,
   RevalidateConfig,
   RouteBudget,
@@ -182,14 +190,7 @@ 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';

package/src/island-collector.ts

@@ -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

@@ -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

@@ -5,15 +5,14 @@
  * 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'] 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`.
@@ -38,7 +37,9 @@ export interface ModeSpec {
   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,
@@ -211,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

@@ -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`,

package/src/route.ts

@@ -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';
-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

@@ -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',