@ultimat3/cli 23.0.0 → 25.0.0

package/src/island-bundle.ts

@@ -15,26 +15,32 @@
 // `globalThis` object created lazily by the first transport call or realtime hook. Measured before
 // that decision on `examples/dummy`, a core-importing wrapper cost contact-sales 875 → 8,827 B.
 // What IS prepended is the realtime install, and only where the island's graph reaches
-// `@ultimat3/realtime` (`island-realtime.ts`). Measured on a fixture, As of 2026-09-22: a Solid
-// island reading `useConnection` 64,964 → 65,067 B (+103 B); an island not reaching realtime +0.
+// `@ultimat3/realtime` (`island-realtime.ts`); the page runtime it awaits is ONE more output,
+// `page-runtime.<identity>.js` beside the entries (`island-runtime.ts`), never inlined into one (#505).
 
 // Bun ships no path API. `posix` does the specifier arithmetic (an app-relative route file is
 // POSIX by construction), `join`/`basename` the filesystem side.
 import { basename, join, posix, relative, sep } from 'node:path';
-import { ISLAND_EXTENSION, IslandInvalidError, islandModuleId } from '@ultimat3/render';
-import { APP_CONFIG_EXPORT } from './app-auth';
-import { APP_CONFIG_FILE } from './app-root';
+import { ISLAND_EXTENSION, islandModuleId } from '@ultimat3/render';
+import { loadAppConfig } from './app-config-load';
 import { IslandBuildFailedError } from './errors';
+import { refuseDuplicatedModules } from './island-duplicate-refusal';
+import { entryMissing, onlyMissing } from './island-entry-missing';
 import { describeBuildError, sourcesContentOf, stableChunk, stripDebugId } from './island-identity';
 import type { BuiltOutput, LinkedFile } from './island-link';
 import { linkOutputs, sharedChunkName } from './island-link';
+import { frameworkDedupePlugins } from './island-package-dedupe';
 import {
   islandRealtimePlugin,
   REALTIME_ISLAND_ENTRY,
   reachesRealtime,
   realtimeIslandEntry,
 } from './island-realtime';
+import type { Runtimes } from './island-runtime';
+import { loadingRuntime, mergeBuilds, runtimeBuilder, runtimeShared } from './island-runtime';
 import { solidDedupePlugin } from './island-solid-dedupe';
+import type { SourcePaths } from './island-sources';
+import { sourcesOnDisk } from './island-sources';
 import { islandStylesPlugin } from './island-styles';
 import { hasPathSegment } from './path-segments';
 import { solidJsxPlugin } from './solid-loader';
@@ -71,6 +77,8 @@ export interface IslandChunk {
    * beyond `bytes`, what a precached page must carry with it. Empty for an island sharing nothing.
    */
   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;
 }
 
 /** A module two or more islands import, served once beside them. */
