@starci/hfs 4.9.5 → 4.9.8

package/CHANGELOG.md

@@ -1,5 +1,29 @@
 # Changelog
 
+## 4.9.8 - 2026-10-28
+
+- Added: `starci app add page <route> --tabs a,b` puts the page tabs in the `Page` header as link tabs (Grammar 0.15.6): the first tab is the route itself, every other one its sub-route `<route>/<tab>`; the server owner resolves the labels (`<page>.tabs.label` and `<page>.tabs.items.<tab>` in every catalog) and passes no state or handler, and the stories carry the tabs. Fewer than two or repeated tab ids are refused (`HFS_ADD_TABS_INVALID`).
+- Changed: `starci app add overlay --form` keeps the decision group in the shell's footer: the way out first, then `<Button type="submit" form="<id>">` naming the body's `Form id` (Grammar 0.15.6 `Button form`), instead of buttons inside the form; the shell no longer passes `closeLabel`, since the footer offers the way out.
+- Fixed: the skeleton's `AppHomePage` (full and lite) and the landing app's `LandingPage` draw one Grammar `Page` with the title (and the landing's lede as `description`) in its header, instead of a bare `Heading` and blocks, which R325 (`@starci/eslint-grammar-core` 0.15.6) now refuses.
+- Changed: the bundled canon pins name the Grammar family 0.15.6 and hfs 4.9.8.
+
+## 4.9.7 - 2026-10-28
+
+- Added: `starci app add block|composite|branch|leaf|page|overlay|layout` writes every front-end unit already in the canon's shape, from `templates/fe/units` (`scaffold/add-fe-unit.mjs`, `add-fe-page.mjs`, `add-fe-overlay.mjs`, `add-fe-layout.mjs`), with its copy in every catalog; nothing that exists is overwritten.
+  - `block <name> [--shapes a,b,c] [--read <read>]`: the connected half folds one `useQuery<Read>Swr` read through `slotOfSwr`/`mapSlot` and takes its shape from the read's `status` (the placeholder's while it loads); the pure half draws through `SlotView`, and with shapes declares `X_SHAPES`, `XShape = (typeof X_SHAPES)[number]` and the exhaustive switch (FE-FUNCTION-7); `stories/blocks/<Name>.stories.tsx` has one story per shape and the loading twin paired by `parameters.dna`. The first block writes the app's one copy of the status owners (`DataSlot`, `SlotLabels`, `slotOfSwr`, `mapSlot`, `loadingSlot`, `useSlotLabels`, `SlotView`) and the shared `status` namespace.
+  - `composite`, `branch`, `leaf`: one file of Grammar parts on resolved fields; in a front end of two or more apps with the shared ui package they, and `SlotView`, go to that package and its barrel (R91), `DataSlot` and `SlotLabels` declared beside `SlotView` and re-exported by `modules/types`.
+  - `page <route> [--blocks a,b]`: the route's `page`, `loading` and `error` files, the server page owner drawing one Grammar `Page` (R325) with the trail and heading in its header and the blocks (or its empty sentence) in its body, its loading view (the same page with `isSkeleton`, STATE-8), its error page (the page with one negative Alert) and the stories pairing the page with its loading view.
+  - `overlay <name> --kind modal|drawer [--form]`: a `Dialog` or trailing `Drawer` owner whose connected half owns its open state; way out first and commit last, in the footer or, with `--form`, as the last row of a Form over a one-column `FormGrid`; stories closed and open.
+  - `layout <segment> [--blocks a,b]`: the segment's layout file and its owner composing `PrimaryRailLayout`, the page in its primary region and the blocks in its rail.
+  - Spec: `src/fe-unit-shape-slot.spec.mjs` adds every kind to a scaffolded full app and lints it with the starci-fe canon and the core Grammar's rules, and type-checks them under the next preset.
+- Changed: `starci app add` prints its `registered patterns` line only for a noun that registers something in hfs.json.
+- Changed: the bundled canon pins name hfs 4.9.7.
+
+## 4.9.6 - 2026-10-28
+
+- Changed: the bundled canon pins name hfs 4.9.6, the Grammar family 0.15.5 (grammar, eslint-grammar-core, eslint-grammar-offset-pop) and eslint-canon-fe 9.4.5.
+- Changed: the app pre-push hook runs `node node_modules/starci-harness/dist/main.js deps check` after the bundled push gate (under `set -e`), so a push whose committed @starci pins npm cannot install, or whose local package copies run ahead of npm, is refused; RT_HOOK_SHAPE (R225) requires the call. Spec: `src/pre-push-hook.spec.mjs`.
+
 ## 4.9.5 - 2026-10-28
 
 - Added: the bundled rule catalog carries R324 (`FE_PAGE_TABS_OUTSIDE_HEADER`, `page-tabs-in-header`) and R325 (`FE_ROUTE_PAGE_OUTSIDE_PAGE`, `route-page-is-one-page`), both enforced by `@starci/eslint-grammar-core`, and their failure-code guidance.

