npm - @ultimat3/cli - Versions diffs - 20.1.6 → 20.2.1 - Mend

@ultimat3/cli 20.1.6 → 20.2.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (37) hide show

package/CLAUDE.md +1 -0
package/package.json +29 -29
package/src/budgets.ts +17 -2
package/src/cmd-dev.ts +14 -15
package/src/cmd-mcp.ts +2 -2
package/src/cmd-shot.ts +49 -9
package/src/dev-render.ts +9 -1
package/src/dev-roles.ts +6 -6
package/src/error-codes.ts +20 -2
package/src/error-page-csp.ts +50 -0
package/src/island-bundle.ts +6 -1
package/src/island-solid-dedupe.ts +108 -0
package/src/mcp-errors.ts +20 -1
package/src/mcp-ui-diff.ts +141 -0
package/src/mcp-ui-inspect.ts +183 -0
package/src/mcp-ui-interact.ts +304 -0
package/src/mcp-ui.ts +53 -15
package/src/output.ts +1 -1
package/src/prerender.ts +3 -0
package/src/scaffold-typecheck.ts +5 -0
package/src/script-csp.ts +5 -2
package/src/serve.ts +8 -0
package/src/shot-theme.ts +52 -0
package/src/templates/index.ts +5 -1
package/src/templates/scaffold-app.ts +14 -155
package/src/templates/scaffold-dashboard-bare.ts +182 -0
package/src/templates/scaffold-dashboard-example.ts +326 -0
package/src/templates/scaffold-dashboard-shared.ts +77 -0
package/src/templates/scaffold-dashboard.ts +27 -0
package/src/templates/scaffold-errors.ts +128 -0
package/src/templates/scaffold-i18n.ts +46 -0
package/src/templates/scaffold-repo.ts +7 -2
package/src/templates/scaffold-shell.ts +461 -0
package/src/templates/scaffold-site.ts +287 -0
package/src/theme-boot.ts +59 -0
package/src/ui-diff.ts +90 -0
package/src/ui-inspect-probe.ts +131 -0

package/src/templates/scaffold-errors.ts ADDED Viewed

