@ultimat3/cli 22.11.0 → 22.13.0

package/src/island-identity.ts

@@ -0,0 +1,158 @@
+// An island output's identity and the one byte string served under it: the source-graph hash
+// that names a URL (`graphHash`), the per-process pin that keeps one URL one byte string
+// (`stableChunk`), and the bundler-diagnostic flattening every island refusal carries. Split from
+// `island-bundle.ts`, which builds; `worker-bundle.ts` names its chunks by the same rules.
+
+import { frameworkVersion, renderThrowable } from '@ultimat3/core';
+import { contentHash } from '@ultimat3/render/server';
+import { IslandBuildFailedError } from './errors';
+
+/**
+ * `sourcemap: 'external'` appends `//# debugId=<hex>` to the chunk. It is a pointer to a map this
+ * framework does not serve, so it is removed rather than shipped — and removing it makes the
+ * emitted bytes identical to what the same build produced before the map was asked for, which is
+ * what keeps `bytes` a budget number and not a build-flag artefact. `slice`, never a `replace` with
+ * an empty replacement — `bun run sql-literal-copies` refuses that shape anywhere but `db/sql.ts`.
+ */
+const DEBUG_ID_COMMENT = '\n//# debugId=';
+
+export function stripDebugId(code: string): string {
+  const at = code.lastIndexOf(DEBUG_ID_COMMENT);
+  return at === -1 ? code : code.slice(0, at);
+}
+
+/**
+ * The chunk's identity, computed from what went IN rather than from what came out.
+ *
+ * `Bun.build` is not byte-deterministic under `minify`. Measured on 1.4.0, one entry point, no
+ * source file touched: a 131,589-byte island alternated between two outputs of IDENTICAL length
+ * differing only in minified identifier names (`var ca=Object.defineProperty` against
+ * `var la=…`) — roughly one build in ten, which is a race in the renamer and not anything a caller
+ * can order. Hashing that output made the URL flap: ten distinct `session-console-*.js` names in
+ * ten minutes, so a service worker's precache manifest named a chunk that already 404ed and a
+ * browser's `immutable` cache never hit on a 131 kB download. Twelve consecutive builds hash
+ * identically here.
+ *
+ * `sourcesContent`, hashed per file and SORTED, so the identity is independent of the order the
+ * bundler happened to visit the graph in. The PATHS are deliberately not in it: they are absolute
+ * on the build machine and would make a chunk built in a container disagree with the same chunk
+ * built on a laptop for no difference a browser could observe. `file` is, so two islands with
+ * byte-identical sources under different names stay two chunks; the framework version and the Bun
+ * version are, because both decide the emitted bytes while no source file moves — an upgrade must
+ * mint a new URL rather than leave a stale chunk pinned in a browser for a year.
+ *
+ * What this gives up, stated plainly: the URL is source-addressed, not byte-addressed, so two
+ * processes building the same sources can serve two byte-strings at one URL. They are the same
+ * program under different local identifier names. That is the trade a nondeterministic bundler
+ * forces, and the alternative — `minify: { identifiers: false }`, which IS deterministic — was
+ * measured at 193,590 bytes against 131,649, +47% raw and +20% gzipped, on every island of every
+ * app. Delete this the day `Bun.build` is deterministic.
+ */
+export function graphHash(file: string, map: string): string {
+  const parsed: unknown = JSON.parse(map);
+  const contents = sourcesContentOf(parsed);
+  if (contents === undefined) {
+    throw new IslandBuildFailedError({
+      file,
+      logs: 'the bundler emitted a source map with no sourcesContent, so the chunk has no stable identity',
+    });
+  }
+  const graph = contents.map((source) => contentHash(source)).sort();
+  return contentHash([file, frameworkVersion(), Bun.version, ...graph].join('\u0000'));
+}
+
+/**
+ * `sourcesContent`, read the way `aggregatedErrors` below reads `errors`: narrowed first,
+ * dereferenced inside a `try`, `undefined` for anything that is not a full list of strings. A
+ * partial list is refused rather than padded — a graph with holes in it hashes two different
+ * islands the same.
+ */
+export function sourcesContentOf(
+  value: unknown,
+  allowEmpty = false,
+): readonly string[] | undefined {
+  if (typeof value !== 'object' || value === null) return undefined;
+  try {
+    const held: unknown = (value as Record<string, unknown>)['sourcesContent'];
+    // Empty is admitted only for a split build's output, where a chunk of bundler runtime helpers
+    // has no source file behind it and `island-link.ts` names it by its code instead.
+    if (!Array.isArray(held) || (held.length === 0 && !allowEmpty)) return undefined;
+    return held.every((one: unknown) => typeof one === 'string')
+      ? (held as readonly string[])
+      : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * The code this process already emitted for these inputs, or the code it just built.
+ *
+ * Keyed by PATH and validated by the input hash, `transformIslandTsx`'s cache's shape and for its
+ * reason: one entry per island bounds the map by the island count, which is the only quantity that
+ * should bound it, and an entry whose hash no longer matches is replaced rather than served.
+ */
+const emitted = new Map<string, { readonly graph: string; readonly code: string }>();
+
+/** Test seam: the table is process-global because the dev server it serves is too. */
+export function clearIslandChunkCache(): void {
+  emitted.clear();
+}
+
+/**
+ * `graph`, never `hash`: `bun run secret-compare` reads the NAME of a comparison's operands, and a
+ * value called `hash` is a digest an attacker may be probing. This one is a build input's
+ * identity — the same reason `pr-threads.ts` calls a review state `wanted`.
+ */
+export function stableChunk(
+  file: string,
+  graph: string,
+  code: string,
+): { readonly code: string; readonly bytes: number } {
+  const hit = emitted.get(file);
+  const served = hit !== undefined && hit.graph === graph ? hit.code : code;
+  if (served === code) emitted.set(file, { graph, code });
+  // Measured on the code that is SERVED. It was measured on this build's output, which under a
+  // minifier that renames differently between builds is a second size for one URL in one process
+  // — and a budget weighed on bytes no browser receives.
+  return { code: served, bytes: new TextEncoder().encode(served).byteLength };
+}
+
+/**
+ * The bundler's own diagnostics, kept verbatim. An `AggregateError` holds one entry per unresolved
+ * import or syntax error, and flattening them is what puts the line number in the cause instead of
+ * the word "Bundle failed".
+ */
+export function describeBuildError(error: unknown): string {
+  // `renderThrowable`, never `instanceof` + `.message` + `String()`. All three run on a value this
+  // process did not build — a `Proxy` traps `getPrototypeOf`, a `message` getter can raise, and
+  // `String()` throws outright on a Symbol — and what comes back is carried in
+  // `IslandBuildFailedError.logs`, which `errors.ts` interpolates straight into a `cause:`. That
+  // is a cross-file hop neither `scripts/catch-render.ts` nor `scripts/error-render.ts` can
+  // follow: a throw here loses the whole refusal and replaces it with a TypeError about reporting.
+  //
+  // The AggregateError branch stays, and it is the reason this function exists: `Bun.build` packs
+  // one entry per unresolved import or syntax error into `errors`, and flattening them is what
+  // puts a line number in the cause instead of the words "Bundle failed". `stringField` decides
+  // whether the value really is that shape, because `instanceof` is a question a Proxy answers.
+  const aggregate = aggregatedErrors(error);
+  if (aggregate !== undefined && aggregate.length > 0) {
+    return aggregate.map((one: unknown) => renderThrowable(one)).join('; ');
+  }
+  return renderThrowable(error);
+}
+
+/**
+ * `value.errors`, read the way `@ultimat3/core`'s `stringField` reads a string field: narrowed
+ * first, dereferenced inside a `try`, `undefined` for anything else. `instanceof AggregateError`
+ * is a question a `Proxy` answers with its own `getPrototypeOf` trap, so it is not a check.
+ */
+function aggregatedErrors(value: unknown): readonly unknown[] | undefined {
+  if (typeof value !== 'object' || value === null) return undefined;
+  try {
+    const held: unknown = (value as Record<string, unknown>)['errors'];
+    return Array.isArray(held) ? held : undefined;
+  } catch {
+    return undefined;
+  }
+}

package/src/island-link.ts

@@ -0,0 +1,138 @@
+// One split `Bun.build` of every island, turned into the files a browser fetches: an entry per
+// island and a chunk per module two or more islands share, each named by its SOURCE identity and
+// importing the others by that name. `island-bundle.ts` runs the build; this file only links.
+//
+// Why the names are rewritten rather than taken from Bun's `chunk-[hash]`: that hash is of the
+// OUTPUT, and `Bun.build` under `minify` is not byte-deterministic (`graphHash` in
+// `island-bundle.ts` has the measurement). An output-addressed shared chunk flaps its URL, and
+// every entry importing it flaps with it — the precache-404 and cold-cache defect, back.
+
+import { posix } from 'node:path'; // why: Bun ships no path API; `basename` of a specifier.
+import { frameworkVersion } from '@ultimat3/core';
+import { contentHash } from '@ultimat3/render/server';
+import { IslandBuildFailedError } from './errors';
+
+/** One code output of the build, as `island-bundle.ts` hands it over. */
+export interface BuiltOutput {
+  /** Bun's own output path, `./` stripped: `apps/web/app/x.island.js`, `chunk-ab12cd34.js`. */
+  readonly path: string;
+  /** The island file it is the entry for; `undefined` for a shared chunk. */
+  readonly file?: string;
+  /** Emitted code, the debug-id comment already removed. */
+  readonly code: string;
+  /** Its source map's `sourcesContent` — empty for a chunk of bundler runtime helpers only. */
+  readonly sources: readonly string[];
+}
+
+export interface LinkedFile {
+  /** The output this came from, so the caller can pair it with its island. */
+  readonly path: string;
+  readonly file?: string;
+  /** `chunk-<identity>` for a shared chunk; the caller prefixes an entry with its module id. */
+  readonly identity: string;
+  /** The code with every import of another output rewritten to that output's final name. */
+  readonly code: string;
+  /** Final basenames of the outputs this one imports, statically or by `import()`, direct only. */
+  readonly imports: readonly string[];
+}
+
+/** The final basename a shared chunk is served under — beside every entry, under one base path. */
+export const sharedChunkName = (identity: string): string => `chunk-${identity}.js`;
+
+/** Static imports and `import()` both: a browser fetches either before the island is whole. */
+const LOADS = new Set(['import-statement', 'dynamic-import']);
+
+interface Scanned {
+  readonly exports: readonly string[];
+  /** Specifiers exactly as written, each naming another output of this build. */
+  readonly specifiers: readonly string[];
+}
+
+function scan(code: string, byName: ReadonlyMap<string, BuiltOutput>): Scanned {
+  const scanned = new Bun.Transpiler({ loader: 'js' }).scan(code);
+  const specifiers = scanned.imports
+    .filter((one) => LOADS.has(one.kind) && byName.has(posix.basename(one.path)))
+    .map((one) => one.path);
+  return { exports: [...scanned.exports].sort(), specifiers: [...new Set(specifiers)] };
+}
+
+/**
+ * Every output's identity, from what went in: its own sources (hashed and sorted, as `graphHash`
+ * does), its EXPORT names, and the identities of every output it imports. The exports are in it
+ * because they are the link between two files built together — an importer's `import{a as o}`
+ * is only correct against a chunk exporting `a`, so a chunk whose interface moved must not keep a
+ * URL an older importer is holding. The imports are in it because an entry's bytes NAME its
+ * chunks: a moved chunk moves every entry that loads it.
+ */
+export function linkOutputs(outputs: readonly BuiltOutput[]): readonly LinkedFile[] {
+  const byName = new Map(outputs.map((one) => [posix.basename(one.path), one]));
+  const scans = new Map(outputs.map((one) => [one.path, scan(one.code, byName)]));
+  const identities = new Map<string, string>();
+  const visiting = new Set<string>();
+
+  const identityOf = (output: BuiltOutput): string => {
+    const known = identities.get(output.path);
+    if (known !== undefined) return known;
+    if (visiting.has(output.path)) throw cycle(output);
+    visiting.add(output.path);
+    const scanned = scans.get(output.path) ?? { exports: [], specifiers: [] };
+    const deps = scanned.specifiers
+      .map((spec) => byName.get(posix.basename(spec)))
+      .filter((dep): dep is BuiltOutput => dep !== undefined)
+      .map(identityOf)
+      .sort();
+    // A chunk of bundler runtime helpers has no source file behind it — its code IS its source.
+    const own = output.sources.length === 0 ? [contentHash(output.code)] : output.sources;
+    const identity = contentHash(
+      [
+        output.file ?? 'shared',
+        frameworkVersion(),
+        Bun.version,
+        ...own.map((source) => contentHash(source)).sort(),
+        'exports',
+        ...scanned.exports,
+        'imports',
+        ...deps,
+      ].join('\u0000'),
+    );
+    visiting.delete(output.path);
+    identities.set(output.path, identity);
+    return identity;
+  };
+
+  return outputs.map((output) => {
+    const identity = identityOf(output);
+    const scanned = scans.get(output.path) ?? { exports: [], specifiers: [] };
+    let code = output.code;
+    const imports: string[] = [];
+    for (const spec of scanned.specifiers) {
+      const dep = byName.get(posix.basename(spec));
+      if (dep === undefined) continue;
+      const name = sharedChunkName(identityOf(dep));
+      imports.push(name);
+      // The quoted literal, whole: Bun writes every specifier double-quoted, and a chunk name is a
+      // hash no program text contains by accident. Relative, so it resolves beside the importer
+      // under any base path — `/islands/` served, a temp directory in `mountIsland`.
+      code = code.split(JSON.stringify(spec)).join(JSON.stringify(`./${name}`));
+    }
+    return {
+      path: output.path,
+      ...(output.file === undefined ? {} : { file: output.file }),
+      identity,
+      code,
+      imports: [...new Set(imports)].sort(),
+    };
+  });
+}
+
+/**
+ * Two outputs importing each other: esbuild-family splitting does not emit one, and an identity
+ * built from its imports' identities has no answer for it. Refused by name rather than answered
+ * with a hash that silently ignores an edge.
+ */
+function cycle(output: BuiltOutput): IslandBuildFailedError {
+  return new IslandBuildFailedError({
+    file: output.file ?? output.path,
+    logs: `the island build emitted a chunk import cycle through ${output.path}, so its outputs have no source identity to be named by`,
+  });
+}

package/src/island-realtime.ts

@@ -8,13 +8,20 @@ import { dirname, join } from 'node:path';
 import type { BunPlugin } from 'bun';
 import { firstInGraph } from './live-routes';
 
-/** What `Bun.build` is handed for a realtime island; resolved by `islandRealtimePlugin`. */
-export const REALTIME_ISLAND_ENTRY = 'ultimate:island-entry';
+/**
+ * What `Bun.build` is handed for a realtime island: this prefix plus the island's app-root-relative
+ * path, so ONE build can carry every realtime island's wrapper as its own entry point. Resolved by
+ * `islandRealtimePlugin`, and the prefix is what `island-bundle.ts` strips back off Bun's output path.
+ */
+export const REALTIME_ISLAND_ENTRY = 'ultimate:island-entry:';
+
+/** The entry point `Bun.build` is handed for a realtime island. */
+export const realtimeIslandEntry = (file: string): string => `${REALTIME_ISLAND_ENTRY}${file}`;
 
 const REALTIME = '@ultimat3/realtime';
 const NAMESPACE = 'ultimate-island';
 const INSTALL = 'ultimate:island-realtime';
-const MODULE = 'ultimate:island-module';
+const MODULE = 'ultimate:island-module:';
 
 /**
  * Whether the island's own graph value-imports realtime. Relative specifiers only, which is the
@@ -51,9 +58,11 @@ export function realtimeIslandFiles(): ReadonlySet<string> {
 /**
  * `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.
+ * 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.
  */
-const ENTRY_SOURCE = `import '${INSTALL}';\nexport * from '${MODULE}';\n`;
+const entrySource = (file: string): string =>
+  `import '${INSTALL}';\nexport * from '${MODULE}${file}';\n`;
 
 /**
  * The install names `@ultimat3/realtime` BARE, and `islandRealtimePlugin` resolves it from the
@@ -68,29 +77,37 @@ const INSTALL_SOURCE =
   `import { createSignal } from 'solid-js';\n` +
   `installRealtime({ signal: createSignal });\n`;
 
+/**
+ * `file` is the island whose directory every bare `@ultimat3/realtime` resolves from — the first
+ * realtime island of the build. One directory 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.
+ */
 export function islandRealtimePlugin(root: string, file: string): BunPlugin {
   const island = join(root, file);
   return {
     name: 'ultimate-island-realtime',
     setup(build) {
-      build.onResolve({ filter: /^ultimate:island-entry$/ }, () => ({
-        path: 'entry',
+      build.onResolve({ filter: /^ultimate:island-entry:/ }, (args) => ({
+        path: `entry:${args.path.slice(REALTIME_ISLAND_ENTRY.length)}`,
         namespace: NAMESPACE,
       }));
       build.onResolve({ filter: /^ultimate:island-realtime$/ }, () => ({
         path: 'install',
         namespace: NAMESPACE,
       }));
-      build.onResolve({ filter: /^ultimate:island-module$/ }, () => ({ path: island }));
+      build.onResolve({ filter: /^ultimate:island-module:/ }, (args) => ({
+        path: join(root, args.path.slice(MODULE.length)),
+      }));
       // Every bare `@ultimat3/realtime` in this build, the virtual install's included — a virtual
       // module has no directory to resolve from. The island's directory for all of them, which is
-      // what the island itself would get, and one copy in the bundle is the requirement anyway:
-      // the signal the install sets is only read by hooks from the same module instance.
+      // what the island itself would get.
       build.onResolve({ filter: /^@ultimat3\/realtime$/ }, () => ({
         path: Bun.resolveSync(REALTIME, dirname(island)),
       }));
       build.onLoad({ filter: /.*/, namespace: NAMESPACE }, (args) => ({
-        contents: args.path === 'entry' ? ENTRY_SOURCE : INSTALL_SOURCE,
+        contents: args.path.startsWith('entry:')
+          ? entrySource(args.path.slice('entry:'.length))
+          : INSTALL_SOURCE,
         loader: 'js',
       }));
     },

package/src/island-routes.ts

@@ -26,7 +26,9 @@ export function islandRoutes(source: IslandSource): readonly Route[] {
       path: `${ISLAND_BASE_PATH}/*file`,
       meta: { name: 'assets.island', auth: 'public', tags: ['assets'] },
       handler: (request: UltimateRequest): Response => {
-        const chunk = source().chunkAt(request.pathname);
+        // An entry or a shared chunk: an entry's bytes import its chunks by a relative name, so both
+        // have to answer at the one base path, under the one cache rule.
+        const chunk = source().assetAt(request.pathname);
         if (chunk === undefined) {
           const missing = json(
             {

package/src/island-store.ts

@@ -10,7 +10,7 @@
 import { join, relative, sep } from 'node:path'; // why: Bun ships no path-join primitive.
 import { frameworkVersion, logger } from '@ultimat3/core';
 import { contentHash, loadStylesheet } from '@ultimat3/render/server';
-import type { IslandBundle, IslandChunk } from './island-bundle';
+import type { IslandBundle, IslandChunk, SharedChunk } from './island-bundle';
 import { buildIslands, discoverIslands, islandBundle } from './island-bundle';
 import { islandStylesheets } from './island-styles';
 
@@ -23,12 +23,23 @@ interface StoredChunk {
   readonly moduleId: string;
   readonly url: string;
   readonly identity: string;
+  /** The shared chunk URLs the entry loads, transitively (`IslandChunk.imports`). */
+  readonly imports: readonly string[];
+}
+
+/** A shared chunk: no island of its own, verified by the same hash. */
+interface StoredShared {
+  readonly url: string;
+  readonly identity: string;
+  readonly importers: readonly string[];
 }
 
 interface StoreIndex {
   readonly framework: string;
   readonly bun: string;
   readonly chunks: readonly StoredChunk[];
+  /** Absent in a store written before islands were split: read as none. */
+  readonly shared: readonly StoredShared[];
   /**
    * The stylesheets the island build registered, app-relative and sorted. Registered again at boot
    * from the app's own sources, so a container serving these chunks joins the SAME surface
@@ -56,8 +67,15 @@ export async function writeIslandStore(
       moduleId: chunk.moduleId,
       url: chunk.url,
       identity: contentHash(chunk.code),
+      imports: chunk.imports,
     });
   }
+  const shared: StoredShared[] = [];
+  for (const chunk of bundle.shared) {
+    await Bun.write(join(dir, chunkFile(chunk.url)), chunk.code);
+    written.push(`${ISLAND_STORE_DIR}/${chunkFile(chunk.url)}`);
+    shared.push({ url: chunk.url, identity: contentHash(chunk.code), importers: chunk.importers });
+  }
   const stylesheets = islandStylesheets()
     .map((path) => relative(root, path).split(sep).join('/'))
     .filter((path) => !path.startsWith('..'))
@@ -66,6 +84,7 @@ export async function writeIslandStore(
     framework: frameworkVersion(),
     bun: Bun.version,
     chunks,
+    shared,
     stylesheets,
   };
   await Bun.write(join(dir, INDEX), `${JSON.stringify(index, null, 2)}\n`);
@@ -74,6 +93,9 @@ export async function writeIslandStore(
 
 const isString = (value: unknown): value is string => typeof value === 'string';
 
+const stringsOf = (value: unknown): readonly string[] =>
+  Array.isArray(value) ? value.filter(isString) : [];
+
 /** The index, narrowed field by field — a file on disk is input, never a trusted shape. */
 function parseIndex(value: unknown): StoreIndex | undefined {
   if (typeof value !== 'object' || value === null) return undefined;
@@ -86,15 +108,28 @@ function parseIndex(value: unknown): StoreIndex | undefined {
   for (const entry of chunks) {
     if (typeof entry !== 'object' || entry === null) return undefined;
     const chunk = entry as Record<string, unknown>;
-    const { file, moduleId, url, identity } = chunk;
+    const { file, moduleId, url, identity, imports } = chunk;
     if (!isString(file) || !isString(moduleId) || !isString(url) || !isString(identity))
       return undefined;
-    parsed.push({ file, moduleId, url, identity });
+    parsed.push({ file, moduleId, url, identity, imports: stringsOf(imports) });
+  }
+  const shared: StoredShared[] = [];
+  for (const entry of Array.isArray(record['shared']) ? record['shared'] : []) {
+    if (typeof entry !== 'object' || entry === null) return undefined;
+    const { url, identity, importers } = entry as Record<string, unknown>;
+    if (!isString(url) || !isString(identity)) return undefined;
+    shared.push({ url, identity, importers: stringsOf(importers) });
   }
   const sheets = record['stylesheets'];
   // Absent in a 22.3.2 store: read as none, and the boot builds when it matters (see below).
   const stylesheets = Array.isArray(sheets) ? sheets.filter(isString) : [];
-  return { framework: record['framework'], bun: record['bun'], chunks: parsed, stylesheets };
+  return {
+    framework: record['framework'],
+    bun: record['bun'],
+    chunks: parsed,
+    shared,
+    stylesheets,
+  };
 }
 
 /** A verified store, or the one sentence saying why it cannot be served. */
@@ -118,11 +153,15 @@ export async function readIslandStore(root: string): Promise<StoreRead> {
   if (stored.join('\n') !== present.join('\n')) {
     return { stale: 'the stored islands are not the islands this app has' };
   }
-  const chunks: IslandChunk[] = [];
-  for (const entry of index.chunks) {
+  const verified = async (entry: { readonly url: string; readonly identity: string }) => {
     const bytes = Bun.file(join(dir, chunkFile(entry.url)));
     const code = (await bytes.exists()) ? await bytes.text() : undefined;
-    if (code === undefined || contentHash(code) !== entry.identity) {
+    return code === undefined || contentHash(code) !== entry.identity ? undefined : code;
+  };
+  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` };
     }
     chunks.push({
@@ -131,8 +170,26 @@ export async function readIslandStore(root: string): Promise<StoreRead> {
       url: entry.url,
       code,
       bytes: new TextEncoder().encode(code).byteLength,
+      imports: entry.imports,
+    });
+  }
+  const shared: SharedChunk[] = [];
+  for (const entry of index.shared) {
+    const code = await verified(entry);
+    if (code === undefined) {
+      return { stale: `${entry.url} is missing or does not match its recorded hash` };
+    }
+    shared.push({
+      url: entry.url,
+      code,
+      bytes: new TextEncoder().encode(code).byteLength,
+      importers: entry.importers,
     });
   }
+  // An entry importing a chunk the store does not hold would boot to a 404 in every pod.
+  const held = new Set(shared.map((chunk) => chunk.url));
+  const orphan = chunks.flatMap((chunk) => chunk.imports).find((url) => !held.has(url));
+  if (orphan !== undefined) return { stale: `${orphan}, a shared chunk, is not in the store` };
   // In sorted order, as `island` sheets: `stylesFor` orders those by path, so this is the same
   // surface stylesheet the build that wrote the store joined.
   for (const sheet of index.stylesheets) {
@@ -140,7 +197,7 @@ export async function readIslandStore(root: string): Promise<StoreRead> {
     if (!(await source.exists())) return { stale: `${sheet}, an island stylesheet, is missing` };
     loadStylesheet(join(root, sheet), await source.text(), 'island');
   }
-  return { bundle: islandBundle(chunks) };
+  return { bundle: islandBundle(chunks, shared) };
 }
 
 /**

package/src/mcp-errors.ts

@@ -253,6 +253,9 @@ const CLI_FIXES: Readonly<Record<CliErrorCode, string>> = {
     'x verify --only budgets --json   # after moving each await in Page into export const load',
   X_SITEMAP_EXTRA_INVALID:
     'x routes --json   # then list in seo.sitemap.extra only a path a registered app/ route without a policy answers',
+  X_DEV_RESTART_REQUIRED:
+    'x dev --json   # a fresh process; the supervised x dev restarts itself on such a save',
+  X_DEV_ROOT_GONE: 'x dev --json   # from the app root, once it exists again',
 };
 
 const isCliCode = (code: string): code is CliErrorCode =>

package/src/messages.ts

@@ -76,6 +76,7 @@ const CATALOG = {
   'cli.dev.mail.external': 'mail=external({driver} via {detail})',
   'cli.dev.mail.refused': 'mail=refused({detail})',
   'cli.dev.hmr': 'reloaded {file} in {ms}ms',
+  'cli.dev.restart': 'restarting: {reason} — a module that defines a primitive holds the old code',
   // A hard kill leaves the lock behind and that is normal, not a fault — worth one line so a
   // reader knows why the boot paused, and never a finding.
   'cli.dev.staleLock': 'cleared a stale dev.lock — the previous x dev did not shut down cleanly',

package/src/prerender.ts

@@ -141,7 +141,12 @@ function heaviestSource(
   );
   if (heaviest === undefined) return undefined;
   const chunk = bundle.chunkAt(heaviest.url);
-  return chunk === undefined ? [heaviest.url] : [chunk.file];
+  if (chunk !== undefined) return [chunk.file];
+  // A shared chunk has no file of its own: the chain is an island on THIS page that imports it.
+  const importer = bundle.chunks.find(
+    (one) => one.imports.includes(heaviest.url) && entries.some((entry) => entry.url === one.url),
+  );
+  return importer === undefined ? [heaviest.url] : [importer.file, heaviest.url];
 }
 
 export const DEFAULT_ORIGIN = 'https://localhost';

package/src/sw-precache-plan.ts

@@ -135,8 +135,14 @@ export function precacheAssets(input: PrecacheAssetInput): readonly PrecacheAsse
       }
     }
   }
+  // A wanted entry brings the shared chunks it imports: offline, an entry whose chunk was never
+  // cached is an island that fails to boot on the one page that promised to work without a network.
+  for (const chunk of input.islands.chunks) {
+    if (wanted.has(chunk.url)) for (const url of chunk.imports) wanted.add(url);
+  }
   return [
     ...input.islands.chunks.filter((chunk) => wanted.has(chunk.url)),
+    ...input.islands.shared.filter((chunk) => wanted.has(chunk.url)),
     ...input.styles.chunks,
     ...input.scripts,
   ]

package/src/worker-bundle.ts

@@ -9,7 +9,7 @@ import { dirname, join, relative } from 'node:path';
 import type { Route, UltimateRequest } from '@ultimat3/http';
 import { applyCacheHeaders, json } from '@ultimat3/http';
 import { FrameworkScriptBuildFailedError, type FrameworkScriptKind } from './errors';
-import { describeBuildError, graphHash, stripDebugId } from './island-bundle';
+import { describeBuildError, graphHash, stripDebugId } from './island-identity';
 
 /** Under the dev namespace `/_x` — where the socket it opens (`/_x/sync`) already lives. */
 export const SYNC_WORKER_BASE_PATH = '/_x/sync-worker';