@ultimat3/render 29.4.0 → 30.1.0

package/CLAUDE.md

@@ -44,19 +44,19 @@ axiom 6). Never `cli` (upward).
 | Island declaration | `island({ src })` — a **specifier**, never an import, 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. Never widen it. |
 | Island timing | the route's `hydrate` and nothing else. `hydrate: 'never'` + an island, or an `island()` call below the `defineRoute` that drains it, is `X_ISLAND_NOT_HYDRATED`; `islandNeverDrained(spec)` tells the two causes apart so the `fix:` names exactly one edit. |
-| Island node shape | a **branded array** (`IslandNode extends Array<never>`); every walker tests `isIslandNode` BEFORE `Array.isArray`. Solid's `JSX.Element` is an unaugmentable alias whose only object member is `ArrayElement`. Never import solid's union. |
+| Island node shape | a **branded array** (`IslandNode extends Array<never>`); every walker tests `isIslandNode` BEFORE `Array.isArray`. Solid's `JSX.Element` is an unaugmentable alias whose only object member is `ArrayElement`. Never import solid's union. The brands `JSX_NODE`, `ISLAND_NODE`, `HOLE_NODE` are `@ultimat3/core/render-node`'s, imported by `jsx.ts`, `island.ts` and `hole.ts` (`hole.test.ts`) |
 | Island declaration order | `island()` above `defineRoute`, drained by it (`drainDeclaredIslands`), reachable from `./island` and never from `src/index.ts`. Per MODULE (evaluated once), unlike the per-render collector. |
 | Derived budget | `registry.ts`, from the surface: `site/` → `20kb`, `app/` → `34kb` (`DEFAULT_ISLAND_JS_BYTES` above `jsBaselineBytes`), calibrated on a Solid island. A declared `budget.js` wins; a `'never'` route gets none. |
 | `RouteEntry.islands` | filled from `config.islands` at registration and nothing else — `RegisterRouteInput` has no `islands` key. |
 | Island props | declared, JSON-safe, under `ISLAND_PROPS_MAX_BYTES` (16 KiB; the doc comment carries the arithmetic) — `island-props.ts` is the one gate, a structural walk, never a `JSON.stringify` round trip. Over the cap the cause names the heaviest props and the fix names the endpoint pattern, never "raise the cap". `X_ISLAND_PROPS_INVALID` has a row in `@ultimat3/http`'s table (500). |
 | A prop lands via `Object.defineProperty` | never `out[key] = v` — `__proto__` (a real own key off `JSON.parse`) would run the prototype setter. |
 | An attribute alias is a `Map` | never a record (`toString` resolved to a function). `MODE_SPECS[config.render]` is guarded by `Object.hasOwn` for the same reason. |
-| An attribute NAME is validated too | `ATTRIBUTE_NAME` in `html.ts` (`/^[A-Za-z_:][-A-Za-z0-9_:.]*$/`), refused as `null`; the `on*` handler check folds case. `head.ts`'s `renderTag` shares the predicate (`isAttributeName`). One predicate, never two. |
+| An attribute NAME is validated too | `ATTRIBUTE_NAME` in `html.ts` (`/^[A-Za-z_:][-A-Za-z0-9_:.]*$/`), refused as `null`; the `on*` handler check folds case. `head-attributes.ts` prints a head tag through the same `attributePair`, one exception: a `link` href reads `safeUrl` as a `src` (raster `data:image/`) and `rel="alternate"` keeps `android-app:`/`ios-app:`. A drop logs `head.attribute_dropped` once per tag and attribute in dev. One rule, never two. |
 | Which attributes take a URL | `URL_BEARING_ATTRIBUTES` in `html.ts` — core's four plus `data`, `poster`, `ping`, `xlink:href`. `srcdoc` is refused outright (entity-decoded, then parsed as HTML). |
 | Island collection | per render, `renderToHtml(tree, { islands })`. Never module-global and never on an ambient context. |
 | A byte count in a message | `formatBytes` from `@ultimat3/core`, never a local one. |
 | Island bytes | **not this package's**: `@ultimat3/cli`'s `packages/cli/src/budgets.ts` measures the EMITTED document and is the gate. What stays here is the budget grammar (`parseByteBudget`) and `defaultIslandBudget`. |
-| The hydration runtime's CSP | `HYDRATE_RUNTIME_BODIES` — every body `hydrateRuntime` can emit (seven subsets, each with and without the hold part — fourteen). It is inline in every document with an island and `@ultimat3/http`'s `script-src` is `'self' 'wasm-unsafe-eval'`, so `@ultimat3/cli`'s `script-csp.ts` hashes this list at boot. `runtimeBody` is the one place the served and hashed text are one string. **Uncovered**: `render-stream.ts`'s per-hole `<script>$X("id")</script>` (unreachable today; the first real hole needs a nonce). |
+| The hydration runtime's CSP | `HYDRATE_RUNTIME_BODIES` — every body `hydrateRuntime` can emit (seven subsets, each with and without the hold part — fourteen). It is inline in every document with an island and `@ultimat3/http`'s `script-src` is `'self' 'wasm-unsafe-eval'`, so `@ultimat3/cli`'s `script-csp.ts` hashes this list at boot. `runtimeBody` is the one place the served and hashed text are one string. A hole's reveal body is the constant `$X()`, hashed through `STREAM_REVEAL_BODIES`, and reachable. |
 | Island markup | the props `<script>` is emitted INSIDE the wrapper by `render-html.ts`; an assembler only adds `hydrateRuntime(directives)`. |
 | Island boot | `el.__x` holds the boot PROMISE, never a boolean. |
 | Island mount markers | `data-x-mounted=""` when `mount()` resolved, `data-x-failed="<message>"` when it rejected — set by the runtime, never by `emitIslandAttributes`. The rejection handler RETHROWS. Prelude sizes `As of 2026-10-05`: `idle` 1,843, `visible` 886, `interaction` 1,728 B (what `DEFAULT_ISLAND_JS_BYTES` derives from). |
