@ultimat3/cli 20.2.0 → 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.2.0",
+  "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.2.0",
-    "@ultimat3/admin": "20.2.0",
-    "@ultimat3/ai": "20.2.0",
-    "@ultimat3/auth": "20.2.0",
-    "@ultimat3/cache": "20.2.0",
-    "@ultimat3/core": "20.2.0",
-    "@ultimat3/db": "20.2.0",
-    "@ultimat3/entity": "20.2.0",
-    "@ultimat3/flags": "20.2.0",
-    "@ultimat3/http": "20.2.0",
-    "@ultimat3/i18n": "20.2.0",
-    "@ultimat3/jobs": "20.2.0",
-    "@ultimat3/mail": "20.2.0",
-    "@ultimat3/manifest": "20.2.0",
-    "@ultimat3/mcp": "20.2.0",
-    "@ultimat3/money": "20.2.0",
-    "@ultimat3/notify": "20.2.0",
-    "@ultimat3/policy": "20.2.0",
-    "@ultimat3/pwa": "20.2.0",
-    "@ultimat3/query": "20.2.0",
-    "@ultimat3/realtime": "20.2.0",
-    "@ultimat3/render": "20.2.0",
-    "@ultimat3/schema": "20.2.0",
-    "@ultimat3/scraping": "20.2.0",
-    "@ultimat3/seo": "20.2.0",
-    "@ultimat3/storage": "20.2.0",
-    "@ultimat3/testing": "20.2.0",
-    "@ultimat3/time": "20.2.0",
+    "@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/cmd-shot.ts

@@ -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,9 +192,13 @@ 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;
@@ -234,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
@@ -322,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.
@@ -352,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
@@ -364,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);
@@ -415,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/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/shot-theme.ts

@@ -0,0 +1,52 @@
+// The script a capture runs ahead of the document when a theme was ASKED for. Since 20.2.0 the
+// boot inlines a theme script (`@ultimat3/render`'s `themeScriptBody`) whose fallback is the app's
+// `theme.defaultMode`, and only a stored choice under `THEME_STORAGE_KEY` beats it — so emulating
+// `prefers-color-scheme` alone photographs a `defaultMode: 'dark'` app dark whatever was requested
+// (issue #489). A requested theme is therefore stored as the visitor's CHOICE, on the page's origin,
+// before the boot reads it: the picture is then what a visitor who chose that theme sees.
+
+import { THEME_STORAGE_KEY } from '@ultimat3/render';
+import type { ColorScheme } from '@ultimat3/scraping';
+import { BadFlagError } from './errors';
+
+/** What `x shot --theme` accepts: the two the boot honours from storage, and nothing else. */
+const SHOT_THEMES = ['light', 'dark'] as const;
+export type ShotTheme = (typeof SHOT_THEMES)[number];
+
+const isShotTheme = (value: string): value is ShotTheme =>
+  (SHOT_THEMES as readonly string[]).includes(value);
+
+/**
+ * `--theme light|dark` on a ROUTE shot, or nothing — the box's own preference and the app's own
+ * default, which is what `x shot` has always photographed. Refused by name for any other value:
+ * `no-preference` is the scraping vocabulary's clear, not a theme a reader can ask for.
+ */
+export function readThemeFlag(value: string | undefined): ShotTheme | undefined {
+  if (value === undefined) return undefined;
+  if (isShotTheme(value)) return value;
+  throw new BadFlagError({
+    flag: 'theme',
+    command: 'shot',
+    reason: `"${value}" is not a theme; it is light or dark`,
+    fix: 'x shot / --theme light --json',
+  });
+}
+
+/**
+ * The seeding expression, DETERMINISTIC per scheme: the offline drivers key recordings on the exact
+ * string, and a test asserts on it by value. `'no-preference'` answers `undefined` — the boot
+ * honours only `"light"` and `"dark"` from storage, so there is no choice to store, and storing
+ * anything else would be a value the tokens have no block for.
+ *
+ * `JSON.stringify` on both halves, never a value pasted between quotes: the key and the scheme land
+ * inside a JS string, where one `"` ends it. The `try` is for the origin the page starts on:
+ * `about:blank` is opaque and its `localStorage` throws, and a throw from a new-document script
+ * would surface as a page error on a capture that has not navigated yet.
+ */
+export function themeChoiceExpression(scheme: ColorScheme): string | undefined {
+  if (scheme === 'no-preference') return undefined;
+  return (
+    `try{localStorage.setItem(${JSON.stringify(THEME_STORAGE_KEY)},${JSON.stringify(scheme)})}` +
+    'catch(e){}'
+  );
+}

package/src/templates/scaffold-dashboard-shared.ts

@@ -17,10 +17,13 @@ export const routeConfig = (load: string): string => `export const config = defi
   // Auth is a policy, never a route-local flag: one authz system, evaluated everywhere.
   policy: { permission: 'dashboard:read' },
   // Only the toggle island hydrates; the tiles, the chart and the table are server markup. The
-  // island measured 60.9kb minified under Bun 1.4.2 — solid-js is 12.6kb of it, the catalog's
-  // toggle, provider and the ui runtime they share are the rest — so 64kb is that figure plus
-  // the few hundred bytes the minifier moves between Bun patch versions, not headroom to spend.
-  budget: { js: '64kb' },${load}
+  // island measured 34.0kb minified under Bun 1.4.0 (37.0kb under 1.4.2, which honours
+  // \`sideEffects\` and keeps core's declared modules) — solid-js is 15.1kb of it, the catalog's
+  // toggle, provider, the ui runtime they share and the error registry are the rest. It was
+  // 60.9kb before the framework stopped shipping solid-js twice and the i18n catalog with it
+  // (issue #490), which is what put this at 64kb; 60kb is the figure the scaffold budgets held
+  // before that, kept rather than tightened so a Bun patch cannot red a first \`bin/check\`.
+  budget: { js: '60kb' },${load}
   meta: ({ t }) => ({
     title: t('app.dashboard.title'),
     description: t('app.dashboard.description'),
@@ -69,6 +72,6 @@ unitTest('the dashboard renders on the server, is gated, and has an offline stra
 
 unitTest('the dashboard hydrates its one island inside a stated budget', () => {
   expect(config.hydrate).toBe('visible');
-  expect(config.budget.js).toBe('64kb');
+  expect(config.budget.js).toBe('60kb');
 });
 `;