@ultimat3/cli 5.0.1 → 7.0.0

package/src/templates/admin-page.ts

@@ -23,11 +23,50 @@ export interface AdminPageOptions {
    */
   readonly dir?: string;
   readonly locales?: readonly string[];
+  /**
+   * The app's own catalog module — `@<app>/i18n`, read off `packages/i18n/package.json` by
+   * `resolveCatalogModule`. Absent only for an app that ships no such package.
+   */
+  readonly catalogModule?: string;
 }
 
 const titleKeyFor = (name: string): string => `admin.${name}.title`;
 
-const pageSource = (name: string, permission: string, dir: string): string => {
+/**
+ * The generated page reaches strings through the APP's catalog module — the one that calls
+ * `defineCatalogs()` — so a page that renders a string depends on the module that registers them.
+ * `t` from `@ultimat3/i18n` renders while depending on nothing, which is how a shipped app served
+ * every string as a loud miss with a green gate (issue #249). An app with no catalog module keeps
+ * the framework import: emitting one that cannot resolve is worse than the wrong idiom.
+ */
+const catalogImport = (module: string | undefined): string =>
+  module === undefined
+    ? "import { t } from '@ultimat3/i18n';"
+    : `import { useT } from '${module}';`;
+
+/**
+ * The two imports, in the order biome's organize-imports wants — which DEPENDS on the app's scope
+ * and cannot be hardcoded either way. An app catalog (`@myapp/i18n`) sorts BEFORE
+ * `@ultimat3/admin`; the fallback `@ultimat3/i18n` sorts AFTER it. Emitting one fixed order makes
+ * every generated admin page a lint error in exactly one of the two cases, and each case is
+ * covered by a different job — the fallback by `templates`' own linter test, the app-scoped one
+ * only by `scaffold-smoke`, which runs the generators against a real scaffold.
+ */
+const pageImports = (module: string | undefined): string =>
+  [`import type { AdminCustomPage, AdminPageProps } from '@ultimat3/admin';`, catalogImport(module)]
+    .sort((a, b) => (a.slice(a.indexOf("'")) < b.slice(b.indexOf("'")) ? -1 : 1))
+    .join('\n');
+
+/** `useT()` is per render, so the component binds it in its own body. */
+const translatorBinding = (module: string | undefined): string =>
+  module === undefined ? '' : '\n  const t = useT();\n';
+
+const pageSource = (
+  name: string,
+  permission: string,
+  dir: string,
+  module: string | undefined,
+): string => {
   const Name = pascal(name);
   const declaration = camel(name);
   return `// Admin page: /${name}. An ORDINARY component — there is no \`defineRoute\` here, deliberately:
@@ -39,10 +78,9 @@ const pageSource = (name: string, permission: string, dir: string): string => {
 //   import { ${declaration}Page } from './${name}';
 //   defineAdmin({ …, pages: […, ${declaration}Page] })
 
-import type { AdminCustomPage, AdminPageProps } from '@ultimat3/admin';
-import { t } from '@ultimat3/i18n';
+${pageImports(module)}
 
-export function ${Name}Page(props: AdminPageProps) {
+export function ${Name}Page(props: AdminPageProps) {${translatorBinding(module)}
   return (
     <section>
       <h1>{t('${titleKeyFor(name)}')}</h1>
@@ -92,7 +130,10 @@ export function adminPageFiles(
   // Trailing slashes trimmed exactly as `islandFiles` does — one `--at`, one normalization.
   const dir = (options.dir ?? DEFAULT_ADMIN_PAGE_DIR).replace(/\/+$/, '');
   return [
-    { path: `${dir}/${name}.tsx`, contents: pageSource(name, options.permission, dir) },
+    {
+      path: `${dir}/${name}.tsx`,
+      contents: pageSource(name, options.permission, dir, options.catalogModule),
+    },
     { path: `${dir}/${name}.test.ts`, contents: pageTest(name, options.permission) },
     ...resolveLocales(options.locales).map((locale) => ({
       path: catalogPath(locale),

package/src/templates/index.ts

@@ -30,6 +30,7 @@ export type { QueryOptions } from './query';
 export { queryFiles } from './query';
 export type { ResourceOptions } from './resource';
 export { resourceFiles } from './resource';
+export { formIslandFiles } from './resource-form-island';
 export type { RouteOptions, Surface } from './route';
 export { routeFiles } from './route';
 export { appFiles } from './scaffold-app';

package/src/templates/island-fixture.ts

@@ -0,0 +1,76 @@
+// TEST-ONLY. An app root on disk holding emitted files, with the packages an island imports
+// resolvable BY SPECIFIER the way a real app resolves them — so a template that emits
+// `import { Button } from '@ultimat3/ui'` is proven by a build that actually resolves it, and not
+// by a string assertion that the import is present.
+
+// `node:` by necessity, and SYNC by necessity: `[Symbol.dispose]` cannot await, so the teardown
+// half has to be synchronous — and Bun ships neither a path API nor a `symlink`.
+import { mkdirSync, rmSync, symlinkSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import type { GeneratedFile } from './naming';
+
+/** `packages/cli/src/templates` → the repo root, four hops up. */
+const REPO_ROOT = join(import.meta.dir, '..', '..', '..', '..');
+
+/**
+ * INSIDE the checkout, and measured rather than chosen: the identical fixture under `os.tmpdir()`
+ * fails every `@ultimat3/*` and every relative import inside it with `Could not resolve`, because
+ * `Bun.build`'s resolver is scoped to the project `bun test` was started in and an app root outside
+ * it cannot reach its own `node_modules`. `.prerender-fixture` is the same shape for the same
+ * reason. The leading dot keeps it out of every `tsc` wildcard include.
+ */
+const FIXTURE_ROOT = join(REPO_ROOT, 'packages', 'cli', '.island-fixture');
+
+/** The package the fixture lives inside. Linking it would aim a symlink at its own ancestor. */
+const SELF = 'cli';
+
+export interface FixtureApp extends Disposable {
+  /** Absolute path of the app root — what `buildIslands` globs from. */
+  readonly path: string;
+}
+
+/**
+ * Symlinks rather than a `bun install`: the emitted island must resolve THIS working copy of
+ * `@ultimat3/ui`, and an install in a fixture directory would fetch the registry's last release
+ * and quietly prove nothing about the change under test. Every workspace is linked, not a chosen
+ * few — a template that grows an import should build, not fail on a list nobody updated.
+ */
+function linkDependencies(root: string): void {
+  const scope = join(root, 'node_modules', '@ultimat3');
+  mkdirSync(scope, { recursive: true });
+  const packages = join(REPO_ROOT, 'packages');
+  for (const entry of new Bun.Glob('*/package.json').scanSync({ cwd: packages })) {
+    const name = entry.slice(0, entry.indexOf('/'));
+    if (name === SELF) continue;
+    symlinkSync(join(packages, name), join(scope, name), 'dir');
+  }
+  // Resolved, never spelled as a path: the installer's layout is its own business and a hardcoded
+  // `node_modules/solid-js` is a fixture that breaks on a linker change rather than on a real one.
+  symlinkSync(
+    dirname(Bun.resolveSync('solid-js/package.json', REPO_ROOT)),
+    join(root, 'node_modules', 'solid-js'),
+    'dir',
+  );
+}
+
+/**
+ * `Disposable`, so the idiom is `using root = await fixtureAppRoot(label, files)`. `label` is the
+ * caller's, and is what keeps two test FILES off one directory: the path is fixed rather than
+ * random, because a random one cannot be named in `.gitignore` and a crashed run leaves it behind.
+ */
+export async function fixtureAppRoot(
+  label: string,
+  files: readonly GeneratedFile[],
+): Promise<FixtureApp> {
+  const path = join(FIXTURE_ROOT, label);
+  rmSync(path, { recursive: true, force: true });
+  mkdirSync(path, { recursive: true });
+  linkDependencies(path);
+  for (const file of files) await Bun.write(join(path, file.path), String(file.contents));
+  return {
+    path,
+    [Symbol.dispose]: (): void => {
+      rmSync(path, { recursive: true, force: true });
+    },
+  };
+}

package/src/templates/island.ts

@@ -1,7 +1,8 @@
 // `x g island <name>` — the one file on a route that ships JavaScript. Not a ninth primitive and
 // not a component generator: an island is a client ENTRY POINT, so what the scaffold has to get
-// right is the filename (the bundler discovers by it) and the `mount` export (the hydration
-// runtime calls it by name). Both are pinned by the emitted test.
+// right is the filename (the bundler discovers by it), the `mount` export (the hydration runtime
+// calls it by name) and what `mount` DOES — Solid's `render`, the one client shape the island build
+// compiles. All three are pinned by the emitted test, which builds the chunk and mounts it.
 
 import type { GeneratedFile } from './naming';
 import { kebab, pascal } from './naming';
@@ -11,6 +12,18 @@ export interface IslandOptions {
   readonly dir: string;
 }
 
+/**
+ * `join(import.meta.dir, '..', …)` back to the app root, one hop per directory segment. The
+ * emitted test names the island app-root-relative because that is how `discoverIslands` reports it,
+ * so the two spellings have to agree or `mountIsland` reports a file it did not build.
+ */
+export const upToAppRoot = (dir: string): string =>
+  dir
+    .split('/')
+    .filter((part) => part.length > 0)
+    .map(() => "'..'")
+    .join(', ');
+
 const islandSource = (name: string): string => {
   const Name = pascal(name);
   return `// ${Name}: the interactive half of an otherwise static page, and the only module on this
@@ -21,39 +34,136 @@ const islandSource = (name: string): string => {
 // A string has no import edge, so nothing follows one into this file and the page's bundle graph
 // stays the page's (axiom 6). WHEN it wakes is the route's \`hydrate\`, never a declaration here.
 
+import type { JSX } from 'solid-js';
+import { createSignal } from 'solid-js';
+import { render } from 'solid-js/web';
+import styles from './${name}.module.scss';
+
 /** What the server sends. Declared here AND in the page's \`island({ props })\` — both, or neither. */
 export interface ${Name}Props {
   /** Already translated: this runs in the browser, where \`t()\`'s catalog is not. */
   readonly label: string;
 }
 
+/**
+ * Solid, and not hand-written DOM: reactivity is a COMPILE-time contract that \`babel-preset-solid\`
+ * fulfils inside the island build, which is what makes \`count()\` read below update that one text
+ * node and nothing around it. A component written against an eager JSX factory reads every signal
+ * once and never again — it renders, and then it is a photograph.
+ */
+function ${Name}(props: ${Name}Props): JSX.Element {
+  const [count, setCount] = createSignal(0);
+  return (
+    <p class={styles.panel}>
+      <button type="button" class={styles.trigger} onClick={() => setCount(count() + 1)}>
+        {props.label}
+      </button>
+      <output data-role="count">{count()}</output>
+    </p>
+  );
+}
+
 /**
  * The one export the hydration runtime calls — \`import(entry).then((m) => m.mount(el, props))\`.
- * \`el\` is the wrapper the page rendered, with the server's own markup already inside it, so a
- * mount that replaces the markup instead of taking it over is a visible flash on every load.
+ * \`el\` is the wrapper the page rendered, with the server's own markup already inside it.
+ *
+ * The shell is cleared first, and that line is load-bearing: Solid's \`render\` APPENDS when the
+ * container already has children, so without it the server's markup stays on screen above a
+ * second, live copy of the same thing.
  */
 export function mount(el: HTMLElement, props: ${Name}Props): void {
-  el.textContent = props.label;
-  el.addEventListener('click', () => {
-    // \`dataset.open\`, not \`dataset['open']\`: the bracket form is lint/complexity/useLiteralKeys,
-    // which the app's own \`biome check\` fails on — twice, in the one file every island copies.
-    el.dataset.open = el.dataset.open === 'true' ? 'false' : 'true';
-  });
+  el.textContent = '';
+  render(() => <${Name} {...props} />, el);
 }
 `;
 };
 
+const islandStyle = (): string => `// Semantic tokens only — a raw hex here is a dark-theme bug and
+// a lint failure. Scoped by the island build, with the class names the server hashed.
+@use '@ultimat3/ui/tokens' as tokens;
+
+.panel {
+  display: flex;
+  align-items: center;
+  gap: tokens.space(2);
+}
+
+.trigger {
+  padding: tokens.space(2);
+  border-radius: tokens.radius('sm');
+  background: tokens.role('surface-raised');
+  color: tokens.role('fg');
+}
+`;
+
 const islandTest = (
   name: string,
-): string => `// The runtime boots an island by calling \`mount\` on whatever the module exports. A renamed or
-// deleted export is a page that renders, serves, passes every other gate and does nothing when
-// clicked — which is exactly the failure nothing else in the build can see.
+  dir: string,
+): string => `// The island the browser actually runs. \`mountIsland\` builds this entry with the same
+// \`buildIslands\` that \`x build\` and \`x dev\` use, imports the emitted chunk the way the hydration
+// runtime does, and drives \`mount\` against a DOM small enough to read.
+//
+// Importing the module and asserting \`typeof mount === 'function'\` proves the file exists, and a
+// file that exists is exactly what ships dead: a renamed export, a dropped handler and a signal
+// that never reaches the DOM all pass that test and none of them survive this one.
+
+import { join } from 'node:path';
+import { buildIslands } from '@ultimat3/cli';
+import {
+  afterAll,
+  beforeAll,
+  describe,
+  expect,
+  type MountedIsland,
+  mountIsland,
+  test,
+} from '@ultimat3/testing';
 
-import { expect, unitTest } from '@ultimat3/testing';
-import * as entry from './${name}.island';
+const APP_ROOT = join(import.meta.dir, ${upToAppRoot(dir)});
+const ISLAND = '${dir}/${name}.island.tsx';
+
+let mounted: MountedIsland;
+
+// The build is a Babel pass plus a browser bundle — seconds, not milliseconds. It lives in
+// \`beforeAll\` with its own timeout because \`test\` takes no third argument: fixtures are resolved
+// per case, so the slow work goes where it can be given one and every case shares the result.
+beforeAll(async () => {
+  mounted = await mountIsland({
+    build: buildIslands,
+    root: APP_ROOT,
+    file: ISLAND,
+    props: { label: 'Open' },
+    // What the server rendered inside the island's wrapper. \`mount\` replaces it.
+    shell: '<span>Open</span>',
+  });
+}, 60_000);
 
-unitTest('${name}.island exports the mount the hydration runtime calls', () => {
-  expect(typeof entry.mount).toBe('function');
+// The fake \`document\` is process-global: left installed it reaches every LATER FILE in the run.
+//
+// \`?.\` on a binding the type says is always set: TypeScript's definite-assignment analysis does not
+// cross the \`beforeAll\` closure, so a setup that REJECTED leaves this undefined at run time — and
+// bun runs \`afterAll\` regardless. Unguarded, the build failure is followed by a \`TypeError:
+// undefined is not an object\` that says nothing, and that second line is the one a tail reads.
+// Nothing is skipped by the guard: \`mountIsland\` restores the process itself when a mount throws.
+afterAll(() => {
+  mounted?.[Symbol.dispose]();
+});
+
+describe('the ${name} island', () => {
+  test('mount replaces the server shell', () => {
+    expect(mounted.find('span')).toBeNull();
+    // Solid compiles to real DOM calls; a chunk that fell back to the classic React factory names
+    // a global that is not in it, and \`Bun.build\` answers \`success: true\` over that all the same.
+    expect(mounted.code).not.toMatch(/\\bReact\\b/);
+  });
+
+  test('a click reaches the DOM through the signal', () => {
+    expect(mounted.text('[data-role="count"]')).toBe('0');
+    // \`false\` means no handler ran — an island whose onClick never reached the DOM looks identical
+    // to a selector typo otherwise.
+    expect(mounted.fire('button', 'click')).toBe(true);
+    expect(mounted.text('[data-role="count"]')).toBe('1');
+  });
 });
 `;
 
@@ -62,6 +172,7 @@ export function islandFiles(rawName: string, options: IslandOptions): readonly G
   const dir = options.dir.replace(/\/+$/, '');
   return [
     { path: `${dir}/${name}.island.tsx`, contents: islandSource(name) },
-    { path: `${dir}/${name}.island.test.ts`, contents: islandTest(name) },
+    { path: `${dir}/${name}.module.scss`, contents: islandStyle() },
+    { path: `${dir}/${name}.island.test.ts`, contents: islandTest(name, dir) },
   ];
 }

package/src/templates/resource-form-island.ts

@@ -0,0 +1,279 @@
+// The slice's client entry: `x g resource <name>` emits its form as an ISLAND, because that is the
+// one shape the framework compiles for a browser. A plain `.tsx` with a signal and an `onSubmit`
+// is not a smaller version of this — the island glob never discovers it, and a server render drops
+// every `on*` prop (`packages/render/src/html.ts`) and reads each signal exactly once.
+
+// Bun ships no path API, and the one arithmetic this file does is a specifier: the island's path
+// seen from the page's directory, which `island-bundle.ts` resolves the same way at build time.
+import { posix } from 'node:path';
+import { upToAppRoot } from './island';
+import type { GeneratedFile, NameSet } from './naming';
+
+/**
+ * What the PAGE has to write, which is not what the island's own directory would suggest.
+ *
+ * `island({ src })` resolves against the route file, and `x g resource widget` writes its page at
+ * `apps/web/app/widgets/` while the island lands in `apps/web/app/widget/` — so the `'./…'` this
+ * file used to print resolved to `apps/web/app/widgets/widget-form.island.tsx`, a path the build
+ * never bundles, and an author following the comment got `X_ISLAND_INVALID`. Derived from the two
+ * directories rather than written down, so it cannot disagree with where the files actually go.
+ */
+export const formIslandSpecifier = (feature: NameSet, dir: string, pageDir: string): string => {
+  const relative = posix.join(posix.relative(pageDir, dir), `${feature.kebab}-form.island.tsx`);
+  return relative.startsWith('.') ? relative : `./${relative}`;
+};
+
+const formIslandSource = (
+  feature: NameSet,
+  specifier: string,
+): string => `// ${feature.pascal}Form: the only module of the ${feature.kebab} slice a browser downloads.
+//
+// The page names this file by SPECIFIER, never by import — and the specifier is resolved against
+// the PAGE, which is one directory across from this one:
+//   const ${feature.pascal}Form = island({
+//     src: '${specifier}',
+//     props: ['endpoint', 'locale', 'labels'],
+//   });
+//   <${feature.pascal}Form endpoint={derivePath('create${feature.pascal}').path} locale={locale} labels={labels} />
+// A string has no import edge, so the page's bundle graph stays the page's (axiom 6).
+
+import { Button, Form, Input, setSolidRuntime, UiProvider } from '@ultimat3/ui';
+import type { JSX } from 'solid-js';
+import * as solidRuntime from 'solid-js';
+import { createSignal } from 'solid-js';
+import { render } from 'solid-js/web';
+import styles from './ui.module.scss';
+
+/** Every string this module renders, and the path it posts to. An island's props cross the seam as
+ *  JSON inside the document, so \`t()\`'s catalog cannot travel — the server translates. */
+export interface ${feature.pascal}FormProps {
+  /** \`derivePath('create${feature.pascal}').path\`, minted on the server: one namer for the route. */
+  readonly endpoint: string;
+  /** The request's own locale. A browser has no ambient one the server ever agreed to. */
+  readonly locale: string;
+  readonly labels: {
+    readonly title: string;
+    readonly submit: string;
+    readonly saved: string;
+    readonly retry: string;
+  };
+}
+
+type SaveState = 'idle' | 'saved' | 'failed';
+
+/**
+ * Presentation only: the action this submits to owns validation server-side, so the form never
+ * re-implements the invariant — a blank title fails at the boundary, not in the DOM.
+ *
+ * A plain \`fetch\` to the path the server minted, not the typed client: \`rpc()\` pulls
+ * \`@ultimat3/action\` into the chunk, which is larger than everything else here put together. The
+ * naming rule is still the framework's; only the transport is second.
+ */
+function ${feature.pascal}FormBody(props: ${feature.pascal}FormProps): JSX.Element {
+  const [title, setTitle] = createSignal('');
+  const [state, setState] = createSignal<SaveState>('idle');
+
+  // A rejected \`fetch\` — offline, DNS, an aborted request — is the same OUTCOME as a refused one,
+  // and it is the one \`retry\` exists for. Without the catch, \`setState\` is never reached: the
+  // status line stays empty, and the rejection escapes the \`void send()\` below as an unhandled one.
+  const send = async (): Promise<void> => {
+    try {
+      const response = await fetch(props.endpoint, {
+        method: 'POST',
+        headers: { 'content-type': 'application/json' },
+        body: JSON.stringify({ title: title() }),
+      });
+      setState(response.ok ? 'saved' : 'failed');
+    } catch {
+      setState('failed');
+    }
+  };
+
+  const status = (): string => {
+    if (state() === 'saved') return props.labels.saved;
+    return state() === 'failed' ? props.labels.retry : '';
+  };
+
+  return (
+    <Form
+      class={styles.item}
+      onSubmit={(event) => {
+        event.preventDefault();
+        void send();
+      }}
+    >
+      <Input
+        aria-label={props.labels.title}
+        value={title()}
+        onInput={(event) => setTitle(event.currentTarget.value)}
+      />
+      <Button type="submit">{props.labels.submit}</Button>
+      <p data-role="status" role="status" aria-live="polite">
+        {status()}
+      </p>
+    </Form>
+  );
+}
+
+/**
+ * The one export the hydration runtime calls — \`import(entry).then((m) => m.mount(el, props))\`.
+ *
+ * \`setSolidRuntime\` comes FIRST and it 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. Delete the line and the first \`<UiProvider>\` render throws X_UI_RUNTIME_MISSING —
+ * loud on purpose, because a DOM render that lost its runtime is a theme toggle that does nothing.
+ *
+ * The shell is cleared first: Solid's \`render\` APPENDS when the container already has children,
+ * so without it the server's markup stays on screen above a second, live copy of the same thing.
+ */
+export function mount(el: HTMLElement, props: ${feature.pascal}FormProps): void {
+  setSolidRuntime(solidRuntime);
+  el.textContent = '';
+  render(
+    () => (
+      <UiProvider locale={props.locale}>
+        <${feature.pascal}FormBody {...props} />
+      </UiProvider>
+    ),
+    el,
+  );
+}
+`;
+
+const formIslandTest = (
+  feature: NameSet,
+  dir: string,
+): string => `// The form the browser actually runs. \`mountIsland\` builds this entry with the same
+// \`buildIslands\` that \`x build\` and \`x dev\` use, imports the emitted chunk the way the hydration
+// runtime does, and drives \`mount\` against a DOM small enough to read.
+//
+// It is the test that keeps this file a CLIENT entry. A generated form that only typechecks is
+// what shipped before: server-rendered, every \`on*\` prop dropped, every signal read once.
+
+import { join } from 'node:path';
+import { buildIslands } from '@ultimat3/cli';
+import {
+  afterAll,
+  beforeAll,
+  describe,
+  expect,
+  type FakeElement,
+  type MountedIsland,
+  mountIsland,
+  test,
+} from '@ultimat3/testing';
+
+const APP_ROOT = join(import.meta.dir, ${upToAppRoot(dir)});
+const ISLAND = '${dir}/${feature.kebab}-form.island.tsx';
+const ENDPOINT = '/api/${feature.kebab}/create-${feature.kebab}';
+
+const LABELS = { title: 'Title', submit: 'Save', saved: 'Saved', retry: 'Try again' };
+
+const calls: { url: string; body: Record<string, unknown> }[] = [];
+
+/** One stub, both outcomes: the mount costs seconds, so the network's answer is a switch. */
+let networkFails = false;
+
+let mounted: MountedIsland;
+
+// The build is a Babel pass plus a browser bundle — seconds, not milliseconds. It lives in
+// \`beforeAll\` with its own timeout because \`test\` takes no third argument: fixtures are resolved
+// per case, so the slow work goes where it can be given one and every case shares the result.
+beforeAll(async () => {
+  mounted = await mountIsland({
+    build: buildIslands,
+    root: APP_ROOT,
+    file: ISLAND,
+    props: { endpoint: ENDPOINT, locale: 'en', labels: LABELS },
+    // What the server rendered inside the island's wrapper. \`mount\` replaces it.
+    shell: '<p>Loading</p>',
+    globals: {
+      fetch: (url: string, init: { body: string }): Promise<{ ok: boolean }> => {
+        calls.push({ url, body: JSON.parse(init.body) as Record<string, unknown> });
+        // What a browser rejects with when there is no network. Not a response: \`response.ok\`
+        // is never read on this path, which is exactly why the form has to catch it.
+        return networkFails
+          ? Promise.reject(new TypeError('Failed to fetch'))
+          : Promise.resolve({ ok: true });
+      },
+    },
+  });
+}, 60_000);
+
+// The fake \`document\` is process-global: left installed it reaches every LATER FILE in the run.
+//
+// \`?.\` on a binding the type says is always set: TypeScript's definite-assignment analysis does not
+// cross the \`beforeAll\` closure, so a setup that REJECTED leaves this undefined at run time — and
+// bun runs \`afterAll\` regardless. Unguarded, the build failure is followed by a \`TypeError:
+// undefined is not an object\` that says nothing, and that second line is the one a tail reads.
+// Nothing is skipped by the guard: \`mountIsland\` restores the process itself when a mount throws.
+afterAll(() => {
+  mounted?.[Symbol.dispose]();
+});
+
+/**
+ * One mount, driven as a session: the cases below run in order against the same island, because
+ * building the real chunk costs seconds and repeating it per case would pay them for state each
+ * case sets up anyway. What each one asserts is independent.
+ */
+describe('the ${feature.kebab} form island', () => {
+  test('mount replaces the server shell with the editor', () => {
+    expect(mounted.find('p')?.getAttribute('data-role')).toBe('status');
+    // Solid compiles to real DOM calls; a chunk that fell back to the classic React factory names
+    // a global that is not in it, and \`Bun.build\` answers \`success: true\` over that all the same.
+    expect(mounted.code).not.toMatch(/\\bReact\\b/);
+  });
+
+  test('the field tracks, and submit posts what was typed', async () => {
+    const field: FakeElement | null = mounted.find('input');
+    expect(field).not.toBeNull();
+    if (field !== null) field.value = 'First ${feature.camel}';
+    // \`false\` means no handler ran — an island whose onInput never reached the DOM looks
+    // identical to a selector typo otherwise.
+    expect(mounted.fire(field, 'input')).toBe(true);
+    expect(mounted.fire('form', 'submit', { preventDefault: () => {} })).toBe(true);
+    await Promise.resolve();
+
+    expect(calls).toEqual([{ url: ENDPOINT, body: { title: 'First ${feature.camel}' } }]);
+  });
+
+  test('the status line answers the response', () => {
+    // The signal reached the DOM: an eager JSX factory renders '' here and never runs again.
+    expect(mounted.text('[data-role="status"]')).toBe(LABELS.saved);
+  });
+
+  test('a request that never got a response still reaches retry', async () => {
+    // The outcome \`retry\` is FOR. A \`fetch\` that rejects reaches no \`response.ok\`, so without
+    // the catch in \`send\` the status line stays on its last value and the rejection escapes.
+    networkFails = true;
+    expect(mounted.fire('form', 'submit', { preventDefault: () => {} })).toBe(true);
+    await Promise.resolve();
+    await Promise.resolve();
+
+    expect(mounted.text('[data-role="status"]')).toBe(LABELS.retry);
+  });
+});
+`;
+
+/**
+ * The slice's form, as the one client shape: `<dir>/<feature>-form.island.tsx` plus its test.
+ *
+ * `pageDir` is the directory of the page that declares it — the caller's, because only the caller
+ * runs both generators and knows where the other one put its file.
+ */
+export function formIslandFiles(
+  feature: NameSet,
+  dir: string,
+  pageDir: string,
+): readonly GeneratedFile[] {
+  return [
+    {
+      path: `${dir}/${feature.kebab}-form.island.tsx`,
+      contents: formIslandSource(feature, formIslandSpecifier(feature, dir, pageDir)),
+    },
+    {
+      path: `${dir}/${feature.kebab}-form.island.test.ts`,
+      contents: formIslandTest(feature, dir),
+    },
+  ];
+}