@ultimat3/cli 22.14.0 → 23.0.0

package/src/templates/scaffold-docs.ts

@@ -22,14 +22,23 @@ not exist — five of these had an empty column and were each measured green on
 | Rule | Detail | Refused by |
 |---|---|---|
 | One gate | \`bin/check\` — \`x build\` and then \`x verify\`. Green means shippable; never merge red. | the gate itself, and \`.github/workflows/ci.yml\` on every push and pull request |
+| Coverage | the unit suite covers 95% of the lines and functions of this app's own source — every file under \`apps/\` and \`packages/\`, one no test loads counted at 0%. A floor, not the goal: a test added to raise it is proven by mutation — break the source, watch it go red, restore | \`X_COVERAGE_BELOW_FLOOR\` on the \`unit\` step; \`coverage\` in \`x.verify.json\` states the floor, and it only rises |
 | One way | generators, not hand-rolled files: \`x g resource\`, \`x g action\`, \`x g route\` | review |
 | Surfaces | \`site/\` is 0kb JS and may not import \`app/\`; \`shared/\` is a leaf | \`X_BOUNDARY_SITE_TO_APP\` |
 | Data | routes call actions and queries; only \`repo.ts\` touches the database | \`X_BOUNDARY_ROUTE_TO_DB\` |
+| Repos | a \`repo.ts\` reads through the typed handle, never a \`sql\` literal the handle can express | \`guards/repo-raw-sql.ts\` |
 | Errors | never \`throw new Error\` — subclass \`UltimateError\` with a code, a cause and a fix | \`guards/bare-error.ts\` |
 | Money | \`{ minor, currency }\`, never a float — \`money()\` on the column | the type: \`price: 19.99\` is TS2322, \`number\` is not \`MoneyInput\` |
 | Time | store UTC, format with an explicit IANA time zone | \`guards/unzoned-date.ts\` |
 | Strings | every user-facing string goes through \`t()\` | \`guards/untranslated-string.ts\` |
 | Colour | semantic tokens only, never a raw hex | \`guards/raw-colour.ts\` |
+| Lengths | a length is a token or \`rem()\`, never a raw \`px\` | \`guards/raw-length.ts\` |
+| Breakpoints | a viewport query names a breakpoint rung (\`respond-up\`, \`respond-down\`, \`respond-between\`), never a width | \`guards/raw-breakpoint.ts\` |
+| Layers | a \`z-index\` is a named layer, never a number | \`guards/raw-z-index.ts\` |
+| Shadows | a shadow comes off the shadow scale, never a hand-written offset and blur | \`guards/raw-shadow.ts\` |
+| Timing | a duration and an easing curve come off the motion scale, never a literal | \`guards/raw-motion.ts\` |
+| Classes | a class a component reads off its stylesheet is one that sheet compiles | \`guards/undefined-style-class.ts\` |
+| Properties | a custom property a stylesheet reads is one the app declares | \`guards/undeclared-custom-property.ts\` |
 | Interaction | a click is answered by a control — never a \`<div onClick>\`, and never a \`role=\` where the native tag exists | \`guards/semantic-interactive.ts\` |
 | Focus | \`outline: none\` replaces the ring in the same rule or the one beside it, or it does not remove it | \`guards/focus-visible.ts\` |
 | Images | every image carries width + height or an aspect-ratio, and the priority one is never \`loading="lazy"\` | \`guards/image-dimensions.ts\` |
@@ -51,6 +60,23 @@ unit of review, and \`x verify\` refuses it. The one exemption is a file that is
 it has one job by construction, and its length tracks the API's size rather than its complexity;
 one statement of logic in such a file re-arms the ceiling on the same save.
 
+Coverage counts execution, not validation: 100% is reachable with zero assertions, and a covered
+branch whose test cannot fail is worse than an uncovered one, because it reads as done. An
+\`exclude\` entry under \`coverage\` is for code a unit test cannot execute — an island's
+browser-only mount, a container entry point — carries its \`why\`, and is printed by \`x doctor\`.
+
+Every test the scaffold and the generators write is the idiom to copy. All of them run on the
+\`unit\` step — in process, on the in-memory driver, with no database, browser or server:
+
+| What | How its test runs it | Copy from |
+|---|---|---|
+| a page | \`renderRoute(page, { url, actor })\` — \`load\`, \`meta\` and the page on one resolution; assert on \`view.text\`, \`view.html\`, \`view.meta\`, \`view.islands\` | \`apps/web/app/dashboard/page.test.ts\` |
+| a component | \`renderView(Component, props)\` | \`apps/web/shared/shell.test.ts\` |
+| an island | \`mountIsland\`, once per state its \`*.island.states.ts\` declares | \`apps/web/shared/theme-toggle.island.test.ts\` |
+| an action or a query | \`target.as(actor, input)\` — the refusal first, then what it answers | \`apps/web/api/health.test.ts\` |
+| a job, a task, a backfill | \`test('…', async ({ runJobs }) => …)\` — a worker in this process; assert on \`trace.steps\` and each run's \`outcome\` | what \`x g job\` writes |
+| a repo, a seed | as an actor, \`runWithContext(createContext({ actor }), …)\`, with \`driver.reset?.()\` after each | \`packages/db/src/seed.test.ts\` |
+
 Money is the one row with no guard, deliberately: a float has no static signature a text rule can
 see, and the type already fires — measured, \`price: 19.99\` in a seed is
 \`TS2322: Type 'number' is not assignable to type 'MoneyInput'\`. A guard that pretended to check
@@ -86,6 +112,9 @@ ${app.kebab} — Ultimate app. Read AGENTS.md first; it is the same content in t
 - Scaffold, do not hand-write: \`x g <kind> <name>\` — \`x g --help\` lists every kind, and is the
   only place that list is stated.
 - Destructive DB work goes in a branch: \`x db branch create <name>\`, never the shared dev DB.
+- \`x db gen\` also writes \`packages/db/schema/\` — the whole schema as SQL, one file per table.
+  Read it; never edit it. \`x verify\` fails with \`X_SCHEMA_DUMP_DRIFT\` when it is not what the
+  migrations produce, and \`x db gen\` rewrites it.
 - \`x doctor\` explains a broken environment and prints the fix command for every finding.
 
 \`.claude/\` holds the harness that reads this file: \`/feature\`, \`/planx\`, \`/verify\` and four
@@ -182,7 +211,12 @@ exec bunx x verify "$@"
 
 const composeDev = (
   app: NameSet,
-): string => `# Optional: x dev needs none of this. Use it when you want the real Postgres/NATS/MinIO locally.
+): string => `# Optional: x dev needs none of this. Use it when you want a real Postgres, NATS and S3 locally:
+#
+#   docker compose -f docker/docker-compose.dev.yml up -d
+#   DATABASE_URL=postgres://postgres:${app.kebab}@127.0.0.1:5432/${app.kebab} NATS_URL=nats://127.0.0.1:4222 \\
+#   S3_ENDPOINT=http://127.0.0.1:9000 S3_BUCKET=${app.kebab} S3_FORCE_PATH_STYLE=1 \\
+#   S3_ACCESS_KEY_ID=${app.kebab} S3_SECRET_ACCESS_KEY=${app.kebab}-dev x dev
 #
 # Every published port binds 127.0.0.1, not 0.0.0.0. This stack ships its credentials in the file,
 # as a dev stack reasonably does — so the short form \`'5432:5432'\` would put an authenticated
@@ -204,13 +238,24 @@ services:
     image: nats:2-alpine
     command: ['-js']
     ports: ['127.0.0.1:4222:4222']
+  # Versity S3 Gateway over a directory: a directory under /data is a bucket, so the volume mounted
+  # at /data/${app.kebab} IS the bucket — ready on the first \`up\`, no CreateBucket call. It checks
+  # the region a request was signed for, and an app that sets no S3_REGION signs for \`auto\` — so
+  # that is this gateway's region. A server for a laptop; production is any S3-compatible endpoint.
   s3:
-    image: minio/minio
-    command: ['server', '/data']
+    image: versity/versitygw:v1.8.0
     environment:
-      MINIO_ROOT_USER: ${app.kebab}
-      MINIO_ROOT_PASSWORD: ${app.kebab}-dev
+      VGW_BACKEND: posix
+      VGW_BACKEND_ARG: /data
+      VGW_PORT: ':9000'
+      VGW_REGION: auto
+      ROOT_ACCESS_KEY: ${app.kebab}
+      ROOT_SECRET_KEY: ${app.kebab}-dev
     ports: ['127.0.0.1:9000:9000']
+    volumes: ['s3bucket:/data/${app.kebab}']
+
+volumes:
+  s3bucket:
 `;
 
 /** Docs, shims and container files for a new app, in the order a reader meets them. */

