@ultimat3/cli 22.15.0 → 24.0.0

package/src/solid-loader.ts

@@ -73,6 +73,10 @@ interface CacheEntry {
  */
 const cache = new Map<string, CacheEntry>();
 
+/** Transforms running now, and the `prepareStackTrace` the first of them found (see below). */
+let inFlight = 0;
+let foundStackTrace: typeof Error.prepareStackTrace;
+
 /** Test seam: the cache is process-global because the dev server it serves is too. */
 export function clearIslandTransformCache(): void {
   cache.clear();
@@ -92,8 +96,12 @@ export async function transformIslandTsx(source: string, path: string): Promise<
 
   // Babel installs its own `prepareStackTrace` on the first TRANSFORM — not on import, which is
   // where this guard was first put — and leaving it installed makes `Error.captureStackTrace`
-  // strict for every unrelated module loaded later in the same process.
-  const saved = Error.prepareStackTrace;
+  // strict for every unrelated module loaded later in the same process, and names every error in
+  // it `Error` (a `TypeError`'s stack then opens `Error: …`). Saved by the FIRST transform in
+  // flight and restored by the LAST: `Bun.build` loads a second `.tsx` while the first compiles,
+  // and a per-call save taken inside that window saved Babel's own rewriter and restored it last.
+  if (inFlight === 0) foundStackTrace = Error.prepareStackTrace;
+  inFlight += 1;
   let code: string | null | undefined;
   try {
     // `transformAsync` and never `transformFileAsync`: the latter is gated behind `@babel/core`'s
@@ -111,7 +119,8 @@ export async function transformIslandTsx(source: string, path: string): Promise<
     });
     code = result?.code;
   } finally {
-    Error.prepareStackTrace = saved;
+    inFlight -= 1;
+    if (inFlight === 0) Error.prepareStackTrace = foundStackTrace;
   }
   // A parse error is NOT caught here: Babel's own message already names the file, the line and the
   // column ("a.island.tsx: Unexpected token (2:23)"), and `buildOne` wraps whatever escapes in

package/src/source-edit.ts

@@ -0,0 +1,49 @@
+// The two text edits a generator makes to a file the app owns: one keyed line added to an object
+// literal, and one import added where the formatter's sorted block would have it. Shared by the
+// registrars (`handle-registration.ts`, `admin-registration.ts`) so "in key order, expanded" means
+// one thing in both.
+
+const IDENTIFIER = '[A-Za-z_$][\\w$]*';
+
+const keyOf = (item: string): string => item.split(':')[0]?.trim() ?? '';
+
+/** Whether the object body already holds `key` — as `key: value` or as a shorthand. */
+export const holdsKey = (body: string, key: string): boolean =>
+  new RegExp(`(^|[\\s,{])${key}\\s*[:,]`).test(`${body},`);
+
+/**
+ * An object literal's body with `line` on its own row, in key order. A body the author keeps on
+ * one line is expanded — an expanded literal is the shape a formatter leaves alone at any length.
+ * `indent` is what an entry of this literal is indented by.
+ */
+export function withKeyedLine(body: string, key: string, line: string, indent: string): string {
+  if (!body.includes('\n')) {
+    const items = body
+      .split(',')
+      .map((item) => item.trim())
+      .filter((item) => item !== '');
+    const lines = [...items.map((item) => `${indent}${item},`), line].sort((a, b) =>
+      keyOf(a) < keyOf(b) ? -1 : 1,
+    );
+    return `\n${lines.join('\n')}\n${indent.slice(2)}`;
+  }
+  const lines = body.split('\n');
+  const isEntry = (text: string): boolean => new RegExp(`^\\s*${IDENTIFIER}\\s*[:,]`).test(text);
+  const after = lines.findIndex((text) => isEntry(text) && keyOf(text) > key);
+  // Past the last entry when none sorts later: the row before the closing brace's own indent.
+  lines.splice(after === -1 ? lines.length - 1 : after, 0, line);
+  return lines.join('\n');
+}
+
+/** `source` with `line` imported, placed where a sorted import block would have it. */
+export function withSortedImport(source: string, line: string, specifier: string): string {
+  if (source.includes(`from '${specifier}'`)) return source;
+  const imports = [...source.matchAll(/^import\b[^;]*?from\s+'([^']+)';\n/gm)];
+  // Packages only: a relative import is a LATER group, so it is never what this line sorts against.
+  const packages = imports.filter((match) => !(match[1] ?? '').startsWith('.'));
+  const later = packages.find((match) => (match[1] ?? '') > specifier);
+  const last = packages.at(-1);
+  const first = imports[0]?.index ?? 0;
+  const at = later?.index ?? (last === undefined ? first : last.index + last[0].length);
+  return `${source.slice(0, at)}${line}\n${source.slice(at)}`;
+}