@@ -77,7 +77,7 @@ axiom 6). Never `cli` (upward).
 | "Is this a TTL?" has one reader | `parseTtlMs` in `duration.ts`, below `modes.ts` and `render-isr.ts`. |
 | A build-time frame reads a throw with `renderThrowable` | `render-html.ts`, `render-static.ts`, `css-modules.ts`, `module-loader.ts`, `route-data.ts`. `bun run error-render` cannot see a value laundered through a local helper. |
 | `X_ROUTE_LOAD_FAILED` computes its pathname BEFORE the try | `pathnameOf` never throws on a relative `ctx.url`. |
-| The ISR key | `isrKey(url, locale)` — the path in http's `canonicalPath` spelling (no base path), the locale in the reserved `__x_locale` parameter, the sorted query. A key no route owns is never stored. The locale is REQUIRED. The time zone is deliberately not a dimension. `toResult` emits `vary: accept-language`, and `surrogate-key`/`cache-tag` from `@ultimat3/cache`'s `surrogateKeys()` over the route's `revalidateTags` — kept only while the response stays shared: http's `applyCacheHeaders` strips both on a rewrite to `private`/`no-store`. `registry.ts`'s `assertPurgeableTags` screens the tags at registration (`X_ROUTE_MODE_INVALID`); the rest of the shared key is `@ultimat3/http`'s `cache-headers` stage. File and mounted routes are both screened |
+| The ISR key | `isrKey(url, locale, origin?)` — the path in http's `canonicalPath` spelling (no base path), the locale in the reserved `__x_locale` parameter, the request's origin in `__x_origin` when the app declares none, then the sorted DECLARED query. Full rule: `docs/history/render.md` |
 | A bust that lands MID-render | fenced with `@ultimat3/cache`'s `sampleFence({ key, tags })`, taken before `render()` and asked before `store.set`. `registerPath` runs BEFORE the render. |
 | ISR regeneration | `@ultimat3/core`'s `singleFlight`, `deadlineMs` = `regenerateDeadlineMs` (`DEFAULT_ISR_REGENERATE_DEADLINE_MS`, 30 s; `finiteCount` ≥ 1, no opt-out), `schedule` injectable. Past it the PATH is free; the hung render runs on, and `latest` (by identity) drops its result once a newer run started. `render-isr-flight.test.ts`, on a hand-fired scheduler. |
 | Which route a stored ISR path is | exact path first, else the MOST SPECIFIC pattern: `route-pattern.ts`'s `compilePattern` (never a second compiler), sorted on `CompiledPattern.specificity`. Never table order: `describePages()` sorts `*` before `:`. |