package/src/templates/scaffold-guards.ts

@@ -11,31 +11,74 @@
 // about: a control a keyboard cannot reach, a focus ring taken away and not replaced, an image with
 // no box, an animation the compositor cannot run, and an island nobody has seen fail. Each is
 // statically decidable from the file alone — the reason those five and not the many that are not.
+//
+// The seven after those are about the STYLESHEET, which Biome does not read at all: a length, a
+// breakpoint, a layer, a shadow and a tempo off their scales, a class the sheet never compiled and
+// a custom property nothing declares. Until they shipped, raw colour was the only one of the
+// design system's rules a scaffolded app's gate held.
+//
+// And one is about DATA: a `repo.ts` reads through the typed handle. It ships because the generator
+// used to emit string SQL, and every app that started from it copied the shape.
 
 import { animatedLayoutPropertyGuardFiles } from './guard-animated-layout-property';
 import { bareErrorGuardFiles } from './guard-bare-error';
 import { focusVisibleGuardFiles } from './guard-focus-visible';
 import { imageDimensionsGuardFiles } from './guard-image-dimensions';
 import { islandWithoutStatesGuardFiles } from './guard-island-without-states';
+import { rawBreakpointGuardFiles } from './guard-raw-breakpoint';
 import { rawColourGuardFiles } from './guard-raw-colour';
