@ultimat3/cli 23.0.0 → 25.0.0

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)]
+    : [];
+}

package/src/island-realtime.ts

@@ -1,12 +1,14 @@
 // Realtime installed for the author, on exactly the islands that use it: an island whose own import
-// graph reaches `@ultimat3/realtime` is built from a virtual entry that first calls
-// `installRealtime({ signal: createSignal })` with THIS bundle's solid-js, then re-exports the
-// island whole. Every other island is built from its own file and pays nothing (plan 101 slice 14).
+// graph reaches `@ultimat3/realtime` is built from a virtual entry that first awaits the page
+// runtime (`island-runtime.ts`), then calls `installRealtime({ signal: createSignal })` with THIS
+// bundle's solid-js, then re-exports the island whole. Every other island pays nothing.
 
-// why: Bun ships no path API; the entry is joined to the root and resolved from its directory.
-import { dirname, join } from 'node:path';
+// why: Bun ships no path API; the entry is joined to the root, the runtime named by its basename.
+import { basename, join } from 'node:path';
 import type { BunPlugin } from 'bun';
+import { RUNTIME_CHUNK_SPECIFIER, type RuntimeChunk } from './island-runtime';
 import { firstInGraph } from './live-routes';
+import { PAGE_BOOT_BASE_PATH } from './worker-bundle';
 
 /**
  * What `Bun.build` is handed for a realtime island: this prefix plus the island's app-root-relative
@@ -22,6 +24,7 @@ const REALTIME = '@ultimat3/realtime';
 const NAMESPACE = 'ultimate-island';
 const INSTALL = 'ultimate:island-realtime';
 const MODULE = 'ultimate:island-module:';
+const WAIT = 'ultimate:island-page-wait';
 
 /**
  * Whether the island's own graph value-imports realtime. Relative specifiers only, which is the
@@ -71,19 +74,31 @@ const entrySource = (file: string): string =>
  * source is part of the chunk's `sourcesContent`, which is what `graphHash` names the URL from, so
  * a path in it gave the same island a different URL in every checkout and every image build.
  * `solid-js` goes through `island-solid-dedupe.ts` like every other import in the graph.
+ *
+ * The await comes first: no hook may run before the page runtime is installed, and the module
+ * graph is not done — so `mount` is not called — until it is. The page boot carries the runtime
+ * on a document rendered for a principal; anywhere else the island loads the runtime chunk, by a
+ * path relative to its own URL, so it resolves under `/islands/` and beside it in `mountIsland`.
+ * The chunk's URL is in this source, so a new runtime is a new URL for every island loading it.
+ * Then the first-paint hold (#506): `mount` waits for the restored records and the open outbox
+ * (capped), so a reload's first render already carries a queued write's overlay.
  */
-const INSTALL_SOURCE =
-  `import { installRealtime } from '${REALTIME}';\n` +
+const installSource = (runtimeUrl: string): string =>
+  `import { holdFirstPaint, installRealtime } from '${REALTIME}';\n` +
+  `import { awaitPageRuntime } from '${WAIT}';\n` +
   `import { createSignal } from 'solid-js';\n` +
+  `await awaitPageRuntime({ boot: '${PAGE_BOOT_BASE_PATH}/', load: () => import('./${basename(runtimeUrl)}') });\n` +
+  `await holdFirstPaint();\n` +
   `installRealtime({ signal: createSignal });\n`;
 
 /**
- * `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.
+ * `runtime` names the realtime every bare `@ultimat3/realtime` of the build resolves to — the copy
+ * the runtime chunk was built against, resolved from the first realtime island's directory. One
+ * copy for all of them, because one copy in the bundle is the requirement: the signal the install
+ * sets is only read by hooks from the same module instance, and the page object it reads is the
+ * shape that copy's runtime installs.
  */
-export function islandRealtimePlugin(root: string, file: string): BunPlugin {
-  const island = join(root, file);
+export function islandRealtimePlugin(root: string, runtime: RuntimeChunk): BunPlugin {
   return {
     name: 'ultimate-island-realtime',
     setup(build) {
@@ -98,16 +113,21 @@ export function islandRealtimePlugin(root: string, file: string): BunPlugin {
       build.onResolve({ filter: /^ultimate:island-module:/ }, (args) => ({
         path: join(root, args.path.slice(MODULE.length)),
       }));
+      // The wait is realtime's, from the copy the hooks are bundled from; the runtime chunk is
+      // another file of this build's output, fetched by the browser and never bundled in.
+      build.onResolve({ filter: /^ultimate:island-page-wait$/ }, () => ({ path: runtime.wait }));
+      build.onResolve({ filter: RUNTIME_CHUNK_SPECIFIER }, (args) => ({
+        path: args.path,
+        external: true,
+      }));
       // 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.
-      build.onResolve({ filter: /^@ultimat3\/realtime$/ }, () => ({
-        path: Bun.resolveSync(REALTIME, dirname(island)),
-      }));
+      build.onResolve({ filter: /^@ultimat3\/realtime$/ }, () => ({ path: runtime.realtime }));
       build.onLoad({ filter: /.*/, namespace: NAMESPACE }, (args) => ({
         contents: args.path.startsWith('entry:')
           ? entrySource(args.path.slice('entry:'.length))
-          : INSTALL_SOURCE,
+          : installSource(runtime.url),
         loader: 'js',
       }));
     },

package/src/island-routes.ts

@@ -3,7 +3,7 @@
 // would be a page that boots in `x dev` and 404s in the image.
 
 import type { Route, UltimateRequest } from '@ultimat3/http';
-import { applyCacheHeaders, json, NO_STORE } from '@ultimat3/http';
+import { applyCacheHeaders, jsonResponse, NO_STORE } from '@ultimat3/http';
 import type { IslandBundle } from './island-bundle';
 import { ISLAND_BASE_PATH } from './island-bundle';
 
@@ -30,7 +30,7 @@ export function islandRoutes(source: IslandSource): readonly Route[] {
         // 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(
+          const missing = jsonResponse(
             {
               ok: false,
               error: {