@ultimat3/cli 24.0.0 → 25.1.0

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)}`;
+}

package/src/island-harness-route.ts

@@ -4,7 +4,7 @@
 // can only be one of those per checkout.
 
 import type { Route, UltimateRequest } from '@ultimat3/http';
-import { html, json } from '@ultimat3/http';
+import { html, jsonResponse } from '@ultimat3/http';
 import type { IslandStatesManifest } from '@ultimat3/testing';
 import {
   islandShotFile,
@@ -13,8 +13,10 @@ import {
   islandStatesNames,
   parseIslandAddress,
 } from '@ultimat3/testing';
+import { hostRefusal } from './dev-dashboard-guard';
 import { harnessPage, ISLAND_HARNESS_PATH } from './island-harness';
 import type { IslandSource } from './island-routes';
+import { quoteArg } from './shell-quote';
 
 /**
  * A getter, never the manifests: `x dev` rebuilds on the watcher tick, and a set captured when the
@@ -25,14 +27,20 @@ import type { IslandSource } from './island-routes';
 export type IslandStatesSource = () => Promise<readonly IslandStatesManifest[]>;
 
 const refused = (cause: string, fix: string): Response =>
-  json(
+  jsonResponse(
     { ok: false, error: { code: 'X_SHOT_ISLAND_UNPHOTOGRAPHABLE', cause, fix } },
     { status: 404 },
   );
 
+/** A value opening with `-` reads as a flag however it is quoted, so it becomes the placeholder. */
+const unflagged = (value: string, placeholder: string): string =>
+  value.startsWith('-') ? placeholder : value;
+
 export interface HarnessRouteInput {
   readonly islands: IslandSource;
   readonly states: IslandStatesSource;
+  /** This dev server's URL, read per request — only what a refused Host's `fix:` line names. */
+  readonly devUrl: () => string;
 }
 
 /**
@@ -44,6 +52,10 @@ export interface HarnessRouteInput {
  * An island or a state this process does not know is the one case that IS refused, and it can only
  * mean the two processes disagree: `x shot` computed its picture list from the states files on disk
  * and this server was booted against an older set.
+ *
+ * Before any of that, the Host: this is a `/_x` route, so it answers a loopback Host only, exactly
+ * as the dashboard does (`hostRefusal`, `X_DEV_HOST_REFUSED`). Without it a DNS-rebinding page
+ * read an island rendered with its declared props — and imported states files — same-origin.
  */
 export function islandHarnessRoutes(input: HarnessRouteInput): readonly Route[] {
   return [
@@ -52,6 +64,8 @@ export function islandHarnessRoutes(input: HarnessRouteInput): readonly Route[]
       path: ISLAND_HARNESS_PATH,
       meta: { name: 'dev._x.island', auth: 'public', tags: ['dev'] },
       handler: async (request: UltimateRequest): Promise<Response> => {
+        const misdirected = hostRefusal(request, input.devUrl());
+        if (misdirected !== undefined) return misdirected;
         const address = parseIslandAddress(request.url.search);
         const all = await input.states();
         const manifest = islandStatesMatching(all, address.island)[0];
@@ -71,7 +85,9 @@ export function islandHarnessRoutes(input: HarnessRouteInput): readonly Route[]
         if (declared === undefined || target === undefined) {
           return refused(
             `${manifest.island} declares no state ${wanted === '' ? '(none named)' : wanted} in theme ${address.theme}`,
-            `x shot --island ${manifest.name} --state ${manifest.states[0]?.id ?? '<id>'} --json`,
+            // Every value here is read off a states file on disk: quoted where it enters the line,
+            // and one opening with `-` is the placeholder — quoting does not stop a flag (L3).
+            `x shot --island ${quoteArg(unflagged(manifest.name, '<island>'))} --state ${quoteArg(unflagged(manifest.states[0]?.id ?? '<id>', '<id>'))} --json`,
           );
         }
         // The chunk is looked up rather than built here: `x dev` already built every island at
@@ -81,7 +97,7 @@ export function islandHarnessRoutes(input: HarnessRouteInput): readonly Route[]
         if (chunk === undefined) {
           return refused(
             `${manifest.island} is declared as an island's states file but this build has no chunk for it`,
