@ultimat3/cli 20.2.0 → 21.0.0

package/src/e2e-preload.ts

@@ -0,0 +1,64 @@
+// The e2e step's own preload: when the gate names an app root (`ULTIMATE_E2E_ROOT`, set by
+// `verify-e2e.ts`), spawn that app on a throwaway database, open ONE browser, install it as the
+// `page` fixture and the `e2eTest` driver, register `deploy.newBuild()` as a restart of the app on
+// its own port, and hand both to any test that asks `e2eBrowser()` / `e2eApp()`.
+
+import { afterAll, beforeEach } from 'bun:test';
+import type { E2eBrowser } from './cdp-browser';
+import { openE2eBrowser } from './cdp-browser';
+import { startE2eApp } from './e2e-app';
+import { E2E_ROOT_ENV, e2eBrowser, publishE2eRun, republishE2eBrowser } from './e2e-browser-handle';
+import { installE2eDriver } from './e2e-driver';
+import type { E2eBrowserPage } from './e2e-page';
+import { answersWithin } from './e2e-probe';
+
+/** How long a live browser gets to answer `1` before it is declared hung and relaunched. */
+const PROBE_MS = 5_000;
+
+const root = Bun.env[E2E_ROOT_ENV];
+if (root !== undefined && root !== '') {
+  const app = await startE2eApp({ root });
+  let builds = 0;
+  // A deploy leaves the browser holding the OLD build's state: a SharedWorker whose socket went
+  // down with the restart and is now deep in its reconnect backoff, and tabs rendered by the old
+  // build. The test that deployed asserts on exactly that; the NEXT test must not inherit it.
+  let deployed = false;
+  const newBuild = async (): Promise<void> => {
+    deployed = true;
+    builds += 1;
+    await app.restart({ BUILD_ID: `e2e-build-${String(builds)}-${String(Date.now())}` });
+  };
+  // `openE2eBrowser`, never the `IfAvailable` door: the step only names a root after finding one.
+  let browser: E2eBrowser = await openE2eBrowser();
+  publishE2eRun({ browser, app });
+  // Installed ONCE, over a page that delegates to whichever browser is current: an `e2eTest` body
+  // is bound to its fixtures when the file DEFINES it, so reinstalling on a relaunch would leave
+  // every test defined before it driving a closed browser.
+  const current: E2eBrowserPage = {
+    url: () => browser.page.url(),
+    goto: (url, options) => browser.page.goto(url, options),
+    evaluate: (expression) => browser.page.evaluate(expression),
+    click: (selector) => browser.page.click(selector),
+    offline: (enabled) => browser.page.offline(enabled),
+  };
+  const uninstall = installE2eDriver({ page: current, baseUrl: app.base, newBuild });
+
+  // A browser that stopped answering takes every later suite down with it, one call deadline per
+  // call (run 8). So each test starts with a short probe, and a browser that fails it — or one a
+  // deploy ran under — is closed and relaunched: the app is untouched, and the test gets a fresh
+  // profile, a fresh SharedWorker and a fresh tab on the same origin.
+  beforeEach(async () => {
+    const alive = !deployed && (await answersWithin(e2eBrowser().page, PROBE_MS));
+    if (alive) return;
+    deployed = false;
+    browser.close();
+    browser = await openE2eBrowser();
+    republishE2eBrowser(browser);
+  });
+
+  afterAll(async () => {
+    uninstall();
+    browser.close();
+    await app.stop();
+  });
+}

package/src/e2e-probe.ts

@@ -0,0 +1,23 @@
+// Is the browser still answering? One cheap `evaluate('1')` raced against a short budget — the
+// question the e2e preload asks before every test, because a hung browser otherwise costs every
+// later suite one full CDP deadline per call (run 8) instead of one relaunch.
+
+/** `true` when the page evaluated `1` within `ms`; a rejection or a stall is `false`, never a throw. */
+export async function answersWithin(
+  page: { evaluate(expression: string): Promise<unknown> },
+  ms: number,
+): Promise<boolean> {
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  const stalled = new Promise<false>((resolve) => {
+    timer = setTimeout(() => resolve(false), ms);
+  });
+  const answered = page.evaluate('1').then(
+    () => true,
+    () => false,
+  );
+  try {
+    return await Promise.race([answered, stalled]);
+  } finally {
+    clearTimeout(timer);
+  }
+}

