@ultimat3/cli 20.1.6 → 20.2.1

package/CLAUDE.md

@@ -1261,6 +1261,7 @@ missing.
 | File | Job |
 |---|---|
 | `island-bundle.ts` | discover `*.island.tsx`, build each as its own entry point, hash it, resolve a page's specifier to its URL |
+| `island-solid-dedupe.ts` | the plugin installed FIRST: every `solid-js` specifier in an island's graph resolves to the APP's copy. `Bun.build` resolves from a module's real path, so a package reached through a symlink (`file:` overrides, `bun link`) brought its own `solid-js` — the scaffold's theme toggle shipped two runtimes under CI's own links, 62,463 B against 50,042 B with one (issue #490), and two runtimes are two reactive graphs |
 | `island-routes.ts` | serve those chunks, at `ISLAND_BASE_PATH`, immutable |
 | `dev-render.ts` | one collector **per render**, and `hydrateRuntime` after the body |
 | `prerender.ts` | build first, write the chunks into the export, then measure |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/cli",
-  "version": "20.1.6",
+  "version": "20.2.1",
   "description": "The `x` binary: new, dev, build, verify, generate, db, mcp, doctor, deploy",
   "license": "MIT",
   "type": "module",
@@ -37,34 +37,34 @@
   },
   "dependencies": {
     "@babel/core": "^7.28.4",
-    "@ultimat3/action": "20.1.6",
-    "@ultimat3/admin": "20.1.6",
-    "@ultimat3/ai": "20.1.6",
-    "@ultimat3/auth": "20.1.6",
-    "@ultimat3/cache": "20.1.6",
-    "@ultimat3/core": "20.1.6",
-    "@ultimat3/db": "20.1.6",
-    "@ultimat3/entity": "20.1.6",
-    "@ultimat3/flags": "20.1.6",
-    "@ultimat3/http": "20.1.6",
-    "@ultimat3/i18n": "20.1.6",
-    "@ultimat3/jobs": "20.1.6",
-    "@ultimat3/mail": "20.1.6",
-    "@ultimat3/manifest": "20.1.6",
-    "@ultimat3/mcp": "20.1.6",
-    "@ultimat3/money": "20.1.6",
-    "@ultimat3/notify": "20.1.6",
-    "@ultimat3/policy": "20.1.6",
-    "@ultimat3/pwa": "20.1.6",
-    "@ultimat3/query": "20.1.6",
-    "@ultimat3/realtime": "20.1.6",
-    "@ultimat3/render": "20.1.6",
-    "@ultimat3/schema": "20.1.6",
-    "@ultimat3/scraping": "20.1.6",
-    "@ultimat3/seo": "20.1.6",
-    "@ultimat3/storage": "20.1.6",
-    "@ultimat3/testing": "20.1.6",
-    "@ultimat3/time": "20.1.6",
+    "@ultimat3/action": "20.2.1",
+    "@ultimat3/admin": "20.2.1",
+    "@ultimat3/ai": "20.2.1",
+    "@ultimat3/auth": "20.2.1",
+    "@ultimat3/cache": "20.2.1",
+    "@ultimat3/core": "20.2.1",
+    "@ultimat3/db": "20.2.1",
+    "@ultimat3/entity": "20.2.1",
+    "@ultimat3/flags": "20.2.1",
+    "@ultimat3/http": "20.2.1",
+    "@ultimat3/i18n": "20.2.1",
+    "@ultimat3/jobs": "20.2.1",
+    "@ultimat3/mail": "20.2.1",
+    "@ultimat3/manifest": "20.2.1",
+    "@ultimat3/mcp": "20.2.1",
+    "@ultimat3/money": "20.2.1",
+    "@ultimat3/notify": "20.2.1",
+    "@ultimat3/policy": "20.2.1",
+    "@ultimat3/pwa": "20.2.1",
+    "@ultimat3/query": "20.2.1",
+    "@ultimat3/realtime": "20.2.1",
+    "@ultimat3/render": "20.2.1",
+    "@ultimat3/schema": "20.2.1",
+    "@ultimat3/scraping": "20.2.1",
+    "@ultimat3/seo": "20.2.1",
+    "@ultimat3/storage": "20.2.1",
+    "@ultimat3/testing": "20.2.1",
+    "@ultimat3/time": "20.2.1",
     "babel-preset-solid": "^1.9.15"
   }
 }

package/src/budgets.ts

@@ -10,7 +10,7 @@ import { existsSync } from 'node:fs';
 import { join } from 'node:path';
 import { ERROR_DOCS_URL } from '@ultimat3/core';
 import type { Manifest, RouteFact } from '@ultimat3/manifest';