-            `x g island ${manifest.name} --at ${manifest.island.split('/').slice(0, -1).join('/')}`,
+            `x g island ${quoteArg(unflagged(manifest.name, '<island>'))} --at ${quoteArg(unflagged(manifest.island.split('/').slice(0, -1).join('/'), '<dir>'))}`,
           );
         }
         return html(harnessPage({ target, state: declared, entry: chunk.url }));

package/src/island-harness-script.ts

@@ -6,6 +6,7 @@
 // the path that serves a page. `@ultimat3/testing`'s `sealNetwork()` patches THIS process's
 // `globalThis.fetch` and cannot reach the page's realm.
 
+import { encodeRecordEnvelope, RECORDS_HEADER } from '@ultimat3/core';
 import type { IslandRouteStub } from '@ultimat3/testing';
 
 /**
@@ -26,6 +27,25 @@ export const HARNESS_GLOBAL = '__xShot';
  */
 const embed = (value: unknown): string => JSON.stringify(value ?? null).replaceAll('<', '\\u003c');
 
+/**
+ * A stub as the page script answers it: `records` becomes the envelope core's own
+ * `encodeRecordEnvelope` builds, behind core's own `RECORDS_HEADER` — the server's two halves,
+ * never a second spelling of either in the browser string below (#683).
+ */
+const wireStub = (stub: IslandRouteStub): unknown => {
+  const { respond } = stub;
+  if (respond.kind !== 'records') return stub;
+  return {
+    match: stub.match,
+    respond: {
+      kind: 'json',
+      ...(respond.status === undefined ? {} : { status: respond.status }),
+      body: encodeRecordEnvelope(respond.data, respond.records, respond.removed),
+      headers: { [RECORDS_HEADER]: '1' },
+    },
+  };
+};
+
 export interface HarnessScriptOptions {
   readonly stubs: readonly IslandRouteStub[];
   /** The frozen instant, with an explicit offset — the manifest's `now`. */
@@ -44,7 +64,7 @@ export interface HarnessScriptOptions {
  * a `pending` fixture, which is a state an author declares on purpose.
  */
 const sealScript = (stubs: readonly IslandRouteStub[]): string => `
-var W=window.${HARNESS_GLOBAL};var STUBS=${embed(stubs)};
+var W=window.${HARNESS_GLOBAL};var STUBS=${embed(stubs.map(wireStub))};
 function bump(){W.activity+=1}
 function stubFor(method,path){var k=method.toUpperCase()+' '+path;
 for(var i=0;i<STUBS.length;i+=1){if(k.indexOf(STUBS[i].match)===0)return STUBS[i].respond}
@@ -57,8 +77,9 @@ function answer(respond,k){
 if(respond===null)return Promise.reject(refuse(k));
 if(respond.kind==='pending')return new Promise(function(){});
 if(respond.kind==='offline')return Promise.reject(new TypeError('x shot: offline fixture for '+k));
+var h=Object.assign({'content-type':'application/json'},respond.headers||{});
 return Promise.resolve(new Response(JSON.stringify(respond.body===undefined?null:respond.body),
-{status:respond.status||200,headers:{'content-type':'application/json'}}))}
+{status:respond.status||200,headers:h}))}
 window.fetch=function(input,init){
 var url=typeof input==='string'?input:(input&&input.url)||String(input);
 var method=(init&&init.method)||(typeof input==='object'&&input&&input.method)||'GET';

package/src/island-identity.ts

@@ -24,14 +24,16 @@ export function stripDebugId(code: string): string {
 /**
  * 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.
+ * `Bun.build` was not byte-deterministic under `minify` before 1.4.1 (oven-sh/bun#40657). 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, 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.
+ * Fixed upstream in 1.4.1; on 1.4.2, 192 child-process build pairs of `examples/dummy`'s islands
+ * under 12- and 16-way contention emitted one byte string per island (2026-10-05, issue #354), and
+ * `island-bytes.test.ts` now demands byte identity outright.
  *
  * `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
@@ -41,12 +43,13 @@ export function stripDebugId(code: string): string {
  * 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.
+ * What this gives up, stated plainly: the URL is source-addressed, not byte-addressed. On a Bun
+ * with the renamer race (< 1.4.1) two processes building the same sources served two byte-strings
+ * at one URL — the same program under different local identifier names — and the alternative,
+ * `minify: { identifiers: false }`, was +47% raw and +20% gzipped. The `engines` floor is now past
+ * the fix, so the reason this function exists is gone; it is kept for now because moving every
+ * island URL to a content hash re-keys every browser cache and every precache manifest, which is a
+ * change of its own to make deliberately (issue #354's follow-up), not a comment edit.
  */
 export function graphHash(file: string, map: string): string {
   const parsed: unknown = JSON.parse(map);

package/src/island-package-dedupe.ts

@@ -0,0 +1,150 @@
+// One copy of each framework package per island chunk: the app's. `island-solid-dedupe.ts`'s rule,
+// for `@ultimat3/*`. The framework ships in lockstep, so the copy the APP installed is the right
+// one for every importer, and a second copy is a second registry, never a feature.
+//
+// Without it `Bun.build` resolves each import from the importing file, so a package nested under
+// another (`node_modules/@ultimat3/ui/node_modules/@ultimat3/core`) is a second module. Linux hid
+// it: Bun links a `file:` package file by file with symlinks, and a realpath folds every nest into
+// one. Windows links without symlinks, so the scaffold smoke's `/posts` island shipped `core` and
+// `schema` more than once: 82,106 B against 60,649 B on Linux, over a 64kb budget.
+// Reproduced on Linux by replacing those links with copies: 75,023 B, and 59,926 B with this plugin.
+
+// why: Bun ships no path API and no existence check; `dirname` walks up the way Node resolution
+// does, `join` builds each candidate, and `existsSync` asks whether one is installed.
+import { existsSync, lstatSync, readdirSync, realpathSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import type { BunPlugin } from 'bun';
+import { conditionTarget } from './island-solid-dedupe';
+
+/** `@ultimat3/<name>` and every subpath of it. */
+export const FRAMEWORK_SPECIFIER = /^@ultimat3\/[^/]+(?:\/.*)?$/;
+
+/** `@ultimat3/core/page` → `{ name: '@ultimat3/core', subpath: './page' }`. */
+export function splitFrameworkSpecifier(specifier: string): {
+  readonly name: string;
+  readonly subpath: string;
+} {
+  const [scope = '', pkg = '', ...rest] = specifier.split('/');
+  return { name: `${scope}/${pkg}`, subpath: rest.length === 0 ? '.' : `./${rest.join('/')}` };
+}
+
+export interface AppPackage {
+  /** The installed package's directory — every export target is joined onto it. */
+  readonly dir: string;
+  /** Its `exports` map, verbatim. */
+  readonly exports: unknown;
+}
+
+/**
+ * The copy the app's own entry would find: `node_modules/<name>` in the app root, then each
+ * directory above it. `null` when none is installed there — a package only nested under another
+ * is left to Bun, which resolves it from its importer as before.
+ */
+export async function resolveAppPackage(root: string, name: string): Promise<AppPackage | null> {
+  for (let dir = root; ; dir = dirname(dir)) {
+    const manifest = join(dir, 'node_modules', name, 'package.json');
+    if (existsSync(manifest)) {
+      const parsed = (await Bun.file(manifest).json()) as { readonly exports?: unknown };
+      // The REAL directory: Bun keys a module by its realpath, so returning the `node_modules/…`
+      // spelling of a symlinked package would bundle it a second time beside every file reached
+      // through its real path — the duplication this plugin exists to remove.
+      return { dir: realpathSync(dirname(manifest)), exports: parsed.exports };
+    }
+    if (dirname(dir) === dir) return null;
+  }
+}
+
+/** Where `subpath` lands in the app's copy, under the browser conditions, or `undefined`. */
+export function appPackagePath(pkg: AppPackage, subpath: string): string | undefined {
+  const exports = pkg.exports;
+  if (exports === null || typeof exports !== 'object' || !Object.hasOwn(exports, subpath)) {
+    return undefined;
+  }
+  const target = conditionTarget((exports as Record<string, unknown>)[subpath]);
+  return target === undefined ? undefined : join(pkg.dir, target);
+}
+
+/** Installed beside `solidDedupePlugin`, before any plugin loads a file. One lookup per package. */
+export function frameworkDedupePlugin(root: string): BunPlugin {
+  const found = new Map<string, Promise<AppPackage | null>>();
+  return {
+    name: 'ultimate-framework-dedupe',
+    setup(build): void {
+      build.onResolve({ filter: FRAMEWORK_SPECIFIER }, async (args) => {
+        const { name, subpath } = splitFrameworkSpecifier(args.path);
+        let pending = found.get(name);
+        if (pending === undefined) {
+          pending = resolveAppPackage(root, name);
+          found.set(name, pending);
+        }
+        const pkg = await pending;
+        const path = pkg === null ? undefined : appPackagePath(pkg, subpath);
+        if (path === undefined) return undefined;
+        // Only when Bun's own answer is a SECOND copy, or this file under a second spelling
+        // (`sameModule`). A path a plugin returns loses its package's `sideEffects`, so taking over
+        // every import shipped ~2.2 KB of untree-shaken core in each island of examples/dummy
+        // (21,945 → 24,202 B on /pricing) while folding nothing on Linux.
+        return sameModule(path, args.path, args.importer) ? undefined : { path };
+      });
+    },
+  };
+}
+
+/**
+ * Whether Bun, left alone, resolves `specifier` from `importer` to `path` itself — as the same
+ * STRING, because Bun keys a module by its path string, never by the file. This compared realpaths
+ * once, which is right on Linux (Bun's resolver answers a realpath, so the strings agree) and wrong
+ * on Windows, where it answers the junction spelling: both sides realpath to one file, Bun kept its
+ * own spelling, every nest this plugin folded got the realpath one, and one file shipped as two
+ * modules (the windows job's `/posts`, 81,306 B against Linux's 59,849 B). `resolve` is injectable
+ * so that spelling can be handed in on a host whose resolver never produces it.
+ */
+export function sameModule(
+  path: string,
+  specifier: string,
+  importer: string,
+  resolve: (specifier: string, from: string) => string = Bun.resolveSync,
+): boolean {
+  try {
+    return resolve(specifier, dirname(importer)) === path;
+  } catch {
+    // Unresolvable from the importer: the app's copy is the only answer there is.
+    return false;
+  }
+}
+
+/**
+ * Whether any installed `@ultimat3/*` package carries a NESTED framework package that is a real
+ * directory rather than a symlink — a second copy no realpath folds, which is a `file:` install on
+ * Windows. Only then is the plugin installed: Bun stops honouring a package's `sideEffects` for
+ * every import an `onResolve` hook sees, even one it answers `undefined` to, so a hook on a tree
+ * with nothing to fold cost each island of examples/dummy ~2.2 KB (21,945 → 24,202 B on /pricing).
+ */
+export function hasNestedFrameworkCopies(root: string): boolean {
+  for (let dir = root; ; dir = dirname(dir)) {
+    const scope = join(dir, 'node_modules', '@ultimat3');
+    if (existsSync(scope)) {
+      for (const pkg of readdirSync(scope)) {
+        const nested = join(scope, pkg, 'node_modules', '@ultimat3');
+        if (!existsSync(nested)) continue;
+        for (const inner of readdirSync(nested)) {
+          if (!lstatSync(join(nested, inner)).isSymbolicLink()) return true;
+        }
+      }
+    }
+    if (dirname(dir) === dir) return false;
+  }
+}
+
+/** The plugin list entry: the dedupe when a nested copy exists, nothing otherwise. */
+export function frameworkDedupePlugins(
+  root: string,
+  platform: NodeJS.Platform = process.platform,
+): readonly BunPlugin[] {
+  // Windows always: a `file:` install there links packages through junctions Bun does not fold,
+  // so the same file is reached under two spellings — the windows job's `/posts` shipped 80.2kb
+  // against Linux's 60kb with only the nested-copy check deciding.
+  return platform === 'win32' || hasNestedFrameworkCopies(root)
+    ? [frameworkDedupePlugin(root)]
+    : [];
+}