package/src/e2e-spawn.ts

@@ -0,0 +1,169 @@
+// The e2e app's PROCESS half: spawn it on a free port, wait for `/readyz`, restart it on the same
+// port as a deploy, stop it. Split from `e2e-app.ts`, which owns the DATABASE half (the throwaway
+// state directory, the reset and the seed), so this half runs against any root with an entry —
+// which is what lets a unit test drive it without a Postgres.
+
+// why: the readiness poll must not go through `globalThis.fetch` — inside `bun test` the testing
+// preload SEALS it, and the app's `/readyz` would be refused as egress. `node:http` is not sealed.
+import { get } from 'node:http';
+// why: Bun exposes no path API — the CLI's own bin is joined, not concatenated.
+import { join } from 'node:path';
+import { assert } from '@ultimat3/core';
+import { E2eAppFailedError } from './e2e-errors';
+
+/** `x dev` (sync included), or the production entry `apps/web/server.ts` under `ROLE=web`. */
+export type E2eAppMode = 'dev' | 'serve';
+
+/** The CLI this process IS — never a global `x`, which may be a different version of the framework. */
+export const X_BIN = join(import.meta.dir, 'bin.ts');
+const POLL_MS = 250;
+
+export interface SpawnedE2eApp {
+  /** `http://localhost:<port>`, no trailing slash. */
+  readonly base: string;
+  /** Kill the process. Idempotent. */
+  stop(): Promise<void>;
+  /** Kill it and start it again on the SAME port, with `env` added — a deploy. Refused after `stop()`. */
+  restart(env?: Readonly<Record<string, string>>): Promise<void>;
+}
+
+export interface SpawnE2eAppOptions {
+  readonly root: string;
+  readonly mode: E2eAppMode;
+  /** Every spawn's environment, on top of this process's minus `NODE_ENV`. */
+  readonly env: Readonly<Record<string, string>>;
+  /** Already screened finite by the caller. */
+  readonly readyTimeoutMs: number;
+}
+
+/** A port nothing holds right now, asked of the OS and handed to the child. */
+const freePort = (): number => {
+  const probe = Bun.serve({ port: 0, fetch: () => new Response() });
+  const port = probe.port ?? 0;
+  probe.stop(true);
+  return port;
+};
+
+/**
+ * This process's environment minus what makes the child a TEST process. Spawned from `bun test`,
+ * `NODE_ENV=test` rode along and the app resolved its environment as `test` — so a development-only
+ * seam (the demo viewer an app installs instead of a sign-in route) was off and every page 401'd.
+ * The app under e2e is a development app unless the caller's `env` says otherwise.
+ */
+export const inherited = (): Record<string, string | undefined> => {
+  const { NODE_ENV: _node, ...rest } = Bun.env;
+  return { ...rest, ULTIMATE_ENV: 'development' };
+};
+
+export const refuse = (step: string, output: string): E2eAppFailedError =>
+  new E2eAppFailedError({ step, output });
+
+/** Spawn the app and answer once `/readyz` does; refuses with the app's own output tail. */
+export async function spawnE2eApp(options: SpawnE2eAppOptions): Promise<SpawnedE2eApp> {
+  const deadline = options.readyTimeoutMs;
+  const port = freePort();
+  // Its own scrape port too: every role opens one, the default is a fixed 9090, and a second app —
+  // or a developer's `x dev` — already holding it is an app that dies at boot with X_PORT_IN_USE.
+  const metricsPort = freePort();
+  const base = `http://localhost:${String(port)}`;
+  const command =
+    options.mode === 'serve'
+      ? ['bun', 'apps/web/server.ts']
+      : ['bun', X_BIN, 'dev', '--port', String(port)];
+  const spawnApp = (extra: Readonly<Record<string, string>>) =>
+    Bun.spawn(command, {
+      cwd: options.root,
+      env: {
+        ...inherited(),
+        ...options.env,
+        METRICS_PORT: String(metricsPort),
+        // The origin the app is actually reachable at. A page that renders a typed client builds
+        // its absolute URLs from it, and without it `/feed` answered 500 with X_ENV_MISSING APP_URL.
+        APP_URL: base,
+        ...(options.mode === 'serve' ? { ROLE: 'web', PORT: String(port) } : {}),
+        ...extra,
+      },
+      stdout: 'pipe',
+      stderr: 'pipe',
+    });
+  const ready = async (child: ReturnType<typeof spawnApp>, tail: () => string): Promise<void> => {
+    for (let waited = 0; waited < deadline; waited += POLL_MS) {
+      if (child.exitCode !== null) break;
+      if (await answersOk(`${base}/readyz`)) return;
+      await Bun.sleep(POLL_MS);
+    }
+    child.kill();
+    await child.exited;
+    throw refuse(`${command.join(' ')} never answered ${base}/readyz`, tail());
+  };
+
+  let child = spawnApp({});
+  // Drained from the start and kept bounded: an app's log is unbounded, and a pipe nobody reads
+  // fills its buffer and blocks the child on its next write — an app that "never got ready".
+  let tail = drainTail(child.stdout, child.stderr);
+  let stopped = false;
+  const stop = async (): Promise<void> => {
+    if (stopped) return;
+    stopped = true;
+    child.kill();
+    await child.exited;
+  };
+  try {
+    await ready(child, tail);
+  } catch (error) {
+    await stop();
+    throw error;
+  }
+  return {
+    base,
+    stop,
+    async restart(next: Readonly<Record<string, string>> = {}): Promise<void> {
+      // `stop()` is final. A child respawned here would be one no later `stop()` kills — the flag
+      // already says done — and `startE2eApp` has deleted the state directory it would boot on.
+      assert(
+        !stopped,
+        'restart() was called on an e2e app that was already stopped, so there is no app to deploy over',
+        'startE2eApp({ root }) again for a fresh app — restart() is for an app that is still running',
+      );
+      // The same port and the same state directory — a deploy, not a second app: a tab already
+      // open on `base` sees the new build on its next request, and the data it wrote is still there.
+      child.kill();
+      await child.exited;
+      child = spawnApp(next);
+      tail = drainTail(child.stdout, child.stderr);
+      await ready(child, tail);
+    },
+  };
+}
+
+const TAIL_CHARS = 16_000;
+
+/** Read both streams to their end in the background; answer the last `TAIL_CHARS` of either. */
+function drainTail(...streams: readonly ReadableStream<Uint8Array>[]): () => string {
+  let text = '';
+  for (const stream of streams) {
+    void (async () => {
+      const decoder = new TextDecoder();
+      for await (const chunk of stream) {
+        text = (text + decoder.decode(chunk, { stream: true })).slice(-TAIL_CHARS);
+      }
+    })().catch(() => undefined);
+  }
+  return () => text;
+}
+
+/** One GET, answered as "2xx or not" — never a throw, and never through the sealed `fetch`. */
+function answersOk(url: string): Promise<boolean> {
+  return new Promise((resolve) => {
+    const request = get(url, (response) => {
+      response.resume();
+      const status = response.statusCode ?? 0;
+      resolve(status >= 200 && status < 300);
+    });
+    request.on('error', () => resolve(false));
+    request.setTimeout(POLL_MS * 4, () => {
+      request.destroy();
+      resolve(false);
+    });
+  });
+}