@@ -93,7 +93,7 @@ axiom 6). Never `cli` (upward).
 | Stream hole deadline | `DEFAULT_HOLE_TIMEOUT_MS` (15 s), `holeTimeoutMs: null` to opt out, otherwise a whole number ≥ 1. A hole reveals exactly once — promise, rejection or deadline. |
 | Errors | `errors.ts` subclasses only, but for `navigation-errors.ts` (re-exported; keeps `./client` off the table). 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`). `ssr` is the one gated mode. |
+| A gated route is never a cached one | `modes.ts` refuses `policy` on both `static` and `isr` (`X_ROUTE_MODE_INVALID`, `modes.test.ts`). `ssr` is the one gated mode. Both also RENDER as nobody: `@ultimat3/cli` wraps them in http's `withAnonymousRequest` (`runtime-render-shared-actor.test.ts`). |
 | Responses | return `RenderResult`. `@ultimat3/http` builds the `Response`. |
 | Who owns `cache-control` | a mode states intent; `@ultimat3/http`'s `cache-headers` stage decides and may overrule. This package cannot see the actor and never tries. |
 | Solid | no `solid-js` import anywhere in this package; `type-pins.tsx` satisfies `JSX.Element` structurally. `jsx.ts` builds inert nodes. Islands are compiled by `@ultimat3/cli`'s `solid-loader.ts` with `babel-preset-solid`. |
@@ -112,14 +112,17 @@ axiom 6). Never `cli` (upward).
 | A package's sheets | carried by BOTH surfaces unless the package claims its directory: `claimStylesheets(import.meta.dir, 'app')` makes every sheet below it that surface's alone, still ordered with the library. `@ultimat3/admin` claims `app` — a `site/` document carried its dashboard CSS (axiom 6). A claim re-classifies sheets already registered and survives `clearStylesheets()`. |
 | The global layer | the app's `shared/global.scss` `@use`s `@ultimat3/ui/global.scss`, side-effect-imported by `shared/global.ts` (this package may not import `ui`). `x verify` fails with `X_STYLES_GLOBAL_MISSING` when a surface's document defines none. |
 | Colours | tokens and `data-theme` only. No hex in `head.ts` or any emitted script. |
-| An island's `mount` | may return `() => void`, its disposer; the runtime never calls it, `@ultimat3/testing`'s `mountIsland` does. |
+| An island's `mount` | RETURNS its disposer: the router calls it on navigation, `mountIsland` on cleanup. Typed `void` or returning nothing is cli's `X_ISLAND_DISPOSER_MISSING` (`boundaries`). |
 | `<head>` binding | `head.ts` stays injection-only; `head-seo.ts` is the ONE binding of `HeadRenderers` to `@ultimat3/seo`. |
-| Client navigation | `navigation*.ts` — soft navigation over server-rendered documents, NOT a mode: the router renders nothing, it swaps the document the route already rendered. Rules are pure (`navigation-rules.ts`: `linkVerdict`, `formVerdict`, `responseVerdict`, `mayPrefetch`) and unit-tested; the DOM half (`navigation-swap.ts`, `navigation.ts`) is proven in Chrome by `packages/cli/e2e/client-navigation-*.e2e.test.ts`. `./navigation` (`navigation-entry.ts`) is the script the CLI builds; importing it starts it, and a document without `ultimate-navigation` is never intercepted. Route-presented modals (`navigation: 'modal'`): the hash grammar and verdicts are pure (`navigation-modal-rules.ts`), the `<dialog>` is `navigation-modal.ts`, styled by `@ultimat3/ui`'s `global.scss` under `NAVIGATION_MODAL_ATTRIBUTE` (pinned by `navigation-modal-style.test.ts` — render never imports ui), proven by `client-navigation-modal.e2e.test.ts`. |
+| Client navigation | `navigation*.ts` — soft navigation over server-rendered documents, NOT a mode: the router swaps the document the route already rendered. Pure rules in `navigation-rules.ts`, proven in Chrome by `packages/cli/e2e/client-navigation-*.e2e.test.ts`; render never imports ui. Full rule: `docs/history/render.md`. `refresh()`'s differences live in `navigation-refresh.ts`; `scheduleRefresh()` is `refresh-idle.ts`, on `./client`, and never reloads without the router. Full rule: `docs/history/render.md` |
 | Modal on the click | `navigation-modal-frame.ts`: `modal.loading(url)` in `navigate`'s synchronous prefix opens the frame off `NAVIGATION_MODALS_META`; the answer's meta still decides. Closing aborts (`abandon`); the router `release()`s before its own dismissals; `settle()` in `finally`. Never `showModal()` where popovers exist, never a toggle on `<html>`/`<body>` ([why](../../docs/history/render.md#the-modal-that-opens-on-the-click)) |
-| Router ↔ the page's lifecycle | `navigation-scroll.ts` owns `scrollRestoration = 'manual'` and RESTORES the entry's saved offset at start, before its first save (a reload, or Back after a full load); `navigation-tabs.ts` owns the `BroadcastChannel`, closed on `pagehide` (it blocks the back/forward cache), reopened and the cache emptied on a persisted `pageshow`. A sheet `loadStylesheets` appends is `owned` at once, so an aborted navigation's sheets are retired by the next swap. A view transition is tracked by identity: an older one finishing never clears the running one. |
+| Router ↔ the page's lifecycle | `navigation-scroll.ts` owns `scrollRestoration = 'manual'` and RESTORES the entry's saved offset at start, before its first save (a reload, or Back after a full load). Full rule: `docs/history/render.md` |
 | Router ↔ islands | ONE bootstrap: the swap re-runs the inline hydration runtime, whose `each` visits a root once per tab (`el.__v`). Never add a second mount path for the router. Dispose = call what `el.__x` resolved to. |
 | Router head diff | only elements a SERVER document put in `<head>` (`documentHead`'s set) may be removed; a script-added one is the tab's. Scripts and stylesheets are never diffed. |
-| Router: nothing is sent twice | every fetch `cache: 'no-cache'` (#693), `redirect: 'manual'`, a POST never re-sent; the cache answers only a reusable 2xx and is emptied by every write signal ([full rule](../../docs/history/render.md#router-nothing-is-sent-twice)) |
+| Router: nothing is sent twice | every fetch `cache: 'no-cache'` (#693), `redirect: 'manual'`, a POST never re-sent; the cache answers only a reusable 2xx and is emptied by every write signal; an answer is bounded by `NAVIGATION_TIMEOUT_MS`, past it a network failure, a refresh's QUIET (`navigation-deadline.ts`) ([full rule](../../docs/history/render.md#router-nothing-is-sent-twice)) |
+| `Hole` | `hole.ts` imports only `@ultimat3/core/render-node` and is a branded array like `IslandNode`; every walker tests `isHoleNode` before `Array.isArray`. `render-html.ts`'s `HoleSink` is per render (`renderToHtml(tree, { islands, holes })`); only the CLI's `stream` branch passes one. Sinkless: children inline, so `budgets` weighs a hole's island; under a hole nested holes are inline |
+| `hydrateRuntime(directives, { async })` | async while a hole is open and no boot is in the document; `route-islands.ts`'s `streamScripts` decides. Body and hash unchanged. Proof: `packages/cli/e2e/stream-hole.e2e.test.ts`, which fails without it |
+| A hole's failure | `error` markup, the log line, `reportError(source: 'http')`, `X_TIMEOUT` for a deadline; nothing once the client cancelled |
 
 Cross-package: `@ultimat3/pwa` consumes route descriptors as **data**, never by import.
 Keep `RouteDescriptor` additive — removing a field breaks `sw.js` generation.

package/README.md

@@ -2,6 +2,8 @@
 
 The `route` primitive and the four render modes.
 
+`bun add @ultimat3/render` · guide: [Routes And Render Modes](https://github.com/developerz-ai/ultimate/wiki/Routes-And-Render-Modes)
+
 | Mode | Behavior | Use |
 |---|---|---|
 | `static` | built once, served as a file | marketing, docs |
@@ -34,6 +36,43 @@ cross-linked in. `enumeratePrerender()` answers params, `enumeratePrerenderEntri
 A key outside the three, a `lastmod` that is neither a string nor a `Date`, or `locales` that is
 not a list of names is `X_PRERENDER_FAILED`, naming the route file.
 