package/src/source-files.ts

@@ -16,6 +16,12 @@ export const SOURCE_GLOBS = [
   'api/**/*.{ts,tsx}',
   'shared/**/*.{ts,tsx}',
   'apps/*/{app,site,api,shared}/**/*.{ts,tsx}',
+  // An app's own entry files: authored, shipped, and outside every surface glob above — a 900-line
+  // `server.ts` or an unrunnable `fix:` in it was invisible to `filesize` and `errors`.
+  // And its guards: run on the gate, held to the error contract, and invisible to `filesize`.
+  'guards/*.ts',
+  'apps/*/server.ts',
+  'apps/*/prerender.ts',
 ] as const;
 
 /**

package/src/stored-object-headers.ts

@@ -0,0 +1,43 @@
+// How a stored object may be presented when the app's own origin serves it (plan 101, s1-sec L6):
+// inline only for a type a browser renders without running anything, a sandboxed download otherwise. Read by
+// both surfaces that serve stored bytes — `/_storage` (`runtime-storage.ts`) and `/media`.
+
+/**
+ * Raster images, audio and video: what an `<img>`, `<audio>` or `<video>` presents and nothing
+ * executes. NOT `image/svg+xml` (it carries `<script>`), `text/html`, `application/xml` or PDF —
+ * any of them opened from the app's origin runs with the app's cookies and its `'self'` sources.
+ */
+const INLINE_TYPES: ReadonlySet<string> = new Set([
+  'image/png',
+  'image/jpeg',
+  'image/gif',
+  'image/webp',
+  'image/avif',
+  'audio/mpeg',
+  'audio/ogg',
+  'audio/wav',
+  'audio/webm',
+  'video/mp4',
+  'video/webm',
+  'video/ogg',
+]);
+
+/** `image/PNG; charset=…` is `image/png`: parameters and case never widen the list. */
+const essenceOf = (contentType: string): string =>
+  (contentType.split(';')[0] ?? '').trim().toLowerCase();
+
+export const isInlineSafe = (contentType: string): boolean =>
+  INLINE_TYPES.has(essenceOf(contentType));
+
+/**
+ * The headers a stored object is served with beyond its type. `attachment` makes a navigation to an
+ * uploaded `text/html` a download instead of a page on the app's origin; an embedding element
+ * (`<img>`, `<video>`) ignores it, so nothing that displays an object inline stops working. The
+ * `sandbox` policy is for the browser that renders it anyway: an opaque origin, no script, no
+ * cookies. `@ultimat3/http`'s security stage keeps it and adds the app's policy beside it.
+ */
+export function storedObjectHeaders(contentType: string): Readonly<Record<string, string>> {
+  return isInlineSafe(contentType)
+    ? {}
+    : { 'content-disposition': 'attachment', 'content-security-policy': 'sandbox' };
+}

package/src/sync-url.ts