-import { formatBytes, parseByteBudget } from '@ultimat3/render';
+import { formatBytes, parseByteBudget, themeScriptBody } from '@ultimat3/render';
 import type { Finding } from './output';
 import type { UnmeasuredRoute } from './static-report';
 import { SW_REGISTER_PATH } from './sw-artifacts';
@@ -253,6 +253,18 @@ export interface MeasuredJs {
  */
 export const FRAMEWORK_SCRIPTS: ReadonlySet<string> = new Set([SW_REGISTER_PATH]);
 
+/**
+ * The inline bodies the boot puts in EVERY document, keyed by the same argument as
+ * `FRAMEWORK_SCRIPTS`: the author cannot edit, delete or move them, so charging one against a
+ * `0kb` budget is a finding nobody can act on. Today that is the no-flash theme script, in each
+ * of its three fallbacks (`theme-boot.ts` uses `themeScript`'s defaults for everything else, so
+ * these are the exact strings a document carries). The hydration runtime is NOT here — it exists
+ * only when the page ships an island, and is the cost of the app's own interactivity.
+ */
+export const FRAMEWORK_INLINE_SCRIPTS: ReadonlySet<string> = new Set(
+  (['light', 'dark', 'system'] as const).map((fallback) => themeScriptBody({ fallback })),
+);
+
 /**
  * What a rendered document actually makes the browser execute: the bytes of every inline script
  * the parser will run, the size of every file a `src` points at, and the size of every island
@@ -301,7 +313,10 @@ export async function measureDocumentJs(html: string, out: string): Promise<Meas
     if (carriesJson(attrs)) continue;
     const src = SRC_ATTR.exec(attrs)?.groups?.['src'];
     if (src === undefined) {
-      jsBytes += Buffer.byteLength(match.groups?.['body'] ?? '', 'utf8');
+      const body = match.groups?.['body'] ?? '';
+      const bytes = Buffer.byteLength(body, 'utf8');
+      if (FRAMEWORK_INLINE_SCRIPTS.has(body)) frameworkBytes += bytes;
+      else jsBytes += bytes;
       continue;
     }
     await weigh(src);

package/src/cmd-dev.ts

@@ -40,6 +40,7 @@ import { describeServices, reportedUrls, resolveServices } from './dev-services'
 import { storageRoutes } from './dev-storage';
 import { createTraceRecorder } from './dev-traces';
 import { watchTree } from './dev-watch-tree';
+import { errorPageStyleSources } from './error-page-csp';
 import { intFlagOr, PORT_RANGE } from './flag-number';
 import { holdUntilShutdown } from './hold';
 import type { IslandBundle } from './island-bundle';
@@ -59,6 +60,7 @@ import { styleBundle } from './style-bundle';
 import { styleRoutes } from './style-routes';
 import { serviceWorkerArtifacts } from './sw-artifacts';
 import { serviceWorkerRoutes } from './sw-routes';
+import { loadThemeMode, themeBoot } from './theme-boot';
 
 const DEFAULT_PORT = 3000;
 
@@ -187,6 +189,8 @@ export async function startDev(options: StartDevOptions): Promise<DevServer> {
   // name it. `undefined` for an app that is not installable, and then nothing is mounted and no
   // document changes — the 0kb baseline is not spent on a `<link>` to a file that does not exist.
   const pwa = await loadPwaArtifacts(options.root);
+  const theme = themeBoot(await loadThemeMode(options.root));
+  const errorStyles = await errorPageStyleSources(options.root);
   // Built once at boot, from this process's own route table and island bundle. `x dev` rebuilds
   // islands on the watcher tick and the worker is NOT rebuilt with them, deliberately: a service
   // worker that changes under a page it already controls is the update path, and re-emitting one
@@ -241,6 +245,7 @@ export async function startDev(options: StartDevOptions): Promise<DevServer> {
     ...appRoutes({
       buildId,
       resolveIsland: (file) => state.islands.resolverFor(file),
+      themeHead: theme.head,
       ...(pwa === undefined ? {} : { pwaHead: pwa.head + (serviceWorker?.head ?? '') }),
     }),
   ];
@@ -264,23 +269,17 @@ export async function startDev(options: StartDevOptions): Promise<DevServer> {
     runtime,
     routes,
     env: options.env,
-    // Read from `app.config.ts` rather than threaded through `DevOptions`: it is the app's own
-    // declaration, and `x dev` and `serve.ts` must not be able to disagree about where the app's
-    // sign-in page is.
+    // Read from `app.config.ts` rather than threaded through `DevOptions`: `x dev` and `serve.ts`
+    // must not be able to disagree about where the app's sign-in page is.
     signInPath: await loadSignInPath(options.root),
-    // The same seam `serve.ts` passes: the app's own error page is a FILE, so the root is what
-    // `startWeb` needs to find one.
+    // The same seam `serve.ts` passes: the app's own error page is a FILE under this root.
     root: options.root,
-    // The documents this process serves that the app did not write — the `/_x` shell and the
-    // screenshot harness's frame. The app's OWN surfaces need no entry any more: their CSS is a
-    // content-hashed file `'self'` already admits (`style-bundle.ts`). `x dev` sends the policy
-    // report-only, so an uncovered `<style>` here is a console report rather than a blank page —
-    // which is how this reached production.
-    inlineStyles: [await devShellStyle(), FRAME_STYLE],
-    // The fourth surface, and the only one an author sees without leaving the page they broke:
-    // the overlay renders this request's own loops under the error it is already showing.
-    // `serve.ts` boots through the same `startRoles` and passes nothing, so production has no
-    // diagnostic to call.
+    // The `/_x` shell, the harness's frame, and the app's own error pages — the inline bodies this
+    // process serves; the app's surfaces are content-hashed files `'self'` admits.
+    inlineStyles: [await devShellStyle(), FRAME_STYLE, ...errorStyles],
+    inlineScripts: [theme.cspSource],
+    // The overlay renders this request's own loops under the error it is already showing.
+    // `serve.ts` boots through the same `startRoles` and passes nothing (axiom 6).
     devNotices: (ctx: RequestContext): readonly OverlayNotice[] =>
       statements.repeatsFor(asCtx(ctx)).map(loopFacts).map(loopNotice),
     // The read-replica scope, opened per request. Absent for every app that names no

package/src/cmd-mcp.ts

@@ -1,4 +1,4 @@
-// `x mcp serve` — the framework's dev MCP server over stdio or HTTP. The 15 tools, the JSON-RPC
+// `x mcp serve` — the framework's dev MCP server over stdio or HTTP. The 18 tools, the JSON-RPC
 // dispatch, both transports and the structural SQL refusals all come from `@ultimat3/mcp`; the CLI
 // supplies only the app, the caller and the socket. A tool answered here would be a second answer
 // to a question the framework already answers.
@@ -117,7 +117,7 @@ export function startMcpHttp(host: CliMcpServer, port: number): McpHttpServer {
  * What the session reports when it is over — on STDERR, which is the half this file's header
  * claimed and did not have. `dispatch` renders a `CommandResult` only after `run` resolves, and
  * this resolves when the peer closes stdin, so nothing lands mid-session; but fd 1 under this
- * transport carries JSON-RPC frames, and `✓ mcp stdio serving 15 tools` arriving on it after the
+ * transport carries JSON-RPC frames, and `✓ mcp stdio serving 18 tools` arriving on it after the
  * loop is a malformed frame to a peer still draining, and a second document under `--json`.
  *
  * Its own function so the addressing is testable without a live peer: `serveStdio` resolves only

package/src/cmd-shot.ts

@@ -8,7 +8,7 @@
 import { mkdirSync } from 'node:fs';
 import { join, resolve } from 'node:path';
 import { IDLE_HYDRATE_TIMEOUT_MS } from '@ultimat3/render';
-import type { ColorScheme, ScrapeDriver, ScrapeSession } from '@ultimat3/scraping';
+import type { ColorScheme, ScrapeDriver, ScrapePage, ScrapeSession } from '@ultimat3/scraping';
 import { DEFAULT_PAGE_TIMEOUT_MS, systemScrapeClock } from '@ultimat3/scraping';
 import { requireAppRoot } from './app-root';
 import { appBrowser } from './browser-launcher';
@@ -32,6 +32,7 @@ import { shotBrowserChoice } from './shot-browser';
 import type { BootDevServer, ShotServer } from './shot-server';
 import { allowHostsFrom, devServerFor, SHOT_DIR } from './shot-server';
 import { SETTLE_POLL_MS, settleIslands } from './shot-settle';
+import { readThemeFlag, themeChoiceExpression } from './shot-theme';
 import type { IslandCount, ShotArtifacts } from './shot-verdict';
 import {
   buildVerdict,
@@ -191,12 +192,25 @@ export interface ShotRun {
    */
   readonly extraHosts?: string | undefined;
   /**
-   * What `prefers-color-scheme` the page sees, emulated BEFORE navigation so the boot script's
-   * "system" branch answers the same on every box. Absent means the box's own preference — what
-   * `x shot` has always done — and `ui.shot` names one explicitly for exactly that reason.
+   * The theme the picture is of. Two things happen BEFORE navigation, because the boot script runs
+   * inline and nothing after `goto` can reach it: `prefers-color-scheme` is emulated so the boot's
+   * "system" branch answers the same on every box, AND the scheme is stored as the visitor's
+   * choice under `THEME_STORAGE_KEY` (`shot-theme.ts`), because an app with `theme.defaultMode`
+   * set answers that before the OS and only a stored choice beats it (issue #489). Absent means
+   * neither: the box's own preference and the app's own default — what `x shot` has always done,
+   * and the point of `defaultMode` — and `ui.shot` names one explicitly for exactly that reason.
    */
   readonly colorScheme?: ColorScheme | undefined;
   readonly now?: (() => Date) | undefined;
+  /**
+   * Something to do with the page AFTER the islands settled and BEFORE the picture — `ui.inspect`
+   * reads the DOM here, on the one navigation the picture already paid for. `settle` re-runs the
+   * island poll (an action that mounts something changes the count the verdict reports); the
+   * caller who never calls it gets the count from the first settle.
+   */
+  readonly act?:
+    | ((page: ScrapePage, settle: () => Promise<IslandCount | null>) => Promise<void>)
+    | undefined;
 }
 
 /** Nothing here may replace the failure that caused it, so a teardown throw is swallowed. */