@@ -0,0 +1,128 @@
+// The two error pages `x new` writes — `apps/web/site/errors/404.html` and `500.html`, the files
+// `packages/cli/src/error-pages.ts` serves verbatim for those statuses and the static export
+// carries as `404.html`. Self-contained documents by construction: a 500 is answered when the app's
+// own stylesheet may be the thing that failed, so nothing here links a bundle, loads a font or runs
+// a script. The `<style>` body is hashed into `style-src` at boot (`error-page-csp.ts`), which is
+// what lets the enforced policy a container sends admit it.
+import type { GeneratedFile, NameSet } from './naming';
+import { titleCase } from './naming';
+/**
+ * The same two hex values `app.config.ts`'s `pwa.colors` declares — one source, read by both
+ * templates, so the splash a browser paints before any stylesheet and the page it shows when the
+ * stylesheet never arrives agree. Raw hex is legal in these two places and nowhere else in an app:
+ * the raw-colour guard scans `.scss` (a page with no stylesheet has no token to read), and an
+ * install prompt has no stylesheet either.
+ */
+export const PWA_COLORS = {
+  themeColor: '#1b1f3b',
+  lightBackground: '#ffffff',
+  darkBackground: '#0b0d1a',
+} as const;
+/** One page per status, English only: the file is served as bytes, so no translator runs. */
+interface ErrorCopy {
+  readonly status: number;
+  readonly title: string;
+  readonly body: string;
+}
+const COPY: readonly ErrorCopy[] = [
+  {
+    status: 404,
+    title: 'Page not found',
+    body: 'There is nothing at this address. The link may be old, or the page may have moved.',
+  },
+  {
+    status: 500,
+    title: 'Something went wrong',
+    body: 'The server could not finish this request. It has been recorded; try again in a moment.',
+  },
+];
+/**
+ * `prefers-color-scheme` rather than `data-theme`: the theme boot script is inlined by the
+ * framework into documents it RENDERS, and this file is served as-is, so the OS preference is the
+ * only signal it has. The dark palette is the default and the light one is the media override,
+ * matching the `theme.defaultMode` the scaffold sets.
+ */
+const style = (): string => `
+      :root {
+        color-scheme: dark light;
+        --bg: ${PWA_COLORS.darkBackground};
+        --fg: #e6e8f0;
+        --muted: #9aa0b5;
+        --accent: #8b93ff;
+        --line: #262a45;
+      }
+      @media (prefers-color-scheme: light) {
+        :root {
+          --bg: ${PWA_COLORS.lightBackground};
+          --fg: ${PWA_COLORS.themeColor};
+          --muted: #5d6280;
+          --accent: #3b46d6;
+          --line: #dfe2ee;
+        }
+      }
+      * { box-sizing: border-box; margin: 0; }
+      html, body { min-height: 100%; }
+      body {
+        display: grid;
+        place-items: center;
+        padding: 2rem;
+        background: var(--bg);
+        color: var(--fg);
+        font-family: system-ui, -apple-system, 'Segoe UI', sans-serif;
+        line-height: 1.5;
+      }
+      main { max-width: 32rem; }
+      .status {
+        font-family: ui-monospace, 'SFMono-Regular', Menlo, monospace;
+        font-size: 0.75rem;
+        letter-spacing: 0.12em;
+        text-transform: uppercase;
+        color: var(--accent);
+      }
+      h1 { margin-top: 0.5rem; font-size: 2rem; font-weight: 600; letter-spacing: -0.02em; }
+      p { margin-top: 0.75rem; color: var(--muted); }
+      a {
+        display: inline-block;
+        margin-top: 1.5rem;
+        padding: 0.6rem 1rem;
+        border: 1px solid var(--line);
+        border-radius: 0.5rem;
+        color: var(--fg);
+        text-decoration: none;
+      }
+      a:hover { border-color: var(--accent); }
+      a:focus-visible { outline: 2px solid var(--accent); outline-offset: 2px; }
+    `;
+const page = (app: NameSet, copy: ErrorCopy): string => `<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1">
+    <meta name="robots" content="noindex">
+    <meta name="theme-color" content="${PWA_COLORS.themeColor}">
+    <title>${copy.title} · ${titleCase(app.raw)}</title>
+    <style>${style()}</style>
+  </head>
+  <body>
+    <main>
+      <p class="status">${String(copy.status)}</p>
+      <h1>${copy.title}</h1>
+      <p>${copy.body}</p>
+      <a href="/">Back to ${titleCase(app.raw)}</a>
+    </main>
+  </body>
+</html>
+`;
+/** `apps/web/site/errors/404.html` and `500.html`, in status order. */
+export const errorPageFiles = (app: NameSet): readonly GeneratedFile[] =>
+  COPY.map((copy) => ({
+    path: `apps/web/site/errors/${String(copy.status)}.html`,
+    contents: page(app, copy),
+  }));

package/src/templates/scaffold-i18n.ts CHANGED Viewed