@@ -43,8 +43,8 @@ export function syncConnectSources(env: Readonly<Record<string, string | undefin
 }
 
 /**
- * The page origins a sync node admits besides its own host name: `APP_URL`'s, when set. Only a
- * deployment that serves the page on another host than the node needs it; an unparsable value is
+ * The page origins a sync node admits besides its own origin: `APP_URL`'s, when set. A deployment
+ * that serves the page on another port or host than the node sees needs it; an unparsable value is
  * refused rather than read as "no page origin", which would refuse every socket in silence.
  */
 export function syncOriginsFrom(env: Readonly<Record<string, string | undefined>>): string[] {

package/src/tasks-facts.ts

@@ -5,35 +5,12 @@
 import type { TaskDescriptor, TaskHandle } from '@ultimat3/jobs';
 import { getTask, registeredTasks } from '@ultimat3/jobs';
 import type { CronPhrases } from '@ultimat3/time';
-import {
-  describeCron,
-  fromEpochMs,
-  nextCronOccurrenceMs,
-  offsetLabel,
-  toZoned,
-} from '@ultimat3/time';
+import { describeCron, fromEpochMs, isoInZone, nextCronOccurrenceMs } from '@ultimat3/time';
 import { BadFlagError } from './errors';
 
 const DEFAULT_COUNT = 5;
 const MAX_COUNT = 50;
 
-const pad2 = (value: number): string => String(value).padStart(2, '0');
-
-/**
- * ISO-8601 rendered with the ZONE's OWN offset (`2026-03-08T03:00:00-04:00`), never collapsed to
- * UTC `Z` — an ambient zone is exactly the bug a task's `tz` exists to prevent. No single
- * "instant in a zone, as ISO" export exists in `@ultimat3/time` to call instead: `toIso` is
- * UTC-`Z` only, `isoDateInZone` is date-only, and `formatWithOffset` renders locale prose, not
- * ISO. So this composes the package's own instant→zoned-wall-clock conversion (`toZoned`) and
- * zone-label helper (`offsetLabel`) rather than a fresh `Intl.DateTimeFormat` call here.
- */
-function isoInZone(ms: number, zone: string): string {
-  const zoned = toZoned(fromEpochMs(ms), zone);
-  const date = `${String(zoned.year).padStart(4, '0')}-${pad2(zoned.month)}-${pad2(zoned.day)}`;
-  const time = `${pad2(zoned.hour)}:${pad2(zoned.minute)}:${pad2(zoned.second)}`;
-  return `${date}T${time}${offsetLabel(zoned.offsetMinutes)}`;
-}
-
 /** `x tasks list` row: the descriptor plus the next occurrence, ms and rendered alike. */
 export interface TaskFact extends TaskDescriptor {
   readonly nextMs: number;
@@ -43,7 +20,7 @@ export interface TaskFact extends TaskDescriptor {
 function toFact(handle: TaskHandle, nowMs: number): TaskFact {
   const descriptor = handle.describe();
   const nextMs = nextCronOccurrenceMs(descriptor.cron, descriptor.tz, nowMs);
-  return { ...descriptor, nextMs, next: isoInZone(nextMs, descriptor.tz) };
+  return { ...descriptor, nextMs, next: isoInZone(fromEpochMs(nextMs), descriptor.tz) };
 }
 
 export function listTaskFacts(nowMs: number): readonly TaskFact[] {
@@ -107,7 +84,7 @@ export function taskShowFacts(
   let cursor = nowMs;
   for (let i = 0; i < count; i += 1) {
     cursor = nextCronOccurrenceMs(descriptor.cron, descriptor.tz, cursor);
-    upcoming.push({ ms: cursor, at: isoInZone(cursor, descriptor.tz) });
+    upcoming.push({ ms: cursor, at: isoInZone(fromEpochMs(cursor), descriptor.tz) });
   }
   return { descriptor, describe: describeCron(descriptor.cron, 'en-US', phrases), upcoming };
 }

package/src/templates/action.ts

@@ -3,9 +3,11 @@
 // job handle, an MCP tool and these tests; the generator writes the declaration and the tests.
 
 import type { FeatureTarget } from './entity';
+import { sortedImports } from './imports';
 import type { GeneratedFile, NameSet } from './naming';
 import { names } from './naming';
-import { sliceExports, sliceFoundation } from './slice-foundation';
+import { PLACEHOLDER_DB_MODULE } from './scaffold-db-client';
+import { sliceExports, sliceFoundation, sliceTakesScaffoldRow } from './slice-foundation';
 import { wrapImport } from './wrap';
 
 /**
@@ -80,6 +82,9 @@ export const ${name.camel} = mutator({
   input: t.object({ id: t.uuid, orgId: t.uuid, title: t.string }),
   output: t.object({ id: t.uuid, title: t.string }),
   policy: can${feature.pascal}Write,
+  // Required on a mutator (X_MUTATOR_NOT_IDEMPOTENT): the client replays this write under one
+  // Idempotency-Key after a dropped response, and the replay answers the first result.
+  idempotent: true,
   // No \`mcp\` until a real description is written: see \`x g action\`.
   // tx.table(name) rather than tx.${feature.plural}: the typed accessor exists only once the app
   // augments LocalTables, and generated code cannot assume that has happened yet. The name is the
@@ -104,6 +109,10 @@ ${
 });
 `;
 
+/** The code the slice's `errors.ts` declares for a missing row. */
+const notFoundCode = (feature: NameSet): string =>
+  `X_${feature.kebab.toUpperCase().split('-').join('_')}_NOT_FOUND`;
+
 const ID = '00000000-0000-4000-8000-000000000001';
 const ORG = '00000000-0000-4000-8000-000000000002';
 const OTHER_ORG = '00000000-0000-4000-8000-000000000009';
@@ -160,20 +169,137 @@ const outsider = testActor('outsider', {
     : ''
 }`;
 
-const actionUnitTest = (
-  name: NameSet,
-  feature: NameSet,
-  isMutator: boolean,
-): string => `// ${name.camel}: its declared shape and the input it refuses. Both are answered by the declaration
-// alone, so they belong to the \`unit\` step — the contract projections are next door.
-${preamble(name, feature, isMutator, 'expect, unitTest', false)}
-${shapeTest(name, isMutator)}
+/** What the unit test may do with the slice the declaration lives in. */
+interface HandlerShape {
+  readonly isMutator: boolean;
+  /** The handler reads a row by id and throws `<Feature>NotFoundError` when there is none. */
+  readonly lookup: boolean;
+  /** The slice still takes the row `x g entity` scaffolds, so the test may store one. */
+  readonly storesRow: boolean;
+  readonly dbModule: string;
+}
+
+/**
+ * The optimistic half, run against the client store `@ultimat3/testing` ships. A twin is replayed
+ * on every rebase, so the two facts worth failing on are the row one application leaves and that a
+ * second leaves the same one — and that a row the store never held is not invented.
+ */
+const localTwinTests = (): string => `
+unitTest('the local twin marks the row pending, and a replay lands in the same place', () => {
+  const store = memoryLocalTx({ [TABLE]: { [id]: { id, title: 'before', pending: false } } });
+  target.local(store.tx, input);
+  const once = store.rows(TABLE);
+  expect(once).toEqual({ [id]: { id, title: 'a title', pending: true } });
+  // A rebase replays the queued write: twice through must equal once through.
+  target.local(store.tx, input);
+  expect(store.rows(TABLE)).toEqual(once);
+});
+
+unitTest('the local twin invents no row the store never held', () => {
+  const store = memoryLocalTx();
+  target.local(store.tx, input);
+  expect(store.rows(TABLE)).toEqual({});
+});
+`;
+
+/** The authoritative half's cases, refusal first, in the shape the slice earns. */
+const handlerTests = (feature: NameSet, shape: HandlerShape): string => {
+  const answer = shape.isMutator ? "{ id, title: 'a title' }" : '{ id }';
+  if (!shape.lookup) {
+    return `
+unitTest('an actor without the grant is refused before the handler runs', async () => {
+  const stranger = testActor('stranger', { orgId }).actor;
+  const refused = await target.as(stranger, input).catch((error: unknown) => error);
+  expect(refused).toBeUltimateError('X_FORBIDDEN');
+});
+
+unitTest('the handler answers a writer in the org', async () => {
+  expect(await target.as(writer, input)).toEqual(${answer});
+});
+`;
+  }
+  const found = shape.isMutator
+    ? "{ id: row.id, title: 'a title' }"
+    : "{ id: row.id, title: 'kept' }";
+  const call = shape.isMutator
+    ? "{ id: row.id, orgId, title: 'a title' }"
+    : '{ id: row.id, orgId }';
+  return `
+unitTest('the handler refuses an id nothing holds', async () => {
+  const refused = await target.as(writer, input).catch((error: unknown) => error);
+  expect(refused).toBeUltimateError('${notFoundCode(feature)}');
+});
+${
+  shape.storesRow
+    ? `
+unitTest('the handler answers the row it found', async () => {
+  const draft = { orgId, title: 'kept', price: { minor: 0, currency: 'USD' } };
+  const row = await runWithContext(createContext({ actor: writer }), () => repo.insert(draft));
+  const answer = await target.as(writer, ${call});
+  expect(answer).toEqual(${found});
+});
+`
+    : ''
+}`;
+};
+
+/**
+ * The unit test: the declaration's shape, the input it refuses, and the HANDLER — run through
+ * `.as()`, the one execution path, against the in-memory driver. A mutator's local twin runs
+ * against `memoryLocalTx`. The contract projections are next door, in their own suite.
+ *
+ * A row is stored only in a slice whose row this generator can spell (`sliceTakesScaffoldRow`): a
+ * slice an author reshaped has its own columns, and a test that inserted `{ title, price }` into
+ * it would be a guess about someone else's table.
+ */
+const actionUnitTest = (name: NameSet, feature: NameSet, shape: HandlerShape): string => {
+  const stores = shape.lookup && shape.storesRow;
+  const testing = [
+    ...(stores ? ['afterEach'] : []),
+    'expect',
+    ...(shape.isMutator ? ['memoryLocalTx'] : []),
+    'unitTest',
+  ].join(', ');
+  return `// ${name.camel}: its declared shape, the input it refuses, and what its handler answers — in
+// process, so all three belong to the \`unit\` step. The contract projections are next door.
+${sortedImports([
+  ...(stores ? ["import { createContext, runWithContext } from '@ultimat3/core';"] : []),
+  "import { testActor } from '@ultimat3/policy';",
+  `import { ${testing} } from '@ultimat3/testing';`,
+  ...(stores ? [`import { driver } from '${shape.dbModule}';`] : []),
+])}${stores ? "\nimport * as repo from '../repo';" : ''}
+import { ${name.camel} } from './${name.kebab}';
+
+const id = '${ID}';
+const orgId = '${ORG}';
+const input = { id, orgId${shape.isMutator ? ", title: 'a title'" : ''} };
+${shape.isMutator ? `\n// The client store's table: the entity's own, so the twin and the server row share one key.\nconst TABLE = '${feature.table}';\n` : ''}
+// Named here because every projection needs a stable name and this file does not boot the app.
+// At boot \`registerActions(await import('./actions'))\` stamps the same name onto the same
+// object, so \`${name.camel}.tool()\` works there with nothing to remember.
+const target = ${name.camel}.named('${name.camel}');
+
+// Holds the grant in the org the input names: past the policy, so what answers is the handler.
+const grant = ['${feature.kebab}:write'];
+const writer = testActor('writer', { orgId, permissions: grant }).actor;
+${
+  stores
+    ? `
+// One store per process: without this, one test's rows are the next test's fixtures.
+afterEach(() => {
+  driver.reset?.();
+});
+`
+    : ''
+}
+${shapeTest(name, shape.isMutator)}
 
 unitTest('${name.camel} rejects input that is not a uuid', async () => {
   await expect(target.input).toRejectInput({ ...input, id: 'not-a-uuid' });
   await expect(target.input).toAcceptInput(input);
 });
-`;
+${shape.isMutator ? localTwinTests() : ''}${handlerTests(feature, shape)}`;
+};
 
 const actionContractTest = (
   name: NameSet,
@@ -218,6 +344,8 @@ export interface ActionOptions extends FeatureTarget {
    * data. `x g resource` passes the entity it is writing in the same run.
    */
   readonly sliceEntity?: string;
+  /** The slice's `repo.ts` as it stands on disk, or absent alongside `sliceEntity`. */
+  readonly sliceRepo?: string;
 }
 
 export function actionFiles(rawName: string, target: ActionOptions): readonly GeneratedFile[] {
@@ -246,7 +374,15 @@ export function actionFiles(rawName: string, target: ActionOptions): readonly Ge
     // suites: the input parse is a `unit` assertion and the three projections are `contract` ones.
     // Emitted as one file, the contract half ran under `unit` and `x test contract` answered
     // X_TEST_NO_FILES; renaming that one file would have put the `unitTest` in the same bind.
-    { path: `${dir}/${name.kebab}.test.ts`, contents: actionUnitTest(name, feature, isMutator) },
+    {
+      path: `${dir}/${name.kebab}.test.ts`,
+      contents: actionUnitTest(name, feature, {
+        isMutator,
+        lookup,
+        storesRow: sliceTakesScaffoldRow(target, target.sliceEntity, target.sliceRepo),
+        dbModule: target.dbModule ?? PLACEHOLDER_DB_MODULE,
+      }),
+    },
     {
       path: `${dir}/${name.kebab}.contract.test.ts`,
       contents: actionContractTest(name, feature, isMutator),

package/src/templates/admin-catalog.ts

@@ -0,0 +1,58 @@
+// The catalog keys the admin reads for a generated entity. An entity in the app's handle IS an
+// admin screen — `defineAdmin({ entities: adminEntitiesOf(db) })` — and that screen resolves
+// `admin.<table>.title` and one `admin.<table>.field.<column>` per column. Nothing emitted them, so
+// a generated list rendered `⟦admin.widgets.field.title⟧` in every header.
+
+import { catalogJson } from './catalog-json';
+import type { FeatureTarget } from './entity';
+import { entityFiles } from './entity';
+import { catalogPath, resolveLocales } from './locales';
+import type { GeneratedFile } from './naming';
+import { kebab, names } from './naming';
+
+/** `    title: text({ max: 200 }),` — one column of the entity this same run writes. */
+const COLUMN_LINE = /^ {4}([A-Za-z_$][\w$]*): [A-Za-z_$][\w$]*\(/gm;
+
+/** `createdAt` → `Created at`, `orgId` → `Org ID`: a label a person reads, in sentence case. */
+export const columnLabel = (property: string): string => {
+  const words = kebab(property)
+    .split('-')
+    .map((word) => (word === 'id' ? 'ID' : word));
+  const [first = '', ...rest] = words;
+  return [`${first[0]?.toUpperCase() ?? ''}${first.slice(1)}`, ...rest].join(' ');
+};
+
+/**
+ * The entries, keyed exactly as `@ultimat3/admin` derives them: both read the entity's own name
+ * (`$name`, the table) and its property names. The columns come off the entity this run writes —
+ * never a second list typed here — so a column added to the template is a label added with it.
+ */
+export function adminCatalogEntries(
+  rawName: string,
+  target: FeatureTarget,
+): Readonly<Record<string, string>> {
+  const name = names(rawName);
+  const source = String(
+    entityFiles(rawName, target).find((file) => file.path.endsWith('/entity.ts'))?.contents ?? '',
+  );
+  const entries: Record<string, string> = {
+    [`admin.${name.table}.title`]: columnLabel(name.plural),
+  };
+  for (const match of source.matchAll(COLUMN_LINE)) {
+    const property = match[1] ?? '';
+    entries[`admin.${name.table}.field.${property}`] = columnLabel(property);
+  }
+  return entries;
+}
+
+/** One mergeable catalog file per locale — for `x g entity`, which has no other catalog entry. */
+export const adminCatalogFiles = (
+  rawName: string,
+  target: FeatureTarget,
+  locales: readonly string[] | undefined,
+): readonly GeneratedFile[] =>
+  resolveLocales(locales).map((locale) => ({
+    path: catalogPath(locale),
+    contents: catalogJson(adminCatalogEntries(rawName, target)),
+    merge: 'json' as const,
+  }));

package/src/templates/admin-page.ts

@@ -4,15 +4,27 @@
 // table and `guardedPage()` is the one thing that decides it. A scaffold that wrote a route
 // declaration here would hand back the unguarded second way in that seam exists to close.
 
+import { ADMIN_FILE } from '../admin-registration';
 import { catalogJson } from './catalog-json';
 import { sortedImports } from './imports';
 import { catalogPath, resolveLocales } from './locales';
 import type { GeneratedFile } from './naming';
 import { camel, kebab, pascal } from './naming';
-import { LINE_WIDTH } from './wrap';
+import { LINE_WIDTH, wrapImport } from './wrap';
 
-/** Where an admin lives when the caller does not say. `x new` scaffolds this layout. */
-export const DEFAULT_ADMIN_PAGE_DIR = 'apps/admin/src/pages';
+/** The directory `defineAdmin` is declared in — the admin's one home, inside the app scan. */
+const ADMIN_HOME = ADMIN_FILE.slice(0, ADMIN_FILE.lastIndexOf('/'));
+
+/**
+ * Where a page lands when the caller does not say: beside the declaration `x new` writes, under the
+ * directory the app scan imports. `apps/admin/src/pages` was outside it, and an admin kept there was
+ * never mounted (`X_ADMIN_UNSCANNED`).
+ */
+export const DEFAULT_ADMIN_PAGE_DIR = `${ADMIN_HOME}/pages`;
+
+/** The import a `defineAdmin` in `ADMIN_FILE` writes for a page in `dir`, when one can be derived. */
+const specifierFor = (dir: string, name: string): string =>
+  dir.startsWith(`${ADMIN_HOME}/`) ? `./${dir.slice(ADMIN_HOME.length + 1)}/${name}` : `./${name}`;
 
 export interface AdminPageOptions {
   /** The permission the page's own work needs. `admin:read` is composed in front of it. */
@@ -115,8 +127,8 @@ const pageSource = (
 // so a route declaration in this file would be a second, unguarded way in.
 //
 // Wire it in once, and add \`navGroup\` to link it in the sidebar — this file is ${dir}/${name}.tsx,
-// so the specifier is relative to wherever \`defineAdmin\` lives:
-//   import { ${declaration}Page } from './${name}';
+// so the specifier is relative to wherever \`defineAdmin\` lives (${ADMIN_FILE} in a scaffolded app):
+//   import { ${declaration}Page } from '${specifierFor(dir, name)}';
 //   defineAdmin({ …, pages: […, ${declaration}Page] })
 //
 // The permission below is declared here AND has to be decided: an authz map built from a fixed
@@ -146,11 +158,27 @@ export const ${declaration}Page: AdminCustomPage = {
 
 const pageTest = (name: string, permission: string): string => {
   const declaration = camel(name);
+  const Name = pascal(name);
+  const url = `http://localhost/admin/${name}`;
   return `// The ${name} admin page is guarded and owns no route of its own — the two facts that separate an
-// admin screen from a page, and the two an edit here is most likely to break.
+// admin screen from a page, and the two an edit here is most likely to break — and it renders
+// from the request it is handed.
+import { adminTestCtx } from '@ultimat3/admin';
 import { knownPermissions } from '@ultimat3/policy';
-import { expect, unitTest } from '@ultimat3/testing';
-import { ${declaration}Page } from './${name}';
+import { expect, renderView, unitTest } from '@ultimat3/testing';
+${wrapImport([`${Name}Page`, `${declaration}Page`], `./${name}`)}
+
+// The component, called the way the admin's frame calls it once the guard has passed: a ctx for
+// an actor holding the page's own permission, the route params, and the request URL.
+unitTest('the ${name} admin page renders', async () => {
+  const view = await renderView(${Name}Page, {
+    ctx: adminTestCtx({ granted: ['admin:read', '${permission}'] }),
+    params: {},
+    url: '${url}',
+  });
+  expect(view.html).toContain('<h1>');
+  expect(view.text).toContain('${url}');
+});
 
 // Both facts the frame reads off the declaration, so both are decidable without a request: a path
 // that is not rooted is X_ADMIN_PAGE_PATH_INVALID, and no permission at all is