@@ -225,7 +239,11 @@ export async function runShot(options: ShotRun): Promise<ShotArtifacts> {
       timeoutMs: options.timeoutMs,
     });
     const page = session.page;
-    if (options.colorScheme !== undefined) await page.colorScheme(options.colorScheme);
+    if (options.colorScheme !== undefined) {
+      await page.colorScheme(options.colorScheme);
+      const choice = themeChoiceExpression(options.colorScheme);
+      if (choice !== undefined) await page.prepare(choice);
+    }
     await page.goto(requestedUrl, { timeout: options.timeoutMs });
     if (options.settleMs > 0) await Bun.sleep(options.settleMs);
     // The probe may legitimately answer nothing — a page that refuses evaluation, a driver with no
@@ -239,10 +257,15 @@ export async function runShot(options: ShotRun): Promise<ShotArtifacts> {
     // The same budget again, and deliberately no new flag: `settleMs` is the deadline at which the
     // runtime CALLS `import()`, so a mount gets exactly as long to settle as the runtime got to
     // start it — and `--settle 0`, which asks for no wait, still gets none.
-    const islands = await settleIslands(probe, {
-      windowMs: options.settleMs,
-      pollMs: SETTLE_POLL_MS,
-    });
+    const settle = (): Promise<IslandCount | null> =>
+      settleIslands(probe, { windowMs: options.settleMs, pollMs: SETTLE_POLL_MS });
+    let islands = await settle();
+    if (options.act !== undefined) {
+      await options.act(page, async () => {
+        islands = await settle();
+        return islands;
+      });
+    }
     const bytes = await page.screenshot({ fullPage: options.fullPage });
     // Read AFTER the capture, so an error logged while the page settled is in the verdict that
     // ships with the picture it explains.
@@ -308,6 +331,11 @@ export const shotCommand: CliCommand = {
         summary: 'attach to a browser somebody else is running (a provider session, a sidecar)',
       },
       { name: 'allow-hosts', type: 'string', summary: 'extra hosts the page may request' },
+      {
+        name: 'theme',
+        type: 'string',
+        summary: "light or dark, stored as the visitor's choice; absent is the app's own default",
+      },
       // A FLAG on `x shot` and never a second command: photographing a route and photographing a
       // component are one job with two subjects, and a parallel command would be the second path
       // axiom 1 refuses.
@@ -338,6 +366,7 @@ export const shotCommand: CliCommand = {
     // report, which is the rule `x routes` and `x mcp` already follow.
     const island = flagString(ctx.args, 'island');
     const state = flagString(ctx.args, 'state');
+    const theme = readThemeFlag(flagString(ctx.args, 'theme'));
     const positional = ctx.args.positionals[0];
     const sweep = flagBool(ctx.args, 'all-islands');
     // Every ambiguous pair refused BY NAME, before a value is read: a reader who typed two
@@ -350,6 +379,16 @@ export const shotCommand: CliCommand = {
       refuseRouteWithIsland(positional, island);
     }
     const component = sweep || (island !== undefined && island !== '');
+    // An island is photographed in BOTH themes by the harness, which owns its `data-theme` and
+    // carries no boot script — so a theme asked for beside one is a request nothing could honour.
+    if (component && theme !== undefined) {
+      throw new BadFlagError({
+        flag: 'theme',
+        command: 'shot',
+        reason: 'photographs a route; an island is photographed in both themes',
+        fix: 'x shot / --theme light --json',
+      });
+    }
     const route = component ? '' : readRoute(positional);
     const port = intFlag(ctx.args, 'port', PORT_RANGE.min, DEFAULT_PORT, PORT_RANGE.max);
     const settleMs = intFlag(ctx.args, 'settle', 0, DEFAULT_SETTLE_MS);
@@ -401,6 +440,7 @@ export const shotCommand: CliCommand = {
         timeoutMs,
         fullPage: flagBool(ctx.args, 'full'),
         extraHosts: flagString(ctx.args, 'allow-hosts'),
+        ...(theme === undefined ? {} : { colorScheme: theme }),
       }),
     );
   },