package/src/error-codes.ts

@@ -30,6 +30,9 @@ export const CLI_OWNED_ERROR_CODES = [
   // `code: STALE` here is invisible to every reader of the code set, and silence there is
   // permissive — the DRYer the author, the less the gate sees (#277).
   'X_ERROR_CODE_UNRESOLVED',
+  // The fourth: registered, presented as live, and constructed by nothing — the state a code is left
+  // in when its last thrower moves on. The reference row has to say so in words.
+  'X_ERROR_CODE_UNTHROWN',
   // Reported as `Finding`s rather than thrown, and unregistered until now because of it — so
   // `x errors explain X_TYPECHECK_FAILED` refused a code `x verify` had just printed. A finding
   // carries an `X_*` code to the same reader a throw does; the registry is what makes that code
@@ -185,6 +188,7 @@ export const CLI_OWNED_ERROR_CODES = [
   'X_E2E_LOCATOR_EMPTY',
   'X_E2E_LOCATOR_AMBIGUOUS',
   'X_E2E_SERVICE_WORKER_ABSENT',
+  'X_E2E_APP_FAILED',
   // The raw-CDP browser under that driver — `cdp-launch.ts`, `cdp-connection.ts`,
   // `cdp-e2e-page.ts`, `cdp-browser.ts`. Four codes and not one, because the four repairs differ:
   // install a browser, read the browser's own stderr, look at the page, raise a deadline.
@@ -262,6 +266,8 @@ export const CLI_ERROR_TITLES: Readonly<Record<CliOwnedErrorCode, string>> = {
   X_ERROR_CODE_UNDOCUMENTED: 'a shipped error code has no row in the error reference',
   X_ERROR_CODE_UNREGISTERED: 'the error reference documents a code no package registers',
   X_ERROR_CODE_UNRESOLVED: 'an error code is written as a name this repository cannot resolve',
+  X_ERROR_CODE_UNTHROWN:
+    'a registered error code is constructed by nothing and its reference row does not say so',
   X_FRAMEWORK_SCHEMA_FAILED: 'a framework table could not be created at boot',
   X_STORAGE_UNWRITABLE: 'the storage disk this process needs cannot be written to',
   X_STORAGE_SECRET_DEV: 'upload grants would be signed with the shipped development key',
@@ -330,6 +336,7 @@ export const CLI_ERROR_TITLES: Readonly<Record<CliOwnedErrorCode, string>> = {
   X_E2E_LOCATOR_EMPTY: 'an e2e locator matched no element',
   X_E2E_LOCATOR_AMBIGUOUS: 'an e2e locator matched more than one element and was asked to click',
   X_E2E_SERVICE_WORKER_ABSENT: 'no service worker took control of the page within the budget',
+  X_E2E_APP_FAILED: 'the app an e2e run spawned did not come up',
   X_CDP_BROWSER_MISSING: 'no Chrome or Chromium is installed for the e2e driver to launch',
   X_CDP_LAUNCH_FAILED: 'the browser started and never announced a DevTools endpoint',
   X_CDP_CALL_FAILED: 'the browser refused a DevTools call',

package/src/error-unthrown.ts

@@ -0,0 +1,130 @@
+// A registered code nothing constructs. The registry and the reference keep a shipped code alive
+// forever — which is right — and that is exactly why a code can outlive its last thrower with no
+// gate noticing: `X_RPC_FAILED` sat registered and documented as live after the transport change
+// took its only throw site away. The reference row has to SAY so, or this reports it.
+
+import { join } from 'node:path';
+import { ERROR_DOCS_URL, maskLiterals, stripComments } from '@ultimat3/core';
+import { RESERVED_HEADING } from './error-contract';
+import type { Finding } from './output';
+import { eachSourceFile, isGenerated, isTest } from './source-files';
+import { isCodeRegistry } from './ts-scan';
+
+const CODE_LITERAL = /(['"`])(X_[A-Z0-9_]+)\1/g;
+const TITLE_KEY = /^[\t ]*(X_[A-Z0-9_]+)\s*:/gm;
+/** A registry's own code LIST line — `'X_FOO',` — declares a code and throws nothing. */
+const LIST_LINE = /^[\t ]*(['"`])X_[A-Z0-9_]+\1\s*,?\s*$/;
+/** `metaMissing: 'X_SEO_META_MISSING'` — the table `@ultimat3/seo` and `@ultimat3/ui` raise from. */
+const TABLE_ENTRY = /\b([a-z][A-Za-z0-9]*)\s*:\s*(['"`])(X_[A-Z0-9_]+)\2/g;
+const MEMBER_READ = /\.([A-Za-z_$][\w$]*)/g;
+
+/** Phrases a reference row uses to say, in words, that nothing throws the code any more. */
+const DECLARED_UNTHROWN = /thrown by nothing|not thrown/i;
+
+export interface CodeUse {
+  /** Every code a package registry names. */
+  readonly registered: ReadonlySet<string>;
+  /** Every code shipped source constructs, compares or raises outside a registry's declaration. */
+  readonly used: ReadonlySet<string>;
+}
+
+/**
+ * One file's contribution. A registry file's code LIST and title KEYS declare; any other literal in
+ * it is a use (a class's `code:`, a `?? 'X_…'` fallback, a comparison). A table entry counts only
+ * once something reads that member — which is how two packages raise every code they own.
+ */
+export function codeUseOf(source: string): {
+  readonly registered: readonly string[];
+  readonly used: readonly string[];
+  readonly table: ReadonlyMap<string, string>;
+  readonly members: readonly string[];
+} {
+  const text = stripComments(source);
+  const members = [...maskLiterals(source).matchAll(MEMBER_READ)].map((m) => m[1] ?? '');
+  if (!isCodeRegistry(text)) {
+    return {
+      registered: [],
+      used: [...text.matchAll(CODE_LITERAL)].map((m) => m[2] ?? ''),
+      table: new Map(),
+      members,
+    };
+  }
+  const registered = [
+    ...[...text.matchAll(TITLE_KEY)].map((m) => m[1] ?? ''),
+    ...[...text.matchAll(CODE_LITERAL)].map((m) => m[2] ?? ''),
+  ];
+  const table = new Map<string, string>();
+  for (const m of text.matchAll(TABLE_ENTRY)) {
+    // `code: 'X_…'` is a class or a factory constructing the code, never a table entry.
+    if (m[1] !== 'code') table.set(m[1] ?? '', m[3] ?? '');
+  }
+  const tableCodes = new Set(table.values());
+  const used: string[] = [];
+  for (const line of text.split('\n')) {
+    if (LIST_LINE.test(line)) continue;
+    for (const m of line.matchAll(CODE_LITERAL)) {
+      const code = m[2] ?? '';
+      if (!tableCodes.has(code)) used.push(code);
+    }
+  }
+  return { registered, used, table, members };
+}
+
+/** Shipped package source only: `scripts/` never ships, so a code only a gate script names is unthrown. */
+export async function collectCodeUse(root: string): Promise<CodeUse> {
+  const registered = new Set<string>();
+  const used = new Set<string>();
+  const table = new Map<string, string>();
+  const members = new Set<string>();
+  for await (const source of eachSourceFile(root)) {
+    if (!/^packages\/[^/]+\/src\//.test(source) || isTest(source) || isGenerated(source)) continue;
+    const use = codeUseOf(await Bun.file(join(root, source)).text());
+    for (const code of use.registered) registered.add(code);
+    for (const code of use.used) used.add(code);
+    for (const [member, code] of use.table) table.set(member, code);
+    for (const member of use.members) members.add(member);
+  }
+  for (const [member, code] of table) if (members.has(member)) used.add(code);
+  return { registered, used };
+}
+
+/** Codes whose reference row says nothing throws them, or that sit under the reserved heading. */
+export function declaredUnthrown(markdown: string): ReadonlySet<string> {
+  const out = new Set<string>();
+  let reserved = false;
+  for (const line of markdown.split('\n')) {
+    if (line.trim() === RESERVED_HEADING) reserved = true;
+    const row = /^\|\s*`(X_[A-Z0-9_]+)`\s*\|/.exec(line);
+    if (row !== null && (reserved || DECLARED_UNTHROWN.test(line))) out.add(row[1] ?? '');
+  }
+  return out;
+}
+
+const unthrownFinding = (code: string, page: string): Finding => ({
+  code: 'X_ERROR_CODE_UNTHROWN',
+  cause: `${code} is registered and ${page} presents it as live, but no shipped source constructs it — a reader matching on it waits for an error that cannot arrive`,
+  // Never "delete the registration": a shipped code is stable forever, and an old log line must
+  // still explain. The row is what has to change.
+  fix: `write "registered, thrown by nothing since <version>" into ${code}'s row in ${page}, naming the code that replaced it — or throw it again where it belongs`,
+  docs: ERROR_DOCS_URL,
+  at: page,
+});
+
+/**
+ * Registered, used by nothing, and not declared unthrown on the reference. A host check — the page
+ * is the host repo's to name, and only a monorepo's walk sees every package's source; in a
+ * generated app every framework code would read as unthrown.
+ */
+export async function checkErrorCodesThrown(
+  root: string,
+  page: string,
+): Promise<readonly Finding[]> {
+  const reference = Bun.file(join(root, page));
+  if (!(await reference.exists())) return [];
+  const exempt = declaredUnthrown(await reference.text());
+  const { registered, used } = await collectCodeUse(root);
+  return [...registered]
+    .filter((code) => !used.has(code) && !exempt.has(code))
+    .sort()
+    .map((code) => unthrownFinding(code, page));
+}

package/src/errors.ts

@@ -287,35 +287,14 @@ export class FixTargetUnknownError extends UltimateError {
   }
 }
 
-/**
- * A build target names an entry file the app does not have. `x build` refuses before it spawns the
- * builder: `bun build`'s own "module not found" says nothing about which file an Ultimate app is
- * supposed to own, and `docker build`'s says nothing about which target wanted it.
- */
-export class BuildEntryMissingError extends UltimateError {
-  constructor(input: { target: string; entry: string }) {
-    super({
-      code: 'X_BUILD_ENTRY_MISSING',
-      cause: `x build --target ${input.target} builds from ${input.entry}, and the app does not have it`,
-      fix: `x new scratch-app --dry-run --json   # its file list carries ${input.entry}; copy that file into this app`,
-    });
-  }
-}
-
-/**
- * A client entry would not compile. `X_BUILD_FAILED`, not a code of its own: an island is a bundle
- * entry point like any other, and the target's own logs are what says which line. The fix builds
- * exactly that one file, so the next message an author reads is the compiler's and not the CLI's.
- */
-export class IslandBuildFailedError extends UltimateError {
-  constructor(input: { file: string; logs: string }) {
-    super({
-      code: 'X_BUILD_FAILED',
-      cause: `${input.file} is an island entry point and would not bundle: ${input.logs}`,
-      fix: `bun build --target browser ${input.file}`,
-    });
-  }
-}
+// The build and bundle refusals live in `build-errors.ts` (split at the 500-line ceiling); re-exported
+// here so every existing `from './errors'` import keeps resolving.
+export type { FrameworkScriptKind } from './build-errors';
+export {
+  BuildEntryMissingError,
+  FrameworkScriptBuildFailedError,
+  IslandBuildFailedError,
+} from './build-errors';
 
 /**
  * `ROLE` selects what a container is. One image runs every role, so a typo is a process that would

package/src/index.ts

@@ -24,7 +24,13 @@ export { findAppRoot, requireAppRoot, requireBunVersion, versionAtLeast } from '
 export type { BoundaryCut, BoundarySplit } from './boundary-cuts';
 export { planBoundaryCuts } from './boundary-cuts';
 export type { BuildStats, RouteStats } from './budgets';
-export { BUILD_STATS_FILE, checkBudgets, readBuildStats } from './budgets';
+export {
+  BUILD_STATS_FILE,
+  checkBudgets,
+  FRAMEWORK_INLINE_SCRIPTS,
+  FRAMEWORK_SCRIPTS,
+  readBuildStats,
+} from './budgets';
 // The raw-CDP browser the driver above runs on. `openE2eBrowserIfAvailable()` is what an app's
 // test preload calls: it answers `undefined` on a machine with no Chrome, so the browser-backed
 // suite SKIPS rather than turning a gate red for a reason unrelated to the change.
@@ -36,8 +42,10 @@ export {
 } from './cdp-browser';
 export type { CdpConnection, CdpConnectionOptions, CdpResult } from './cdp-connection';
 export { cdpConnect } from './cdp-connection';
-export type { CdpE2ePageOptions } from './cdp-e2e-page';
-export { cdpE2ePage } from './cdp-e2e-page';
+export type { CdpE2eTabOptions, E2eTab } from './cdp-e2e-page';
+export { cdpE2eTab } from './cdp-e2e-page';
+export type { CdpE2eSessionOptions, E2eSession } from './cdp-e2e-session';
+export { cdpE2eSession } from './cdp-e2e-session';
 export {
   CdpBrowserMissingError,
   CdpCallFailedError,
@@ -150,9 +158,13 @@ export {
 // The browser-backed e2e driver. `installE2eDriver` is the ONE entry point an app's test preload
 // calls; everything below it is exported because the adapter's own pieces are what a driver author
 // re-uses, and a deep import into `src/` would make each of them a compatibility promise anyway.
+export type { E2eApp, E2eAppMode, StartE2eAppOptions } from './e2e-app';
+export { startE2eApp } from './e2e-app';
+export { e2eApp, e2eBaseUrl, e2eBrowser } from './e2e-browser-handle';
 export type { E2eDriverOptions } from './e2e-driver';
 export { e2eFixtures, installE2eDriver } from './e2e-driver';
 export {
+  E2eAppFailedError,
   E2eEvaluateCapturedError,
   E2eEvaluateThrewError,
   E2eEvaluateUnsupportedError,
@@ -209,6 +221,8 @@ export {
   resetCodeFixes,
   scanScopeFixes,
 } from './error-fixes';
+export type { CodeUse } from './error-unthrown';
+export { checkErrorCodesThrown } from './error-unthrown';
 export {
   BadFlagError,
   BuildEntryMissingError,
@@ -281,7 +295,7 @@ export {
 // `islandBundle`, `writeIslands`, `ISLAND_BASE_PATH` and `ISLAND_GLOB` stay internal: they are
 // `x build`'s and `x dev`'s wiring, and every name here is a semver promise forever.
 export type { IslandBundle, IslandChunk } from './island-bundle';
-export { buildIslands } from './island-bundle';
+export { buildIslands, clearIslandChunkCache } from './island-bundle';
 export type { DrainFailure, DrainOutcome, DrainSkip } from './jobs-drain';
 export { drainJobs } from './jobs-drain';
 export type { JobsListFilter, JobsListResult } from './jobs-report';

package/src/island-bundle.ts

@@ -3,6 +3,13 @@
 // byte-deterministic), plus the resolver that turns a page's `src` specifier into the URL its
 // `data-x-entry` carries. One entry point per island is axiom 6 made mechanical — the page's graph
 // never reaches an island, so a `site/` document stays at 0kb whatever the island imports.
+//
+// No page-client bootstrap is prepended (plan 101, decided 2026-09-22): the handle is one
+// `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.
 
 // Bun ships no path API. `posix` does the specifier arithmetic (an app-relative route file is
 // POSIX by construction), `join`/`basename` the filesystem side.
@@ -11,6 +18,8 @@ import { frameworkVersion, renderThrowable } from '@ultimat3/core';
 import { ISLAND_EXTENSION, IslandInvalidError, islandModuleId } from '@ultimat3/render';
 import { contentHash } from '@ultimat3/render/server';
 import { IslandBuildFailedError } from './errors';
+import { islandRealtimePlugin, REALTIME_ISLAND_ENTRY, reachesRealtime } from './island-realtime';
+import { solidDedupePlugin } from './island-solid-dedupe';
 import { islandStylesPlugin } from './island-styles';
 import { hasPathSegment } from './path-segments';
 import { solidJsxPlugin } from './solid-loader';
@@ -74,10 +83,13 @@ export async function discoverIslands(root: string): Promise<readonly string[]>
 async function buildOne(root: string, file: string): Promise<IslandChunk> {
   // `Bun.build` REJECTS on a failed bundle, it does not answer `success: false` — so the catch is
   // the real path here and the `success` test below is the belt for a future default.
+  // 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 realtime = await reachesRealtime(root, file);
   let built: Awaited<ReturnType<typeof Bun.build>>;
   try {
     built = await Bun.build({
-      entrypoints: [join(root, file)],
+      entrypoints: [realtime ? REALTIME_ISLAND_ENTRY : join(root, file)],
       target: 'browser',
       format: 'esm',
       splitting: false,
@@ -91,7 +103,16 @@ async function buildOne(root: string, file: string): Promise<IslandChunk> {
       // The second closes the same shape of failure — a wrong answer `Bun.build` reports as
       // `success: true`: without it, Bun's file loader resolves a `.module.scss` to its asset
       // PATH, so `styles['x']` is `undefined` and every element renders unclassed.
-      plugins: [solidJsxPlugin, islandStylesPlugin],
+      //
+      // 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.
+      plugins: [
+        ...(realtime ? [islandRealtimePlugin(root, file)] : []),
+        solidDedupePlugin(root),
+        solidJsxPlugin,
+        islandStylesPlugin,
+      ],
       // The third one, and it is a `define` rather than the plugin this used to be: Bun selects
       // the `development`/`production` export condition from the BUILD PROCESS's own `NODE_ENV`,
       // and a defined `process.env.NODE_ENV` overrides it. Measured on 1.4.0, `solid-js` plus
@@ -133,9 +154,8 @@ async function buildOne(root: string, file: string): Promise<IslandChunk> {
     // The FIRST bytes this process emitted for these inputs, so a URL served `immutable` answers
     // one byte string for as long as the process lives. Without it `x dev` re-mints the chunk on
     // every watcher tick and a browser holding the previous one under `max-age=31536000` has two
-    // different files at one address.
-    code: stableCode(file, hash, code),
-    bytes: new TextEncoder().encode(code).byteLength,
+    // different files at one address. `bytes` is measured on THAT code, never on this build's.
+    ...stableChunk(file, hash, code),
   };
 }
 
@@ -148,7 +168,7 @@ async function buildOne(root: string, file: string): Promise<IslandChunk> {
  */
 const DEBUG_ID_COMMENT = '\n//# debugId=';
 
-function stripDebugId(code: string): string {
+export function stripDebugId(code: string): string {
   const at = code.lastIndexOf(DEBUG_ID_COMMENT);
   return at === -1 ? code : code.slice(0, at);
 }
@@ -180,7 +200,7 @@ function stripDebugId(code: string): string {
  * 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.
  */
-function graphHash(file: string, map: string): string {
+export function graphHash(file: string, map: string): string {
   const parsed: unknown = JSON.parse(map);
   const contents = sourcesContentOf(parsed);
   if (contents === undefined) {
@@ -231,11 +251,18 @@ export function clearIslandChunkCache(): void {
  * 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`.
  */
-function stableCode(file: string, graph: string, code: string): string {
+export function stableChunk(
+  file: string,
+  graph: string,
+  code: string,
+): { readonly code: string; readonly bytes: number } {
   const hit = emitted.get(file);
-  if (hit !== undefined && hit.graph === graph) return hit.code;
-  emitted.set(file, { graph, code });
-  return code;
+  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 };
 }
 
 /**