@ultimat3/cli 19.1.3 → 19.2.0

package/src/prerender.ts

@@ -4,7 +4,7 @@
 // only which routes qualify and where the bytes land.
 
 import { join } from 'node:path';
-import { createContext, renderThrowable, runWithContext } from '@ultimat3/core';
+import { createContext, isUltimateError, renderThrowable, runWithContext } from '@ultimat3/core';
 import type { RouteEntry } from '@ultimat3/render';
 import { describeRoutes, routeEntries } from '@ultimat3/render';
 import { renderStatic } from '@ultimat3/render/server';
@@ -21,6 +21,7 @@ import { measurementActor } from './measurement-actor';
 import { loadPwaArtifacts, WEB_MANIFEST_PATH, writePwaIcons } from './pwa-artifacts';
 import type { SkippedRoute, UnmeasuredRoute } from './static-report';
 import { skippedRoute, skipReasonFor, writeStaticReport } from './static-report';
+import { styleBundle, writeStyles } from './style-bundle';
 import { SERVICE_WORKER_PATH, SW_REGISTER_PATH, serviceWorkerArtifacts } from './sw-artifacts';
 
 // Re-exported, never re-declared: `static-report.ts` owns the shape because the report on disk
@@ -78,6 +79,8 @@ export interface PrerenderReport {
   readonly report: string;
   /** Client entries emitted, one chunk each. Reported so "which JS shipped?" needs no unzip. */
   readonly islands: readonly string[];
+  /** Surface stylesheets emitted, one file each — the CSS half of the same question. */
+  readonly styles: readonly string[];
   /**
    * What the service worker could not express, and what its precache manifest weighs too much of.
    *
@@ -144,6 +147,12 @@ export async function prerenderSite(options: PrerenderOptions): Promise<Prerende
   // behind it, so the artifact carries every byte the browser will ask for.
   const islands = await buildIslands(options.root);
   await writeIslands(islands, options.out);
+  // And the stylesheet every document below LINKS. Derived after the island build on purpose:
+  // `islandStylesPlugin` registers an island's own `.module.scss` during `Bun.build`, so a bundle
+  // minted before it would hash CSS the documents do not carry — and the export would publish
+  // pages whose `<link>` names a file the artifact does not have.
+  const styles = styleBundle();
+  await writeStyles(styles, options.out);
   // Same rule, one asset further: a browser asks for `/favicon.ico` on the first page it loads,
   // and a static export has no route to answer it — so the bytes the served surfaces would have
   // returned go into the artifact instead of leaving a 404 in every visitor's console.
@@ -172,7 +181,13 @@ export async function prerenderSite(options: PrerenderOptions): Promise<Prerende
   const serviceWorker =
     pwa === undefined
       ? undefined
-      : serviceWorkerArtifacts({ pwa, buildId, routes: describeRoutes(), islands });
+      : serviceWorkerArtifacts({
+          pwa,
+          buildId,
+          routes: describeRoutes(),
+          islands,
+          styles,
+        });
   if (serviceWorker !== undefined) {
     await Bun.write(join(options.out, SERVICE_WORKER_PATH.slice(1)), serviceWorker.source);
     await Bun.write(join(options.out, SW_REGISTER_PATH.slice(1)), serviceWorker.register);
@@ -240,7 +255,17 @@ export async function prerenderSite(options: PrerenderOptions): Promise<Prerende
       } catch (error) {
         // `renderThrowable`, never `String(error)`: this is a caught unknown, and a hostile
         // `toString` here would take the whole build down instead of one route's measurement.
-        unmeasured.push({ path: entry.path, reason: renderThrowable(error) });
+        // A framework error rides along with its code, cause and fix: `checkBudgets` reports
+        // `X_ISLAND_PROPS_INVALID` under its own name, because that sentence — the island, the
+        // prop, its bytes — is the finding, and `X_BUDGET_UNMEASURED` pointing at this list was
+        // a second command between the author and it.
+        unmeasured.push({
+          path: entry.path,
+          reason: renderThrowable(error),
+          ...(isUltimateError(error)
+            ? { code: error.code, cause: error.cause, fix: error.fix }
+            : {}),
+        });
       }
       continue;
     }
@@ -313,6 +338,7 @@ export async function prerenderSite(options: PrerenderOptions): Promise<Prerende
     stats,
     report,
     islands: islands.chunks.map((chunk) => chunk.file),
+    styles: styles.chunks.map((chunk) => chunk.url),
     serviceWorkerWarnings: serviceWorker?.warnings ?? [],
   };
 }

package/src/serve.ts

@@ -49,6 +49,8 @@ import { readMigrations } from './migrations';
 import { startOtlpExport } from './otlp-export';
 import { loadPwaArtifacts } from './pwa-artifacts';
 import type { RuntimeOverrides } from './runtime-overrides';
+import { styleBundle } from './style-bundle';
+import { styleRoutes } from './style-routes';
 import { serviceWorkerArtifacts } from './sw-artifacts';
 import { serviceWorkerRoutes } from './sw-routes';
 
@@ -329,7 +331,13 @@ async function bootRoles(boot: {
   const serviceWorker =
     pwa === undefined
       ? undefined
-      : serviceWorkerArtifacts({ pwa, buildId, routes: describeRoutes(), islands });
+      : serviceWorkerArtifacts({
+          pwa,
+          buildId,
+          routes: describeRoutes(),
+          islands,
+          styles: styleBundle(),
+        });
   // The app's own MCP endpoint, through the same call `x dev` makes — see `app-mcp.ts`.
   const mcpMount = await mountAppMcp(options.root);
   const routes: readonly Route[] = [
@@ -344,6 +352,9 @@ async function bootRoles(boot: {
     }),
     ...storageRoutes({ storage: runtime.storage }),
     ...islandRoutes(() => islands),
+    // The surface stylesheets the documents link. Built from the registry the `loadApp` above
+    // filled, so this process serves exactly the CSS it renders against.
+    ...styleRoutes(() => styleBundle()),
     ...appRoutes({
       buildId,
       resolveIsland: (file) => islands.resolverFor(file),

package/src/shot-browser.ts

@@ -8,6 +8,7 @@ import {
   cdpUrlFrom,
   cdpUrlProblem,
   executablePathFrom,
+  ShotChromeMissingError,
 } from './browser-launcher';
 import { BadFlagError } from './errors';
 
@@ -21,7 +22,10 @@ const CDP_FIX = 'x shot / --cdp-url wss://cdp.example.com/session/abc';
 export interface ShotBrowserChoice {
   /** Attach here. When set, nothing about a local executable was read. */
   readonly cdpUrl?: string | undefined;
-  /** Launch this. Already proved to exist on disk. */
+  /**
+   * Launch this. Already proved to exist on disk, and never absent alongside an absent `cdpUrl`:
+   * a run that reached this type has a browser, because the alternative is refused above.
+   */
   readonly executablePath?: string | undefined;
 }
 