package/src/dev-render.ts

@@ -65,6 +65,12 @@ export interface DocumentOptions {
    * boot knows it, the renderer cannot ask.
    */
   readonly pwaHead?: string;
+  /**
+   * The no-flash theme `<script>` from `theme-boot.ts`, or absent for a caller that renders no
+   * documents a browser paints. Document-level for `pwaHead`'s reason — the same tag on every page,
+   * decided by `app.config.ts`, which the boot read and the renderer cannot.
+   */
+  readonly themeHead?: string;
 }
 
 export interface DevRenderOptions extends DocumentOptions {
@@ -99,7 +105,9 @@ const headFor = async (
       await entry.config.meta(metaContextFor(ctx, data)),
       seoRenderers({ path: new URL(ctx.url).pathname }),
     ),
-  ) + (options.pwaHead ?? '');
+  ) +
+  (options.themeHead ?? '') +
+  (options.pwaHead ?? '');
 
 /**
  * `<link rel="stylesheet">` for the surface's own stylesheets, or nothing at all when the surface

package/src/dev-roles.ts

@@ -100,6 +100,8 @@ export interface StartRolesOptions {
    * serves: that policy is what rendered every deployed app completely unstyled.
    */
   readonly inlineStyles?: readonly string[];
+  /** `script-src` sources beyond the hydration runtime's — the theme boot's hash. */
+  readonly inlineScripts?: readonly string[];
   /**
    * Non-fatal findings the browser overlay shows next to an error, for the request being answered.
    * Only `x dev` supplies one — `serve.ts` boots through this same function and omits it, so a
@@ -321,16 +323,14 @@ function startWeb(options: StartRolesOptions, mount?: WebSocketMount<SyncWs>): S
         rateLimit: { scope: store?.scope ?? 'process' },
         // Hashes, never `'unsafe-inline'`: a `render: 'static'` page is a file on disk, so
         // nothing can stamp a per-response nonce into it, but its body is fixed and a hash is a
-        // function of that body. Read after `loadApp` — importing the app IS what registered them.
-        // BOTH directives, and the script half is the one that was missing: the hydration runtime
-        // is emitted inline in every document that carries an island, so `script-src 'self'` meant
-        // no island booted anywhere the policy is enforced — which is every container, and never
-        // `x dev`, where it is report-only.
+        // function of that body. BOTH directives: the hydration runtime is emitted inline in every
+        // document that carries an island, so `script-src 'self'` meant no island booted anywhere
+        // the policy is enforced — every container, and never `x dev`, where it is report-only.
         security: {
           csp: {
             extend: {
               'style-src': inlineStyleSources(options.inlineStyles ?? []),
-              'script-src': inlineScriptSources(),
+              'script-src': inlineScriptSources(options.inlineScripts ?? []),
             },
           },
         },

package/src/error-codes.ts

@@ -157,6 +157,17 @@ export const CLI_OWNED_ERROR_CODES = [
   // `ui.shot` (the dev MCP server): a route it will not photograph, and why.
   'X_UI_SHOT_ROUTE_UNKNOWN',
   'X_UI_SHOT_ROUTE_UNBUDGETED',
+  // `ui.interact`: the four ways a step list is refused. All four REFUSE rather than trim or skip
+  // — a step dropped, a keystroke swallowed or a navigation followed changes what the picture is of.
+  'X_UI_INTERACT_STEPS_INVALID',
+  'X_UI_INTERACT_SECRET_FIELD',
+  'X_UI_INTERACT_LEFT_APP',
+  'X_UI_INTERACT_STEP_FAILED',
+  // `ui.diff`: the three ways two captures fail to become a comparison. The path gate is what
+  // lets a file-reading tool sit under `dev:read` — it reads `.x/shot/` and nothing else.
+  'X_UI_DIFF_PATH_OUTSIDE',
+  'X_UI_DIFF_FILE_MISSING',
+  'X_UI_DIFF_SIZE_MISMATCH',
   // `x shot --island` — one code per way a component's named state fails to become a picture.
   // The last of the four is the one that gates: it is checked against the expansion computed
   // before a browser existed, so a capture loop that swallowed a failure cannot exit 0.
@@ -300,8 +311,15 @@ export const CLI_ERROR_TITLES: Readonly<Record<CliOwnedErrorCode, string>> = {
   X_WORKSPACE_DEP_UNDECLARED: 'a workspace imports another workspace it does not declare',
   X_PACKAGE_DUPLICATED: 'two copies of one registry-holding framework package are installed',
   X_SHOT_BROWSER_MISSING: 'x shot found no browser library in the app',
-  X_UI_SHOT_ROUTE_UNKNOWN: 'ui.shot was asked for a path no route answers',
-  X_UI_SHOT_ROUTE_UNBUDGETED: 'ui.shot refused a route that declares no budget.js',
+  X_UI_SHOT_ROUTE_UNKNOWN: 'a ui.* tool was asked for a path no route answers',
+  X_UI_SHOT_ROUTE_UNBUDGETED: 'a ui.* tool refused a route that declares no budget.js',
+  X_UI_INTERACT_STEPS_INVALID: 'a ui.interact step list is over its bounds or malformed',
+  X_UI_INTERACT_SECRET_FIELD: 'ui.interact refused to type into a password field',
+  X_UI_INTERACT_LEFT_APP: 'a ui.interact step navigated off the dev server origin',
+  X_UI_INTERACT_STEP_FAILED: 'a ui.interact step raised a scraping error',
+  X_UI_DIFF_PATH_OUTSIDE: 'ui.diff was handed a path that does not resolve inside .x/shot/',
+  X_UI_DIFF_FILE_MISSING: 'ui.diff was handed a capture that is not on disk',
+  X_UI_DIFF_SIZE_MISMATCH: 'ui.diff was handed two captures of different sizes',
   X_SHOT_ISLAND_STATES_EMPTY: 'an island states file declares no manifest',
   X_SHOT_ISLAND_UNPHOTOGRAPHABLE: 'the island never reached a state worth photographing',
   X_SHOT_ISLAND_UNSTUBBED_REQUEST: 'the island requested something no state stub answers',

package/src/error-page-csp.ts

@@ -0,0 +1,50 @@
+// The `style-src` sources that admit an app's own error pages. `error-pages.ts` serves
+// `apps/web/site/errors/<status>.html` verbatim, and such a page is a self-contained document —
+// it carries its own `<style>`, because the app's stylesheet bundle is not linked from it. Under
+// the enforced policy a container sends, `style-src 'self' <overlay hash>` blocked that block and
+// the page rendered unstyled; `x dev` sends the policy report-only, so the same page looked fine
+// on every author's machine. Hashed at boot, like the hydration runtime: a hash is a function of
+// the body, and these files do not change while a container runs.
+
+// why: Bun exposes no path-join primitive, and the directory is app-root-relative — the same
+// necessity `error-pages.ts` records.
+import { join } from 'node:path';
+import { cspHashSource } from '@ultimat3/http';
+import { ERROR_PAGE_DIR } from './error-pages';
+
+/**
+ * `<style>` bodies, in document order, exactly as the browser will hash them: the text between
+ * the tags, untrimmed. A trimmed body hashes to a different value and admits nothing.
+ */
+export function inlineStyleBodies(html: string): readonly string[] {
+  const bodies: string[] = [];
+  const pattern = /<style(?:\s[^>]*)?>([\s\S]*?)<\/style>/gi;
+  for (let match = pattern.exec(html); match !== null; match = pattern.exec(html)) {
+    bodies.push(match[1] ?? '');
+  }
+  return bodies;
+}
+
+/**
+ * One hash per distinct `<style>` body across every error page the app ships. Read once at boot:
+ * a page an author drops in while `x dev` runs is served (the reader is per request) but not yet
+ * admitted, which the report-only policy there turns into a console report, not a blank page.
+ */
+export async function errorPageStyleSources(root: string): Promise<readonly string[]> {
+  const dir = join(root, ERROR_PAGE_DIR);
+  const sources = new Set<string>();
+  for (const name of await htmlFilesIn(dir)) {
+    const html = await Bun.file(join(dir, name)).text();
+    for (const body of inlineStyleBodies(html)) sources.add(cspHashSource(body));
+  }
+  return [...sources].sort();
+}
+
+/** `Bun.Glob.scan` throws `ENOENT` on a missing directory, and no error pages is the common case. */
+async function htmlFilesIn(dir: string): Promise<readonly string[]> {
+  try {
+    return (await Array.fromAsync(new Bun.Glob('*.html').scan({ cwd: dir }))).sort();
+  } catch {
+    return [];
+  }
+}