@@ -81,6 +89,7 @@ export interface SharedChunk {
   readonly bytes: number;
   /** The islands (app-root-relative) that load it — for a finding that names what an author edits. */
   readonly importers: readonly string[];
+  readonly sources?: SourcePaths;
 }
 
 export interface IslandBundle {
@@ -120,6 +129,7 @@ async function buildAll(
   root: string,
   files: readonly string[],
   splitting: boolean,
+  runtimes: Runtimes,
 ): Promise<{ readonly chunks: readonly IslandChunk[]; readonly shared: readonly SharedChunk[] }> {
   if (files.length === 0) return { chunks: [], shared: [] };
   // Inside the refusal: the realtime probe PARSES the island's graph, and a file that will not
@@ -135,6 +145,7 @@ async function buildAll(
   // 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 runtime = live[0] === undefined ? undefined : await runtimes(live[0]);
   const entrypoints = files.map((file, index) =>
     realtime[index] === true ? realtimeIslandEntry(file) : join(root, file),
   );
@@ -162,10 +173,13 @@ async function buildAll(
       //
       // The dedupe goes FIRST: it answers `solid-js` specifiers before either plugin loads a file,
       // so the `solid-js/web` helpers the JSX transform writes into a symlinked package resolve
-      // to the app's one copy. See `island-solid-dedupe.ts` for the measurement.
+      // to the app's one copy. See `island-solid-dedupe.ts` for the measurement. `@ultimat3/*`
+      // 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: [
-        ...(live[0] === undefined ? [] : [islandRealtimePlugin(root, live[0])]),
+        ...(runtime === undefined ? [] : [islandRealtimePlugin(root, runtime)]),
         solidDedupePlugin(root),
+        ...frameworkDedupePlugins(root),
         solidJsxPlugin,
         islandStylesPlugin,
       ],
@@ -188,9 +202,13 @@ async function buildAll(
       // output has. See `graphHash`. Measured on 1.4.0 against a 131 kB island: 277ms with it and
       // 276ms without, so the map costs nothing worth naming.
       sourcemap: 'external',
+      // The fifth: which inputs each output carries, so one module bundled twice is refused below
+      // rather than shipped (`island-duplicates.ts`). Measured on 1.4.2 against examples/dummy's
+      // feed island, five interleaved builds each way: 44 ms without, 48 ms with, noise-level.
+      metafile: true,
     });
   } catch (error) {
-    throw await blame(root, files, error, splitting);
+    throw await blame(root, files, error, splitting, runtimes);
   }
   if (!built.success) {
     throw new IslandBuildFailedError({
@@ -198,9 +216,18 @@ async function buildAll(
       logs: built.logs.map((log) => String(log)).join('; '),
     });
   }
-  const linked = linkOutputs(await builtOutputs(files, built.outputs));
-  const chunks = entryChunks(files, linked);
-  return { chunks, shared: sharedChunks(chunks, linked) };
+  if (built.metafile === undefined) {
+    throw new IslandBuildFailedError({
+      file: files.join(', '),
+      logs: 'the bundler returned no metafile',
+    });
+  }
+  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 shared = sharedChunks(chunks, linked, sources);
+  return { chunks, shared: [...shared, ...runtimeShared(runtime, live)] };
 }
 
 /**
@@ -213,11 +240,12 @@ async function blame(
   files: readonly string[],
   error: unknown,
   splitting: boolean,
+  runtimes: Runtimes,
 ): Promise<IslandBuildFailedError> {
   if (files.length > 1) {
     for (const file of files) {
       try {
-        await buildAll(root, [file], splitting);
+        await buildAll(root, [file], splitting, runtimes);
       } catch (alone) {
         if (alone instanceof IslandBuildFailedError) return alone;
       }
@@ -242,8 +270,10 @@ const withoutExtension = (file: string): string =>
 
 /** Every code output paired with its source map's inputs and, for an entry, its island. */
 async function builtOutputs(
+  root: string,
   files: readonly string[],
   artifacts: readonly Bun.BuildArtifact[],
+  sourcePaths: Map<string, SourcePaths>,
 ): Promise<readonly BuiltOutput[]> {
   const byStem = new Map(files.map((file) => [withoutExtension(file), file]));
   const maps = new Map<string, string>();
@@ -256,7 +286,9 @@ async function builtOutputs(
     const key = outputKey(artifact.path);
     const file = artifact.kind === 'entry-point' ? byStem.get(withoutExtension(key)) : undefined;
     const map = maps.get(`${artifact.path}.map`);
-    const sources = map === undefined ? undefined : sourcesContentOf(JSON.parse(map), true);
+    const parsed: unknown = map === undefined ? undefined : JSON.parse(map);
+    const sources = parsed === undefined ? undefined : sourcesContentOf(parsed, true);
+    sourcePaths.set(key, await sourcesOnDisk(root, parsed));
     if (sources === undefined || (artifact.kind === 'entry-point' && file === undefined)) {
       throw new IslandBuildFailedError({
         file: file ?? key,
@@ -277,6 +309,7 @@ async function builtOutputs(
 function entryChunks(
   files: readonly string[],
   linked: readonly LinkedFile[],
+  sources: ReadonlyMap<string, SourcePaths>,
 ): readonly IslandChunk[] {
   const shared = new Map(
     linked
@@ -312,6 +345,7 @@ function entryChunks(
       // different files at one address. `bytes` is measured on THAT code, never on this build's.
       ...stableChunk(file, entry.identity, entry.code),
       imports: closure(entry.imports),
+      sources: sources.get(entry.path) ?? [],
     });
   }
   return chunks;
@@ -321,6 +355,7 @@ function entryChunks(
 function sharedChunks(
   chunks: readonly IslandChunk[],
   linked: readonly LinkedFile[],
+  sources: ReadonlyMap<string, SourcePaths>,
 ): readonly SharedChunk[] {
   const out: SharedChunk[] = [];
   for (const one of linked) {
@@ -333,6 +368,7 @@ function sharedChunks(
         .filter((chunk) => chunk.imports.includes(url))
         .map((chunk) => chunk.file)
         .sort(),
+      sources: sources.get(one.path) ?? [],
     });
   }
   return out.sort((a, b) => (a.url < b.url ? -1 : a.url > b.url ? 1 : 0));
@@ -357,20 +393,9 @@ export interface BuildIslandsOptions {
   readonly sharedChunks?: boolean;
 }
 
-/**
- * `islands.sharedChunks` as `defineConfig` validated it — `false` for an app with no config file or
- * none of it. Structural, never `instanceof`, for `loadNavigation`'s reason.
- */
+/** `islands.sharedChunks` off the one loader (`app-config-load.ts`) — `false` with no config file. */
 export async function loadSharedChunks(root: string): Promise<boolean> {
-  const configPath = join(root, APP_CONFIG_FILE);
-  if (!(await Bun.file(configPath).exists())) return false;
-  const config: unknown = ((await import(configPath)) as Record<string, unknown>)[
-    APP_CONFIG_EXPORT
-  ];
-  if (typeof config !== 'object' || config === null) return false;
-  const islands: unknown = (config as Record<string, unknown>)['islands'];
-  if (typeof islands !== 'object' || islands === null) return false;
-  return (islands as Record<string, unknown>)['sharedChunks'] === true;
+  return (await loadAppConfig(root))?.islands.sharedChunks ?? false;
 }
 
 /** Build every island in the app. An app with none returns an empty bundle and costs one glob. */
@@ -385,43 +410,15 @@ export async function buildIslands(
   // an empty bundle here would surface two steps later, as a chunk table with no entry for a file
   // the caller can see on disk.
   if (only !== undefined && files.length === 0) throw onlyMissing(only, discovered);
+  const runtimes = runtimeBuilder(root, ISLAND_BASE_PATH);
   if (options.sharedChunks ?? (await loadSharedChunks(root))) {
-    const built = await buildAll(root, files, true);
+    const built = await buildAll(root, files, true, runtimes);
     return islandBundle(built.chunks, built.shared);
   }
-  // One build per island, splitting off: each chunk is self-contained, so its size is the whole
-  // answer to "what does booting this island cost?" and nothing is shaken for another island.
-  const solo = await Promise.all(files.map((file) => buildAll(root, [file], false)));
-  return islandBundle(solo.flatMap((one) => one.chunks));
-}
-
-/**
- * Same code as an unbuildable `src`: "this path cannot become a client entry" is one condition.
- *
- * Two fixes, because there are two causes and only one of them can be repaired by naming a path.
- * The line was `pass only: '<app-root-relative path>.island.tsx'` — a placeholder nobody can run,
- * which no gate could see: `fixProblem` fails a fix only for ADVICE with no command token, and a
- * sentence with neither is not advice. Both forms below are constructed from what the caller
- * already handed in, so neither can name a path this app does not have.
- */
-function onlyMissing(only: string, discovered: readonly string[]): IslandInvalidError {
-  const cause =
-    `buildIslands was asked for ${JSON.stringify(only)} alone, which is not one of the ` +
-    `${discovered.length} islands this app has (${discovered.length === 0 ? 'none' : discovered.join(', ')})`;
-  // The basename match first: a filter that misses normally missed on the PREFIX — a route-relative
-  // specifier where `discoverIslands`' app-root-relative path was wanted — and the filename
-  // survives that. Falling back to the first keeps the fix a real path rather than a shape.
-  const nearest =
-    discovered.find((file) => posix.basename(file) === posix.basename(only)) ?? discovered[0];
-  // An app with no islands cannot be pointed at one, so the fix WRITES the file that was asked
-  // for — the same command `entryMissing` hands back, split off the same path.
-  if (nearest === undefined) {
-    return new IslandInvalidError(
-      cause,
-      `x g island ${posix.basename(only, ISLAND_EXTENSION)} --at ${posix.dirname(only)}`,
-    );
-  }
-  return new IslandInvalidError(cause, `buildIslands(root, { only: '${nearest}' })`);
+  // One build per island, splitting off: each chunk is self-contained but for the page runtime,
+  // the ONE file beside it every realtime island loads, counted once however many load it.
+  const solo = await Promise.all(files.map((file) => buildAll(root, [file], false, runtimes)));
+  return islandBundle(...mergeBuilds(solo));
 }
 
 export function islandBundle(
@@ -449,25 +446,6 @@ export function islandBundle(
   };
 }
 
-/**
- * The specifier named no file the build could bundle. `X_ISLAND_INVALID` is render's and is
- * borrowed rather than renamed here: "this src cannot become a client entry" is the condition that
- * code already means, and a second name for it is a second thing to look up.
- */
-function entryMissing(
-  routeFile: string,
-  src: string,
-  target: string,
-  chunks: readonly IslandChunk[],
-): IslandInvalidError {
-  const known = chunks.map((chunk) => chunk.file);
-  return new IslandInvalidError(
-    `${routeFile} declares island src ${JSON.stringify(src)}, which resolves to ${target} — a ` +
-      `file this build did not bundle (${known.length === 0 ? 'it found no islands at all' : `it found ${known.join(', ')}`})`,
-    `x g island ${posix.basename(target, ISLAND_EXTENSION)} --at ${posix.dirname(target)}`,
-  );
-}
-
 /** Write every chunk under the static export, at the same URL the documents already carry. */
 export async function writeIslands(bundle: IslandBundle, out: string): Promise<void> {
   for (const chunk of [...bundle.chunks, ...bundle.shared]) {

package/src/island-capture.ts

@@ -265,7 +265,7 @@ export async function captureIslandState(
         state: target.state,
         theme: target.theme,
         reason: `produced ${bytes.byteLength} bytes, under the ${floor}-byte floor — that is not an image`,
-        fix: `x shot --island ${target.name} --browser /usr/bin/chromium --json`,
+        fix: `x shot --island ${target.name} --browser /usr/bin/chromium --json   # macOS: --browser "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"; Windows: --browser "C:\\Program Files\\Google\\Chrome\\Application\\chrome.exe"`,
       });
     }
     await Bun.write(join(options.outDir, target.file), bytes);

package/src/island-duplicate-refusal.ts

@@ -0,0 +1,57 @@
+// What a module bundled twice costs the build. A framework bug refuses it: one file under two
+// spellings, or a second `@ultimat3/*` copy, is the framework's resolver or dedupe failing. A
+// third-party package installed twice with identical bytes is the app's lockfile, which the app
+// did not write by hand — so it is a warning naming the bytes, never a broken build.
+
+import { logger, UltimateError } from '@ultimat3/core';
+import type { DuplicatedModule, IslandMetafile, ModuleIdentityIo } from './island-duplicates';
+import { duplicatedModules, hostIo } from './island-duplicates';
+import { quoteArg } from './shell-quote';
+
+/** The framework's own scope: a second copy of one of these is ours to fold (`island-package-dedupe.ts`). */
+const FRAMEWORK_SCOPE = '@ultimat3/';
+
+/** A duplicate only the framework can have caused. */
+export const isFrameworkDuplicate = (one: DuplicatedModule): boolean =>
+  one.sameFile || (one.packageName?.startsWith(FRAMEWORK_SCOPE) ?? false);
+
+/**
+ * Its own code, not `X_BUILD_FAILED`: that one's fix re-runs `bun build`, which SUCCEEDS here — the
+ * build did not fail, it shipped one module twice and said `success: true`. Every refusal is a
+ * framework defect, so the fix is the report that gets it fixed.
+ */
+export class IslandModuleDuplicatedError extends UltimateError {
+  constructor(island: string, found: readonly DuplicatedModule[]) {
+    const wasted = found.reduce((sum, one) => sum + one.wastedBytes, 0);
+    const listed = found
+      .slice(0, 3)
+      .map((one) => `${one.package ?? 'one file'} as ${one.spellings.join(' and ')}`)
+      .join('; ');
+    super({
+      code: 'X_ISLAND_MODULE_DUPLICATED',
+      cause:
+        `${island} bundles ${found.length} module(s) more than once in ${found[0]?.output ?? 'its chunk'} ` +
+        `(${wasted} B shipped twice): ${listed}${found.length > 3 ? `; and ${found.length - 3} more` : ''}`,
+      fix: `gh issue create --repo developerz-ai/ultimate --title ${quoteArg(`X_ISLAND_MODULE_DUPLICATED in ${island}`)} — paste this error's --json as the body: the framework bundled one of its own modules twice`,
+    });
+  }
+}
+
+/** The one line a third-party copy costs: the island, the package, the bytes, and what to run. */
+export const thirdPartyWarning = (island: string, one: DuplicatedModule): string =>
+  `X_ISLAND_MODULE_DUPLICATED (warning): ${island} bundles ${one.package ?? 'a package'} twice ` +
+  `(${one.wastedBytes} B shipped twice, as ${one.spellings.join(' and ')}) — fix: bun why ` +
+  `${quoteArg(one.packageName ?? '<package>')}, then bun install --force to fold the copies`;
+
+/** Refuse a framework duplicate; warn about each third-party one. */
+export async function refuseDuplicatedModules(
+  island: string,
+  metafile: IslandMetafile,
+  io: ModuleIdentityIo = hostIo(),
+  warn: (line: string) => void = (line) => logger.warn(line),
+): Promise<void> {
+  const found = await duplicatedModules(metafile, io);
+  const fatal = found.filter(isFrameworkDuplicate);
+  if (fatal.length > 0) throw new IslandModuleDuplicatedError(island, fatal);
+  for (const one of found) warn(thirdPartyWarning(island, one));
+}

package/src/island-duplicates.ts

@@ -0,0 +1,221 @@
+// One module, one copy per island chunk — read off the build's metafile. Bun keys a module by its
+// path STRING, so one file reached under two spellings ships twice: a drive letter in two cases, `\`
+// beside `/`, a junction beside its target. Measured on the windows job, the scaffold's `/posts`
+// island shipped 81,306 B against Linux's 59,849 B from the same source, with `success: true`.
+
+// why: Bun ships no path API and no realpath; `win32`/`posix` let a Windows-shaped metafile be
+// judged on any host, and `realpathSync` folds a link into the file it names.
+import { realpathSync } from 'node:fs';
+import { posix, win32 } from 'node:path';
+
+/** The part of `Bun.BuildMetafile` the guard reads — `Bun.BuildMetafile` satisfies it as is. */
+export interface IslandMetafile {
+  readonly outputs: Readonly<
+    Record<
+      string,
+      { readonly inputs: Readonly<Record<string, { readonly bytesInOutput: number }>> }
+    >
+  >;
+}
+
+/** The filesystem the guard asks, injectable so a Windows tree can be judged on a Linux runner. */
+export interface ModuleIdentityIo {
+  /** What Bun's metafile keys are relative to: the BUILDING process's cwd (`island-sources.ts`). */
+  readonly cwd: string;
+  /** win32 compares case-insensitively and treats `\` and `/` as one separator. */
+  readonly platform: NodeJS.Platform;
+  /** Throws for a path with no file behind it — a virtual module keeps its own spelling. */
+  readonly realpath: (path: string) => string;
+  /** A file's text, or `undefined` when there is none. */
+  readonly readText: (path: string) => Promise<string | undefined>;
+}
+
+export const hostIo = (): ModuleIdentityIo => ({
+  cwd: process.cwd(),
+  platform: process.platform,
+  realpath: (path) => realpathSync(path),
+  readText: async (path) => {
+    const file = Bun.file(path);
+    return (await file.exists()) ? file.text() : undefined;
+  },
+});
+
+/**
+ * `path` as `island-package-dedupe.ts` spells every framework file it answers: the realpath. What a
+ * resolver answered under another spelling (a Windows junction) is renamed through this before a
+ * plugin hands it to `Bun.build`, so one file is one module string. A path with no file stays.
+ */
+export function realSpelling(path: string): string {
+  try {
+    return realpathSync(path);
+  } catch {
+    return path;
+  }
+}
+
+/** One module an output carries more than once. */
+export interface DuplicatedModule {
+  /** The output path as the metafile names it. */
+  readonly output: string;
+  /** Every spelling it was bundled under, absolute, in the metafile's order. */
+  readonly spellings: readonly string[];
+  /** Bytes the output carries beyond its largest copy. */
+  readonly wastedBytes: number;
+  /** One file under several spellings (`true`), or byte-identical copies of one package (`false`). */
+  readonly sameFile: boolean;
+  /** `name@version` when the copies are a package's. */
+  readonly package?: string;
+  /** The package's `name` alone — what `bun why` is asked about. */
+  readonly packageName?: string;
+}
+
+interface Input {
+  readonly spelling: string;
+  readonly bytes: number;
+  readonly canonical: string;
+}
+
+interface PackageOf {
+  readonly id: string;
+  readonly name: string;
+  readonly subpath: string;
+}
+
+/** The realpath, `/`-separated, lowercased where the filesystem is case-insensitive. */
+function canonicalOf(absolute: string, io: ModuleIdentityIo): string {
+  let real = absolute;
+  try {
+    real = io.realpath(absolute);
+  } catch {
+    // No file behind it: a virtual module, judged by its spelling alone.
+  }
+  const slashed = real.replace(/^\\\\\?\\/, '').replaceAll('\\', '/');
+  return io.platform === 'win32' ? slashed.toLowerCase() : slashed;
+}
+
+/** The nearest `package.json` with a `name` above `file`, as `name@version` + the file under it. */
+async function packageOf(
+  file: string,
+  io: ModuleIdentityIo,
+  manifests: Map<string, Promise<{ name: string; version: string } | null>>,
+): Promise<PackageOf | undefined> {
+  const path = io.platform === 'win32' ? win32 : posix;
+  for (let dir = path.dirname(file); ; dir = path.dirname(dir)) {
+    let pending = manifests.get(dir);
+    if (pending === undefined) {
+      pending = io.readText(path.join(dir, 'package.json')).then(namedManifest);
+      manifests.set(dir, pending);
+    }
+    const found = await pending;
+    if (found !== null) {
+      const subpath = path.relative(dir, file).replaceAll('\\', '/');
+      const id = `${found.name}@${found.version}`;
+      return {
+        id,
+        name: found.name,
+        subpath: io.platform === 'win32' ? subpath.toLowerCase() : subpath,
+      };
+    }
+    if (path.dirname(dir) === dir) return undefined;
+  }
+}
+
+function namedManifest(text: string | undefined): { name: string; version: string } | null {
+  if (text === undefined) return null;
+  try {
+    const parsed: unknown = JSON.parse(text);
+    if (typeof parsed !== 'object' || parsed === null) return null;
+    const { name, version } = parsed as Record<string, unknown>;
+    return typeof name === 'string'
+      ? { name, version: typeof version === 'string' ? version : '' }
+      : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Every module an output carries twice: first by canonical path, then — between inputs that are
+ * still distinct — by package. Two copies count as one module only when they are the same file of
+ * the same `name@version` AND hold the same bytes, so a patched or differently-versioned copy is
+ * left alone. Contents are read only for a package collision, never for every input.
+ */
+export async function duplicatedModules(
+  metafile: IslandMetafile,
+  io: ModuleIdentityIo,
+): Promise<readonly DuplicatedModule[]> {
+  const path = io.platform === 'win32' ? win32 : posix;
+  const manifests = new Map<string, Promise<{ name: string; version: string } | null>>();
+  const found: DuplicatedModule[] = [];
+  for (const [output, { inputs }] of Object.entries(metafile.outputs)) {
+    const byPath = new Map<string, Input[]>();
+    for (const [key, { bytesInOutput }] of Object.entries(inputs)) {
+      // A namespaced key (`x-realtime-island:…`) is a virtual module: no file, no second spelling.
+      if (/^[a-z][\w-]+:(?![\\/])/i.test(key)) continue;
+      const spelling = path.resolve(io.cwd, key);
+      const canonical = canonicalOf(spelling, io);
+      const group = byPath.get(canonical) ?? [];
+      group.push({ spelling, bytes: bytesInOutput, canonical });
+      byPath.set(canonical, group);
+    }
+    for (const group of byPath.values()) {
+      if (group.length > 1) found.push(duplicate(output, group, true));
+    }
+    found.push(...(await packageCopies(output, [...byPath.values()], io, manifests)));
+  }
+  return found;
+}
+
+/** Distinct files that are one package's one file, byte for byte, under two install paths. */
+async function packageCopies(
+  output: string,
+  groups: readonly (readonly Input[])[],
+  io: ModuleIdentityIo,
+  manifests: Map<string, Promise<{ name: string; version: string } | null>>,
+): Promise<readonly DuplicatedModule[]> {
+  const byPackage = new Map<string, { pkg: PackageOf; inputs: Input[] }>();
+  for (const group of groups) {
+    const first = group[0];
+    if (first === undefined) continue;
+    const pkg = await packageOf(first.spelling, io, manifests);
+    if (pkg === undefined) continue;
+    const key = `${pkg.id}/${pkg.subpath}`;
+    const entry = byPackage.get(key) ?? { pkg, inputs: [] };
+    entry.inputs.push(first);
+    byPackage.set(key, entry);
+  }
+  const found: DuplicatedModule[] = [];
+  for (const { pkg, inputs } of byPackage.values()) {
+    if (inputs.length < 2) continue;
+    const byHash = new Map<string, Input[]>();
+    for (const input of inputs) {
+      const text = await io.readText(input.spelling);
+      if (text === undefined) continue;
+      const hash = String(Bun.hash(text));
+      byHash.set(hash, [...(byHash.get(hash) ?? []), input]);
+    }
+    for (const same of byHash.values()) {
+      if (same.length > 1) found.push(duplicate(output, same, false, pkg.id, pkg.name));
+    }
+  }
+  return found;
+}
+
+function duplicate(
+  output: string,
+  inputs: readonly Input[],
+  sameFile: boolean,
+  id?: string,
+  name?: string,
+): DuplicatedModule {
+  const bytes = inputs.map((one) => one.bytes);
+  const wastedBytes = bytes.reduce((sum, one) => sum + one, 0) - Math.max(...bytes);
+  return {
+    output,
+    spellings: inputs.map((one) => one.spelling),
+    wastedBytes,
+    sameFile,
+    ...(id === undefined ? {} : { package: id }),
+    ...(name === undefined ? {} : { packageName: name }),
+  };
+}

package/src/island-entry-missing.ts

@@ -0,0 +1,64 @@
+// The refusals for an island the build cannot answer: a `buildIslands({ only })` naming no island, and
+// a route's `src` resolving to a file the build did not bundle. Split from `island-bundle.ts`, which
+// keeps the build; both refusals are render's `X_ISLAND_INVALID` (see `entryMissing`).
+
+// why: Bun ships no path API; `posix` does the specifier arithmetic on app-relative paths.
+import { posix } from 'node:path';
+import { ISLAND_EXTENSION, IslandInvalidError } from '@ultimat3/render';
+import { quoteArg } from './shell-quote';
+
+/**
+ * Same code as an unbuildable `src`: "this path cannot become a client entry" is one condition.
+ *
+ * Two fixes, because there are two causes and only one of them can be repaired by naming a path.
+ * The line was `pass only: '<app-root-relative path>.island.tsx'` — a placeholder nobody can run,
+ * which no gate could see: `fixProblem` fails a fix only for ADVICE with no command token, and a
+ * sentence with neither is not advice. Both forms below are constructed from what the caller
+ * already handed in, so neither can name a path this app does not have.
+ */
+export function onlyMissing(only: string, discovered: readonly string[]): IslandInvalidError {
+  const cause =
+    `buildIslands was asked for ${JSON.stringify(only)} alone, which is not one of the ` +
+    `${discovered.length} islands this app has (${discovered.length === 0 ? 'none' : discovered.join(', ')})`;
+  // The basename match first: a filter that misses normally missed on the PREFIX — a route-relative
+  // specifier where `discoverIslands`' app-root-relative path was wanted — and the filename
+  // survives that. Falling back to the first keeps the fix a real path rather than a shape.
+  const nearest =
+    discovered.find((file) => posix.basename(file) === posix.basename(only)) ?? discovered[0];
+  // An app with no islands cannot be pointed at one, so the fix WRITES the file that was asked
+  // for — the same command `entryMissing` hands back, split off the same path.
+  if (nearest === undefined) {
+    return new IslandInvalidError(cause, generateIslandFix(only));
+  }
+  return new IslandInvalidError(cause, `buildIslands(root, { only: '${nearest}' })`);
+}
+
+/**
+ * The specifier named no file the build could bundle. `X_ISLAND_INVALID` is render's and is
+ * borrowed rather than renamed here: "this src cannot become a client entry" is the condition that
+ * code already means, and a second name for it is a second thing to look up.
+ */
+export function entryMissing(
+  routeFile: string,
+  src: string,
+  target: string,
+  chunks: readonly { readonly file: string }[],
+): IslandInvalidError {
+  const known = chunks.map((chunk) => chunk.file);
+  return new IslandInvalidError(
+    `${routeFile} declares island src ${JSON.stringify(src)}, which resolves to ${target} — a ` +
+      `file this build did not bundle (${known.length === 0 ? 'it found no islands at all' : `it found ${known.join(', ')}`})`,
+    generateIslandFix(target),
+  );
+}
+
+/**
+ * `x g island <name> --at <dir>`, split off a path the caller or a route file supplied. Each half is
+ * quoted (security audit of plan 101 sweep 1c, M1), and one opening with `-` is the placeholder:
+ * quoting does not stop `x` reading `--json` as a flag (L3).
+ */
+function generateIslandFix(path: string): string {
+  const name = posix.basename(path, ISLAND_EXTENSION);
+  const dir = posix.dirname(path);
+  return `x g island ${quoteArg(name.startsWith('-') ? '<name>' : name)} --at ${quoteArg(dir.startsWith('-') ? '<dir>' : dir)}`;
+}