@ultimat3/cli 22.15.0 → 24.0.0

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';
@@ -39,6 +41,14 @@ const BIOME_VERSION = '2.5.8';
  */
 const TYPESCRIPT_VERSION = '^7.0.2';
 
+/**
+ * The Solid runtime every island and `@ultimat3/ui` component renders with, exact for the reason
+ * `BIOME_VERSION` is: the CLI compiles islands with `babel-preset-solid ^1.9.15`, and a scaffold
+ * that installed an older runtime than the compiler targets drifted as a buried literal (1.9.14
+ * beside the repository's 1.9.15). `scaffold-repo.test.ts` holds it equal to the root manifest's.
+ */
+const SOLID_VERSION = '1.9.15';
+
 // `engines.bun` is `REQUIRED_BUN`, the floor the SHIPPED `x` enforces
 // (`packages/cli/src/app-root.ts`), and not a second literal. It was one: `>=1.3.0`, a whole minor
 // BELOW the CLI the app then runs, so on a box with Bun 1.3.x `bun install` succeeded and the very
@@ -97,7 +107,7 @@ const rootPackage = (app: NameSet, version: string): string => `{
     "@ultimat3/schema": "^${version}",
     "@ultimat3/seo": "^${version}",
     "@ultimat3/ui": "^${version}",
-    "solid-js": "1.9.14"
+    "solid-js": "${SOLID_VERSION}"
   },
   "engines": {
     "bun": ">=${REQUIRED_BUN}"
@@ -187,7 +197,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 +237,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 +352,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>/);
 });
 `;
 
@@ -292,17 +272,11 @@ const toggleIsland =
 // 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.
+// The control itself is the catalog's \`ThemeToggle\`; this file is only the runtime it needs. It
+// reads the browser on its own: the theme the boot stamped on \`<html>\`, then \`theme.defaultMode\`
+// (stamped beside it), then the OS.
 