+import { rawLengthGuardFiles } from './guard-raw-length';
+import { rawMotionGuardFiles } from './guard-raw-motion';
+import { rawShadowGuardFiles } from './guard-raw-shadow';
+import { rawZIndexGuardFiles } from './guard-raw-z-index';
+import { repoRawSqlGuardFiles } from './guard-repo-raw-sql';
 import { semanticInteractiveGuardFiles } from './guard-semantic-interactive';
+import { undeclaredCustomPropertyGuardFiles } from './guard-undeclared-custom-property';
+import { undefinedStyleClassGuardFiles } from './guard-undefined-style-class';
 import { untranslatedStringGuardFiles } from './guard-untranslated-string';
 import { unzonedDateGuardFiles } from './guard-unzoned-date';
 import type { GeneratedFile } from './naming';
 
+/**
+ * Every guard the framework ships, by the name its file carries — the ONE list. `x new` writes all
+ * of them (`scaffoldGuardFiles`), `x g guard <name>` writes the one it is asked for by name
+ * (`shippedGuardFiles`), and `x doctor` names the ones an app does not have. Sorted, so the three
+ * agree on an order. A new shipped guard is one module beside these and one row here.
+ */
+const SHIPPED: readonly (readonly [string, () => readonly GeneratedFile[]])[] = [
+  ['animated-layout-property', animatedLayoutPropertyGuardFiles],
+  ['bare-error', bareErrorGuardFiles],
+  ['focus-visible', focusVisibleGuardFiles],
+  ['image-dimensions', imageDimensionsGuardFiles],
+  ['island-without-states', islandWithoutStatesGuardFiles],
+  ['raw-breakpoint', rawBreakpointGuardFiles],
+  ['raw-colour', rawColourGuardFiles],
+  ['raw-length', rawLengthGuardFiles],
+  ['raw-motion', rawMotionGuardFiles],
+  ['raw-shadow', rawShadowGuardFiles],
+  ['raw-z-index', rawZIndexGuardFiles],
+  ['repo-raw-sql', repoRawSqlGuardFiles],
+  ['semantic-interactive', semanticInteractiveGuardFiles],
+  ['undeclared-custom-property', undeclaredCustomPropertyGuardFiles],
+  ['undefined-style-class', undefinedStyleClassGuardFiles],
+  ['untranslated-string', untranslatedStringGuardFiles],
+  ['unzoned-date', unzonedDateGuardFiles],
+];
+
+/** The names, in the order every list of them is shown. */
+export const SHIPPED_GUARD_NAMES: readonly string[] = SHIPPED.map(([name]) => name);
+
+/**
+ * The shipped guard of that name with its test, or `undefined` when the name is not one — which
+ * is an app's own convention, and `x g guard` then writes the blank template instead.
+ */
+export const shippedGuardFiles = (name: string): readonly GeneratedFile[] | undefined =>
+  SHIPPED.find(([shipped]) => shipped === name)?.[1]();
+
 /**
  * Every guard `x new` ships, each with its test. One module per guard, because an app deletes a
  * rule it does not want by deleting one file — and a guard the app then writes for itself is
  * `x g guard <name>`, the same shape.
  */