@@ -108,9 +108,55 @@ const i18nCatalog = (app: NameSet): string =>
   catalogJson({
     'site.home.title': app.pascal,
     'site.home.description': 'Everything you need, one command from shippable.',
+    'site.home.eyebrow': 'Built on Ultimate',
+    'site.home.headline': 'Ship the whole product, not a prototype.',
+    'site.home.lede':
+      'Typed routes, actions and queries, one authz system, budgets that fail the build, and a dark, designed shell — all from one command.',
     'site.home.cta': 'Open the dashboard',
+    'site.home.secondary': 'Open the admin',
+    'site.home.f1Title': 'One command to a running app',
+    'site.home.f1Body':
+      'bin/setup installs, migrates and seeds; bin/dev runs every role in one process.',
+    'site.home.f2Title': 'Policies, not flags',
+    'site.home.f2Body':
+      'Every route, action and query declares who may call it, and one system decides.',
+    'site.home.f3Title': 'Budgets that fail the build',
+    'site.home.f3Body':
+      'This page ships zero JavaScript, and the gate refuses the first byte over it.',
+    'shell.brand': app.pascal,
+    'shell.nav.dashboard': 'Dashboard',
+    'shell.nav.posts': 'Posts',
+    'shell.footer': 'Built with Ultimate',
     'app.dashboard.title': 'Dashboard',
     'app.dashboard.description': 'Your workspace.',
+    'app.dashboard.subtitle': 'What this app looks like from above.',
+    'app.dashboard.statTotal': 'Posts',
+    'app.dashboard.hintTotal': 'in the seeded org',
+    'app.dashboard.statWeek': 'Created this week',
+    'app.dashboard.hintVsPriorWeek': 'vs the week before',
+    'app.dashboard.statToday': 'Created today',
+    'app.dashboard.hintToday': 'so far, UTC',
+    'app.dashboard.chartTitle': 'Posts per day',
+    'app.dashboard.chartRange': 'Last 14 days, UTC',
+    'app.dashboard.chartLabel': 'Posts created per day over the last 14 days',
+    'app.dashboard.tableTitle': 'Latest posts',
+    'app.dashboard.tableCaption': 'The ten newest posts',
+    'app.dashboard.columnTitle': 'Title',
+    'app.dashboard.columnCreated': 'Created',
+    'app.dashboard.emptyTitle': 'No posts yet',
+    'app.dashboard.statRoutes': 'Routes',
+    'app.dashboard.hintRoutes': 'registered at boot',
+    'app.dashboard.statLocales': 'Locales',
+    'app.dashboard.hintLocales': 'in the catalog',
+    'app.dashboard.statRoles': 'Roles',
+    'app.dashboard.hintRoles': 'declared in shared/roles.ts',
+    'app.dashboard.statVersion': 'Ultimate',
+    'app.dashboard.hintVersion': 'framework version',
+    'app.dashboard.routesTitle': 'Route table',
+    'app.dashboard.routesCaption': 'Every route this app registers',
+    'app.dashboard.columnPath': 'Path',
+    'app.dashboard.columnSurface': 'Surface',
+    'app.dashboard.columnRender': 'Render',
     'app.offline.title': 'You are offline',
     'app.offline.description': 'This page will refresh itself when the connection returns.',
     'admin.home.title': 'Admin',

package/src/templates/scaffold-repo.ts CHANGED Viewed

@@ -14,6 +14,7 @@ import { dbPackageFiles } from './scaffold-db-package';
 import { docsFiles } from './scaffold-docs';
 import { domainPackageFiles } from './scaffold-domain-package';
 import { envExampleSource, envSchemaSource } from './scaffold-env';
+import { PWA_COLORS } from './scaffold-errors';
 import { scaffoldGuardFiles } from './scaffold-guards';
 import { i18nFiles } from './scaffold-i18n';
 import { mcpPackageFiles } from './scaffold-mcp-package';
@@ -213,10 +214,14 @@ export const config = defineConfig({
     offline: { fallback: '/offline' },
     name: '${titleCase(app.raw)}',
     colors: {
-      light: { themeColor: '#1b1f3b', backgroundColor: '#ffffff' },
-      dark: { themeColor: '#1b1f3b', backgroundColor: '#0b0d1a' },
+      light: { themeColor: '${PWA_COLORS.themeColor}', backgroundColor: '${PWA_COLORS.lightBackground}' },
+      dark: { themeColor: '${PWA_COLORS.themeColor}', backgroundColor: '${PWA_COLORS.darkBackground}' },
     },
   },
+  // The theme a first visit opens in; the framework inlines the no-flash boot script that reads
+  // it, and a choice stored by the theme toggle wins over it on every later visit; 'system' follows
+  // the OS.
+  theme: { defaultMode: 'dark' },
   ai: { mcp: { expose: true, path: '/mcp' } },
 });
 `;

package/src/templates/scaffold-shell.ts ADDED Viewed

@@ -0,0 +1,461 @@
+// The generated app's frame — `apps/web/shared/shell.tsx` over the catalog's `AppShell` — and the
+// one island the scaffold ships, the theme toggle. Split out of `scaffold-app.ts` because that file
+// is the three surfaces and this is the chrome every `app/` page sits inside. Before this the
+// dashboard was an `<h1>` in a panel and the scaffold imported nothing from `@ultimat3/ui`; an app
+// that starts from it now starts from a designed product, and deletes what it does not want.
+import { sortedImports } from './imports';
+import { upToAppRoot } from './island';
+import type { GeneratedFile, NameSet } from './naming';
+const SHELL_DIR = 'apps/web/shared';
+/** `nav` on the shell names the destinations; `--no-example` has no `/posts` to point at. */
+const navType = (example: boolean): string => (example ? "'dashboard' | 'posts'" : "'dashboard'");
+const postsItem = (example: boolean): string =>
+  example ? `\n            {item('posts', '/posts', t('shell.nav.posts'), iconList)}` : '';
+// Plain strings for the framework lines, never template literals: the workspace-dependency scanner
+// blanks a string's contents but not a nested template's, so a template here would bill the CLI
+// for the imports of the app it writes.
+const shell = (
+  app: NameSet,
+  example: boolean,
+): string => `// The app's frame: brand mark, the sidebar with one link per destination, an environment pill,
+// the page's own actions at the end of the bar, and a footer — composed over the catalog's
+// \`AppShell\`, so the skip link, the landmarks and the phone layout are the framework's and not
+// this file's. \`site/page.tsx\` does NOT use it: the landing page is a 0kb document and this is the
+// signed-in product's chrome. Every page under \`app/\` does.
+//
+// \`useT()\`, not \`t\` from @ultimat3/i18n — see apps/web/site/page.tsx for why.
+${sortedImports([
+  `import { useT } from '@${app.kebab}/i18n';`,
+  "import { tryResolveEnvironment } from '@ultimat3/core';",
+  "import { AppShell, Icon, type IconGlyph, Link } from '@ultimat3/ui';",
+  "import { iconHexagon } from '@ultimat3/ui/icons/hexagon';",
+  "import { iconLayoutDashboard } from '@ultimat3/ui/icons/layout-dashboard';",
+  ...(example ? ["import { iconList } from '@ultimat3/ui/icons/list';"] : []),
+  "import type { JSX } from 'solid-js';",
+])}
+import styles from './shell.module.scss';
+/** The routes the sidebar knows about. A page names itself so its link can carry aria-current. */
+export type ShellNav = ${navType(example)};
+export interface ShellProps {
+  readonly nav?: ShellNav | undefined;
+  /** Controls that belong to the page, rendered at the end of the header bar — a theme toggle. */
+  readonly actions?: JSX.Element | undefined;
+  readonly children: JSX.Element;
+}
+export function Shell(props: ShellProps): JSX.Element {
+  const t = useT();
+  // Where this build runs — a fact read from the process, never a translated word. Absent when
+  // neither ULTIMATE_ENV nor NODE_ENV names one, and the pill is absent with it.
+  const environment = tryResolveEnvironment();
+  const item = (id: ShellNav, href: string, label: string, glyph: IconGlyph): JSX.Element => (
+    <li>
+      <Link
+        class={styles.navLink}
+        href={href}
+        tone="inherit"
+        underline="none"
+        aria-current={props.nav === id ? 'page' : false}
+      >
+        <Icon glyph={glyph} size="sm" class={styles.navIcon} />
+        <span>{label}</span>
+      </Link>
+    </li>
+  );
+  return (
+    <div class={styles.doc}>
+      <AppShell
+        sidebarWidth="13.5rem"
+        stickyHeader
+        header={
+          <div class={styles.bar}>
+            <Link class={styles.brand} href="/" tone="inherit" underline="none">
+              {/* The mark: one accent tile, one glyph. Decorative — the wordmark beside it is the name. */}
+              <span class={styles.mark} aria-hidden="true">
+                <Icon glyph={iconHexagon} size="sm" />
+              </span>
+              <span class={styles.wordmark}>{t('shell.brand')}</span>
+            </Link>
+            <div class={styles.end}>
+              {environment === undefined ? null : (
+                <span class={styles.env}>
+                  {/* The pulse is a CSS opacity animation: alive without a byte of script. */}
+                  <span class={styles.envDot} aria-hidden="true" />
+                  {environment}
+                </span>
+              )}
+              {props.actions}
+            </div>
+          </div>
+        }
+        sidebar={
+          <ul class={styles.nav}>
+            {item('dashboard', '/dashboard', t('shell.nav.dashboard'), iconLayoutDashboard)}${postsItem(example)}
+          </ul>
+        }
+        footer={<span>{t('shell.footer')}</span>}
+      >
+        {props.children}
+      </AppShell>
+    </div>
+  );
+}
+`;
+const shellStyle = (): string => `@use '@ultimat3/ui/tokens' as tokens;
+// \`display: contents\` so the wrapper vanishes from the box tree: AppShell's own grid is the
+// layout, and this div exists only to scope the rules below.
+.doc {
+  display: contents;
+}
+.bar {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: tokens.space(4);
+  inline-size: 100%;
+}
+.end {
+  display: inline-flex;
+  align-items: center;
+  gap: tokens.space(3);
+}
+.brand {
+  display: inline-flex;
+  align-items: center;
+  gap: tokens.space(3);
+  color: tokens.role('fg-strong');
+  &:hover .mark {
+    background: tokens.role('accent', 0.22);
+  }
+}
+// One accent tile. The only saturated surface in the chrome, so the eye has exactly one anchor.
+.mark {
+  display: inline-grid;
+  place-items: center;
+  inline-size: tokens.space(8);
+  block-size: tokens.space(8);
+  border: 1px solid tokens.role('accent', 0.35);
+  border-radius: tokens.radius('md');
+  background: tokens.role('accent', 0.12);
+  color: tokens.role('accent');
+  transition: background-color tokens.duration('fast') tokens.easing('out');
+}
+.wordmark {
+  @include tokens.data-text;
+  font-size: tokens.text('sm');
+  font-weight: tokens.weight('medium');
+  letter-spacing: tokens.tracking('tight');
+}
+.env {
+  @include tokens.data-text;
+  display: inline-flex;
+  align-items: center;
+  gap: tokens.space(2);
+  padding: tokens.space(1) tokens.space(3);
+  border: 1px solid tokens.role('line', 0.7);
+  border-radius: tokens.radius('pill');
+  color: tokens.role('fg-muted');
+  font-size: tokens.text('xs');
+}
+.envDot {
+  inline-size: tokens.space(2);
+  block-size: tokens.space(2);
+  border-radius: tokens.radius('full');
+  background: tokens.role('success');
+  animation: pulse 2.4s tokens.easing('in-out') infinite;
+}
+// Opacity only — the one property family the motion guard admits, and the global reduced-motion
+// rule switches it off.
+@keyframes pulse {
+  50% {
+    opacity: 0.35;
+  }
+}
+.nav {
+  display: flex;
+  // A row on a phone — stacked links cost a fifth of the first screen — a rail from md up.
+  flex-direction: row;
+  gap: tokens.space(1);
+  margin: 0;
+  padding: 0;
+  overflow-x: auto;
+  list-style: none;
+  @include tokens.respond-to(md) {
+    flex-direction: column;
+  }
+}
+.navLink {
+  display: flex;
+  align-items: center;
+  gap: tokens.space(3);
+  padding: tokens.space(2) tokens.space(3);
+  border-radius: tokens.radius('md');
+  color: tokens.role('fg-muted');
+  font-size: tokens.text('sm');
+  transition:
+    color tokens.duration('fast') tokens.easing('out'),
+    background-color tokens.duration('fast') tokens.easing('out');
+  &:hover {
+    color: tokens.role('fg-strong');
+    background: tokens.role('surface');
+  }
+  &[aria-current='page'] {
+    color: tokens.role('fg-strong');
+    background: tokens.role('surface-raised');
+    box-shadow: inset 0 0 0 1px tokens.role('line', 0.7);
+    .navIcon {
+      color: tokens.role('accent');
+    }
+  }
+}
+.navIcon {
+  flex: none;
+  color: tokens.role('fg-muted');
+  transition: color tokens.duration('fast') tokens.easing('out');
+}
+`;
+const shellTest =
+  (): string => `// The frame, rendered the way a route renders it: through the framework's server JSX factory,
+// with the app's own catalog registered by the import. What can go wrong is structural — the
+// current page losing its \`aria-current\`, the page's actions landing outside the banner — and
+// both are invisible to a typecheck.
+import { h, type JsxComponent } from '@ultimat3/render';
+import { renderToHtml } from '@ultimat3/render/server';
+import { expect, unitTest } from '@ultimat3/testing';
+// A DYNAMIC import, after the static ones above have run: importing \`@ultimat3/render\` is what
+// installs the loader that compiles this app's \`.tsx\` to the framework's JSX factory, and a
+// plugin only reaches modules loaded after it. Imported statically, \`shell.tsx\` is transpiled
+// ahead of that install, to \`React.createElement\` against a global that does not exist — the
+// route modules never meet this because \`x dev\` loads them after the framework.
+//
+// \`h\` is typed for the framework's own components; \`Shell\` carries Solid's JSX types. The cast
+// is the seam itself — the assertions below are what check it at runtime.
+const shell = (await import('./shell')).Shell as unknown as JsxComponent;
+unitTest('the shell marks the current destination and keeps the page in <main>', async () => {
+  const html = await renderToHtml(
+    h(shell, { nav: 'dashboard', children: h('p', { 'data-role': 'page' }, 'body') }),
+  );
+  expect(html).toContain('aria-current="page"');
+  expect(html).toContain('href="/dashboard"');
+  // Landmarks come from AppShell: one banner, one navigation, one main, one contentinfo.
+  expect(html.match(/<main\\b/g)?.length).toBe(1);
+  expect(html.match(/<nav\\b/g)?.length).toBe(1);
+  expect(html).toMatch(/<main[^>]*>[\\s\\S]*data-role="page"[\\s\\S]*<\\/main>/);
+});
+unitTest('no nav marks nothing current, and the actions land in the header', async () => {
+  const html = await renderToHtml(
+    h(shell, {
+      actions: h('button', { type: 'button', 'data-role': 'action' }, 'act'),
+      children: h('p', null, 'body'),
+    }),
+  );
+  expect(html).not.toContain('aria-current="page"');
+  expect(html).toMatch(/<header[^>]*>[\\s\\S]*data-role="action"[\\s\\S]*<\\/header>/);
+});
+`;
+const toggleIsland =
+  (): string => `// The theme toggle, as the one island the scaffold ships: the only module of the dashboard a
+// browser downloads. Named by SPECIFIER from the page, never by import:
+//   const ThemeSwitch = island({ src: '../../shared/theme-toggle.island.tsx', props: ['locale'] });
+//
+// The control itself is the catalog's \`ThemeToggle\`; this file is the runtime it needs and the
+// one decision the framework cannot make for it — see \`bootedEnv\` below.
+import {
+  browserThemeEnv,
+  setSolidRuntime,
+  THEME_ATTRIBUTE,
+  type ThemeEnv,
+  ThemeToggle,
+  UiProvider,
+} from '@ultimat3/ui';
+import {
+  createContext,
+  createEffect,
+  createMemo,
+  createSignal,
+  onCleanup,
+  useContext,
+} from 'solid-js';
+import { render } from 'solid-js/web';
+export interface ThemeToggleIslandProps {
+  /** The request's own locale, for the control's labels. A browser has no ambient one. */
+  readonly locale: string;
+}
+/**
+ * With no stored choice the catalog's \`resolveTheme\` asks the OS — but the document already wears
+ * the theme the framework's boot script stamped from \`theme.defaultMode\` (dark, in this app), so
+ * a toggle that asked the OS would show one theme while the page wore another. The boot's verdict
+ * is on \`<html>\` before this runs: read it once, and let a stored choice win as it does there.
+ */
+export const bootedEnv = (): ThemeEnv => {
+  const booted = document.documentElement.getAttribute(THEME_ATTRIBUTE) === 'dark';
+  return { ...browserThemeEnv(), prefersDark: () => booted };
+};
+/**
+ * The one export the hydration runtime calls. \`setSolidRuntime\` comes FIRST and is not optional:
+ * \`@ultimat3/ui\` imports types from solid-js and never a runtime, so the reactive graph a
+ * component reaches is the one an entry registers. Six NAMED imports, never a namespace: a
+ * namespace object keeps every export of solid-js alive in the chunk. The shell is cleared before
+ * \`render\`, which APPENDS — the server's copy would otherwise stay on screen beside the live one.
+ */
+export function mount(el: HTMLElement, props: ThemeToggleIslandProps): void {
+  setSolidRuntime({ createContext, useContext, createSignal, createMemo, createEffect, onCleanup });
+  const env = bootedEnv();
+  el.textContent = '';
+  render(
+    () => (
+      <UiProvider locale={props.locale}>
+        <ThemeToggle mode="toggle" env={env} />
+      </UiProvider>
+    ),
+    el,
+  );
+}
+`;
+const toggleStates =
+  (): string => `// The states the theme toggle can be photographed in. \`x shot --island theme-toggle --json\`
+// takes one picture per state per theme into \`.x/shot/island/theme-toggle/\`. PURE DATA: no JSX,
+// and the one import is \`import type\` — the command has to know the list before a browser exists.
+import { defineIslandStates } from '@ultimat3/testing';
+import type { ThemeToggleIslandProps } from './theme-toggle.island';
+export const themeToggleStates = defineIslandStates({
+  island: '${SHELL_DIR}/theme-toggle.island.tsx',
+  states: [
+    {
+      id: 'default',
+      title: 'the toggle as the dashboard header renders it',
+      props: { locale: 'en' } satisfies ThemeToggleIslandProps,
+    },
+  ],
+});
+`;
+const toggleTest =
+  (): string => `// The toggle the browser actually runs: built with the same \`buildIslands\` as \`x build\`, mounted
+// against a DOM small enough to read, and clicked. What it pins is the one decision this island
+// makes — the boot's verdict on \`<html>\` is what the control starts from, and a click writes the
+// key the boot script reads back on the next load.
+import { join } from 'node:path';
+import { buildIslands } from '@ultimat3/cli';
+import {
+  afterAll,
+  beforeAll,
+  describe,
+  expect,
+  type MountedIsland,
+  mountIsland,
+  test,
+} from '@ultimat3/testing';
+import { THEME_ATTRIBUTE, THEME_STORAGE_KEY } from '@ultimat3/ui';
+import { bootedEnv } from './theme-toggle.island';
+const APP_ROOT = join(import.meta.dir, ${upToAppRoot(SHELL_DIR)});
+const ISLAND = '${SHELL_DIR}/theme-toggle.island.tsx';
+/** What the island reads through \`browserThemeEnv\`: storage and the OS query, both fakes. */
+const stored = new Map<string, string>();
+const localStorage = {
+  getItem: (key: string): string | null => stored.get(key) ?? null,
+  setItem: (key: string, value: string): void => void stored.set(key, value),
+  removeItem: (key: string): void => void stored.delete(key),
+};
+const matchMedia = (): Record<string, unknown> => ({
+  matches: false,
+  addEventListener: () => {},
+  removeEventListener: () => {},
+});
+let mounted: MountedIsland;
+beforeAll(async () => {
+  mounted = await mountIsland({
+    build: buildIslands,
+    root: APP_ROOT,
+    file: ISLAND,
+    props: { locale: 'en' },
+    shell: '<button type="button">theme</button>',
+    globals: { localStorage, matchMedia },
+  });
+}, 60_000);
+afterAll(() => {
+  mounted?.[Symbol.dispose]();
+});
+describe('the theme toggle island', () => {
+  test('mount renders the catalog control over the server shell', () => {
+    expect(mounted.find('button')).not.toBeNull();
+    expect(mounted.code).not.toMatch(/\\bReact\\b/);
+  });
+  test('a click stores the opposite theme and applies it to <html>', () => {
+    // No stamp on this document, so the island booted light; the click flips it. \`false\` means
+    // no handler ran — an onClick that never reached the DOM looks identical to a selector typo.
+    expect(mounted.fire('button', 'click')).toBe(true);
+    expect(stored.get(THEME_STORAGE_KEY)).toBe('dark');
+    expect(mounted.documentElement.getAttribute(THEME_ATTRIBUTE)).toBe('dark');
+  });
+  test('the env the island builds starts from the theme stamped on <html>', () => {
+    // The fake document is still installed here, so this reads exactly what \`mount\` read.
+    mounted.documentElement.setAttribute(THEME_ATTRIBUTE, 'dark');
+    expect(bootedEnv().prefersDark()).toBe(true);
+    mounted.documentElement.setAttribute(THEME_ATTRIBUTE, 'light');
+    expect(bootedEnv().prefersDark()).toBe(false);
+  });
+});
+`;
+/** The frame and the toggle island, with the states file the gate requires beside every island. */
+export function shellFiles(app: NameSet, example: boolean): readonly GeneratedFile[] {
+  return [
+    { path: `${SHELL_DIR}/shell.tsx`, contents: shell(app, example) },
+    { path: `${SHELL_DIR}/shell.module.scss`, contents: shellStyle() },
+    { path: `${SHELL_DIR}/shell.test.ts`, contents: shellTest() },
+    { path: `${SHELL_DIR}/theme-toggle.island.tsx`, contents: toggleIsland() },
+    { path: `${SHELL_DIR}/theme-toggle.island.states.ts`, contents: toggleStates() },
+    { path: `${SHELL_DIR}/theme-toggle.island.test.ts`, contents: toggleTest() },
+  ];
+}