@ultimat3/cli 27.5.0 → 27.6.0

package/CLAUDE.md

@@ -111,7 +111,7 @@ Commands: `bun test packages/cli` (from the repo root — the test preload lives
 | `page-navigation.ts` | the client router for `navigation.client` surfaces — built, routed and named ONCE for `x dev`, the container and the static export; none opted in builds nothing |
 | `page-speculation.ts` | Speculation Rules for documents WITHOUT the router (`navigation.speculation`): the allow-list of pure-read pages, the one tag, and its `script-src` hash — composed once for all three writers. An allow-list, never "every link but": a prefetch is a real GET with cookies |
 | `static-document.ts` | a served `static` page: `304` on a matching `If-None-Match`, and (container only, `memoStatic`) the document kept after its first render. Never `x dev` — a save moves the stylesheet URL the kept document names |
-| `island-bundle.ts` / `island-store.ts` / `island-sources.ts` / `island-realtime.ts` / `island-runtime.ts` / `solid-loader.ts` | islands: one `Bun.build` each, source-addressed; the image build writes a verified store the container loads — each chunk's recorded source files (`island-sources.ts`) are rehashed at read, so an edit since the build is a rebuild, never the old chunk. `island-runtime.ts` builds realtime's page runtime ONCE per build as `/islands/page-runtime.<id>.js` (resolved through `@ultimat3/realtime/page-runtime`), which a realtime island awaits where no page boot is rendered |
+| `island-bundle.ts` / `island-store.ts` / `island-sources.ts` / `island-realtime.ts` / `island-realtime-state.ts` / `island-runtime.ts` / `solid-loader.ts` | islands: one `Bun.build` each, source-addressed; the image build writes a verified store the container loads — each chunk's recorded source files (`island-sources.ts`) are rehashed at read, so an edit since the build is a rebuild, never the old chunk. `island-runtime.ts` builds realtime's page runtime ONCE per build as `/islands/page-runtime.<id>.js` (resolved through `@ultimat3/realtime/page-runtime`), which a realtime island awaits where no page boot is rendered. `island-realtime-state.ts`: which realtime islands only FOLLOW the socket (not held, no first-paint wait); the answer rides `IslandChunk.realtime` via the store to the renderer |
 | `local-cli.ts` / `local-cli-handoff.ts` | a global `x` hands over to the app's own CLI (`local-cli.ts` decides whether); the hand-off forwards SIGTERM/SIGHUP at once and a SIGINT only if the child is still running after a 1 s grace (a terminal Ctrl-C already reached it), and exits with the child's code |
 | `serve-prebuilt.ts` / `serve-prebuilt-paths.ts` | the image's prebuilt store (`node_modules/.cache/ultimate`, never `.x/` — state, tmpfs): every role adopts its compiled stylesheets before importing the app; a boot that built an island or ran Sass logs `X_IMAGE_NOT_PREBUILT` once |
 | `dev-*.ts` | `x dev` only: dashboard sources, traces, the N+1 ledger, the watcher, the reload, the lock, the port |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/cli",
-  "version": "27.5.0",
+  "version": "27.6.0",
   "description": "The `x` binary: new, dev, build, verify, generate, db, mcp, doctor, deploy",
   "license": "MIT",
   "type": "module",
@@ -39,33 +39,33 @@
   },
   "dependencies": {
     "@babel/core": "^8.0.1",
-    "@ultimat3/action": "27.5.0",
-    "@ultimat3/admin": "27.5.0",
-    "@ultimat3/ai": "27.5.0",
-    "@ultimat3/auth": "27.5.0",
-    "@ultimat3/cache": "27.5.0",
-    "@ultimat3/core": "27.5.0",
-    "@ultimat3/db": "27.5.0",
-    "@ultimat3/entity": "27.5.0",
-    "@ultimat3/flags": "27.5.0",
-    "@ultimat3/http": "27.5.0",
-    "@ultimat3/i18n": "27.5.0",
-    "@ultimat3/jobs": "27.5.0",
-    "@ultimat3/mail": "27.5.0",
-    "@ultimat3/manifest": "27.5.0",
-    "@ultimat3/mcp": "27.5.0",
-    "@ultimat3/money": "27.5.0",
-    "@ultimat3/notify": "27.5.0",
-    "@ultimat3/policy": "27.5.0",
-    "@ultimat3/pwa": "27.5.0",
-    "@ultimat3/query": "27.5.0",
-    "@ultimat3/realtime": "27.5.0",
-    "@ultimat3/render": "27.5.0",
-    "@ultimat3/schema": "27.5.0",
-    "@ultimat3/seo": "27.5.0",
-    "@ultimat3/storage": "27.5.0",
-    "@ultimat3/testing": "27.5.0",
-    "@ultimat3/time": "27.5.0",
+    "@ultimat3/action": "27.6.0",
+    "@ultimat3/admin": "27.6.0",
+    "@ultimat3/ai": "27.6.0",
+    "@ultimat3/auth": "27.6.0",
+    "@ultimat3/cache": "27.6.0",
+    "@ultimat3/core": "27.6.0",
+    "@ultimat3/db": "27.6.0",
+    "@ultimat3/entity": "27.6.0",
+    "@ultimat3/flags": "27.6.0",
+    "@ultimat3/http": "27.6.0",
+    "@ultimat3/i18n": "27.6.0",
+    "@ultimat3/jobs": "27.6.0",
+    "@ultimat3/mail": "27.6.0",
+    "@ultimat3/manifest": "27.6.0",
+    "@ultimat3/mcp": "27.6.0",
+    "@ultimat3/money": "27.6.0",
+    "@ultimat3/notify": "27.6.0",
+    "@ultimat3/policy": "27.6.0",
+    "@ultimat3/pwa": "27.6.0",
+    "@ultimat3/query": "27.6.0",
+    "@ultimat3/realtime": "27.6.0",
+    "@ultimat3/render": "27.6.0",
+    "@ultimat3/schema": "27.6.0",
+    "@ultimat3/seo": "27.6.0",
+    "@ultimat3/storage": "27.6.0",
+    "@ultimat3/testing": "27.6.0",
+    "@ultimat3/time": "27.6.0",
     "babel-preset-solid": "^1.9.15"
   }
 }