package/src/island-bundle.ts

@@ -11,6 +11,7 @@ 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 { solidDedupePlugin } from './island-solid-dedupe';
 import { islandStylesPlugin } from './island-styles';
 import { hasPathSegment } from './path-segments';
 import { solidJsxPlugin } from './solid-loader';
@@ -91,7 +92,11 @@ 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: [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

package/src/island-solid-dedupe.ts

@@ -0,0 +1,108 @@
+// One Solid runtime per island chunk: the app's. Every `solid-js` specifier in the island's graph
+// — the entry's own `render` from `solid-js/web`, and the `solid-js/web` helpers the JSX
+// transform writes into every `@ultimat3/ui` component — resolves to the copy the APP installed.
+//
+// Without this, `Bun.build` resolves each import from the importing file's REAL path. A package
+// reached through a symlink (`file:` overrides, `bun link`, a workspace with its own install)
+// resolves `solid-js` from its own `node_modules`, and the chunk ships two runtimes: measured on
+// the scaffold's theme-toggle island under CI's own `file:` links, 62,463 B against 50,042 B with
+// one (issue #490). Two copies are also two reactive graphs — a context created by one is never
+// found by the other's `useContext` — so the dedupe is a correctness rule that happens to be the
+// biggest single cut in the chunk, not a size trick.
+
+// why: Bun ships no path API; `dirname` recovers the package directory from the manifest path
+// `Bun.resolveSync` answers, and `join` puts an export target under it.
+import { dirname, join } from 'node:path';
+import type { BunPlugin } from 'bun';
+
+const SOLID_PACKAGE = 'solid-js';
+
+/** `solid-js` and every subpath of it — `solid-js/web`, `solid-js/store`, `solid-js/h`. */
+export const SOLID_SPECIFIER = /^solid-js(?:\/.*)?$/;
+
+/**
+ * The conditions an island is built under, in the order they are tried: `browser` because the
+ * chunk runs there, `import` because it is ESM, `default` as the map's own fallback. NOT
+ * `development` — `island-bundle.ts` defines `process.env.NODE_ENV` as `"production"` for the
+ * same reason, and solid nests `development` INSIDE `browser`, so walking without it is what
+ * selects `dist/solid.js` over `dist/dev.js`.
+ */
+const BROWSER_CONDITIONS: readonly string[] = ['browser', 'import', 'default'];
+
+/** `solid-js` → `.`, `solid-js/web` → `./web`: the key the package's `exports` map uses. */
+export function solidSubpath(specifier: string): string {
+  return specifier === SOLID_PACKAGE ? '.' : `.${specifier.slice(SOLID_PACKAGE.length)}`;
+}
+
+/**
+ * The target one `exports` entry names under the conditions above — depth-first, in the map's
+ * own key order, which is how Node and Bun read a conditions object. A string is a target; a
+ * nested object is walked; a condition the island does not build under (`node`, `worker`,
+ * `require`, `types`, `development`) is skipped. `undefined` when nothing matched, and the
+ * caller then leaves the specifier to Bun's own resolver rather than guessing.
+ */
+export function conditionTarget(entry: unknown): string | undefined {
+  if (typeof entry === 'string') return entry;
+  if (entry === null || typeof entry !== 'object' || Array.isArray(entry)) return undefined;
+  for (const [condition, nested] of Object.entries(entry)) {
+    if (!BROWSER_CONDITIONS.includes(condition)) continue;
+    const target = conditionTarget(nested);
+    if (target !== undefined) return target;
+  }
+  return undefined;
+}
+
+export interface AppSolid {
+  /** The installed package's directory — where every export target is joined onto. */
+  readonly dir: string;
+  /** Its `exports` map, verbatim. */
+  readonly exports: unknown;
+}
+
+/**
+ * The `solid-js` the app installed, found the way the app's own entry would find it: from the app
+ * root upward. `null` when there is none — an app with no islands never gets here, and an island
+ * importing solid where none is installed fails the build in Bun's own words either way.
+ */
+export async function resolveAppSolid(root: string): Promise<AppSolid | null> {
+  let manifest: string;
+  try {
+    manifest = Bun.resolveSync(`${SOLID_PACKAGE}/package.json`, root);
+  } catch {
+    return null;
+  }
+  const parsed = (await Bun.file(manifest).json()) as { readonly exports?: unknown };
+  return { dir: dirname(manifest), exports: parsed.exports };
+}
+
+/** Where `specifier` lands in the app's own copy, or `undefined` to leave it to Bun. */
+export function appSolidPath(solid: AppSolid, specifier: string): string | undefined {
+  const exports = solid.exports;
+  if (exports === null || typeof exports !== 'object') return undefined;
+  const entry = Object.hasOwn(exports, solidSubpath(specifier))
+    ? (exports as Record<string, unknown>)[solidSubpath(specifier)]
+    : undefined;
+  const target = conditionTarget(entry);
+  return target === undefined ? undefined : join(solid.dir, target);
+}
+
+/**
+ * The plugin `island-bundle.ts` installs FIRST, so it sees every `solid-js` specifier before the
+ * JSX and style plugins do. Resolved once per build and cached: the map is read from disk at
+ * most one time however many modules import solid.
+ */
+export function solidDedupePlugin(root: string): BunPlugin {
+  let app: Promise<AppSolid | null> | null = null;
+  return {
+    name: 'ultimate-solid-dedupe',
+    setup(build): void {
+      build.onResolve({ filter: SOLID_SPECIFIER }, async (args) => {
+        app ??= resolveAppSolid(root);
+        const solid = await app;
+        if (solid === null) return undefined;
+        const path = appSolidPath(solid, args.path);
+        return path === undefined ? undefined : { path };
+      });
+    },
+  };
+}

package/src/mcp-errors.ts

@@ -55,9 +55,28 @@ const CLI_FIXES: Readonly<Record<CliErrorCode, string>> = {
   X_PACKAGE_DUPLICATED:
     'x i18n check --json   # the finding names both copies and the package.json to pin',
   X_SHOT_BROWSER_MISSING: 'bun add -d puppeteer-core',
-  X_UI_SHOT_ROUTE_UNKNOWN: 'x routes --json   # then ui.shot with one of its path values',
+  X_UI_SHOT_ROUTE_UNKNOWN:
+    'x routes --json   # then call the ui.* tool with one of its path values',
   X_UI_SHOT_ROUTE_UNBUDGETED:
     "x build --target static --json && x verify --only budgets --json   # after declaring budget: { js: '<n>kb' } in the route file",
+  // The four `ui.interact` refusals. None can be repaired by a command — each is a change to the
+  // step list the agent sends — so each names the command that SHOWS what a valid resend needs.
+  X_UI_INTERACT_STEPS_INVALID:
+    'x help shot --json   # then resend ui.interact with at most 12 one-key steps, type.text under 500 chars and wait under 5000 ms',
+  X_UI_INTERACT_SECRET_FIELD:
+    'x shot --all-islands --json   # or --island <name>: a declared state renders the filled form without the secret ever being typed',
+  X_UI_INTERACT_LEFT_APP:
+    'x routes --json   # then resend ui.interact with steps that stay on one of its paths',
+  X_UI_INTERACT_STEP_FAILED:
+    'x routes --json   # then run ui.inspect on the route first and copy a selector it reports with count >= 1',
+  // The three `ui.diff` codes. Every capture it can compare was written by `x shot` or a `ui.*`
+  // tool under `.x/shot/`, so the runnable half is the command that writes one there.
+  X_UI_DIFF_PATH_OUTSIDE:
+    'x shot / --json   # then pass the image path it answers, relative to the app root: ui.diff reads .x/shot/ and nothing else',
+  X_UI_DIFF_FILE_MISSING:
+    'x shot / --json   # then diff the image path it answers; a capture ui.shot wrote is listed in its own answer',
+  X_UI_DIFF_SIZE_MISMATCH:
+    'x shot / --json   # photograph both captures at one viewport with one fullPage setting, then diff those two',
   // The four island-capture codes. Each one's real repair is an edit to the app's own states file
   // or component, which no command can perform — so each names the command that REPRODUCES it with
   // the file and the reason attached, which is the runnable half.