-export const scaffoldGuardFiles = (): readonly GeneratedFile[] => [
-  ...animatedLayoutPropertyGuardFiles(),
-  ...bareErrorGuardFiles(),
-  ...focusVisibleGuardFiles(),
-  ...imageDimensionsGuardFiles(),
-  ...islandWithoutStatesGuardFiles(),
-  ...rawColourGuardFiles(),
-  ...semanticInteractiveGuardFiles(),
-  ...untranslatedStringGuardFiles(),
-  ...unzonedDateGuardFiles(),
-];
+export const scaffoldGuardFiles = (): readonly GeneratedFile[] =>
+  SHIPPED.flatMap(([, files]) => files());

package/src/templates/scaffold-http.ts

@@ -49,27 +49,29 @@ const httpConfigTest =
 // only thing that can go wrong is nobody importing the module — which is exactly how a shipped app
 // rendered every string as ⟦key⟧ for a whole release (issue #249), one seam along.
 import { configuredHttp, resetHttpConfig } from '@ultimat3/http';
-import { expect, unitTest } from '@ultimat3/testing';
+import { afterAll, expect, unitTest } from '@ultimat3/testing';
 import './http';
 
+// Read ONCE, at module scope: every case asserts on what the import registered, in any order.
+const declared = configuredHttp();
+
 unitTest('importing the module IS the registration', () => {
-  const declared = configuredHttp();
-  expect(declared).toBeDefined();
   // The list is empty on a fresh scaffold and that is the shipped default; what is asserted is
   // that the KEY reaches the boot, so adding an origin to it takes effect.
   expect(declared?.cors?.origins).toEqual([]);
 });
 
 unitTest('the boot-owned keys are absent — the boot measures them, an app can only guess', () => {
-  const declared = configuredHttp() ?? {};
+  expect(declared).toBeDefined();
   for (const key of ['port', 'hostname', 'dev', 'buildId', 'signInPath']) {
-    expect({ key, declared: Object.hasOwn(declared, key) }).toEqual({ key, declared: false });
+    expect({ key, declared: Object.hasOwn(declared ?? {}, key) }).toEqual({ key, declared: false });
   }
 });
 
 // The registration is process-global, so a suite that left it set would hand the next file this