package/src/dev-route-table.ts

@@ -188,6 +188,7 @@ export async function devRouteTable(input: DevRouteTableInput): Promise<DevRoute
       buildId: input.buildId,
       ...(input.isr === undefined ? {} : { isr: input.isr }),
       resolveIsland: (file) => input.islands().resolverFor(file),
+      realtimeIslands: () => input.islands().realtime,
       ...(sync.head === undefined ? {} : { sync: sync.head }),
       persisted: sync.persisted,
       ...(navigation.head === undefined ? {} : { navigation: navigation.head }),

package/src/document-options.ts

@@ -3,6 +3,7 @@
 // 500-line ceiling; one declaration for `x dev`, the container and the static export.
 
 import type { ClientSyncHead } from '@ultimat3/render';
+import type { IslandRealtime } from './island-realtime-state';
 import type { NavigationDocumentHead } from './page-navigation';
 
 /**
@@ -15,6 +16,12 @@ export type IslandResolver = (routeFile: string) => (src: string) => string;
 
 export interface DocumentOptions {
   readonly resolveIsland?: IslandResolver;
+  /**
+   * The served bundle's realtime islands, by app-root-relative file (`IslandBundle.realtime`):
+   * which pages earn the page boot, and which islands are held until they mount. A function, as
+   * `resolveIsland` is — `x dev` swaps the bundle on a rebuild. Absent, no island is realtime.
+   */
+  readonly realtimeIslands?: () => ReadonlyMap<string, IslandRealtime>;
   /**
    * `<link rel="manifest">`, both `theme-color` metas and the apple-touch links — `PwaArtifacts.head`
    * from `pwa-artifacts.ts`, or absent when the app is not installable.

package/src/island-bundle.ts

@@ -33,9 +33,10 @@ import { frameworkDedupePlugins } from './island-package-dedupe';
 import {
   islandRealtimePlugin,
   REALTIME_ISLAND_ENTRY,
-  reachesRealtime,
   realtimeIslandEntry,
+  realtimeKind,
 } from './island-realtime';
+import type { IslandRealtime } from './island-realtime-state';
 import type { Runtimes } from './island-runtime';
 import { loadingRuntime, mergeBuilds, runtimeBuilder, runtimeShared } from './island-runtime';
 import { solidDedupePlugin } from './island-solid-dedupe';
@@ -79,6 +80,12 @@ export interface IslandChunk {
   readonly imports: readonly string[];
   /** The files on disk it was built from (`island-sources.ts`). Absent on a chunk not built here. */
   readonly sources?: SourcePaths;