-import {
-  browserThemeEnv,
-  setSolidRuntime,
-  THEME_ATTRIBUTE,
-  type ThemeEnv,
-  ThemeToggle,
-  UiProvider,
-} from '@ultimat3/ui';
+import { setSolidRuntime, ThemeToggle, UiProvider } from '@ultimat3/ui';
 import {
   createContext,
   createEffect,
@@ -318,17 +292,6 @@ export interface ThemeToggleIslandProps {
   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
@@ -338,12 +301,11 @@ export const bootedEnv = (): ThemeEnv => {
  */
 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} />
+        <ThemeToggle mode="toggle" />
       </UiProvider>
     ),
     el,
@@ -373,26 +335,14 @@ export const themeToggleStates = defineIslandStates({
 
 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.
+// against a DOM small enough to read, and clicked. What it pins: the boot's verdict on \`<html>\` is
+// what the control starts from, and a click writes the key the boot script reads back 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';
+import { describeIslandState, expect, test } from '@ultimat3/testing';
+import { THEME_ATTRIBUTE, THEME_DEFAULT_ATTRIBUTE, THEME_STORAGE_KEY } from '@ultimat3/ui';
+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>();
@@ -401,49 +351,68 @@ const localStorage = {
   setItem: (key: string, value: string): void => void stored.set(key, value),
   removeItem: (key: string): void => void stored.delete(key),
 };
+/** One OS query, shared by every \`matchMedia\` call: \`flipOs\` changes it and tells the listeners. */
+const os = { dark: false, listeners: new Set<() => void>() };
 const matchMedia = (): Record<string, unknown> => ({
-  matches: false,
-  addEventListener: () => {},
-  removeEventListener: () => {},
+  get matches(): boolean {
+    return os.dark;
+  },
+  addEventListener: (_type: string, listener: () => void) => void os.listeners.add(listener),
+  removeEventListener: (_type: string, listener: () => void) => void os.listeners.delete(listener),
 });
+const flipOs = (dark: boolean): void => {
+  os.dark = dark;
+  for (const listener of os.listeners) listener();
+};
 
-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('with nothing stored, a click flips the theme the boot stamped — not the OS', () => {
+    // The OS fake says light. The boot stamped this app's \`defaultMode\`, dark, so the visible
+    // theme is dark and the first click must go light; a toggle that asked the OS would write the
+    // dark already on screen and look dead.
+    stored.clear();
+    mounted().documentElement.setAttribute(THEME_DEFAULT_ATTRIBUTE, 'dark');
+    mounted().documentElement.setAttribute(THEME_ATTRIBUTE, 'dark');
+    expect(mounted().fire('button', 'click')).toBe(true);
+    expect(stored.get(THEME_STORAGE_KEY)).toBe('light');
+    expect(mounted().documentElement.getAttribute(THEME_ATTRIBUTE)).toBe('light');
   });
 
-  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);
+  test("an OS flip is followed while nothing is stored and the app's default is 'system'", () => {
+    stored.clear();
+    mounted().documentElement.setAttribute(THEME_DEFAULT_ATTRIBUTE, 'system');
+    flipOs(true);
+    expect(mounted().documentElement.getAttribute(THEME_ATTRIBUTE)).toBe('dark');
+    // A fixed default is the app's own opinion: the OS does not override it.
+    mounted().documentElement.setAttribute(THEME_DEFAULT_ATTRIBUTE, 'dark');
+    flipOs(false);
+    expect(mounted().documentElement.getAttribute(THEME_ATTRIBUTE)).toBe('dark');
   });
 });
 `;

package/src/templates/scaffold-site.ts

@@ -45,7 +45,7 @@ export const config = defineRoute({
   }),
 });
 
-export function HomePage() {
+export function Page() {
   const t = useT();
 
   return (
@@ -259,23 +259,49 @@ const siteStyle = (): string => `@use '@ultimat3/ui/tokens' as tokens;
 }
 `;
 
-const sitePageTest =
-  (): string => `// The landing page ships zero JS and declares its metadata. Both are promises the file makes in
-// its config, and both are the kind that rot silently when someone adds one import.
-import { metaContextFor, routeDataFor } from '@ultimat3/render';
-import { expect, unitTest } from '@ultimat3/testing';
-import { config } from './page';
-
-// The same two objects a render builds: \`routeDataFor\` resolves the route's data once, and
-// \`metaContextFor\` wraps it the way every render mode wraps it before calling \`meta\`.
-const ctx = { params: {}, url: 'https://example.test/' };
-
-unitTest('the landing page ships zero JS and declares metadata', async () => {
-  expect(config.render).toBe('static');
-  expect(config.hydrate).toBe('never');
-  expect(config.budget.js).toBe('0kb');
-  const meta = await config.meta(metaContextFor(ctx, await routeDataFor(config, ctx)));
-  expect(meta.title ?? '').not.toBe('');
+const sitePageTest = (
+  app: NameSet,
+): string => `// The landing page, rendered: what a visitor reads, where its two calls to action lead, and that
+// it ships zero JS. Each is a promise the file makes, and each rots silently on one import.
+${sortedImports([
+  `import { useT } from '@${app.kebab}/i18n';`,
+  "import { expect, renderRoute, unitTest } from '@ultimat3/testing';",
+])}
+import * as page from './page';
+
+const url = 'https://example.test/';
+
+unitTest('the landing page says what the catalog says, under one h1', async () => {
+  const t = useT();
+  const view = await renderRoute(page, { url });
+  expect(view.html.match(/<h1\\b/g)).toHaveLength(1);
+  expect(view.text).toContain(t('site.home.headline'));
+  expect(view.text).toContain(t('site.home.lede'));
+  // Three facts, each a heading and a body.
+  expect(view.html.match(/<h2\\b/g)).toHaveLength(3);
+  for (const key of ['site.home.f1Title', 'site.home.f2Body', 'site.home.f3Title'] as const) {
+    expect(view.text).toContain(t(key));
+  }
+  // A key no catalog holds renders as \u27e6key\u27e7 — to a visitor, with every other check green.
+  expect(view.text).not.toContain('\u27e6');
+});
+
+unitTest('its two calls to action lead into the product', async () => {
+  const view = await renderRoute(page, { url });
+  const hrefs = [...view.html.matchAll(/<a\\b[^>]*href="([^"]*)"/g)].map((match) => match[1]);
+  expect(hrefs).toEqual(['/dashboard', '/admin']);
+});
+
+unitTest('it ships zero JS and declares the metadata a search result renders', async () => {
+  const t = useT();
+  const view = await renderRoute(page, { url });
+  expect(page.config.render).toBe('static');
+  expect(page.config.hydrate).toBe('never');
+  expect(page.config.budget.js).toBe('0kb');
+  // What the render DID, beside what the config declares: no island left the page.
+  expect(view.islands).toEqual([]);
+  expect(view.meta.title).toBe(t('site.home.title'));
+  expect(view.meta.description).toBe(t('site.home.description'));
 });
 `;
 
@@ -283,5 +309,5 @@ unitTest('the landing page ships zero JS and declares metadata', async () => {
 export const siteFiles = (app: NameSet): readonly GeneratedFile[] => [
   { path: 'apps/web/site/page.tsx', contents: sitePage(app) },
   { path: 'apps/web/site/page.module.scss', contents: siteStyle() },
-  { path: 'apps/web/site/page.test.ts', contents: sitePageTest() },
+  { path: 'apps/web/site/page.test.ts', contents: sitePageTest(app) },
 ];

package/src/templates/scaffold-ui-package.ts

@@ -31,6 +31,23 @@ export function Card(props: CardProps) {
 }
 `;
 
+const uiCardTest =
+  (): string => `// The card, rendered the way a page renders it. What a typecheck cannot see is where a prop
+// lands: the title is the card's heading, and the children follow it inside the same section.
+import { expect, renderView, unitTest } from '@ultimat3/testing';
+import { Card } from './card';
+
+unitTest('the card puts its title in a heading and its children after it', async () => {
+  const view = await renderView(Card, { title: 'Usage', children: 'body copy' });
+  expect(view.html).toMatch(/^<section[^>]*><h2[^>]*>Usage<\\/h2>body copy<\\/section>$/);
+});
+
+unitTest('a card with no children is its heading and nothing else', async () => {
+  const view = await renderView(Card, { title: 'Empty' });
+  expect(view.text).toBe('Empty');
+});
+`;
+
 const uiCardStyle = (): string => `@use '@ultimat3/ui/tokens' as tokens;
 
 .card {
@@ -52,5 +69,6 @@ export const uiPackageFiles = (app: NameSet): readonly GeneratedFile[] => [
   ...packageShapeFiles(app, 'ui', DESCRIPTION),
   { path: 'packages/ui/src/index.ts', contents: uiIndex() },
   { path: 'packages/ui/src/card.tsx', contents: uiCard() },
+  { path: 'packages/ui/src/card.test.ts', contents: uiCardTest() },
   { path: 'packages/ui/src/card.module.scss', contents: uiCardStyle() },
 ];