@ultimat3/render 27.4.0 → 27.6.0

package/CLAUDE.md

@@ -63,7 +63,7 @@ axiom 6). Never `cli` (upward).
 | A runtime that calls `boot` | TERMINATES the chain: `idle`/`visible` end in `.catch(hush)`, `interaction` passes `off` as the rejection arm. `hydrate-runtime.test.ts` reds on an unhandled rejection. |
 | `idle` replays too | `idle` and `interaction` share ONE `catchUp(el)` in `hydrate.ts` (capture listeners for `data-x-events`, default `click`; a queue; `aim`; one flush). A caught event wakes an `idle` island early; each event replays once. `hydrate-replay.test.ts`. |
 | Where `interaction` replays | `aim(el, ev)`, never `ev.target` — `mount` usually clears the root, detaching the pressed node. Kept → original target; replaced → `path(el, target)`'s structural walk (same tag, same place), then `document.elementFromPoint(ev.clientX, ev.clientY)` (unless `ev.detail === 0`), then the island root. A hit outside the island falls back to the root. `hydrate-replay.test.ts`. |
-| A held island | `hold` on the collector (the host decides — the CLI holds realtime islands on a page-boot document); `island-hold.ts` owns the attribute, the inline `visibility:hidden`, the cap `ISLAND_HOLD_MS` and the runtime part. Emitted right after the prelude; booted at once, revealed TOGETHER on both mount arms, at the cap, or by CSS (`ISLAND_HOLD_REVEAL`, keyframes in `@ultimat3/ui`'s `global.scss`) — never hidden for good. `catchUp`'s `on` lets go after a mount it did not flush. `island-hold.test.ts`, `island-hold-replay.test.ts`. |
+| A held island | `hold` on the collector (the host decides — the CLI holds store-reading realtime islands on a page-boot document); `island-hold.ts` owns the attribute, the inline `visibility:hidden`, the cap `ISLAND_HOLD_MS` and the runtime part. Emitted right after the prelude; booted at once, revealed TOGETHER on both mount arms, at the cap, or by CSS (`ISLAND_HOLD_REVEAL`, keyframes in `@ultimat3/ui`'s `global.scss`) — never hidden for good. `catchUp`'s `on` lets go after a mount it did not flush. `island-hold.test.ts`, `island-hold-replay.test.ts`. |
 | `idle`'s deadline | `IDLE_HYDRATE_TIMEOUT_MS`, interpolated INTO the runtime string and exported for `x shot`'s settle. |
 | Route truth | `registry.ts`. Never a second route list and never a second matcher — `@ultimat3/http`'s trie (`stages.ts`) serves requests. `routeFor` is an exact-path `Map` lookup. |
 | Route filename | `page.tsx` under `site/`/`app/` — `ROUTE_FILENAME`, keyed by `RouteSurface`. Anything else is `X_ROUTE_FILE_INVALID`, any file under `api/` or `shared/` included. |

package/README.md

@@ -456,10 +456,11 @@ and a second copy of the number is a settle that shoots early and calls a health
 
 **A held island** (`data-x-hold`, `As of 2026-10`) is one whose server markup must not paint before
 it mounts — an offline reload's cached count under a queued write (#506). The collector's
-`hold: (src) => boolean` names them (the host's call: `@ultimat3/cli` holds realtime islands on a
-document that carries the page boot); the wrapper is `visibility:hidden` from its first byte, the
+`hold: (src) => boolean` names them (the host's call: `@ultimat3/cli` holds, on a document that
+carries the page boot, the realtime islands that read the record store or the outbox — never one
+that only follows a channel's events); the wrapper is `visibility:hidden` from its first byte, the
 runtime boots it at once whatever the strategy, and reveals it when `mount()` settles either way or
-at `ISLAND_HOLD_MS` (3000), whichever comes first — and at the same cap by CSS alone (`ISLAND_HOLD_REVEAL`, keyframes in `@ultimat3/ui`'s `global.scss`), so a page with no script still shows the markup. Only a page holding an island pays for that part
+at `ISLAND_HOLD_MS` (3000), whichever comes first — and at the same cap by CSS alone (`ISLAND_HOLD_REVEAL`, keyframes in `@ultimat3/ui`'s `global.scss`), so a page with no script still shows the markup — and at once, not at the cap, where the browser says scripting is off (`@media (scripting: none)` in the same sheet). Only a page holding an island pays for that part
 of the runtime, and `HYDRATE_RUNTIME_BODIES` carries both variants.
 
 ## Two entry points
@@ -486,7 +487,8 @@ 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`.
+`NavigationModalPathInvalidError`, `NAVIGATE_EVENT`, `NAVIGATED_EVENT`, `NAVIGATION_ERROR_EVENT`,
+`disposeIslands`.
 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
@@ -497,6 +499,24 @@ graph is the navigation helpers plus `@ultimat3/core/page` (`client-bundle.test.
 import { navigate, refresh } from '@ultimat3/render/client';
 ```
 
+**`disposeIslands(root, kept?)`** (`island-dispose.ts`, `As of 2026-10`) is the one protocol for
+letting go of mounted islands: every island under `root` — `root` too, when it is an island's
+wrapper — has what its `mount` returned called once its boot resolves, an island whose boot never
+started is settled so it mounts nothing, and the count of boots settled is returned. Idempotent
+per island: a second call over the same subtree runs no disposer twice and returns 0. The router
+calls it on the body it swaps out and on a modal it closes. An island that replaces markup holding
+other islands calls it on each element it drops (attached or already detached), instead of reading
+the runtime's private `el.__x`:
+
+```ts
+import { disposeIslands } from '@ultimat3/render/client';
+
+/** The nodes an island is about to take off the page for good. */
+export function release(dropped: readonly Node[]): void {
+  for (const node of dropped) if (node instanceof Element) disposeIslands(node);
+}
+```
+
 ## Error classes
 
 Every error class `src/index.ts` exports, for `instanceof` inside one process. Across a wire or
@@ -549,6 +569,7 @@ a job boundary the class is gone and the `code` is what survives — match on th
 | `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` |
 | `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 |
+| `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 |
 | `clientPathStyleTags`, `CLIENT_PATH_STYLE_META` | `<meta name="ultimate-path-style">` — the action path style the server serves, for the browser's typed client. No tag for `'resource'`, the default |
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/render",
-  "version": "27.4.0",
+  "version": "27.6.0",
   "description": "The route primitive and the five render modes: static, isr, ssr, stream, spa.",
   "license": "MIT",
   "type": "module",
@@ -40,11 +40,11 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/cache": "27.4.0",
-    "@ultimat3/core": "27.4.0",
-    "@ultimat3/http": "27.4.0",
-    "@ultimat3/i18n": "27.4.0",
-    "@ultimat3/seo": "27.4.0",
+    "@ultimat3/cache": "27.6.0",
+    "@ultimat3/core": "27.6.0",
+    "@ultimat3/http": "27.6.0",
+    "@ultimat3/i18n": "27.6.0",
+    "@ultimat3/seo": "27.6.0",
     "sass": "1.105.1"
   }
 }

package/src/client.ts

@@ -1,13 +1,15 @@
 // `@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`, the pure rules and `@ultimat3/core/page`, held there
-// by `client-bundle.test.ts`.
+// `navigation-api.ts`, `navigation-errors.ts`, `island-dispose.ts`, the pure rules and
+// `@ultimat3/core/page`, held there by `client-bundle.test.ts`.
 //
-//   import { navigate, openModal, refresh } from '@ultimat3/render/client';
+//   import { disposeIslands, navigate, openModal, refresh } from '@ultimat3/render/client';
 //
 // The same names stay exported from `.` for compatibility; an island imports them from here.
 
+// An island that drops markup holding other islands releases them first: `disposeIslands(node)`.
+export { disposeIslands } from './island-dispose';
 export type { NavigateToOptions } from './navigation-api';
 export { closeModal, navigate, openModal, refresh } from './navigation-api';
 export { NavigationModalPathInvalidError } from './navigation-errors';

package/src/island-dispose.ts

@@ -0,0 +1,59 @@
+// Letting go of mounted islands: the one protocol for calling what each island's `mount` returned.
+// The client router uses it when it swaps a page or closes a modal; an island that replaces markup
+// holding OTHER islands (a live list redrawing rows whose menus are islands) uses it on the nodes
+// it drops, through `@ultimat3/render/client`. Nothing else may read `el.__x`.
+
+/** What `hydrate.ts`'s runtime leaves on an island root: the boot promise. */
+interface IslandElement extends Element {
+  __x?: Promise<unknown>;
+}
+
+const ISLAND_ATTRIBUTE = 'data-x-island';
+
+/**
+ * Islands this module already let go of. A disposer runs ONCE: a second call over the same subtree
+ * (an island that released its rows, then the router swapping the page they were on) would
+ * otherwise schedule each `mount`'s return twice, and count as a boot the resolved promise the
+ * first call left on an island that never started. Weak, so a dropped element is not kept alive.
+ */
+const released = new WeakSet<Element>();
+
+/**
+ * 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
+ * disposer is what its `mount` returned (held by `el.__x`), called once that boot resolves; a
+ * `mount` that returned nothing has nothing to call. A rejected boot has nothing to dispose, and
+ * the rejection is already on the element as `data-x-failed`. An island whose boot has not STARTED
+ * (an `idle` one still waiting for the browser, a `visible` one never scrolled to) is settled
+ * instead: the hydration runtime's `boot` answers an element that already has `__x` with it, so
+ * 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.
+ */
+export function disposeIslands(
+  root: Element,
+  kept: (el: Element) => boolean = () => false,
+): number {
+  let disposed = 0;
+  const under = root.querySelectorAll<IslandElement>(`[${ISLAND_ATTRIBUTE}]`);
+  const islands: Iterable<IslandElement> = root.hasAttribute(ISLAND_ATTRIBUTE)
+    ? [root, ...under]
+    : under;
+  for (const el of islands) {
+    if (released.has(el) || kept(el)) continue;
+    released.add(el);
+    if (el.__x === undefined) {
+      el.__x = Promise.resolve();
+      continue;
+    }
+    disposed += 1;
+    el.__x.then(
+      (dispose) => {
+        if (typeof dispose === 'function') dispose();
+      },
+      () => undefined,
+    );
+  }
+  return disposed;
+}

package/src/island-hold.ts

@@ -1,7 +1,8 @@
 // A HELD island (#506): server markup that must not paint before the island mounts, because what
 // it shows can be older than what the page will show — an offline reload's cached count, under a
 // queued write the mount rebuilds. Hidden from its first byte, booted at once, revealed when the
-// mount settles or at the cap. Who is held is the renderer's caller's call (`hold` on the collector).
+// mount settles or at the cap. Who is held is the renderer's caller's call (`hold` on the collector):
+// only an island with page state to restore — server markup nothing will contradict is never hidden.
 
 /** On a held island's wrapper until the runtime reveals it; what the runtime finds it by. */
 export const ISLAND_HOLD_ATTRIBUTE = 'data-x-hold';
@@ -17,7 +18,9 @@ export const ISLAND_HOLD_MS = 3_000;
 /**
  * The keyframes that reveal a held island with no script at all — JS off, the runtime blocked, a
  * strategy part that threw before the hold could run. Defined in `@ultimat3/ui`'s `global.scss`
- * (this package may not import `ui`; `island-hold-replay.test.ts` holds the two spellings equal).
+ * (this package may not import `ui`; `island-hold-replay.test.ts` holds the two spellings equal),
+ * beside the `@media (scripting: none)` rule that cancels the hold at once where the browser says
+ * scripting is off: the keyframes are the cap for everything that rule cannot see.
  */
 export const ISLAND_HOLD_REVEAL = 'ultimate-hold-reveal';
 

package/src/navigation-modal.ts

@@ -6,6 +6,7 @@
  * `navigation.ts` decides WHEN (`navigation-modal-rules.ts`); this file only shows and hides.
  */
 
+import { disposeIslands } from './island-dispose';
 import { metaOf } from './navigation-fetch';
 import { entryOf, STATE_KEY, withoutFragment } from './navigation-history';
 import {
@@ -17,7 +18,7 @@ import {
   type PresentationFacts,
   presentation,
 } from './navigation-modal-rules';
-import { disposeIslands, runScripts } from './navigation-swap';
+import { runScripts } from './navigation-swap';
 
 export interface ModalController {
   /** The open modal's address (`/runs/new`), or `undefined`. */
@@ -106,7 +107,7 @@ export function modalController(
     dialog = undefined;
     openAt = undefined;
     leaving = false;
-    disposeIslands(open, () => false);
+    disposeIslands(open);
     if (open.open) open.close();
     open.remove();
     doc.title = title;
@@ -199,7 +200,7 @@ export function modalController(
       // One modal at a time: the next address replaces this one's content, in the same dialog.
       // Closed as `dismiss` closes it — no longer `dialog` — so its own `close` event, queued or
       // (in any engine that fires it at once) synchronous, is never read as the visitor closing.
-      disposeIslands(open, () => false);
+      disposeIslands(open);
       dialog = undefined;
       if (open.open) open.close();
     }

package/src/navigation-swap.ts

@@ -5,14 +5,9 @@
  * island bootstrap (`hydrate.ts`'s runtime) over the new body. There is no second mount path.
  */
 
+import { disposeIslands } from './island-dispose';
 import { NAVIGATION_PERSIST_ATTRIBUTE } from './navigation-rules';
 
-/** What `hydrate.ts`'s runtime leaves on an island root: the boot promise and the visited mark. */
-interface IslandElement extends Element {
-  __x?: Promise<unknown>;
-}
-
-const ISLAND_SELECTOR = '[data-x-island]';
 const STYLESHEET = 'link[rel~="stylesheet"]';
 
 const isStylesheet = (el: Element): boolean =>
@@ -81,33 +76,6 @@ export function loadStylesheets(
   ).then(() => undefined);
 }
 
-/**
- * Calls each island's disposer — what its `mount` returned, held by `el.__x` — unless the island
- * is carried across. A rejected boot has nothing to dispose, and the rejection is already on the
- * element as `data-x-failed`. An island whose boot has not STARTED (an `idle` one still waiting
- * for the browser, a `visible` one never scrolled to) is settled instead: the hydration runtime's
- * `boot` answers an element that already has `__x` with it, so the pending boot mounts nothing into
- * a body that left the document — a mount nobody would ever dispose.
- */
-export function disposeIslands(root: Element, kept: (el: Element) => boolean): number {
-  let disposed = 0;
-  for (const el of root.querySelectorAll<IslandElement>(ISLAND_SELECTOR)) {
-    if (kept(el)) continue;
-    if (el.__x === undefined) {
-      el.__x = Promise.resolve();
-      continue;
-    }
-    disposed += 1;
-    el.__x.then(
-      (dispose) => {
-        if (typeof dispose === 'function') dispose();
-      },
-      () => undefined,
-    );
-  }
-  return disposed;
-}
-
 /** `[data-x-persist="id"]` present in BOTH documents: the live element moves into the next body. */
 export function persistedPairs(
   current: ParentNode,