+## `<Hole>`: a subtree that arrives after the first flush
+
+`Hole` (from `@ultimat3/render`) marks what a `stream` page does not wait for. Its children are a
+thunk or an async component, started after the shell left, in the request's context.
+
+```tsx
+import { Hole } from '@ultimat3/render';
+import { Skeleton } from '@ultimat3/ui';
+import type { JSX } from 'solid-js';
+
+// Yours: the components and the read.
+type View = (props: { rows?: readonly unknown[] }) => JSX.Element;
+declare const Stats: View, StatsUnavailable: View;
+declare const statsQuery: (input: object) => Promise<readonly unknown[]>;
+
+const readStats = async () => <Stats rows={await statsQuery({})} />;
+
+export function Page() {
+  return <Hole fallback={<Skeleton lines={3} />} error={<StatsUnavailable />}>{readStats}</Hole>;
+}
+```
+
+| Case | What happens |
+|---|---|
+| `stream` | `fallback` is in the first flush; holes fill in completion order; the document closes when the last one settles |
+| `ssr`, `static`, `isr`, a test, `budgets` | one flush, so the hole is its children, inline. A hole's island is weighed; a throw is the render's |
+| nested | inline inside the outer hole |
+| a throw, or the 15 s deadline | `error`'s markup (default: hidden, empty), a log line, and `reportError(source: 'http')` |
+| status, redirect | `load`'s: decided before the flush. Under the CLI a `setCookie()`/`setRedirect()` inside a hole is `X_STREAM_ALREADY_FLUSHED`, the hole's error markup |
+| cancellation | each hole's `resolve` gets its own signal: aborted at its deadline (`X_TIMEOUT`) and on a disconnect; the CLI makes it the ambient `useContext().signal` |
+| an idle socket | while a hole is open, `<!---->` every `keepAliveMs` (`DEFAULT_STREAM_KEEPALIVE_MS`, 1 s): a write resets Bun's `idleTimeout` |
+
+`holeSink({ enter? })` from `@ultimat3/render/server` is the walk's sink (`renderToHtml(tree, { holes })`),
+for a host assembling its own stream; `enter(signal, run)` is the host's scope for a hole's children.
+`StreamHole` gains `error?` and `after?(outcome)` (asked on every reveal, failed ones too);
+`hydrateRuntime(directives, { async: true })` is the runtime for a document still parsing.
+
 ## `load` is the one server-side data seam
 
 Optional, and the only way a page gets data. It runs **once per render** and the result is handed
@@ -68,7 +107,7 @@ returns its data through `withStatus(404, data)`. The same object comes back, so
 `load`'s type, `meta`'s `data` or the page's props changes; every render mode reads the status off
 it (`routeStatusOf`), and a 4xx or 5xx is `robots: noindex` by construction, applied by the
 descriptor's `meta` after the route's own ran. Not a throw: a throw is the framework's error page,
-outside the app's shell, and `As of 2026-09-07` that was the only way to a 404 — ai-maxxing's
+outside the app's shell, and `As of 2026-09-07` that was the only way to a 404 — one adopter's
 `/fleet/nope` rendered the right page and answered 200. A 3xx is `X_ROUTE_STATUS_INVALID`. A
 redirect is `setRedirect(location, status)` from `@ultimat3/http`, called inside `load`: the page
 path answers that 3xx before rendering a document, `private, no-store` unless the route declares a
@@ -168,6 +207,15 @@ From code — an island, an app script — `navigate(url, { replace? })`, `refre
 island imports them from **`@ultimat3/render/client`**, never the barrel — see
 [Two entry points](#two-entry-points). [Navigating from code](../../wiki/Client-Navigation.md#navigating-from-code).
 
+`refresh()` is the same page for the same visitor (`navigation-refresh.ts`): no view transition,
+focus kept on the control the visitor was in (`markFocus`/`restoreFocus` in `navigation-dom.ts`: by
+`id`, else `name` in its form, else `[data-row]` + tag + place), no announcement, a navigation in
+flight never aborted for it, nothing under an open modal. `scheduleRefresh()` (`refresh-idle.ts`,
+on `/client`) is "a channel said the page changed": one running, one owed, held while the tab is
+hidden, a dialog or popover is open, a field has focus, text is selected, a navigation runs or
+within `QUIET_MS` (1 s) of input; nothing after a lost session and nothing without the router.
+[Client navigation](../../wiki/Client-Navigation.md#refresh-is-the-same-page).
+
 ## Mode invariants, checked at registration
 
 | Mode | Invariant | Error if violated |
@@ -177,7 +225,6 @@ island imports them from **`@ultimat3/render/client`**, never the barrel — see
 | `ssr` | cannot be prerendered | `X_ROUTE_MODE_INVALID` |
 | any but `ssr` | declares no `cache` — `static`/`isr` headers are the mode, a `stream` is always `private, no-store` | `X_ROUTE_MODE_INVALID` |
 | gated (`policy`) | its `cache` is never `public`/`immutable` — one actor's document in a shared cache | `X_ROUTE_MODE_INVALID` |
-| `stream` | at least one `<Suspense>` boundary | `X_ROUTE_MODE_INVALID` |
 
 Plus surface rules: `site/` allows `static | isr | ssr`, `app/` allows `stream | ssr`, and a `site/` route that opts into hydration without a `budget.js`
 is a build error.
@@ -400,14 +447,15 @@ type DispatchProps = {
 };
 const Picker = (props: { readonly models: readonly Model[] }) => <ul>{props.models.length}</ul>;
 
-export function mount(el: HTMLElement, props: DispatchProps): void {
+export function mount(el: HTMLElement, props: DispatchProps): () => void {
   const [models, setModels] = createSignal<readonly Model[]>(props.models);
   if (props.modelsEndpoint !== undefined) {
     fetch(props.modelsEndpoint, { credentials: 'same-origin' })
       .then((response) => response.json())
       .then((rows: readonly Model[]) => setModels(rows));
   }
-  render(() => <Picker models={models()} />, el);
+  // The disposer, returned: the client router calls it on navigation (X_ISLAND_DISPOSER_MISSING).
+  return render(() => <Picker models={models()} />, el);
 }
 ```
 