+  /**
+   * Absent unless the island's graph reaches `@ultimat3/realtime`: then whether it has page state
+   * to restore or only follows the socket (`island-realtime-state.ts`). On the chunk, so the
+   * answer travels with the app it was asked of — through the store, to the document renderer.
+   */
+  readonly realtime?: IslandRealtime;
 }
 
 /** A module two or more islands import, served once beside them. */
@@ -102,6 +109,8 @@ export interface IslandBundle {
    * than emitting a `data-x-entry` no browser can import.
    */
   resolverFor(routeFile: string): (src: string) => string;
+  /** Every realtime island of THIS app, by file: what a document's page boot and holds are read from. */
+  readonly realtime: ReadonlyMap<string, IslandRealtime>;
   /** The chunk a URL names — for serving it, and for naming the island a budget finding blames. */
   chunkAt(url: string): IslandChunk | undefined;
   /** An entry OR a shared chunk at `url` — what the `/islands/*` route serves. */
@@ -137,17 +146,19 @@ async function buildAll(
   // no code, no file and no fix — before `Bun.build` ever ran to raise the one below.
   const realtime = await Promise.all(
     files.map((file) =>
-      reachesRealtime(root, file).catch((error: unknown) => {
+      realtimeKind(root, file).catch((error: unknown) => {
         throw new IslandBuildFailedError({ file, logs: describeBuildError(error) });
       }),
     ),
   );
   // Only an island whose own graph reaches `@ultimat3/realtime` is wrapped (`island-realtime.ts`);
   // every other one is built from its own file, byte for byte what it was.
-  const live = files.filter((_, index) => realtime[index] === true);
+  const live = files.filter((_, index) => realtime[index] !== undefined);
+  const follows = new Set(files.filter((_, index) => realtime[index] === 'follows'));
+  const kinds = new Map(files.map((file, index) => [file, realtime[index]]));
   const runtime = live[0] === undefined ? undefined : await runtimes(live[0]);
   const entrypoints = files.map((file, index) =>
-    realtime[index] === true ? realtimeIslandEntry(file) : join(root, file),
+    realtime[index] !== undefined ? realtimeIslandEntry(file) : join(root, file),
   );
   let built: Awaited<ReturnType<typeof Bun.build>>;
   try {
@@ -177,7 +188,7 @@ async function buildAll(
       // gets the same rule (`island-package-dedupe.ts`): a nested copy is a second module where no
       // symlink folds it, which is every `file:` install on Windows.
       plugins: [
-        ...(runtime === undefined ? [] : [islandRealtimePlugin(root, runtime)]),
+        ...(runtime === undefined ? [] : [islandRealtimePlugin(root, runtime, follows)]),
         solidDedupePlugin(root),
         ...frameworkDedupePlugins(root),
         solidJsxPlugin,
@@ -225,7 +236,12 @@ async function buildAll(
   await refuseDuplicatedModules(files.join(', '), built.metafile);
   const sources = new Map<string, SourcePaths>();
   const linked = linkOutputs(await builtOutputs(root, files, built.outputs, sources));
-  const chunks = loadingRuntime(entryChunks(files, linked, sources), live, runtime);
+  const chunks = loadingRuntime(entryChunks(files, linked, sources), live, runtime).map(
+    (chunk): IslandChunk => {
+      const kind = kinds.get(chunk.file);
+      return kind === undefined ? chunk : { ...chunk, realtime: kind };
+    },
+  );
   const shared = sharedChunks(chunks, linked, sources);
   return { chunks, shared: [...shared, ...runtimeShared(runtime, live)] };
 }
@@ -439,9 +455,13 @@ export function islandBundle(
   const byFile = new Map(chunks.map((chunk) => [chunk.file, chunk]));
   const byUrl = new Map(chunks.map((chunk) => [chunk.url, chunk]));
   const sharedByUrl = new Map(shared.map((chunk) => [chunk.url, chunk]));
+  const realtime = new Map<string, IslandRealtime>();
+  for (const chunk of chunks)
+    if (chunk.realtime !== undefined) realtime.set(chunk.file, chunk.realtime);
   return {
     chunks,
     shared,
+    realtime,
     resolverFor(routeFile: string): (src: string) => string {
       const dir = posix.dirname(routeFile);
       return (src: string): string => {

package/src/island-realtime-state.ts

@@ -0,0 +1,78 @@
+// Which realtime islands have page state to RESTORE, and which only follow the socket. A held
+// island (#506, `@ultimat3/render`'s `island-hold.ts`) is hidden until it mounts because its server
+// markup can be older than the record store and the outbox the page boot restores. An island whose
+// whole realtime use is a channel's events, a roster or the connection reads neither: its server
+// markup is as current as any other island's, so hiding it only delayed the page's content.
+
+import { firstInGraph } from './live-routes';
+
+const REALTIME = '@ultimat3/realtime';
+
+/**
+ * The barrel's value exports that read neither the record store nor the outbox: a membership, its
+ * roster, the socket's state, and the declarations that spell a topic. An ALLOW list on purpose —
+ * a name this list has never heard of (a hook added next year) is state until someone says not.
+ */
+export const FOLLOW_ONLY_EXPORTS: readonly string[] = [
+  'useChannel',
+  'usePresence',
+  'useConnection',
+  'hasPageSocket',
+  'readPresence',
+  'channel',
+  'channelRef',
+  'topic',
+];
+
+/**
+ * A named import or re-export of the barrel, as `Bun.Transpiler` PRINTS one: a statement to a
+ * line, double quotes, type-only names already erased. Read off the transpiler's output, never
+ * off the author's source, so a comment or a multi-line clause is not this pattern's problem.
+ */
+const NAMED = /^(?:import|export) \{([^}]*)\} from "@ultimat3\/realtime";?$/gm;
+
+/**
+ * The barrel's names one module takes by value — `[]` when it takes none, `undefined` when it
+ * takes the barrel in a form with no list of names (`import *`, `export *`, a bare or default
+ * import, `import()`). Counted against the transpiler's own import records: a statement this file
+ * cannot read is never silently skipped, it makes the answer unknown.
+ */
+export function realtimeBindings(source: string, path: string): readonly string[] | undefined {
+  const transpiler = new Bun.Transpiler({ loader: path.endsWith('x') ? 'tsx' : 'ts' });
+  const statements = transpiler.scanImports(source).filter((entry) => entry.path === REALTIME);
+  if (statements.length === 0) return [];
+  const names: string[] = [];
+  let named = 0;
+  for (const match of transpiler.transformSync(source).matchAll(NAMED)) {
+    named += 1;
+    for (const binding of (match[1] ?? '').split(',')) {
+      const name = binding.split(/\sas\s/)[0]?.trim() ?? '';
+      if (name !== '') names.push(name);
+    }
+  }
+  return named === statements.length ? names : undefined;
+}
+
+/**
+ * What a realtime island is to the page boot: `restores` reads the record store or the outbox
+ * (held, and its `mount` waits for the restore), `follows` only follows the socket (neither).
+ * Carried on the island's own chunk (`IslandChunk.realtime`), never in process state: an answer is
+ * about one app's file, and two apps built in one process can spell two islands the same way.
+ */
+export type IslandRealtime = 'restores' | 'follows';
+
+/**
+ * Whether a realtime island restores nothing: every module of its relative graph takes only
+ * `FOLLOW_ONLY_EXPORTS` from the barrel. One unknown name, or one statement with no names, and it
+ * restores — the answer every realtime island had before. Pure: asked per build, of that build's
+ * root. The blind spot is `reachesRealtime`'s own: a PACKAGE reading the store for the island is
+ * not seen.
+ */
+export async function followsOnly(root: string, file: string): Promise<boolean> {
+  const restores = await firstInGraph(root, file, (source, path) => {
+    const names = realtimeBindings(source, path);
+    const follows = names?.every((name) => FOLLOW_ONLY_EXPORTS.includes(name)) === true;
+    return follows ? undefined : true;
+  });
+  return restores !== true;
+}

package/src/island-realtime.ts

@@ -1,11 +1,14 @@
 // Realtime installed for the author, on exactly the islands that use it: an island whose own import
 // graph reaches `@ultimat3/realtime` is built from a virtual entry that first awaits the page
 // runtime (`island-runtime.ts`), then calls `installRealtime({ signal: createSignal })` with THIS
-// bundle's solid-js, then re-exports the island whole. Every other island pays nothing.
+// bundle's solid-js, then re-exports the island whole. Every other island pays nothing. An island
+// that reads the record store or the outbox also waits for the page's restore before it mounts
+// (#506); one that only follows the socket does not (`island-realtime-state.ts`).
 
 // why: Bun ships no path API; the entry is joined to the root, the runtime named by its basename.
 import { basename, join } from 'node:path';
 import type { BunPlugin } from 'bun';
+import { followsOnly, type IslandRealtime } from './island-realtime-state';
 import { RUNTIME_CHUNK_SPECIFIER, type RuntimeChunk } from './island-runtime';
 import { firstInGraph } from './live-routes';
 import { PAGE_BOOT_BASE_PATH } from './worker-bundle';
@@ -23,6 +26,7 @@ export const realtimeIslandEntry = (file: string): string => `${REALTIME_ISLAND_
 const REALTIME = '@ultimat3/realtime';
 const NAMESPACE = 'ultimate-island';
 const INSTALL = 'ultimate:island-realtime';
+const RESTORE = 'ultimate:island-restore';
 const MODULE = 'ultimate:island-module:';
 const WAIT = 'ultimate:island-page-wait';
 
@@ -39,33 +43,32 @@ export async function reachesRealtime(root: string, file: string): Promise<boole
     );
     return scanned.some((entry) => entry.path === REALTIME) ? true : undefined;
   });
-  // Recorded with the answer, so the document renderer can ask it of a page's islands without a
-  // second graph walk per request. Every build re-asks, so an edit that drops realtime drops it.
-  if (found === true) realtimeIslands.add(file);
-  else realtimeIslands.delete(file);
   return found === true;
 }
 
-/** App-root-relative island files whose graph reaches realtime, as the last build answered. */
-const realtimeIslands = new Set<string>();
-
 /**
- * The islands (app-root-relative POSIX paths) the last build found reaching realtime. A page needs
- * realtime's page boot only if one of ITS islands does — `settings` paid 34.9 kB of boot script
- * for an island that never touched a record.
+ * Both of a build's answers about one island, for its chunk to carry (`IslandChunk.realtime`):
+ * `undefined` when its graph never reaches realtime. A page needs realtime's page boot only if one
+ * of ITS islands does — `settings` paid 34.9 kB of boot script for an island that never touched a
+ * record — and holds only the ones that restore.
  */
-export function realtimeIslandFiles(): ReadonlySet<string> {
-  return realtimeIslands;
+export async function realtimeKind(
+  root: string,
+  file: string,
+): Promise<IslandRealtime | undefined> {
+  if (!(await reachesRealtime(root, file))) return undefined;
+  return (await followsOnly(root, file)) ? 'follows' : 'restores';
 }
 
 /**
  * `export *` and never a named list: the hydration runtime reads `mount` off the module, and the
  * wrapper must not decide which of an island's names survive. The install is imported FIRST, so it
  * has run before the island's module body — and every hook the island calls — does. One install
- * module for every realtime island of the build, so a page with two of them loads it once.
+ * module for every realtime island of the build, so a page with two of them loads it once; an
+ * island with page state to restore imports the restore, which imports that same install.
  */
-const entrySource = (file: string): string =>
-  `import '${INSTALL}';\nexport * from '${MODULE}${file}';\n`;
+const entrySource = (file: string, follows: boolean): string =>
+  `import '${follows ? INSTALL : RESTORE}';\n` + `export * from '${MODULE}${file}';\n`;
 
 /**
  * The install names `@ultimat3/realtime` BARE, and `islandRealtimePlugin` resolves it from the
@@ -80,25 +83,40 @@ const entrySource = (file: string): string =>
  * on a document rendered for a principal; anywhere else the island loads the runtime chunk, by a
  * path relative to its own URL, so it resolves under `/islands/` and beside it in `mountIsland`.
  * The chunk's URL is in this source, so a new runtime is a new URL for every island loading it.
- * Then the first-paint hold (#506): `mount` waits for the restored records and the open outbox
- * (capped), so a reload's first render already carries a queued write's overlay.
  */
 const installSource = (runtimeUrl: string): string =>
-  `import { holdFirstPaint, installRealtime } from '${REALTIME}';\n` +
+  `import { installRealtime } from '${REALTIME}';\n` +
   `import { awaitPageRuntime } from '${WAIT}';\n` +
   `import { createSignal } from 'solid-js';\n` +
   `await awaitPageRuntime({ boot: '${PAGE_BOOT_BASE_PATH}/', load: () => import('./${basename(runtimeUrl)}') });\n` +
-  `await holdFirstPaint();\n` +
   `installRealtime({ signal: createSignal });\n`;
 
+/**
+ * The first-paint hold (#506), for an island that reads the record store or the outbox: `mount`
+ * waits for the restored records and the open outbox (capped), so a reload's first render already
+ * carries a queued write's overlay. After the install, which it imports: the wait needs the page
+ * runtime, and no hook runs before the island's module graph — this module included — is done.
+ * An island that only follows the socket never imports it, so it mounts as soon as the runtime is
+ * there and its chunk carries no `first-paint-hold.ts`.
+ */
+const restoreSource = (): string =>
+  `import '${INSTALL}';\n` +
+  `import { holdFirstPaint } from '${REALTIME}';\n` +
+  `await holdFirstPaint();\n`;
+
 /**
  * `runtime` names the realtime every bare `@ultimat3/realtime` of the build resolves to — the copy
  * the runtime chunk was built against, resolved from the first realtime island's directory. One
  * copy for all of them, because one copy in the bundle is the requirement: the signal the install
  * sets is only read by hooks from the same module instance, and the page object it reads is the
- * shape that copy's runtime installs.
+ * shape that copy's runtime installs. `follows` is THIS build's islands that restore nothing: an
+ * island absent from it waits for the restore, which is the answer that can never paint stale.
  */
-export function islandRealtimePlugin(root: string, runtime: RuntimeChunk): BunPlugin {
+export function islandRealtimePlugin(
+  root: string,
+  runtime: RuntimeChunk,
+  follows: ReadonlySet<string> = new Set(),
+): BunPlugin {
   return {
     name: 'ultimate-island-realtime',
     setup(build) {
@@ -110,6 +128,10 @@ export function islandRealtimePlugin(root: string, runtime: RuntimeChunk): BunPl
         path: 'install',
         namespace: NAMESPACE,
       }));
+      build.onResolve({ filter: /^ultimate:island-restore$/ }, () => ({
+        path: 'restore',
+        namespace: NAMESPACE,
+      }));
       build.onResolve({ filter: /^ultimate:island-module:/ }, (args) => ({
         path: join(root, args.path.slice(MODULE.length)),
       }));
@@ -126,8 +148,13 @@ export function islandRealtimePlugin(root: string, runtime: RuntimeChunk): BunPl
       build.onResolve({ filter: /^@ultimat3\/realtime$/ }, () => ({ path: runtime.realtime }));
       build.onLoad({ filter: /.*/, namespace: NAMESPACE }, (args) => ({
         contents: args.path.startsWith('entry:')
-          ? entrySource(args.path.slice('entry:'.length))
-          : installSource(runtime.url),
+          ? entrySource(
+              args.path.slice('entry:'.length),
+              follows.has(args.path.slice('entry:'.length)),
+            )
+          : args.path === 'restore'
+            ? restoreSource()
+            : installSource(runtime.url),
         loader: 'js',
       }));
     },

package/src/island-store.ts

@@ -13,6 +13,7 @@ import { contentHash, loadStylesheet } from '@ultimat3/render/server';
 import { IslandBuildFailedError } from './errors';
 import type { IslandBundle, IslandChunk, SharedChunk } from './island-bundle';
 import { buildIslands, discoverIslands, islandBundle } from './island-bundle';
+import type { IslandRealtime } from './island-realtime-state';
 import type { SourceDigester, SourceStamp } from './island-sources';
 import { changedSource, isRecordableSource, sourceDigester, stampSources } from './island-sources';
 import { islandStylesheets } from './island-styles';
@@ -54,6 +55,13 @@ interface StoreIndex {
    * read the store, and present on any that rebuilt.
    */
   readonly stylesheets: readonly string[];
+  /**
+   * Each realtime island's kind, by file — `IslandChunk.realtime` as the build answered it, which
+   * the document renderer reads per request and a pod that builds nothing never computed. One
+   * object for the index rather than a field per chunk, so its ABSENCE is readable: `undefined`
+   * only for an index that did not record it, which is stale.
+   */
+  readonly realtime: ReadonlyMap<string, IslandRealtime> | undefined;
 }
 
 const chunkFile = (url: string): string => url.slice(url.lastIndexOf('/') + 1);
@@ -119,8 +127,11 @@ export async function writeIslandStore(
     chunks,
     shared,
     stylesheets,
+    realtime: bundle.realtime,
   };
-  await Bun.write(join(dir, INDEX), `${JSON.stringify(index, null, 2)}\n`);
+  // The bundle's own answer as a JSON object, sorted so the index is reproducible.
+  const realtime = Object.fromEntries([...bundle.realtime].sort(([a], [b]) => (a < b ? -1 : 1)));
+  await Bun.write(join(dir, INDEX), `${JSON.stringify({ ...index, realtime }, null, 2)}\n`);
   return [...written, `${ISLAND_STORE_DIR}/${INDEX}`];
 }
 
@@ -129,6 +140,19 @@ const isString = (value: unknown): value is string => typeof value === 'string';
 const stringsOf = (value: unknown): readonly string[] =>
   Array.isArray(value) ? value.filter(isString) : [];
 
+/** `undefined` unless every value is a kind this build knows: anything else is not an answer. */
+function kindsOf(value: unknown): ReadonlyMap<string, IslandRealtime> | undefined {
+  if (typeof value !== 'object' || value === null || Array.isArray(value)) return undefined;
+  // A Map, never the parsed object indexed by file: the file names are the index's own DATA, and
+  // an object answers `constructor` or `__proto__` with something that is not a kind.
+  const kinds = new Map<string, IslandRealtime>();
+  for (const [file, kind] of Object.entries(value)) {
+    if (kind !== 'restores' && kind !== 'follows') return undefined;
+    kinds.set(file, kind);
+  }
+  return kinds;
+}
+
 /**
  * `undefined` when the field is absent or any entry is malformed or names a path outside the app:
  * a store that cannot say what it was built from cannot be checked, which is stale — never
@@ -187,6 +211,7 @@ function parseIndex(value: unknown): StoreIndex | { readonly unchecked: string }
     chunks: parsed,
     shared,
     stylesheets,
+    realtime: kindsOf(record['realtime']),
   };
 }
 
@@ -223,6 +248,11 @@ export async function readIslandStore(root: string): Promise<StoreRead> {
       stale: `built by framework ${index.framework} on Bun ${index.bun}, serving ${frameworkVersion()} on Bun ${Bun.version}`,
     };
   }
+  if (index.realtime === undefined) {
+    return {
+      stale: `${ISLAND_STORE_DIR}/${INDEX} does not say which islands are realtime, so no page would carry the boot they need`,
+    };
+  }
   const stored = index.chunks.map((chunk) => chunk.file).sort();
   const present = [...(await discoverIslands(root))];
   if (stored.join('\n') !== present.join('\n')) {
@@ -243,12 +273,14 @@ export async function readIslandStore(root: string): Promise<StoreRead> {
     const code = (await bytes.exists()) ? await bytes.text() : undefined;
     return code === undefined || contentHash(code) !== entry.identity ? undefined : code;
   };
+  const kinds = index.realtime;
   const chunks: IslandChunk[] = [];
   for (const entry of index.chunks) {
     const code = await verified(entry);
     if (code === undefined) {
       return { stale: `${entry.url} is missing or does not match its recorded hash` };
     }
+    const kind = kinds.get(entry.file);
     chunks.push({
       file: entry.file,
       moduleId: entry.moduleId,
@@ -256,6 +288,7 @@ export async function readIslandStore(root: string): Promise<StoreRead> {
       code,
       bytes: new TextEncoder().encode(code).byteLength,
       imports: entry.imports,
+      ...(kind === undefined ? {} : { realtime: kind }),
     });
   }
   const shared: SharedChunk[] = [];

package/src/prerender.ts

@@ -267,6 +267,7 @@ export async function prerenderSite(options: PrerenderOptions): Promise<Prerende
   const database = measureDatabase(options.root);
   const documentOptions = {
     resolveIsland: (file: string) => islands.resolverFor(file),
+    realtimeIslands: () => islands.realtime,
     themeHead: theme.head,
     ...(brand === undefined ? {} : { brandHead: brand.head }),
     ...(speculation === undefined ? {} : { speculationHead: speculation.head }),

package/src/route-islands.ts

@@ -13,7 +13,6 @@ import {
   renderHead,
 } from '@ultimat3/render';
 import type { DocumentOptions } from './document-options';
-import { realtimeIslandFiles } from './island-realtime';
 
 /**
  * One collector per RENDER, never module-global: two requests render different params, and a
@@ -34,12 +33,17 @@ export const collectorFor = (
     // realtime island's server markup is held off screen until it mounts over the restored store.
     ...(scope === undefined || options.sync === undefined
       ? {}
-      : { hold: (src: string) => reachesRealtime(entry, src) }),
+      : { hold: (src: string) => restoresState(entry, options, src) }),
   });
 
-/** Whether `src`, as the page at `entry` wrote it, is an island the last build found realtime. */
-const reachesRealtime = (entry: RouteEntry, src: string): boolean =>
-  realtimeIslandFiles().has(posix.join(posix.dirname(entry.file), src));
+/**
+ * Whether `src`, as the page at `entry` wrote it, is an island the served bundle built as realtime
+ * AND reading the record store or the outbox. An island that only follows the socket — a channel's
+ * events, a roster, the connection — has no markup the restore could contradict, so hiding it
+ * only delayed the page's content (`island-realtime-state.ts`).
+ */
+const restoresState = (entry: RouteEntry, options: DocumentOptions, src: string): boolean =>
+  options.realtimeIslands?.().get(posix.join(posix.dirname(entry.file), src)) === 'restores';
 
 /**
  * Realtime's page boot, as one deferred script — or nothing. Two conditions, both exact: the
@@ -61,7 +65,7 @@ export function bootScript(
   // An island's module id is derived from its `src`, written relative to the page that renders it:
   // each realtime island file, spelled from THIS page, is the id its directive would carry.
   const pageDir = posix.dirname(entry.file);
-  const reaches = [...realtimeIslandFiles()].some((file) => {
+  const reaches = [...(options.realtimeIslands?.().keys() ?? [])].some((file) => {
     const src = posix.relative(pageDir, file);
     return rendered.has(islandModuleId(src.startsWith('.') ? src : `./${src}`));
   });

package/src/serve-web.ts

@@ -151,6 +151,7 @@ export async function webSurface(
     ...appRoutes({
       buildId,
       resolveIsland: (file) => islands.resolverFor(file),
+      realtimeIslands: () => islands.realtime,
       ...(sync.head === undefined ? {} : { sync: sync.head }),
       persisted: sync.persisted,
       ...(navigation.head === undefined ? {} : { navigation: navigation.head }),