-// app's config. \`resetHttpConfig()\` is the seam; this is the one place it is called.
-unitTest('and it is resettable, so no test file inherits the server config of another', () => {
+// app's config. \`resetHttpConfig()\` is the seam, and this is the one place it is called — after
+// the cases, so none of them depends on running before it.
+afterAll(() => {
   resetHttpConfig();
   expect(configuredHttp()).toBeUndefined();
 });

package/src/templates/scaffold-repo.ts

@@ -6,6 +6,8 @@
 
 import { ENV_EXAMPLE_PATH } from '@ultimat3/core';
 import { REQUIRED_BUN } from '../app-root';
+import type { CoverageExclude } from '../coverage-floor';
+import { COVERAGE_BAR } from '../coverage-floor';
 import { VERIFY_FLOOR_FILE } from '../verify-floor';
 import type { VerifyStepName } from '../verify-step';
 import type { GeneratedFile, NameSet } from './naming';
@@ -187,7 +189,7 @@ const appConfig = (
 // a missing value fails the boot with the exact command that fixes it, never at the first request.
 // A named export, never a default: the CLI and the runtime both import \`config\` by name.
 import type { EnvSchema } from '@ultimat3/core';
-import { defineConfig, defineEnv } from '@ultimat3/core';
+import { defineConfig, defineEnv, defineMeasurementActor, userActor } from '@ultimat3/core';
 
 ${envDeclaration()}
 
@@ -227,6 +229,18 @@ export const config = defineConfig({
   theme: { defaultMode: 'dark' },
   ai: { mcp: { expose: true, path: '/mcp' } },
 });
+
+/**
+ * Who \`x build\`'s budget pass renders \`app/\` as. A page that reads rows reads its actor's org
+ * through the typed handle, which refuses an actor with none (X_TENANCY_ACTOR_ORG_REQUIRED) — and
+ * the framework's default measurement actor is a \`service\` with no org, so such a route is never
+ * weighed (X_BUDGET_UNMEASURED). A member of the demo org is a declared viewer: no row has to
+ * exist. Loaded lazily, so this file's import graph stays the config's own.
+ */
+defineMeasurementActor(async () => {
+  const { DEMO_ORG_ID } = await import('./apps/web/shared/demo-org');
+  return userActor({ id: 'x-build-measure', orgId: DEMO_ORG_ID, roles: ['member'] });
+});
 `;
 
 // `biome.json` is strict JSON — Biome's own parser rejects a `//` comment in it, which made every
@@ -330,8 +344,44 @@ const SCAFFOLD_FLOOR: readonly VerifyStepName[] = [
 /** The two suites only the example slice writes a file for — a floor step with no file is red. */
 const EXAMPLE_FLOOR: readonly VerifyStepName[] = ['live', 'job'];
 
+/**
+ * What a unit test cannot execute in a scaffolded app, each with its reason — `x doctor` prints
+ * them. Two kinds and no more: a file here is a file the floor does not see, so the list is not
+ * a place to put code that merely has no test yet.
+ */
+export const SCAFFOLD_COVERAGE_EXCLUDE: readonly CoverageExclude[] = [
+  {
+    glob: 'apps/**/*.island.tsx',
+    why: 'an island runs in a browser: its test mounts a BUILT chunk (mountIsland), and Bun cannot map that chunk back to this source — its states are held by guards/island-without-states.ts and photographed by x shot --island',
+  },
+  {
+    glob: 'apps/*/server.ts',
+    why: 'the container entry point: it boots the roles and lives as long as the process — bin/dev and the image exercise it',
+  },
+  {
+    glob: 'apps/*/prerender.ts',
+    why: "the static build's entry point: x build --target static runs it, and the budgets step weighs what it writes",
+  },
+];
+
+/**
+ * The coverage floor every scaffolded app starts on: the bar the framework holds its own packages
+ * to (`COVERAGE_BAR`), not a softer one for apps. `scaffold-smoke` runs the app's own `x verify`,
+ * so the scaffold is green at it on what it generates or the job is red.
+ */
 const verifyFloor = (example: boolean): string =>
-  `${JSON.stringify({ steps: example ? [...SCAFFOLD_FLOOR, ...EXAMPLE_FLOOR] : SCAFFOLD_FLOOR }, null, 2)}\n`;
+  `${JSON.stringify(
+    {
+      steps: example ? [...SCAFFOLD_FLOOR, ...EXAMPLE_FLOOR] : SCAFFOLD_FLOOR,
+      coverage: {
+        lines: COVERAGE_BAR,
+        funcs: COVERAGE_BAR,
+        exclude: SCAFFOLD_COVERAGE_EXCLUDE,
+      },
+    },
+    null,
+    2,
+  )}\n`;
 
 const bunfig = (): string => `[test]
 root = "."

package/src/templates/scaffold-roles.ts

@@ -6,18 +6,34 @@
 import type { GeneratedFile } from './naming';
 import { wrapList } from './wrap';
 
-/**
- * A role's grants as Biome prints them. The example slice's \`post:read\`/\`post:write\` ride along
- * with it: \`x g resource post\` would have granted them, and the scaffold writes that result.
- */
-const grants = (base: string, example: string | undefined): string =>
+/** A role's grants as Biome prints them: one line when it fits, one grant per line when not. */
+const grants = (list: readonly string[]): string =>
   wrapList(
     '    ',
     'grants: [',
-    [base, ...(example === undefined ? [] : [example])].map((grant) => `'${grant}'`),
+    list.map((grant) => `'${grant}'`),
     '],',
   );
 
+/** The three gates `@ultimat3/admin` asks before any per-table one — `ADMIN_OPERATION_RULES`. */
+const ADMIN_GATES = ['admin:read', 'admin:write', 'admin:destroy'] as const;
+
+/**
+ * What the two built-in screens with no table behind them ask beside `admin:read`: `/admin/jobs`
+ * and `/admin/audit`. Held by the role that runs the admin, or both links are a 403.
+ */
+const ADMIN_SCREENS = ['job:read', 'audit:read'] as const;
+
+/**
+ * What the admin asks for one table on the handle: `<table>:read|write|delete`. The example slice
+ * adds `posts`, so the scaffold writes the grants `x g resource post` would have — the same three
+ * `generate-grants.ts` adds for every entity generated later.
+ */
+const tableGrants = (table: string): readonly string[] =>
+  ['read', 'write', 'delete'].map((verb) => `${table}:${verb}`);
+
+const EXAMPLE_TABLE = 'posts';
+
 const rolesSource = (
   example: boolean,
 ): string => `// Who holds which permission, for the whole app. Roles are sugar: every one expands to a flat
@@ -33,6 +49,12 @@ const rolesSource = (
 // \`x g policy <feature>\` declares \`<feature>:read\` and \`<feature>:write\` and grants them below —
 // read to member, write to admin. A permission no role holds is one no actor can ever exercise,
 // and \`x verify\`'s policy step refuses it (X_PERMISSION_UNGRANTED).
+//
+// The admin at /admin asks TWO permissions per operation: its own gate (\`admin:read\` to look,
+// \`admin:write\` to create or edit, \`admin:destroy\` to delete) and the table's
+// (\`<table>:read|write|delete\`); its jobs and audit screens ask \`job:read\` and \`audit:read\`. \`x g entity\` and \`x g resource\` declare and grant a new table's
+// three to \`admin\` here. A view-only operator is a role holding \`admin:read\` and each
+// \`<table>:read\` and nothing else: every write is refused by the same decision that hid its button.
 
 import { definePermissions, defineRoles } from '@ultimat3/policy';
 
@@ -42,16 +64,30 @@ import { definePermissions, defineRoles } from '@ultimat3/policy';
 // in silence while nothing declared it, so every scaffolded app answered HTTP 500 on /dashboard
 // and /admin from its first \`x dev\`, under a green gate. A permission a role grants and a
 // permission a route requires both belong here.
-export const appPermissions = definePermissions(['admin:read', 'dashboard:read']);
+${wrapList(
+  '',
+  'export const appPermissions = definePermissions([',
+  [
+    ...ADMIN_GATES,
+    ...ADMIN_SCREENS,
+    'dashboard:read',
+    ...(example ? tableGrants(EXAMPLE_TABLE) : []),
+  ].map((permission) => `'${permission}'`),
+  ']);',
+)}
 
 export const roles = defineRoles({
   member: {
     description: 'Signed in. Reads the app surface.',
-${grants('dashboard:read', example ? 'post:read' : undefined)}
+${grants(['dashboard:read', ...(example ? ['post:read'] : [])])}
   },
   admin: {
     description: 'Runs the app: the /admin surface, plus everything a member may do.',
-${grants('admin:read', example ? 'post:write' : undefined)}
+${grants([
+  ...ADMIN_GATES,
+  ...ADMIN_SCREENS,
+  ...(example ? ['post:write', ...tableGrants(EXAMPLE_TABLE)] : []),
+])}
     inherits: ['member'],
   },
 });
@@ -85,6 +121,17 @@ unitTest('admin inherits every member grant and adds its own', () => {
   for (const permission of member) expect(admin).toContain(permission);
 });
 
+// \`admin:read\` alone looks; a write needs \`admin:write\` and a delete \`admin:destroy\`. The admin
+// role holds all three, and a member none — so "view-only" is a role, never a mode.
+unitTest('the admin role holds all three admin gates, and a member none of them', () => {
+  const admin = expandRoles(['admin'], roles);
+  const member = expandRoles(['member'], roles);
+  for (const gate of ['admin:read', 'admin:write', 'admin:destroy']) {
+    expect(admin).toContain(gate);
+    expect(member).not.toContain(gate);
+  }
+});
+
 unitTest('a role nobody declared grants nothing', () => {
   expect(expandRoles(['visitor'], roles)).toEqual([]);
 });

package/src/templates/scaffold-shell.ts

@@ -183,7 +183,7 @@ const shellStyle = (): string => `@use '@ultimat3/ui/tokens' as tokens;
   block-size: tokens.space(2);
   border-radius: tokens.radius('full');
   background: tokens.role('success');
-  animation: pulse 2.4s tokens.easing('in-out') infinite;
+  animation: pulse calc(#{tokens.duration('slower')} * 4) tokens.easing('in-out') infinite;
 }
 
 // Opacity only — the one property family the motion guard admits, and the global reduced-motion
@@ -245,45 +245,25 @@ const shellStyle = (): string => `@use '@ultimat3/ui/tokens' as tokens;
 `;
 
 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;
+  (): string => `// The frame, rendered the way a route renders it, 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 { expect, renderView, unitTest } from '@ultimat3/testing';
+import { Shell } from './shell';
 
 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"');
+  const view = await renderView(Shell, { nav: 'dashboard', children: 'the page body' });
+  expect(view.html).toMatch(/<a href="\\/dashboard" aria-current="page"/);
   // 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>/);
+  expect(view.html.match(/<main\\b/g)).toHaveLength(1);
+  expect(view.html.match(/<nav\\b/g)).toHaveLength(1);
+  expect(view.html).toMatch(/<main[^>]*>the page body<\\/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 view = await renderView(Shell, { actions: 'the page actions', children: 'body' });
+  expect(view.html).not.toContain('aria-current="page"');
+  expect(view.html).toMatch(/<header[^>]*>[\\s\\S]*the page actions[\\s\\S]*<\\/header>/);
 });
 `;
 
@@ -379,20 +359,10 @@ const toggleTest =
 
 import { join } from 'node:path';
 import { buildIslands } from '@ultimat3/cli';
-import {
-  afterAll,
-  beforeAll,
-  describe,
-  expect,
-  type MountedIsland,
-  mountIsland,
-  test,
-} from '@ultimat3/testing';
+import { describeIslandState, expect, 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';
+import { themeToggleStates } from './theme-toggle.island.states';
 
 /** What the island reads through \`browserThemeEnv\`: storage and the OS query, both fakes. */
 const stored = new Map<string, string>();
@@ -407,42 +377,38 @@ const matchMedia = (): Record<string, unknown> => ({
   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]();
-});
+// The state \`x shot --island theme-toggle\` photographs is the state this mounts: one manifest,
+// so the picture and the assertion cannot be of two different components.
+const island = {
+  build: buildIslands,
+  root: join(import.meta.dir, ${upToAppRoot(SHELL_DIR)}),
+  shell: '<button type="button">theme</button>',
+  globals: { localStorage, matchMedia },
+};
 
-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/);
+describeIslandState(themeToggleStates, 'default', island, (mounted) => {
+  test('the default state renders the catalog control over the server shell', () => {
+    // \`aria-pressed\` is the live control's: the shell's own button carries none, so a mount that
+    // rendered nothing leaves this selector with no match.
+    expect(mounted().find('button[aria-pressed]')).not.toBeNull();
+    expect(mounted().code).not.toMatch(/\\bReact\\b/);
+    // The state's own prop reached the island: the provider stamps the locale it was handed.
+    expect(mounted().documentElement.getAttribute('lang')).toBe('en');
   });
 
   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(mounted().fire('button', 'click')).toBe(true);
     expect(stored.get(THEME_STORAGE_KEY)).toBe('dark');
-    expect(mounted.documentElement.getAttribute(THEME_ATTRIBUTE)).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');
+    mounted().documentElement.setAttribute(THEME_ATTRIBUTE, 'dark');
     expect(bootedEnv().prefersDark()).toBe(true);
-    mounted.documentElement.setAttribute(THEME_ATTRIBUTE, 'light');
+    mounted().documentElement.setAttribute(THEME_ATTRIBUTE, 'light');
     expect(bootedEnv().prefersDark()).toBe(false);
   });
 });