package/README.md

@@ -10,6 +10,9 @@ Every command runs at the app root. A side is judged with its folder as the root
 ```sh
 starci app scaffold <name> [--into <dir>] [--edition full|lite] [--cwd <dir>]
 starci app add <api|webhook|realtime|saga|job|reactor|queue|projection|cli|table|app> <name> [--fe] [--no-types] [options] [--cwd <dir>]
+starci app add <block|composite|branch|leaf> <name> [--shapes a,b,c] [--read <read>] [--app <fe app>] [--cwd <dir>]
+starci app add <page|layout> <route> [--blocks a,b] [--tabs a,b] [--app <fe app>] [--cwd <dir>]
+starci app add overlay <name> --kind modal|drawer [--form] [--app <fe app>] [--cwd <dir>]
 starci app lint [--cwd <dir>] [--changed <file>...] [--workspace <dir>] [--fix] [--format text|json] [--sonar <file>]
 starci app sync (--check | --write) [--cwd <dir>]
 starci app check [--cwd <dir>] [--json] [--fast] [--base <ref>] [--db-types]
@@ -24,6 +27,27 @@ starci app secret list|show|set|gen ... [--cwd <dir>]
 starci app hygiene [--cwd <dir>]
 ```
 
+`starci app add` writes every front-end unit, in either edition, already in the shape of the harness's `contexts/code/fe`
+and `contexts/ui`, from `templates/fe/units`, with its copy in every catalog; nothing that exists is overwritten.
+
+- `block`: its connected half (one `useQuery<Read>Swr` read folded by `slotOfSwr` and `mapSlot`, its labels and the retry)
+  over its pure half of Grammar parts drawn through `SlotView`, plus `stories/blocks/<Name>.stories.tsx` (one story per drawn
+  shape and the loading twin, paired for the DNA gate). `--shapes a,b,c` adds the `X_SHAPES` inventory, the `XShape` union
+  and the exhaustive switch, and the connected half takes the shape from the read's `status`. The first block writes the
+  app's one copy of the status owners and the shared `status` catalog namespace (FE-ERROR-1).
+- `composite`, `branch`, `leaf`: one file of Grammar parts taking resolved fields. In a front end of two or more apps with
+  the shared ui package these, and `SlotView`, go to that package and its barrel (R91).
+- `page <route>`: `app/[locale]/<route>/{page,loading,error}.tsx`, the server page owner `<Name>Page` drawing one Grammar
+  `Page` (R325) whose header carries the trail and the heading and whose body composes `--blocks` (blocks that take no input;
+  else the page's empty sentence) and, with `--tabs a,b`, the page tabs in its header as link tabs (the first tab the route, each
+  other one its sub-route `<route>/<tab>`, the selected tab the current path's), its loading view `<Name>LoadingPage` (the same page drawn with `isSkeleton`, STATE-8),
+  `<Name>ErrorPage` (the page with one negative Alert), and the stories pairing the page with its loading view.
+- `overlay <name> --kind modal|drawer`: `features/overlays/<Name>Overlay`, a `Dialog` or a trailing `Drawer` whose connected
+  half owns its open state; its decision group puts the way out first and the commit last, always in the footer; with `--form`
+  the body holds a Form with an `id` over a one-column `FormGrid` and the footer's commit submits it by `form="<id>"`; stories draw it closed and open.
+- `layout <segment>`: `app/[locale]/<segment>/layout.tsx` and `features/layouts/<Name>Layout`, which composes Grammar's
+  `PrimaryRailLayout`: the routed page in its primary region, `--blocks` in its rail. A frame never insets a page.
+
 ## Lite edition
 
 Lite is the smaller edition of the same HFS standard, not another profile or engine. The declaration sets `edition` to `lite`;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@starci/hfs",
-  "version": "4.9.5",
+  "version": "4.9.8",
   "description": "The StarCi app command implementation for scaffolding, linting, checking and synchronizing one product repository.",
   "type": "module",
   "license": "MIT",

package/runtime/knowledge/hfs/canon-pins.yaml

@@ -31,7 +31,7 @@ pins:
     source: packages/event-stream/package.json
     why: 'the one server-sent-events client of every front end (fe-stack event-stream, owner:event-stream-package): the transport client layer (modules/api/sse/clients) creates one instance for the app with the bearer token source and the stream operations follow on it; it carries Last-Event-ID resume, the capped doubling backoff, the heartbeat timeout, the single 401 renewal and the useSWRSubscription adapter, so no app keeps a hand-written reader.'
   '@starci/grammar':
-    version: 0.15.4
+    version: 0.15.6
     group: starci
     install: registry
     side: fe
@@ -45,21 +45,21 @@ pins:
     source: packages/eslint-canon-be/package.json
     why: 'the back-end ESLint canon: `loadHfs(import.meta.url)` of be/eslint.config.mjs finds the app-root hfs.json (kind app) and gives every linted file the view of the be side, and the project graph is built per side; its bundled runtime copies (slots, canon-pins, failure codes, the architecture machine) put .starcistacks and .sops.yaml at the app root; `starciBeConfig({ hfs: loadHfs(import.meta.url) })` is the typed factory and the BE-CONVENTION laws are its rules.'
   '@starci/eslint-canon-fe':
-    version: 9.4.4
+    version: 9.4.5
     group: starci
     install: registry
     side: fe
     source: packages/eslint-canon-fe/package.json
     why: 'the front-end ESLint canon: `loadHfs(import.meta.url)` of fe/eslint.config.mjs finds the app-root hfs.json (kind app) and gives every linted file the view of the fe side, and the project graph is built per side; its bundled runtime copies (slots, canon-pins, failure codes, the architecture machine) put .starcistacks and .sops.yaml at the app root; the front end has no tests (FE_NO_TESTS R97 in hfs) and no-vietnamese-in-source (R91) applies.'
   '@starci/eslint-grammar-core':
-    version: 0.15.4
+    version: 0.15.6
     group: starci
     install: registry
     side: fe
     source: packages/eslint-grammar-core/package.json
     why: 'the StarCi Grammar component API lint, versioned with @starci/grammar; front ends compose this family package with the universal FE canon.'
   '@starci/eslint-grammar-offset-pop':
-    version: 0.15.4
+    version: 0.15.6
     group: starci
     install: registry
     side: fe
@@ -106,7 +106,7 @@ pins:
     source: packages/ai-router/package.json
     why: 'the AI pool router of a back end: a NestJS module that routes OpenAI-compatible chat, stream and embeddings calls across keys, models and providers, with @starci/ai-router/testing for its specs; @starci/jest-preset compiles it as an ESM-only dependency.'
   '@starci/hfs':
-    version: 4.9.5
+    version: 4.9.8
     group: starci
     install: registry
     side: both

package/runtime/knowledge/hfs/rules.yaml

@@ -3894,7 +3894,7 @@ rules:
       - {kind: runtime, id: protected-zone, at: scripts/hfs/runtime-rules/rights-policy.mjs}
   - id: R225
     code: "RT_HOOK_SHAPE"
-    law: "The app hook templates keep the gate model: pre-commit is L0 only (no typecheck or test run); pre-push invokes the bundled scripts/guards/release-push-gate.mjs policy for fast-forward main, a clean outgoing secret scan and annotated v* tags. It runs no build, test, typecheck or lint."
+    law: "The app hook templates keep the gate model: pre-commit is L0 only (no typecheck or test run); pre-push invokes the bundled scripts/guards/release-push-gate.mjs policy for fast-forward main, a clean outgoing secret scan and annotated v* tags, then the harness's `starci deps check` (every committed @starci pin installable from npm, no local package copy ahead of npm). It runs no build, test, typecheck or lint."
     scope: runtime
     kinds: [check]
     gates: [land, runtime]

package/runtime/scripts/hfs/runtime-rules/hook-shape.mjs

@@ -1,7 +1,8 @@
 // hook-shape.mjs - RT_HOOK_SHAPE (knowledge/hfs/rules.yaml, gate runtime): the app hook templates keep the gate model.
 //   pre-commit  L0 only: no typecheck and no test run (`test:` scripts, npm test, jest, vitest, a spec). Types and the targeted specs
 //               belong to the op gate.
-//   pre-push    the bundled push gate owns fast-forward main, annotated tags and the secret scan; no build, test or lint run.
+//   pre-push    the bundled push gate owns fast-forward main, annotated tags and the secret scan, then `starci deps check` the
+//               app's @starci pins; no build, test or lint run.
 // Guard hooks keep their host timeout above the runtime's own input, verdict, cleanup and output budgets.
 // Comments are not judged (the templates explain what they do not run). Pure apart from ctx.read.
 import { shellCommandSource } from '../../lib/shell-source.mjs';
@@ -23,7 +24,7 @@ const PRE_PUSH_FORBIDDEN = [
   [/\btypecheck\b/, 'a typecheck'],
   [/\blint\b/, 'a lint run'],
 ];
-const PRE_PUSH_MARKERS = ["node --input-type=module -e", "import { main } from '@starci/hfs/runtime/scripts/guards/release-push-gate.mjs'", 'process.exit(await main())'];
+const PRE_PUSH_MARKERS = ["node --input-type=module -e", "import { main } from '@starci/hfs/runtime/scripts/guards/release-push-gate.mjs'", 'process.exit(await main())', 'node node_modules/starci-harness/dist/main.js deps check'];
 
 const finding = (file, message) => ({ code: CODE, level: 'error', path: file, message: `${CODE} ${file}: ${message}` });
 
@@ -39,7 +40,7 @@ function fileHookShapeFindings({ path: file, name, text }) {
     const missing = PRE_PUSH_MARKERS.filter((marker) => !body.includes(marker));
     if (missing.length) {
       const markers = missing.map((m) => `\`${m}\``).join(', ');
-      found.push(finding(file, `the push gate lacks the bundled gate marker${missing.length === 1 ? '' : 's'} ${markers}; it must invoke the shared fast-forward, annotation and secret-scan policy`));
+      found.push(finding(file, `the push gate lacks the bundled gate marker${missing.length === 1 ? '' : 's'} ${markers}; it must invoke the shared fast-forward, annotation and secret-scan policy and the dependency push gate`));
     }
   }
   return found;

package/scaffold/add-fe-layout.mjs

@@ -0,0 +1,46 @@
+// starci app add layout <segment> [--blocks a,b] [--app <fe app>] - one route-segment layout in the canon's shape.
+//
+//   starci app add layout settings                          app/[locale]/settings/layout.tsx and features/layouts/SettingsLayout
+//   starci app add layout settings --blocks settings-nav-block   the blocks fill the frame's rail
+//
+// The route file only mounts the layout owner (contexts/code/fe architecture.md FE-ARCHITECTURE-1). The owner is a server
+// component that composes a Grammar layout frame, `PrimaryRailLayout`: the routed page is its primary region and the `--blocks`
+// (existing blocks of components/blocks) its rail. A frame places regions only and never insets a page or draws a page head;
+// `Page` owns both (contexts/ui/components page-header.md). The owner has no copy to resolve, so it has no pure half and no story:
+// the frame's look is the Grammar's and the regions are the page's and the blocks'. The bodies are templates/fe/units/layout/.
+import fs from 'node:fs';
+import path from 'node:path';
+import { ScaffoldError, pascalOf } from './service.mjs';
+import { appOf, declarationOf, fill, writeNew } from './add-fe-unit.mjs';
+import { blockParts, blocksOf, routeSegmentsOf } from './add-fe-page.mjs';
+
+/**
+ * Generates one route-segment layout in the app at `repoRoot`.
+ *
+ * @param {{ repoRoot: string, segment: string, options?: { app?: string, blocks?: string } }} input - The app root, the segment under [locale] and the options.
+ * @returns {{ created: string[] }} The files written, relative to the app root.
+ */
+export function addFeLayout({ repoRoot, segment, options = {} }) {
+  const segments = routeSegmentsOf(segment);
+  const appBase = `fe/apps/${appOf(declarationOf(repoRoot), options.app)}`;
+  const Name = `${pascalOf(segments.join('-'))}Layout`;
+  const route = `${appBase}/src/app/[locale]/${segments.join('/')}/layout.tsx`;
+  const owner = `${appBase}/src/features/layouts/${Name}`;
+  for (const relative of [route, owner]) {
+    if (fs.existsSync(path.join(repoRoot, ...relative.split('/')))) throw new ScaffoldError('HFS_ADD_EXISTS', `${relative} already exists; starci app add never overwrites a unit`);
+  }
+  const blocks = blocksOf(repoRoot, appBase, options.blocks);
+  const parts = blockParts(blocks, '                ');
+  const vars = {
+    Name, segment: segments.join('/'),
+    blockImports: parts.imports,
+    railDoc: blocks.length === 0 ? 'leaves its rail empty until a block fills it' : `fills its rail with ${blocks.join(', ')}`,
+    frame: blocks.length === 0
+      ? '<PrimaryRailLayout primary={props.content} />'
+      : ['(', '    <PrimaryRailLayout', '        primary={props.content}', '        rail={', '            <>', parts.jsx, '            </>', '        }', '    />', ')'].join('\n'),
+  };
+  const created = [];
+  writeNew(created, repoRoot, route, fill('layout/route-layout.tsx.tpl', vars));
+  writeNew(created, repoRoot, `${owner}/index.tsx`, fill('layout/index.tsx.tpl', vars));
+  return { created };
+}

package/scaffold/add-fe-overlay.mjs

@@ -1 +1,109 @@
+// starci app add overlay <name> --kind modal|drawer [--form] [--app <fe app>] - one overlay owner in the canon's shape.
+//
+//   starci app add overlay invite-member --kind modal          features/overlays/InviteMemberOverlay: a Dialog
+//   starci app add overlay edit-details --kind drawer --form   a Drawer from the trailing edge holding a one-column form
+//
+// The two shells an overlay owner may draw are Grammar's `Dialog` (a modal) and `Drawer` (contexts/ui/components
+// dialog-drawer.md). The connected half (`"use client"`, an overlay entry of FE-BOUNDARY-2) owns whether it is open and resolves
+// every label; the pure half takes `{ props, on }` of atoms (FE-FUNCTION-2). The decision group puts the way out first and the
+// commit last (action-group.md `decision`, CTA-5), always in the shell's footer. With `--form`, the body holds a Form with an `id`
+// whose fields sit in a one-column `FormGrid` (text-field.md `narrow`), and the footer's commit is `type="submit"` with
+// `form="<id>"`, so it submits that form from outside it. The bodies are templates/fe/units/overlay/; the stories draw it closed and open. A page or layout owner mounts it.
+import fs from 'node:fs';
+import path from 'node:path';
+import { ScaffoldError, camelOf, pascalOf } from './service.mjs';
+import { addCatalogNamespaces, appOf, declarationOf, fill, humanOf, words, writeNew } from './add-fe-unit.mjs';
 
+/** The shells an overlay may be: `--kind` to Grammar component. */
+const SHELLS = Object.freeze({ modal: 'Dialog', drawer: 'Drawer' });
+
+/** The copy of a new overlay, by catalog locale; any other locale takes the English words. */
+const OVERLAY_COPY = Object.freeze({
+  en: { open: 'Open', cancel: 'Cancel', submit: 'Save', description: 'Describe the task this overlay holds.', name: 'Name' },
+  vi: { open: 'Mở', cancel: 'Hủy', submit: 'Lưu', description: 'Mô tả việc mà lớp phủ này đảm nhận.', name: 'Tên' },
+});
+
+/** The variables of the overlay templates for one shell, with or without a form. */
+function overlayVars({ Name, nameKebab, shell, form }) {
+  const decision = (indent, cancel, commit) => [
+    `${indent}<Button intent="dismiss" onPress={${cancel}}>`,
+    `${indent}    {props.props.cancelLabel}`,
+    `${indent}</Button>`,
+    `${indent}${commit}`,
+    `${indent}    {props.props.submitLabel}`,
+    `${indent}</Button>`,
+  ].join('\n');
+  const shellAttributes = shell === 'Drawer' ? '        placement="right"\n' : '';
+  /** The shell's footer: the decision group, the way out first and the commit last. */
+  const footer = (commit) => [
+    '        footer={(close) => (',
+    '            <>',
+    decision('                ', 'close', commit),
+    '            </>',
+    '        )}',
+    '',
+  ].join('\n');
+  if (form) {
+    const formId = `${nameKebab}-form`;
+    return {
+      grammarImports: ['Button', shell, 'Form', 'FormGrid', 'Input'].sort().join(', '),
+      labelMembers: '        readonly nameLabel: string\n',
+      labelsResolved: '                nameLabel: t("name"),\n',
+      labelsFixture: '    nameLabel: "Name",\n',
+      submitMember: '        readonly submit: (input: FormData) => void\n',
+      submitHandler: 'submit: () => setIsOpen(false)',
+      submitFixture: 'submit: () => undefined',
+      doc: `The ${shell} holding one form: its fields in one column in the body, the footer's way out first and the submit, which names the form, last.`,
+      shellAttributes,
+      footer: footer(`<Button type="submit" form="${formId}" intent="commit">`),
+      body: [
+        `        <Form id="${formId}" label={props.props.title} onSubmit={props.on.submit}>`,
+        '            <FormGrid columns={1}>',
+        `                <Input id="${nameKebab}-name" name="name" label={props.props.nameLabel} isRequired />`,
+        '            </FormGrid>',
+        '        </Form>',
+      ].join('\n'),
+    };
+  }
+  return {
+    grammarImports: ['Button', shell, 'Text'].sort().join(', '),
+    labelMembers: '        readonly description: string\n',
+    labelsResolved: '                description: t("description"),\n',
+    labelsFixture: '    description: "Describe the task this overlay holds.",\n',
+    submitMember: '        readonly confirm: () => void\n',
+    submitHandler: 'confirm: () => setIsOpen(false)',
+    submitFixture: 'confirm: () => undefined',
+    doc: `The ${shell} of one task: its sentence, and the footer's way out first and commit last.`,
+    shellAttributes,
+    footer: footer('<Button intent="commit" onPress={props.on.confirm}>'),
+    body: '        <Text>{props.props.description}</Text>',
+  };
+}
+
+/**
+ * Generates one overlay owner in the app at `repoRoot`.
+ *
+ * @param {{ repoRoot: string, name: string, options?: { app?: string, kind?: string, form?: boolean } }} input - The app root, the overlay name and the options.
+ * @returns {{ created: string[] }} The files written or extended, relative to the app root.
+ */
+export function addFeOverlay({ repoRoot, name, options = {} }) {
+  const shell = SHELLS[options.kind];
+  if (shell === undefined) throw new ScaffoldError('HFS_ADD_OVERLAY_KIND', `an overlay names its shell with --kind ${Object.keys(SHELLS).join('|')}; those are the only two`);
+  const base = pascalOf(name);
+  if (!/^[A-Z][A-Za-z0-9]*$/.test(base)) throw new ScaffoldError('HFS_ADD_NAME_INVALID', `${name} is not a unit name`);
+  const Name = base.endsWith('Overlay') ? base : `${base}Overlay`;
+  const appBase = `fe/apps/${appOf(declarationOf(repoRoot), options.app)}`;
+  const folder = `${appBase}/src/features/overlays/${Name}`;
+  if (fs.existsSync(path.join(repoRoot, ...folder.split('/')))) throw new ScaffoldError('HFS_ADD_EXISTS', `${folder} already exists; starci app add never overwrites a unit`);
+  const form = options.form === true;
+  const vars = { Name, shell, nameCamel: camelOf(Name), title: humanOf(words(base).join('-')), ...overlayVars({ Name, nameKebab: words(Name).join('-'), shell, form }) };
+  const created = [];
+  writeNew(created, repoRoot, `${folder}/index.tsx`, fill('overlay/index.tsx.tpl', vars));
+  writeNew(created, repoRoot, `${folder}/component.tsx`, fill('overlay/component.tsx.tpl', vars));
+  writeNew(created, repoRoot, `${appBase}/stories/overlays/${Name}.stories.tsx`, fill('overlay/stories.tsx.tpl', vars));
+  addCatalogNamespaces(created, { repoRoot, appBase }, (locale) => {
+    const copy = OVERLAY_COPY[locale] ?? OVERLAY_COPY.en;
+    return { [vars.nameCamel]: { title: vars.title, open: copy.open, ...(form ? { name: copy.name } : { description: copy.description }), cancel: copy.cancel, submit: copy.submit } };
+  });
+  return { created };
+}

package/scaffold/add-fe-page.mjs

@@ -1 +1,138 @@
+// starci app add page <route> [--blocks a,b] [--tabs a,b] [--app <fe app>] - one route page of the locale segment, in the canon's shape.
+//
+//   starci app add page handoffs                       app/[locale]/handoffs/{page,loading,error}.tsx, HandoffsPage, HandoffsErrorPage
+//   starci app add page settings/billing --blocks invoice-list-block
+//   starci app add page settings --tabs profile,billing   header.tabs: Profile at /settings, Billing at /settings/billing
+//
+// The route files only adapt (contexts/code/fe function.md FE-FUNCTION-5, architecture.md FE-ARCHITECTURE-1, boundaries.md
+// FE-BOUNDARY-1). The page owner `features/pages/<Name>Page` is a server component that resolves its copy and draws one Grammar
+// `Page` (R325) whose header carries the trail and the heading (page commands and page tabs go to the header, R324), and whose body
+// composes the `--blocks` (blocks of components/blocks that already exist), or the page's empty sentence when none is named. With
+// `--tabs`, the header carries the page tabs as link tabs (contexts/ui/components tabs.md `level:page`): the first tab is the route
+// itself and every other one its sub-route `<route>/<tab>`, which the author adds as its own page; Grammar selects the tab of the
+// current path, so the server owner passes no state and no handler. The
+// owner also exports the route's loading view, the same page drawn with `isSkeleton` (contexts/ui composition.md STATE-8), and
+// `<Name>ErrorPage` keeps the page and puts one negative Alert where the first region would be. The bodies are
+// templates/fe/units/page/; the stories pair the page with its loading view for the DNA gate.
+import fs from 'node:fs';
+import path from 'node:path';
+import { ScaffoldError, camelOf, pascalOf } from './service.mjs';
+import { addCatalogNamespaces, appOf, declarationOf, fill, humanOf, words, writeNew } from './add-fe-unit.mjs';
 
+/** The copy of a new page, by catalog locale; any other locale takes the English sentences. */
+const PAGE_COPY = Object.freeze({
+  en: { breadcrumb: 'Breadcrumb', home: 'Home', empty: 'Nothing to show yet.', failed: 'This page could not be loaded.', retry: 'Try again' },
+  vi: { breadcrumb: 'Đường dẫn', home: 'Trang chủ', empty: 'Chưa có gì để hiển thị.', failed: 'Không tải được trang này.', retry: 'Thử lại' },
+});
+
+const SEGMENT = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+
+/** The static segments of `<route>` (`settings/billing`); a dynamic or grouped segment is the author's to write. */
+export function routeSegmentsOf(route) {
+  const segments = String(route).split('/').filter(Boolean);
+  if (segments.length === 0 || segments.some((segment) => !SEGMENT.test(segment))) {
+    throw new ScaffoldError('HFS_ADD_ROUTE_INVALID', `${route} is not a route of kebab-case segments (a dynamic [param] or (group) segment is written by hand)`);
+  }
+  return segments;
+}
+
+/**
+ * The blocks of `--blocks a,b`, as their PascalCase names: each an existing block of the app whose connected half takes no input
+ * (`export const X = () =>`), since a generated owner has no value to hand one; a block that takes input is composed by hand.
+ */
+export function blocksOf(repoRoot, appBase, option) {
+  if (option === undefined) return [];
+  return String(option).split(',').map((value) => value.trim()).filter(Boolean).map((value) => {
+    const Name = pascalOf(value);
+    const entry = path.join(repoRoot, ...appBase.split('/'), 'src', 'components', 'blocks', Name, 'index.tsx');
+    if (!fs.existsSync(entry)) {
+      throw new ScaffoldError('HFS_ADD_BLOCK_MISSING', `--blocks names ${Name}, which is no block of ${appBase}/src/components/blocks (starci app add block ${value})`);
+    }
+    if (!new RegExp(`export const ${Name} = \\(\\)`).test(fs.readFileSync(entry, 'utf8'))) {
+      throw new ScaffoldError('HFS_ADD_BLOCK_TAKES_INPUT', `${Name} takes input the generated owner cannot supply; compose it in the owner by hand`);
+    }
+    return Name;
+  });
+}
+
+/**
+ * The page tabs of `--tabs a,b`: two or more distinct kebab-case ids, each with its catalog key and its route. The first tab is
+ * the page's own route, every other one the sub-route `<route>/<id>`.
+ */
+export function tabsOf(route, option) {
+  if (option === undefined) return [];
+  const ids = String(option).split(',').map((value) => value.trim()).filter(Boolean);
+  if (ids.length < 2 || new Set(ids).size !== ids.length || ids.some((id) => !SEGMENT.test(id))) {
+    throw new ScaffoldError('HFS_ADD_TABS_INVALID', `--tabs ${option} is not two or more distinct kebab-case tab ids (a,b)`);
+  }
+  return ids.map((id, index) => ({ id, key: camelOf(id), label: humanOf(id), href: index === 0 ? `/${route}` : `/${route}/${id}` }));
+}
+
+/** The imports and the JSX lines of the blocks a page or layout composes. */
+export const blockParts = (blocks, indent) => ({
+  imports: blocks.map((Name) => `import { ${Name} } from "@/components/blocks/${Name}"\n`).join(''),
+  jsx: blocks.map((Name) => `${indent}<${Name} />`).join('\n'),
+});
+
+/**
+ * Generates one route page in the app at `repoRoot`.
+ *
+ * @param {{ repoRoot: string, route: string, options?: { app?: string, blocks?: string, tabs?: string } }} input - The app root, the route under [locale] and the options.
+ * @returns {{ created: string[] }} The files written or extended, relative to the app root.
+ */
+export function addFePage({ repoRoot, route, options = {} }) {
+  const segments = routeSegmentsOf(route);
+  const appBase = `fe/apps/${appOf(declarationOf(repoRoot), options.app)}`;
+  const base = pascalOf(segments.join('-'));
+  const Name = `${base}Page`;
+  const vars = {
+    Name, LoadingName: `${base}LoadingPage`, ErrorName: `${base}ErrorPage`, nameCamel: camelOf(Name), route: segments.join('/'),
+    routeId: segments.join('-'), title: humanOf(words(base).join('-')),
+  };
+  const routeDir = `${appBase}/src/app/[locale]/${vars.route}`;
+  for (const relative of [`${routeDir}/page.tsx`, `${appBase}/src/features/pages/${Name}`, `${appBase}/src/features/pages/${vars.ErrorName}`]) {
+    if (fs.existsSync(path.join(repoRoot, ...relative.split('/')))) throw new ScaffoldError('HFS_ADD_EXISTS', `${relative} already exists; starci app add never overwrites a unit`);
+  }
+  const blocks = blocksOf(repoRoot, appBase, options.blocks);
+  const tabs = tabsOf(vars.route, options.tabs);
+  const parts = blockParts(blocks, '        ');
+  const empty = blocks.length === 0;
+  const tabbed = tabs.length > 0;
+  const pageVars = {
+    ...vars,
+    grammarImports: empty ? 'EmptyNotice, Page' : 'Page',
+    blockImports: parts.imports,
+    body: empty ? '        <EmptyNotice message={props.props.empty} />' : parts.jsx,
+    emptyMember: empty ? '        readonly empty: string\n' : '',
+    emptyResolved: empty ? '        empty: t("empty"),\n' : '',
+    emptyFixture: empty ? '    empty: "Nothing to show yet.",\n' : '',
+    tabsMember: tabbed
+      ? '        /** The page tabs: link tabs, the selected one follows the current path. */\n        readonly tabsLabel: string\n        readonly tabs: ReadonlyArray<{ readonly id: string; readonly label: string; readonly href: string }>\n'
+      : '',
+    tabsHeader: tabbed ? '            tabs: { label: props.props.tabsLabel, items: props.props.tabs },\n' : '',
+    tabsResolved: tabbed
+      ? `        tabsLabel: t("tabs.label"),\n        tabs: [\n${tabs.map((tab) => `            { id: "${tab.id}", label: t("tabs.items.${tab.key}"), href: "${tab.href}" },\n`).join('')}        ],\n`
+      : '',
+    tabsFixture: tabbed
+      ? `    tabsLabel: "${vars.title}",\n    tabs: [\n${tabs.map((tab) => `        { id: "${tab.id}", label: "${tab.label}", href: "${tab.href}" },\n`).join('')}    ],\n`
+      : '',
+  };
+  const created = [];
+  writeNew(created, repoRoot, `${routeDir}/page.tsx`, fill('page/route-page.tsx.tpl', vars));
+  writeNew(created, repoRoot, `${routeDir}/loading.tsx`, fill('page/route-loading.tsx.tpl', vars));
+  writeNew(created, repoRoot, `${routeDir}/error.tsx`, fill('page/route-error.tsx.tpl', vars));
+  writeNew(created, repoRoot, `${appBase}/src/features/pages/${Name}/index.tsx`, fill('page/index.tsx.tpl', pageVars));
+  writeNew(created, repoRoot, `${appBase}/src/features/pages/${Name}/component.tsx`, fill('page/component.tsx.tpl', pageVars));
+  writeNew(created, repoRoot, `${appBase}/src/features/pages/${vars.ErrorName}/index.tsx`, fill('page/error-index.tsx.tpl', vars));
+  writeNew(created, repoRoot, `${appBase}/src/features/pages/${vars.ErrorName}/component.tsx`, fill('page/error-component.tsx.tpl', vars));
+  writeNew(created, repoRoot, `${appBase}/stories/pages/${Name}.stories.tsx`, fill('page/stories.tsx.tpl', pageVars));
+  addCatalogNamespaces(created, { repoRoot, appBase }, (locale) => {
+    const copy = PAGE_COPY[locale] ?? PAGE_COPY.en;
+    return { [vars.nameCamel]: {
+      title: vars.title, breadcrumb: copy.breadcrumb, home: copy.home, ...(empty ? { empty: copy.empty } : {}),
+      ...(tabbed ? { tabs: { label: vars.title, items: Object.fromEntries(tabs.map((tab) => [tab.key, tab.label])) } } : {}),
+      failed: copy.failed, retry: copy.retry,
+    } };
+  });
+  return { created };
+}