@@ -31,6 +35,12 @@ export interface ShotBrowserInput {
   /** `--browser` as typed, before `PUPPETEER_EXECUTABLE_PATH` / `CHROME_PATH`. */
   readonly browserFlag?: string | undefined;
   readonly env: Readonly<Record<string, string | undefined>>;
+  /**
+   * Test seam: how a path is proved to be on disk. Injected rather than stubbed globally, so the
+   * probe below is asserted identically on a machine that has Chrome and on one that does not —
+   * an assertion whose verdict depends on the box it runs on is not an assertion.
+   */
+  readonly exists?: (path: string) => boolean;
 }
 
 /**
@@ -47,8 +57,14 @@ export interface ShotBrowserInput {
  *    the flag IS read.
  * 3. **On an attach, no executable is read at all.** Checking the filesystem for a binary this run
  *    will never execute is how a correct remote capture gets refused on a box with no Chrome.
+ * 4. **A local run with no browser anywhere is refused HERE.** `puppeteer-core` has no bundled
+ *    browser and no default, so "nothing named" is not "the library finds its own" — it is a throw
+ *    from inside somebody else's library, after `runShot` has already booted an embedded Postgres,
+ *    saying ``An `executablePath` or `channel` must be specified``. The same fact is knowable from
+ *    the environment and four filesystem probes before anything starts.
  */
 export function shotBrowserChoice(input: ShotBrowserInput): ShotBrowserChoice {
+  const exists = input.exists ?? browserBinaryExists;
   if (input.cdpFlag !== undefined && input.browserFlag !== undefined) {
     throw new BadFlagError({
       flag: 'cdp-url',
@@ -71,8 +87,11 @@ export function shotBrowserChoice(input: ShotBrowserInput): ShotBrowserChoice {
     }
     return { cdpUrl };
   }
-  const executablePath = executablePathFrom(input.browserFlag, input.env);
-  if (executablePath !== undefined && !browserBinaryExists(executablePath)) {
+  const executablePath = executablePathFrom(input.browserFlag, input.env, exists);
+  // Nothing named and nothing probed: not a bad flag, because no flag was typed — a machine with no
+  // browser on it, which is a configuration to repair rather than a value to correct.
+  if (executablePath === undefined) throw new ShotChromeMissingError();
+  if (!exists(executablePath)) {
     throw new BadFlagError({
       flag: 'browser',
       command: 'shot',
@@ -80,5 +99,5 @@ export function shotBrowserChoice(input: ShotBrowserInput): ShotBrowserChoice {
       fix: 'x shot / --browser /usr/bin/chromium',
     });
   }
-  return executablePath === undefined ? {} : { executablePath };
+  return { executablePath };
 }

package/src/static-report.ts

@@ -60,6 +60,17 @@ export type UnmeasuredRoute = {
   /** The DECLARED path, as `X_BUDGET_UNMEASURED`'s `at:` spells it, so the two rows join. */
   readonly path: string;
   readonly reason: string;
+  /**
+   * The throwable's own `code`, `cause` and `fix` when the render failed with an `UltimateError`
+   * — absent for a bare `TypeError`. Carried so the `budgets` step can report a failure that IS
+   * an instruction under its own code rather than under `X_BUDGET_UNMEASURED`: an island handed
+   * props over `ISLAND_PROPS_MAX_BYTES` throws `X_ISLAND_PROPS_INVALID` naming the prop and its
+   * bytes, and "run x build, its unmeasured list says why" sent the reader to a second command to
+   * read the sentence this build had already composed.
+   */
+  readonly code?: string;
+  readonly cause?: string;
+  readonly fix?: string;
 };
 
 /** One HTML file in the artifact, and the declared route that produced it. */
@@ -171,8 +182,17 @@ const isSkipped = (value: unknown): value is SkippedRoute =>
   typeof value['why'] === 'string' &&
   inDomain(SKIP_REASONS, value['reason']);
 
+const optionalString = (value: unknown): boolean =>
+  value === undefined || typeof value === 'string';
+
+/** The three coded fields are optional TOGETHER on the way in; a present one must be a string. */
 const isUnmeasured = (value: unknown): value is UnmeasuredRoute =>
-  isRecord(value) && typeof value['path'] === 'string' && typeof value['reason'] === 'string';
+  isRecord(value) &&
+  typeof value['path'] === 'string' &&
+  typeof value['reason'] === 'string' &&
+  optionalString(value['code']) &&
+  optionalString(value['cause']) &&
+  optionalString(value['fix']);
 
 const isEmitted = (value: unknown): value is EmittedPage =>
   isRecord(value) &&

package/src/style-bundle.ts

@@ -0,0 +1,124 @@
+// The surface stylesheet table: the CSS a document on `site/` or `app/` carries, content-hashed
+// and addressed as a FILE rather than inlined into every response. The island table's shape one
+// asset over (`island-bundle.ts`), because the two answer the same question — "what does this
+// document make the browser fetch, and can it keep it?" — and one mechanism is the whole point.
+//
+// Why it stopped being an inline `<style>`: measured against ai-maxxing on 2026-09-06, every
+// `app/` document carried one 156,738-byte block — 1,336 rules from 406 module sources, byte
+// identical across `/`, `/fleet`, `/fleet/[host]` and the session page — inside a response the
+// pipeline sends `Cache-Control: private, no-store`. 92% of the dashboard document and 89% of the
+// session document, re-sent and re-parsed on every navigation, cacheable by nothing.
+
+// Bun ships no path API; `join` is the filesystem side of writing a chunk into a static export.
+// why: Bun exposes no path API — nothing native joins a directory to a URL-shaped path.
+import { join } from 'node:path';
+import type { Surface } from '@ultimat3/render';
+import { SURFACES } from '@ultimat3/render';
+import { contentHash, stylesFor, stylesheetsRevision } from '@ultimat3/render/server';
+
+/**
+ * The surfaces a stylesheet is minted for. `api/` is dropped for `documentSurfaces`' reason — it
+ * emits no document, so a file no `<link>` can ever name would be bytes in the export and an entry
+ * in the precache manifest with no reader. `shared/` stays: `x shot --island` renders an island
+ * that lives there, and `surfaceOf` answers `shared` for it.
+ */
+const STYLED_SURFACES: readonly Surface[] = SURFACES.filter((surface) => surface !== 'api');
+
+/**
+ * Where a surface stylesheet is served from, in `x dev`, in the container and in a static export.
+ * Sits beside `ISLAND_BASE_PATH`, `ICON_BASE_PATH` and `MEDIA_BASE_PATH`, and outside the dev-only
+ * `/_x` namespace for their reason: the URL is baked into documents a static export publishes, so
+ * a dev-only path would be a page that renders in `x dev` and 404s on a CDN.
+ */
+export const STYLE_BASE_PATH = '/styles';
+
+export interface StyleChunk {
+  /**
+   * Every surface whose documents link it, sorted. Usually one — `site/` and `app/` carry
+   * different modules — but an app whose only CSS is its global layer produces one byte string for
+   * all three, and shipping it three times would put three copies in the static export and three
+   * entries in the precache manifest, which has a budget.
+   */
+  readonly surfaces: readonly Surface[];
+  /** Immutable, content-addressed URL. What `<link rel="stylesheet">` carries. */
+  readonly url: string;
+  readonly css: string;
+  readonly bytes: number;
+}
+
+export interface StyleBundle {
+  readonly chunks: readonly StyleChunk[];
+  /** The `href` a document on this surface links, or `undefined` when the surface has no CSS. */
+  hrefFor(surface: Surface | null): string | undefined;
+  /** The chunk a URL names — for serving it, and for writing it into a static export. */
+  chunkAt(url: string): StyleChunk | undefined;
+}
+
+/**
+ * `stylesFor(null)` and `stylesFor('shared')` select the same sheets by construction — a `null`
+ * surface matches only the package sheets, which `'shared'` already carries — so the one chunk
+ * answers both. `island-harness.ts` is the caller that can hold a `null`.
+ */
+const surfaceKey = (surface: Surface | null): Surface => surface ?? 'shared';
+
+/**
+ * Derived, never cached across a change: `stylesheetsRevision()` moves when a sheet's rules move,
+ * and island CSS registers on every `buildIslands` — which `x dev` re-runs on every watcher tick.
+ * Memoised on that revision rather than recomputed per request, because the derivation is a filter
+ * over every registered sheet plus a hash of the ~150 kB it joins.
+ */
+let memo: { readonly revision: number; readonly bundle: StyleBundle } | undefined;
+
+export function styleBundle(): StyleBundle {
+  const revision = stylesheetsRevision();
+  if (memo !== undefined && memo.revision === revision) return memo.bundle;
+  const bundle = styleBundleOf(
+    STYLED_SURFACES.map((surface) => ({ surface, css: stylesFor(surface) })).filter(
+      (sheet) => sheet.css.length > 0,
+    ),
+  );
+  memo = { revision, bundle };
+  return bundle;
+}
+
+/**
+ * Test seam, and the shape `islandBundle` has: a table built from what the caller supplies.
+ *
+ * The URL is the content hash and nothing else — no surface in the name — because a surface is not
+ * a property of the BYTES. Two surfaces with identical CSS are one file, one precache entry and
+ * one download, which is what the name would otherwise prevent. The same `contentHash` that stamps
+ * an ETag, a precache revision and an island chunk: one identity for a byte string, not a fourth.
+ */
+export function styleBundleOf(
+  sheets: readonly { readonly surface: Surface; readonly css: string }[],
+): StyleBundle {
+  const byCss = new Map<string, Surface[]>();
+  for (const sheet of sheets) {
+    const held = byCss.get(sheet.css);
+    if (held === undefined) byCss.set(sheet.css, [sheet.surface]);
+    else held.push(sheet.surface);
+  }
+  const chunks: readonly StyleChunk[] = [...byCss].map(([css, surfaces]) => ({
+    surfaces: [...surfaces].sort(),
+    url: `${STYLE_BASE_PATH}/${contentHash(css)}.css`,
+    css,
+    bytes: new TextEncoder().encode(css).byteLength,
+  }));
+  const bySurface = new Map(
+    chunks.flatMap((chunk) => chunk.surfaces.map((surface) => [surface, chunk] as const)),
+  );
+  const byUrl = new Map(chunks.map((chunk) => [chunk.url, chunk]));
+  return {
+    chunks,
+    hrefFor: (surface: Surface | null): string | undefined =>
+      bySurface.get(surfaceKey(surface))?.url,
+    chunkAt: (url: string): StyleChunk | undefined => byUrl.get(url),
+  };
+}
+
+/** Write every surface stylesheet under a static export, at the URL the documents already carry. */
+export async function writeStyles(bundle: StyleBundle, out: string): Promise<void> {
+  for (const chunk of bundle.chunks) {
+    await Bun.write(join(out, chunk.url.slice(1)), chunk.css);
+  }
+}

package/src/style-csp.ts

@@ -1,19 +1,21 @@
-// Every inline `<style>` body a served process can put in a document, as the `style-src` sources
-// that admit it. Read from the stylesheet registry at boot rather than checked in as a constant:
-// importing the app's modules IS what fills that registry, so a committed hash would describe a
-// stylesheet the document no longer carries — and the CSP would block the framework's own CSS.
+// Every inline `<style>` body a served process can still put in a document, as the `style-src`
+// sources that admit it. The caller names them, because the caller is what knows which documents
+// it mounted.
+//
+// The app's OWN CSS is no longer among them, `As of 2026-09-06`: a surface stylesheet is served as
+// a content-hashed file (`style-bundle.ts`) and a same-origin `<link>` is admitted by the `'self'`
+// already in `@ultimat3/http`'s `style-src`. This function used to hash `stylesFor(surface)` for
+// all four surfaces — 157 kB of CSS hashed at boot to admit a block that is not emitted any more,
+// which is a rule describing a document nobody serves. So a production boot (`serve.ts`, which
+// passes no extras) now extends `style-src` with nothing at all.
 
 import { cspHashSource } from '@ultimat3/http';
-import { SURFACES } from '@ultimat3/render';
-import { stylesFor } from '@ultimat3/render/server';
 
 /**
- * Call AFTER `loadApp`. One hash per distinct body: `stylesFor` is what `dev-render.ts` puts in
- * the tag, per surface, so hashing the same call is the only way the two cannot drift. `extra`
- * carries the documents this package does not render — `/_x`'s shell — because the caller is what
- * knows which of them it mounted.
+ * Call with the inline bodies THIS process emits. `x dev` passes the `/_x` shell's stylesheet and
+ * the screenshot harness's frame style — documents this package renders itself, which no app
+ * surface can see.
  */
-export function inlineStyleSources(extra: readonly string[] = []): readonly string[] {
-  const bodies = [...SURFACES.map((surface) => stylesFor(surface)), ...extra];
+export function inlineStyleSources(bodies: readonly string[] = []): readonly string[] {
   return [...new Set(bodies.filter((body) => body.length > 0).map(cspHashSource))].sort();
 }

package/src/style-routes.ts

@@ -0,0 +1,56 @@
+// Serving the surface stylesheets. `x dev` and the container mount the same route over the same
+// table, for `island-routes.ts`' reason: the URL is minted by one resolver and baked into the
+// document, so a dev-only path would be a page that paints in `x dev` and renders naked in the
+// image.
+
+import type { Route, UltimateRequest } from '@ultimat3/http';
+import { applyCacheHeaders, json } from '@ultimat3/http';
+import type { StyleBundle } from './style-bundle';
+import { STYLE_BASE_PATH } from './style-bundle';
+
+/**
+ * A getter, not the bundle: `x dev` re-registers island CSS on every watcher tick, and a table
+ * captured when the route was mounted would serve the stylesheet as it was at boot for the rest of
+ * the session.
+ */
+export type StyleSource = () => StyleBundle;
+
+/**
+ * The URL is content-addressed, so the bytes behind it never change and the answer is
+ * `public, max-age=31536000, immutable` — the same headers an island chunk earns, and the whole
+ * reason this is a file rather than 157 kB of `<style>` inside a `no-store` document.
+ *
+ * A miss can only be a document older than this process's registry, which is a fact worth stating
+ * rather than a bare 404 whose meaning an agent has to guess.
+ */
+export function styleRoutes(source: StyleSource): readonly Route[] {
+  return [
+    {
+      method: 'GET',
+      path: `${STYLE_BASE_PATH}/*file`,
+      meta: { name: 'assets.style', auth: 'public', tags: ['assets'] },
+      handler: (request: UltimateRequest): Response => {
+        const chunk = source().chunkAt(request.pathname);
+        if (chunk === undefined) {
+          return json(
+            {
+              ok: false,
+              error: {
+                code: 'X_ROUTE_NOT_FOUND',
+                cause: `no surface stylesheet is registered at ${request.pathname} — the document that asked for it was rendered against an older build`,
+                // No `x` citation, for `island-routes.ts`' reason: this route is mounted in
+                // exactly two places (`cmd-dev.ts`, `serve.ts`) and neither reads `.x/static`.
+                fix: 'reload the page — this process serves only the stylesheet its own modules registered, and the document holding this URL came from an earlier build',
+              },
+            },
+            { status: 404 },
+          );
+        }
+        return applyCacheHeaders(
+          new Response(chunk.css, { headers: { 'content-type': 'text/css; charset=utf-8' } }),
+          { mode: 'immutable' },
+        );
+      },
+    },
+  ];
+}

package/src/sw-artifacts.ts

@@ -9,6 +9,7 @@ import type { RouteDescriptor } from '@ultimat3/render';
 import type { IslandBundle } from './island-bundle';
 import { msg } from './messages';
 import type { PwaArtifacts } from './pwa-artifacts';
+import type { StyleBundle } from './style-bundle';
 
 /** Root scope, so `/sw.js` and nothing under a directory — `assertScope` refuses the rest. */
 export const SERVICE_WORKER_PATH = '/sw.js';
@@ -43,6 +44,12 @@ export interface ServiceWorkerInput {
   readonly buildId: string;
   readonly routes: readonly RouteDescriptor[];
   readonly islands: IslandBundle;
+  /**
+   * The surface stylesheets every document links. Precached beside the island chunks and for the
+   * same reason: they are content-addressed and served `immutable`, and a document that reaches
+   * the offline fallback with no CSS is a page the visitor cannot read.
+   */
+  readonly styles: StyleBundle;
 }
 
 /**
@@ -71,14 +78,15 @@ const pwaRoutes = (routes: readonly RouteDescriptor[]): readonly PwaRoute[] =>
   });
 
 /**
- * Every island chunk, precached. They are content-addressed and served `immutable`, so the
- * revision IS the URL's hash and a byte-identical chunk across deploys is never re-downloaded.
+ * Every island chunk and every surface stylesheet, precached. They are content-addressed and
+ * served `immutable`, so the revision IS the URL's hash and a byte-identical asset across deploys
+ * is never re-downloaded.
  *
  * Sorted by url, because `buildPrecacheManifest` sorts its own entries but the ASSET list is what
  * decides which of two equal urls wins, and `sw.js` must be byte-identical for identical input.
  */
-const islandAssets = (islands: IslandBundle): readonly PrecacheAsset[] =>
-  [...islands.chunks]
+const staticAssets = (islands: IslandBundle, styles: StyleBundle): readonly PrecacheAsset[] =>
+  [...islands.chunks, ...styles.chunks]
     .map((chunk) => ({ url: chunk.url, revision: chunk.url, bytes: chunk.bytes }))
     .sort((a, b) => (a.url < b.url ? -1 : a.url > b.url ? 1 : 0));
 
@@ -133,7 +141,7 @@ export function serviceWorkerArtifacts(
         neverCache: pwa.offline.neverCache,
       },
       capabilities: { backgroundSync: pwa.backgroundSync, push: pwa.push },
-      assets: islandAssets(input.islands),
+      assets: staticAssets(input.islands, input.styles),
     },
     input.buildId,
   );

package/src/templates/resource-form-island.ts

@@ -39,8 +39,14 @@ const formIslandSource = (
 
 import { Button, Form, Input, setSolidRuntime, UiProvider } from '@ultimat3/ui';
 import type { JSX } from 'solid-js';
-import * as solidRuntime from 'solid-js';
-import { createSignal } from 'solid-js';
+import {
+  createContext,
+  createEffect,
+  createMemo,
+  createSignal,
+  onCleanup,
+  useContext,
+} from 'solid-js';
 import { render } from 'solid-js/web';
 import styles from './ui.module.scss';
 
@@ -123,11 +129,15 @@ function ${feature.pascal}FormBody(props: ${feature.pascal}FormProps): JSX.Eleme
  * registers. Delete the line and the first \`<UiProvider>\` render throws X_UI_RUNTIME_MISSING —
  * loud on purpose, because a DOM render that lost its runtime is a theme toggle that does nothing.
  *
+ * Six NAMED imports, never \`import * as solidRuntime\`: a namespace object handed to a function
+ * keeps every export of solid-js alive, and the bundler cannot shake what it cannot see unused —
+ * measured at 14.8 kB minified per island chunk (5.6 kB gzipped) for the namespace form.
+ *
  * The shell is cleared first: Solid's \`render\` APPENDS when the container already has children,
  * so without it the server's markup stays on screen above a second, live copy of the same thing.
  */
 export function mount(el: HTMLElement, props: ${feature.pascal}FormProps): void {
-  setSolidRuntime(solidRuntime);
+  setSolidRuntime({ createContext, useContext, createSignal, createMemo, createEffect, onCleanup });
   el.textContent = '';
   render(
     () => (

package/src/templates/scaffold-repo.ts

@@ -307,6 +307,12 @@ const bunfig = (): string => `[test]
 root = "."
 # Frozen clock, seeded RNG, sealed network — nondeterminism in a test is a bug.
 preload = ["@ultimat3/testing/preload"]
+# An island is mounted from a BUILT chunk that \`mountIsland\` writes to a temp .mjs, so
+# \`bun test --coverage\` reports that file: two minified lines, under a name no source has. Bun
+# does not remap a pre-built module through its sourcemap (measured on 1.4.0, and the build does
+# emit one), so the row can only ever be noise — the island's own .island.tsx is not what it
+# describes. Ignoring it removes the phantom; it hides no line any test was covering.
+coveragePathIgnorePatterns = ["**/*.mjs"]
 `;
 
 const scssTypes =

package/src/verify-checks.ts

@@ -34,6 +34,7 @@ import type { Finding } from './output';
 import { findingFrom } from './output';
 import { checkMigrationDrift } from './schema-drift';
 import { scanSiteMeta } from './seo-meta';
+import { readStaticReport } from './static-report';
 import { floorProblemFindings, readVerifyFloor } from './verify-floor';
 import type { VerifyStep } from './verify-step';
 import { fromExec, fromFindings, hostFindings } from './verify-step';
@@ -211,6 +212,11 @@ export const VERIFY_STEPS: readonly VerifyStep[] = [
       // to a hard `X_PRERENDER_FAILED` on `examples/dummy`), and it would be a second builder
       // beside `apps/web/prerender.ts`, which is where an app reads `SITE_ORIGIN`.
       const stats = await readBuildStats(ctx.root);
+      // The report beside the stats, for the one thing `checkBudgets` reads off it: a route the
+      // build rendered and could not weigh because its island was handed props over the cap is
+      // reported under `X_ISLAND_PROPS_INVALID` — the build's own sentence, naming the prop and
+      // its bytes — and not as an `X_BUDGET_UNMEASURED` whose fix is to go and read this file.
+      const report = await readStaticReport(ctx.root);
       // The load's own findings, FIRST and never dropped. A module that would not import registers
       // no route, so its budget is missing from the manifest and every route it declared reads as
       // `X_BUDGET_UNMEASURED` — the symptom, pointing the reader at `x build` for a file that will
@@ -224,7 +230,7 @@ export const VERIFY_STEPS: readonly VerifyStep[] = [
         // JavaScript does this route's document boot? A live read with no island is a route
         // whose answer is "none", which no suite can fail on — the page renders, at 200.
         ...(await liveRouteFindings(ctx.root)),
-        ...checkBudgets(manifest, stats),
+        ...checkBudgets(manifest, stats, report?.unmeasured),
       ]);
     },
   },

package/src/verify-tests.ts

@@ -36,13 +36,26 @@ type TypedTest = Exclude<TestType, 'unit'>;
 
 const TYPED_SUFFIXES = '{contract,live,job,e2e,eval}';
 
-const SUMMARIES: Readonly<Record<TypedTest, string>> = {
-  contract: 'action/query schemas, policy denials, emitted OpenAPI and MCP shapes',
-  live: 'live-query snapshots, incremental patches, reconnect deltas',
-  job: 'step replay, idempotency dedupe, retry/backoff, outbox atomicity',
-  e2e: 'the built output, incl. offline and SW update',
-  eval: 'LLM output scored against thresholds',
-};
+/**
+ * `Object.create(null)`, not a `{}` literal, because `stepFor` reads it with a COMPUTED key
+ * (`SUMMARIES[type]`). On a normal object literal every `Object.prototype` member reads back as
+ * present, so a table read that way answers a function instead of `undefined` for a key nobody
+ * declared — the defect `scripts/proto-index.ts` exists to keep out, thirteen instances across
+ * four sweeps. `type` is a closed union here and cannot be `'constructor'` today, which is
+ * exactly the argument every one of those thirteen had before it stopped being true.
+ *
+ * Same repair, and the same reason, as `packages/i18n/src/catalog.ts`.
+ */
+const SUMMARIES: Readonly<Record<TypedTest, string>> = Object.assign(
+  Object.create(null) as Record<TypedTest, string>,
+  {
+    contract: 'action/query schemas, policy denials, emitted OpenAPI and MCP shapes',
+    live: 'live-query snapshots, incremental patches, reconnect deltas',
+    job: 'step replay, idempotency dedupe, retry/backoff, outbox atomicity',
+    e2e: 'the built output, incl. offline and SW update',
+    eval: 'LLM output scored against thresholds',
+  },
+);
 
 /**
  * Every rule that decides a file's type, MOST SPECIFIC FIRST: the first entry a path matches owns

package/src/web-binding.ts

@@ -0,0 +1,22 @@
+// How a process binds its sockets, and what it admits about itself. A LEAF: it imports nothing,
+// so every role can read it without pulling `dev-roles` — which is what made this its own file.
+// `dev-sync` needs the default and `dev-roles` already imports `dev-sync`, so reading it from
+// there would be a runtime import cycle in the framework's own boot path.
+
+export interface WebBinding {
+  readonly dev: boolean;
+  /**
+   * The interface every socket this process opens binds to — the web role, the metrics endpoint
+   * and the `sync` node alike. ONE value, because they are one decision: a process that serves
+   * its app on loopback and its live-query patch stream on `0.0.0.0` has not bound to loopback,
+   * it has just moved which port the exposure is on.
+   */
+  readonly hostname: string;
+}
+
+/**
+ * Loopback and dev-mode. What `x dev` means, and what a container must override — a process bound
+ * to `localhost` inside a container is unreachable from the port mapping, the load balancer and
+ * every PaaS health probe, which is the same failure in four costumes.
+ */
+export const DEV_BINDING: WebBinding = { dev: true, hostname: 'localhost' };