@@ -509,7 +557,7 @@ side effect. Anything that loads an app's source — `x dev`, `x build`, `server
 `@ultimat3/render/client` is the **browser** entry — what an island or a page script calls:
 `navigate`, `refresh`, `openModal`, `closeModal`, `NavigateToOptions`,
 `NavigationModalPathInvalidError`, `NAVIGATE_EVENT`, `NAVIGATED_EVENT`, `NAVIGATION_ERROR_EVENT`,
-`disposeIslands`.
+`disposeIslands`, `scheduleRefresh`.
 The barrel bundles for the browser but its `sideEffects` keeps `errors.ts` — render's code table,
 and core's and schema's titles tables behind it — in every chunk that reaches it; this entry's
 graph is the navigation helpers plus `@ultimat3/core/page` (`client-bundle.test.ts`). `As of
@@ -590,8 +638,10 @@ a job boundary the class is gone and the `code` is what survives — match on th
 | `ISLAND_HOLD_ATTRIBUTE`, `ISLAND_HOLD_MS`, `ISLAND_HOLD_REVEAL` | a held island's marker, and the cap after which it shows its server markup regardless |
 | `parseByteBudget`, `defaultIslandBudget` | the `'40kb'` budget grammar, and the ceiling a declared island earns |
 | `mergeHead`, `renderHead`, `themeScript` | `<head>` merge + the one inlined script; it stamps `data-theme` and, beside it, the fallback itself as `data-theme-default` for `@ultimat3/ui`'s `clearTheme`/`watchOsTheme` |
+| `zoneScript`, `zoneScriptBody`, `ZONE_SCRIPT_MAX_BYTES` | `time.detect`'s inline script, `app/` documents only: writes `x_timezone_detected` from `Intl`'s zone, which `@ultimat3/http` ranks below every chosen zone. Under 200 B; tag and CSP hash from one body |
 | `clientNavigationTags`, `linkVerdict`, `formVerdict`, `responseVerdict`, `reusable`, `mayPrefetch`, `NAVIGATION_*` (`NAVIGATION_ERROR_EVENT`‡), `NAVIGATE_EVENT`‡, `NAVIGATED_EVENT`‡ | the client router's document tags and its pure rules; the router itself is `@ultimat3/render/navigation`, built and served by the CLI |
 | `navigate`‡, `refresh`‡, `openModal`‡, `closeModal`‡, `NavigateToOptions`‡, `NavigationModalPathInvalidError`‡ | navigating from code: the router when the page has one, the browser's own load when not. Import from `/client` in an island |
+| `scheduleRefresh`‡ | a `refresh()` once the visitor is idle, coalesced; never a reload |
 | `disposeIslands` (on `/client` only) | dispose the islands mounted under an element: what the router does on a swap, for an island that drops markup holding other islands |
 | `modalAddress`, `modalLocation`, `addressOf`, `presentation`, `modalHistory`, `leaveModal`, `NAVIGATION_PRESENTATION_META`, `NAVIGATION_MODAL_ATTRIBUTE` | route-presented modals (`navigation: 'modal'`): the hash grammar, when an answer is a modal, and what leaving one does to history |
 | `declaresModal`, `parseModalRoutes`, `modalRouteList`, `ModalRoutes`, `NAVIGATION_MODALS_META`, `NAVIGATION_MODAL_BODY_ATTRIBUTE`, `NAVIGATION_MODAL_CLOSE_ATTRIBUTE`, `NAVIGATION_MODAL_SKELETON_ATTRIBUTE` | the modal that opens on the click: the meta naming a surface's modal routes (composed by the server, read by the router) and the frame's attributes, styled by `@ultimat3/ui` |
@@ -621,9 +671,11 @@ a job boundary the class is gone and the `code` is what survives — match on th
   a tag bust and evicts their renders in flight, where the default `'stale'` answers the old copy
   once more: the next request on this replica and on each one the broadcast reaches; a replica
   that misses it serves its copy until `ttl`. `maxStale` bounds how long past its `ttl` a copy is
-  served (`0`: never; the default under `'purge'`). `query: ['page']` (or `[]`) is the only part
-  of the query string in the key and in the URL `load` is given (`isrRequestUrl`†); a route that
-  declares none still keys on the whole query string, and `x verify` says so. **Never stored:** a
+  served (`0`: never; the default under `'purge'`). `query: ['page']` is the only part of the
+  query string in the key and in the URL `load` is given (`isrRequestUrl`†); a route that declares
+  none keys on none. With no declared origin the key carries the request's (`isrKey`†'s third
+  argument, `__x_origin`), and with one `load` is given that origin. `isr` and `static` render as
+  nobody: no actor, no inbound header, the default zone. Per-visitor means `ssr`. **Never stored:** a
   5xx (the last good page keeps answering, stale; a 1 s cooldown stops a render per request), a
   render whose `load` returned `noStore(data)`, one invalidated while it ran, a throw, a redirect.
 - **A store two processes write needs `IsrStore.tagFence`**† — `sample` / `bump` / an atomic

package/package.json

@@ -1,7 +1,18 @@
 {
   "name": "@ultimat3/render",
-  "version": "29.4.0",
+  "version": "30.1.0",
   "description": "The route primitive and the five render modes: static, isr, ssr, stream, spa.",
+  "keywords": [
+    "ultimate",
+    "bun",
+    "framework",
+    "ssr",
+    "ssg",
+    "isr",
+    "streaming",
+    "solidjs"
+  ],
+  "homepage": "https://github.com/developerz-ai/ultimate/wiki/Routes-And-Render-Modes",
   "license": "MIT",
   "type": "module",
   "sideEffects": [
@@ -40,11 +51,11 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/cache": "29.4.0",
-    "@ultimat3/core": "29.4.0",
-    "@ultimat3/http": "29.4.0",
-    "@ultimat3/i18n": "29.4.0",
-    "@ultimat3/seo": "29.4.0",
-    "sass": "1.105.1"
+    "@ultimat3/cache": "30.1.0",
+    "@ultimat3/core": "30.1.0",
+    "@ultimat3/http": "30.1.0",
+    "@ultimat3/i18n": "30.1.0",
+    "@ultimat3/seo": "30.1.0",
+    "sass": "1.105.2"
   }
 }

package/src/client-pins-tag.ts

@@ -0,0 +1,23 @@
+/**
+ * Every pinned action and query the server serves, as a `<head>` tag:
+ * `<meta name="ultimate-pins" content="…">`, read by `@ultimat3/core`'s `renderedActionPin` /
+ * `renderedQueryPin` for every browser caller that reaches one by NAME. Principal-free, so every
+ * document may carry it — and an app that pins nothing writes no tag and renders the same bytes.
+ */
+
+import type { ClientPins } from '@ultimat3/core';
+import { CLIENT_PINS_META, encodeClientPins } from '@ultimat3/core';
+import type { HeadTag } from './head';
+
+/** `pins` is what the server's registries declare, read per render — `defineApi` may run late. */
+export function clientPinTags(pins: ClientPins): readonly HeadTag[] {
+  const content = encodeClientPins(pins);
+  if (content === undefined) return [];
+  return [
+    {
+      kind: 'meta',
+      key: `meta:${CLIENT_PINS_META}`,
+      attrs: { name: CLIENT_PINS_META, content },
+    },
+  ];
+}

package/src/client.ts

@@ -1,10 +1,10 @@
 // `@ultimat3/render/client` — THE browser entry of this package: what an island or a page script
 // may call, and nothing that drags the rest along. The `.` barrel bare-retains `errors.ts` (render's
 // whole code table, registered at import, plus core's titles tables); this entry's graph is
-// `navigation-api.ts`, `navigation-errors.ts`, `island-dispose.ts`, the pure rules and
-// `@ultimat3/core/page`, held there by `client-bundle.test.ts`.
+// `navigation-api.ts`, `navigation-errors.ts`, `island-dispose.ts`, `refresh-idle.ts`, the pure
+// rules and `@ultimat3/core/page`, held there by `client-bundle.test.ts`.
 //
-//   import { disposeIslands, navigate, openModal, refresh } from '@ultimat3/render/client';
+//   import { navigate, refresh, scheduleRefresh } from '@ultimat3/render/client';
 //
 // The same names stay exported from `.` for compatibility; an island imports them from here.
 
@@ -14,3 +14,5 @@ export type { NavigateToOptions } from './navigation-api';
 export { closeModal, navigate, openModal, refresh } from './navigation-api';
 export { NavigationModalPathInvalidError } from './navigation-errors';
 export { NAVIGATE_EVENT, NAVIGATED_EVENT, NAVIGATION_ERROR_EVENT } from './navigation-rules';
+// A channel said the page changed: re-read it once the visitor is idle (`refresh-idle.ts`).
+export { scheduleRefresh } from './refresh-idle';

package/src/css-modules.ts

@@ -230,7 +230,7 @@ const CHARSET_HEAD = /^\uFEFF?(?:@charset\s+"[^"]*"\s*;\s*)?/u;
  * decoded as UTF-8 by every browser. It is wrong about a fragment. The registry concatenates
  * modules verbatim, so every module after the first that holds a `content: '·'` began with a BOM
  * glued to its first selector — `\uFEFF.dashboard_256ee8e0{display:grid}` — which the browser reads
- * as an unparseable selector and drops with its whole rule. Measured on ai-maxxing's home
+ * as an unparseable selector and drops with its whole rule. Measured on one adopter's home
  * stylesheet, 2026-09-06: seven modules, seven first rules gone, the dashboard's grid container
  * painting `display: block` with only the UA rule in Chrome's matched styles. The bundle is served
  * `text/css; charset=utf-8` by the route, so no sheet needs to claim its encoding at all.

package/src/head-attributes.ts

@@ -0,0 +1,57 @@
+// Single responsibility: the attributes of one `<head>` tag. `attributePair` is the rule, with one
+// exception for what a `link` href may name, and a dropped attribute is said out loud in dev: an
+// icon or an alternate that prints with no href otherwise fails with nothing to read.
+
+import { escapeHtml, isLocal, logger, safeUrl } from '@ultimat3/core';
+import type { HeadTag } from './head';
+import { attributePair } from './html';
+
+/** A declared app deep link. Spelled exactly: a control character in it is not this scheme. */
+const APP_LINK = /^(?:android-app|ios-app):\/\//i;
+
+/** Past this many a row is spreading new keys every render: stop remembering, stop warning. */
+const MAX_WARNED_DROPS = 256;
+const warnedDrops = new Set<string>();
+
+/**
+ * A `link` href is fetched or read as metadata, never navigated, so `safeUrl` answers it as it does
+ * a rendered `src`: a raster `data:image/` stays (an inline favicon), SVG and every other scheme do
+ * not. `rel="alternate"` alone is never fetched at all, only read by a crawler, so the two app-link
+ * schemes are kept there, on the exact value: `alternate stylesheet` is a fetch.
+ */
+function linkHref(tag: HeadTag, value: string): string | null {
+  const url = safeUrl(value, 'src');
+  if (url !== null) return url;
+  const rel = tag.attrs?.['rel'];
+  const isAlternate = typeof rel === 'string' && rel.trim().toLowerCase() === 'alternate';
+  return isAlternate && APP_LINK.test(value) ? value : null;
+}
+
+function pairOf(tag: HeadTag, name: string, value: string | boolean): string | null {
+  if (tag.kind !== 'link' || name.toLowerCase() !== 'href' || typeof value !== 'string') {
+    return attributePair(name, value);
+  }
+  const url = linkHref(tag, value);
+  return url === null ? null : `${name}="${escapeHtml(url)}"`;
+}
+
+/** Names the tag and the attribute, never the value: it is a row's, and this is a log line. */
+function warnDropped(tag: HeadTag, name: string): void {
+  if (!isLocal({ fallback: 'production' })) return;
+  const seen = `${tag.key}\n${name}`;
+  if (warnedDrops.has(seen) || warnedDrops.size >= MAX_WARNED_DROPS) return;
+  warnedDrops.add(seen);
+  logger.warn('head.attribute_dropped', { tag: tag.key, attribute: name });
+}
+
+/** The attribute string of `tag`, leading space included, or `''`. */
+export function headAttributes(tag: HeadTag): string {
+  const parts: string[] = [];
+  for (const [name, value] of Object.entries(tag.attrs ?? {})) {
+    const pair = pairOf(tag, name, value);
+    if (pair !== null) parts.push(pair);
+    // `false` is how a tag says "not this one", so nothing was lost.
+    else if (value !== false) warnDropped(tag, name);
+  }
+  return parts.length === 0 ? '' : ` ${parts.join(' ')}`;
+}

package/src/head.ts

@@ -12,7 +12,8 @@ import type { RouteMeta } from '@ultimat3/seo';
 import { BudgetExceededError } from './errors';
 // The raw-text escapers are `html.ts`'s and the text/attribute table is core's `escapeHtml` — a
 // second one is how a character ends up missing.
-import { escapeJsonContent, escapeRawTextContent, isAttributeName } from './html';
+import { headAttributes } from './head-attributes';
+import { escapeJsonContent, escapeRawTextContent } from './html';
 
 export type HeadTagKind = 'title' | 'base' | 'meta' | 'link' | 'script' | 'style';
 
@@ -114,15 +115,9 @@ export function renderHead(tags: readonly HeadTag[]): string {
 }
 
 function renderTag(tag: HeadTag): string {
-  // The NAME is emitted verbatim before the `=` and is escaped nowhere, so a key carrying a space
-  // carries a whole second attribute with it — an app spreading a row into `attrs` put a live
-  // event handler in `<head>`. Same predicate `attributePair` uses, never a second copy.
-  const attrs = Object.entries(tag.attrs ?? {})
-    .filter(([name]) => isAttributeName(name))
-    .map(([name, value]) =>
-      value === true ? ` ${name}` : ` ${name}="${escapeHtml(String(value))}"`,
-    )
-    .join('');
+  // `attributePair`, the package's one attribute rule: an app spreading a row into `attrs` reaches
+  // this sink exactly as it reaches a JSX spread. A second copy printed `onload` and `javascript:`.
+  const attrs = headAttributes(tag);
   if (VOID_KINDS.has(tag.kind)) return `<${tag.kind}${attrs}>`;
   const raw = tag.content ?? '';
   return `<${tag.kind}${attrs}>${contentOf(tag, raw)}</${tag.kind}>`;

package/src/hole.ts

@@ -0,0 +1,32 @@
+// `<Hole>`: the marker that makes a subtree of a `stream` page arrive after the first flush. It
+// decides nothing, it only names the three trees. `renderNode` calls a component with no view of
+// the walk, so the walker in `render-html.ts` is what sees this node and picks what it means.
+
+import { HOLE_NODE } from '@ultimat3/core/render-node';
+
+export interface HoleProps {
+  /** Markup in the first flush, until the hole fills. Rendered at shell time. */
+  readonly fallback: unknown;
+  /** Replaces the fallback when `children` throw or miss the deadline. Rendered at shell time. */
+  readonly error?: unknown;
+  /** Awaited after the first flush. A thunk or an async child is what makes the wait start there. */
+  readonly children?: unknown;
+}
+
+/**
+ * Array-based for the reason `IslandNode` states: `ArrayElement` is the one object shape the
+ * configured `JSX.Element` admits, so this is what lets `<Hole>` be an ordinary JSX component.
+ */
+export interface HoleNode extends Array<never> {
+  readonly [HOLE_NODE]: true;
+  readonly props: HoleProps;
+}
+
+/** Tested BEFORE `Array.isArray` by the walker: the array branch would render it as nothing. */
+export function isHoleNode(value: unknown): value is HoleNode {
+  return typeof value === 'object' && value !== null && HOLE_NODE in value;
+}
+
+export function Hole(props: HoleProps): HoleNode {
+  return Object.assign([] as never[], { [HOLE_NODE]: true as const, props });
+}

package/src/html.ts

@@ -119,8 +119,7 @@ const REFUSED_ATTRIBUTES: ReadonlySet<string> = new Set(['srcdoc']);
  */
 const ATTRIBUTE_NAME = /^[A-Za-z_:][-A-Za-z0-9_:.]*$/;
 
-/** Exported for `head.ts`, the package's other attribute sink. One predicate, never two. */
-export const isAttributeName = (name: string): boolean => ATTRIBUTE_NAME.test(name);
+const isAttributeName = (name: string): boolean => ATTRIBUTE_NAME.test(name);
 
 const cssProperty = (name: string): string =>
   name.startsWith('--') ? name : name.replace(/[A-Z]/g, (letter) => `-${letter.toLowerCase()}`);

package/src/hydrate.ts

@@ -295,14 +295,27 @@ export const HYDRATE_RUNTIME_BODIES: readonly string[] = [false, true].flatMap((
   ),
 );
 
+export interface HydrateRuntimeOptions {
+  /**
+   * Run as soon as the script is parsed. An inline module is otherwise deferred until parsing ends,
+   * and a document with a `<Hole>` open is still parsing: its shell's islands would stay dead until
+   * the slowest hole closes. The body, so its CSP hash, is the same either way.
+   */
+  readonly async?: boolean;
+}
+
 /**
  * Emit only the runtime the page's islands actually use. A page of `never` islands gets
  * the empty string — an unused strategy must not cost a byte.
  */
-export function hydrateRuntime(directives: readonly IslandDirective[]): string {
+export function hydrateRuntime(
+  directives: readonly IslandDirective[],
+  options: HydrateRuntimeOptions = {},
+): string {
   const needed = requiredStrategies(directives);
   if (needed.size === 0) return '';
-  return `<script type="module">${runtimeBody(needed, holds(directives))}</script>`;
+  const tag = options.async === true ? '<script type="module" async>' : '<script type="module">';
+  return `${tag}${runtimeBody(needed, holds(directives))}</script>`;
 }
 
 /** Rough emitted size of the hydration runtime for a page, for the budget check. */

package/src/index.ts

@@ -18,6 +18,7 @@ export type { AssetExtension, AssetPath, AssetResolver } from './asset';
 export { ASSET_DIR, ASSET_EXTENSIONS, asset, assetPathProblem, setAssetResolver } from './asset';
 /** The `<meta name="ultimate-path-style">` core's `actionPath` reads — a non-default style only. */
 export { clientPathStyleTags } from './client-path-style-tag';
+export { clientPinTags } from './client-pins-tag';
 /** The `<meta name="ultimate-scope">` core's `pageClient()` reads, on private documents only. */
 export {
   clientPersistTags,
@@ -72,6 +73,8 @@ export {
   themeScriptBody,
 } from './head';
 export { seoRenderers } from './head-seo';
+export type { HoleNode, HoleProps } from './hole';
+export { Hole } from './hole';
 export type { IslandDirective } from './hydrate';
 export {
   emitIslandAttributes,
@@ -97,7 +100,7 @@ export type { IslandProps, JsonValue } from './island-props';
 export { ISLAND_PROPS_MAX_BYTES } from './island-props';
 export { parseByteBudget } from './islands';
 export type { JsxComponent, JsxNode, JsxProps } from './jsx';
-export { Fragment, h, isJsxNode, JSX_NODE } from './jsx';
+export { Fragment, h, isJsxNode } from './jsx';
 export type { ModeCheckContext, ModeSpec, RouteShape } from './modes';
 export {
   assertModeInvariants,
@@ -167,6 +170,7 @@ export {
 } from './navigation-rules';
 export type { ClientNavigationHead } from './navigation-tags';
 export { clientNavigationTags, modalRouteList } from './navigation-tags';
+export { scheduleRefresh } from './refresh-idle';
 export type {
   MountedRouteInput,
   RegisterRouteInput,
@@ -252,3 +256,4 @@ export {
   surfaceAllows,
   surfaceOf,
 } from './surfaces';
+export { ZONE_SCRIPT_MAX_BYTES, zoneScript, zoneScriptBody } from './zone-script';

package/src/island-dispose.ts

@@ -18,6 +18,16 @@ const ISLAND_ATTRIBUTE = 'data-x-island';
  */
 const released = new WeakSet<Element>();
 
+/**
+ * A disposer that threw, handed to the platform's `reportError`: it reaches `window`'s `error`
+ * listeners (the client-errors script among them) as an uncaught error would, once, and the
+ * router's swap carries on. Re-thrown where the platform has none, so it is never swallowed.
+ */
+function reportDisposeFailure(error: unknown): void {
+  if (typeof globalThis.reportError !== 'function') throw error;
+  globalThis.reportError(error);
+}
+
 /**
  * Disposes every island mounted under `root` — `root` itself included when it is an island's
  * wrapper — unless `kept` claims it, and answers how many had a boot to settle. For each one the
@@ -29,7 +39,8 @@ const released = new WeakSet<Element>();
  * the pending boot mounts nothing into markup that left the document — a mount nobody would ever
  * dispose. Works on a detached subtree, so the order against removing `root` does not matter.
  * Idempotent per island: one already let go of is skipped and not counted; one `kept` claimed is
- * untouched, so a later call may still dispose it.
+ * untouched, so a later call may still dispose it. A disposer that throws is reported, not left as
+ * an unhandled rejection: `reportDisposeFailure`.
  */
 export function disposeIslands(
   root: Element,
@@ -50,7 +61,12 @@ export function disposeIslands(
     disposed += 1;
     el.__x.then(
       (dispose) => {
-        if (typeof dispose === 'function') dispose();
+        if (typeof dispose !== 'function') return;
+        try {
+          dispose();
+        } catch (error: unknown) {
+          reportDisposeFailure(error);
+        }
       },
       () => undefined,
     );

package/src/island.ts

@@ -7,6 +7,7 @@
  */
 
 import { renderFixShellArg } from '@ultimat3/core';
+import { ISLAND_NODE } from '@ultimat3/core/render-node';
 import { IslandInvalidError } from './errors';
 import type { JsonValue } from './island-props';
 import type { JsxProps } from './jsx';
@@ -18,9 +19,6 @@ import type { JsxProps } from './jsx';
  */
 export const ISLAND_EXTENSION = '.island.tsx';
 
-/** Registered globally so two copies of this module agree on what an island node is. */
-export const ISLAND_NODE: unique symbol = Symbol.for('ultimate.render.island') as never;
-
 /** Characters that would break out of the `data-x-entry` attribute the specifier lands in. */
 const UNSAFE_SPECIFIER = /["'`<>\s\\]/;
 

package/src/jsx.ts

@@ -4,8 +4,7 @@
  * thing that decides what a tree means. This is what the `.tsx` loader compiles every element to.
  */
 
-/** Registered on the global symbol registry: two copies of this module must agree on a node. */
-export const JSX_NODE: unique symbol = Symbol.for('ultimate.render.jsx') as never;
+import { JSX_NODE } from '@ultimat3/core/render-node';
 
 export type JsxProps = Readonly<Record<string, unknown>>;