@starci/hfs 4.16.5 → 4.17.2

package/runtime/scripts/hfs/architecture/surface-nesting.mjs

@@ -0,0 +1,127 @@
+import { RenderGraph } from './render-graph.mjs';
+/**
+ * R356 `surface-nesting` (FE_SURFACE_NESTING), the whole-program half of the one-file card laws (R340, R351, R354, R348, R366).
+ * ESLint judges one file; an app draws a screen across several, so the check walks the render graph (render-graph.mts) from every
+ * app component and reports, at the inner element, what stands wrongly inside what once every component is replaced by what it
+ * draws and every `children` by what its caller handed it:
+ *
+ *   card-in-card         a card inside a card (surface in surface is banned totally, owner decision 2026-11-01);
+ *   card-in-pane         a card inside `Pane surface`;
+ *   card-in-overlay      a card inside a Dialog, Drawer, AlertDialog or Popover;
+ *   table-in-card        a `DataTable` inside a card (a table stands on the page);
+ *   grid-outside-panes   a `PaneGrid` inside a card or a Page whose chrome is not `panes`;
+ *   heading-over-card    a `Heading`, or a region `Section`, whose only neighbour or child is one card (a card carries its own label);
+ *   label-in-grid        a labelled card repeated by a `.map` in a `Grid kind="cards"` (a repeated tile has no label).
+ *
+ * A finding carries `crossFile: true` when the two elements are drawn in different files, which is what one-file lint cannot see.
+ */
+export const SURFACE_NESTING_RULE_IDS = ['FE_SURFACE_NESTING'];
+const RULE = 'FE_SURFACE_NESTING';
+/** The grammar vocabulary this check reads, in one place so a rename in the grammar is one edit here. */
+export const SURFACE_VOCABULARY = Object.freeze({
+    cards: new Set(['SurfaceCard']),
+    overlays: new Set(['Dialog', 'Drawer', 'AlertDialog', 'Popover']),
+    tables: new Set(['DataTable']),
+    headings: new Set(['Heading']),
+    sections: new Set(['Section']),
+    paneGrids: new Set(['PaneGrid']),
+    pane: 'Pane',
+    page: 'Page',
+    grids: new Set(['Grid']),
+});
+const grammarName = (element) => (element.tag.kind === 'grammar' ? element.tag.name : null);
+const isGrammarIn = (element, names) => {
+    const name = grammarName(element);
+    return name !== null && names.has(name);
+};
+const isTrue = (element, attribute) => {
+    const found = element.attributes.get(attribute);
+    return found !== undefined && found.text !== 'false' && found.text !== null;
+};
+/** The card an element is, or draws at its root through one app component: the one wrapper level the audit allows. */
+const cardOf = (graph, element) => {
+    if (isGrammarIn(element, SURFACE_VOCABULARY.cards))
+        return element;
+    const root = element.tag.kind === 'component' ? graph.rootOf(element) : null;
+    return root && isGrammarIn(root, SURFACE_VOCABULARY.cards) ? root : null;
+};
+const describe = (element) => (element.tag.kind === 'component' ? `${element.tag.name} (${element.tag.file})` : element.tag.name);
+const chainOf = (ancestors, stack) => `${ancestors.map(entry => entry.element.tag.name).join(' > ')}${stack.length > 1 ? ` via ${stack.map(entry => entry.split('#')[1]).join(' > ')}` : ''}`;
+export function checkSurfaceNesting(input) {
+    const graph = new RenderGraph(input.context.ts, input.graph);
+    const found = new Map();
+    const report = (element, outer, kind, message, ancestors, stack) => {
+        const where = graph.locate(element);
+        const key = `${where.path}:${where.line}:${where.column}:${kind}`;
+        if (found.has(key))
+            return;
+        found.set(key, {
+            ruleId: RULE, ...where, kind, crossFile: outer !== null && outer.file !== element.file,
+            message: `${message} (${chainOf(ancestors, stack)}). A card carries its own label and stands on the page or on a canvas pane; a table stands on the page; a grid stands in Page chrome="panes" (contexts/ui/components/card.md).`,
+        });
+    };
+    const visitor = {
+        enter(element, ancestors, stack) {
+            const name = grammarName(element);
+            const nearestCard = [...ancestors].reverse().find(entry => isGrammarIn(entry.element, SURFACE_VOCABULARY.cards));
+            if (name !== null && SURFACE_VOCABULARY.cards.has(name)) {
+                const inPane = [...ancestors].reverse().find(entry => grammarName(entry.element) === SURFACE_VOCABULARY.pane && isTrue(entry.element, 'surface'));
+                const inOverlay = [...ancestors].reverse().find(entry => isGrammarIn(entry.element, SURFACE_VOCABULARY.overlays));
+                if (nearestCard)
+                    report(element, nearestCard.element, 'card-in-card', `${name} is drawn inside ${describe(nearestCard.element)}: surface in surface is banned`, ancestors, stack);
+                else if (inPane)
+                    report(element, inPane.element, 'card-in-pane', `${name} is drawn inside Pane surface`, ancestors, stack);
+                else if (inOverlay)
+                    report(element, inOverlay.element, 'card-in-overlay', `${name} is drawn inside ${describe(inOverlay.element)}: an overlay is a surface already`, ancestors, stack);
+            }
+            if (name !== null && SURFACE_VOCABULARY.tables.has(name) && nearestCard) {
+                report(element, nearestCard.element, 'table-in-card', `${name} is drawn inside ${describe(nearestCard.element)}`, ancestors, stack);
+            }
+            if (name !== null && SURFACE_VOCABULARY.paneGrids.has(name)) {
+                const frame = [...ancestors].reverse().find(entry => {
+                    const frameName = grammarName(entry.element);
+                    return frameName === SURFACE_VOCABULARY.pane || frameName === SURFACE_VOCABULARY.page || SURFACE_VOCABULARY.cards.has(frameName ?? '');
+                });
+                const frameName = frame ? grammarName(frame.element) : null;
+                if (frame && frameName !== SURFACE_VOCABULARY.pane) {
+                    const chrome = frame.element.attributes.get('chrome');
+                    const open = frameName === SURFACE_VOCABULARY.page && (chrome === undefined ? hasSpread(frame.element) : chrome.text === null);
+                    const panes = frameName === SURFACE_VOCABULARY.page && chrome?.text === 'panes';
+                    if (!open && !panes)
+                        report(element, frame.element, 'grid-outside-panes', `${name} is drawn inside ${describe(frame.element)}`, ancestors, stack);
+                }
+            }
+            if (element.repeated) {
+                const inGrid = [...ancestors].reverse().find(entry => isGrammarIn(entry.element, SURFACE_VOCABULARY.grids));
+                const card = inGrid?.element.attributes.get('kind')?.text === 'cards' ? cardOf(graph, element) : null;
+                if (inGrid && card && card.attributes.has('label')) {
+                    report(element, inGrid.element, 'label-in-grid', `${describe(element)} repeats a labelled card in a Grid kind="cards": a repeated tile has no label`, ancestors, stack);
+                }
+            }
+        },
+        parent(element, drawn, ancestors, stack) {
+            if (!isGrammarIn(element, SURFACE_VOCABULARY.sections) || element.attributes.get('kind')?.text === 'list' || drawn.length !== 1)
+                return;
+            const only = drawn[0];
+            if (cardOf(graph, only))
+                report(only, element, 'heading-over-card', `${describe(only)} is the only thing in a Section: the card has two titles`, ancestors, stack);
+        },
+        siblings(elements, ancestors, stack) {
+            for (let index = 0; index < elements.length - 1; index += 1) {
+                const heading = elements[index];
+                if (!isGrammarIn(heading, SURFACE_VOCABULARY.headings))
+                    continue;
+                const next = elements[index + 1];
+                const after = elements[index + 2];
+                if (!cardOf(graph, next) || (after && cardOf(graph, after)))
+                    continue;
+                report(next, heading, 'heading-over-card', `${describe(next)} stands directly under a ${heading.tag.name}, so the card has two titles`, ancestors, stack);
+            }
+        },
+    };
+    const components = graph.allComponents();
+    for (const component of components)
+        graph.walkFrom(component, visitor);
+    return { violations: [...found.values()], coverage: { status: 'checked', components: components.length } };
+}
+const hasSpread = (element) => element.attributes.has('...');

package/runtime/scripts/hfs/architecture/unit-spec-providers.d.mts

@@ -4,7 +4,8 @@ import type { MachineContext } from './machine-ast.mjs';
 /**
  * R48 `unit-spec-providers` (BE_SPEC_QUALITY), the unit test standard's rule 3: the unit spec of a service builds its
  * subject with `Test.createTestingModule({ providers: [...] })`, and that providers array EQUALS the constructor
- * dependencies of the service under test: the service class first, then one provider for each constructor parameter.
+ * dependencies of the service under test: the service class first, then one provider for each required constructor parameter.
+ * A parameter decorated by `Optional()` imported from `@nestjs/common` may be omitted to exercise its absent-provider branch.
  *
  * The service under test is the sibling `<name>.service.ts` of every `<name>.service.spec.ts` under src/ or apps/ (a spec is
  * outside the production program, so it is read from disk). A parameter decorated with a custom `Inject<Thing>()` provides

package/runtime/scripts/hfs/architecture/unit-spec-providers.mjs

@@ -9,7 +9,8 @@ import { checkFunctionSubject, functionSubjectExports, keyOf as literalKey, valu
 /**
  * R48 `unit-spec-providers` (BE_SPEC_QUALITY), the unit test standard's rule 3: the unit spec of a service builds its
  * subject with `Test.createTestingModule({ providers: [...] })`, and that providers array EQUALS the constructor
- * dependencies of the service under test: the service class first, then one provider for each constructor parameter.
+ * dependencies of the service under test: the service class first, then one provider for each required constructor parameter.
+ * A parameter decorated by `Optional()` imported from `@nestjs/common` may be omitted to exercise its absent-provider branch.
  *
  * The service under test is the sibling `<name>.service.ts` of every `<name>.service.spec.ts` under src/ or apps/ (a spec is
  * outside the production program, so it is read from disk). A parameter decorated with a custom `Inject<Thing>()` provides
@@ -80,6 +81,7 @@ function serviceClassFor(ts, rel, serviceRel, serviceFile, imports, list, report
 }
 function checkDependencies(kit, rel, service, serviceFile, list, provided, report) {
     const { serviceName, serviceClass } = service;
+    const checker = kit.checkerOf(serviceFile.sourceFile);
     const dependencies = constructorDependencies(kit, serviceFile, serviceClass);
     const expected = [];
     for (const dependency of dependencies) {
@@ -87,18 +89,23 @@ function checkDependencies(kit, rel, service, serviceFile, list, provided, repor
             report(list, `${rel}: a constructor dependency of ${serviceName.name} cannot be resolved to a token (${dependency.reason}), so its provider cannot be checked; inject it through an exported Inject<Thing>() decorator or a class type.`);
             continue;
         }
-        expected.push(dependency.name);
+        const optional = kit.decorators(dependency.parameter).some(decorator => {
+            const expression = decorator.expression;
+            return kit.ts.isCallExpression(expression) && expression.arguments.length === 0
+                && kit.isImportOf(checker, expression.expression, 'Optional', '@nestjs/common');
+        });
+        expected.push({ name: dependency.name, optional });
     }
     const remaining = [...expected];
     for (const item of provided.slice(1)) {
-        const index = remaining.indexOf(item.name);
+        const index = remaining.findIndex(dependency => dependency.name === item.name);
         if (index === -1)
             report(item.node, `${rel}: ${item.name} is provided but is not a constructor dependency of ${serviceName.name}; a unit spec provides exactly what the constructor needs.`);
         else
             remaining.splice(index, 1);
     }
-    for (const name of remaining)
-        report(list, `${rel}: ${name} is a constructor dependency of ${serviceName.name} but is not provided; add \`{ provide: ${name}, useValue: double }\` (or the class itself) to the providers.`);
+    for (const dependency of remaining.filter(item => !item.optional))
+        report(list, `${rel}: ${dependency.name} is a constructor dependency of ${serviceName.name} but is not provided; add \`{ provide: ${dependency.name}, useValue: double }\` (or the class itself) to the providers.`);
 }
 function checkTestingModule({ ts, kit, rel, serviceRel, serviceFile, imports, call, report }) {
     const list = providerList(ts, call, rel, report);

package/runtime/scripts/hfs/slot-manifest-shape.mjs

@@ -49,13 +49,27 @@ function checkProfileMaps(m, bad) {
             continue;
         }
         for (const extra of Object.keys(m[key]))
-            if (!isSide(extra))
+            if (!isSide(extra) && !(key === 'tiers' && extra === COMPONENT_LIBRARY))
                 bad.push(`${key}.${extra} is not a profile`);
         for (const profile of PROFILES)
             if (!(profile in m[key]))
                 bad.push(`${key}.${profile} is missing`);
     }
 }
+/** The tier matrix of a component library (packages/grammar), beside the be and fe profiles: tiers.grammar. */
+const COMPONENT_LIBRARY = 'grammar';
+function checkComponentLibraryTiers(m, bad) {
+    const tiers = m.tiers?.[COMPONENT_LIBRARY];
+    if (tiers === undefined)
+        return;
+    bad.push(...tierMapProblems(COMPONENT_LIBRARY, tiers));
+    if (!isPlainObject(tiers))
+        return;
+    for (const [tier, def] of Object.entries(tiers))
+        for (const target of def?.mayImport ?? [])
+            if (!(target in tiers))
+                bad.push(`tiers.${COMPONENT_LIBRARY}.${tier}.mayImport names ${target}, which is not a ${COMPONENT_LIBRARY} tier`);
+}
 function checkAppKindAndTierShapes(m, bad) {
     for (const profile of PROFILES) {
         const kinds = m.appKinds?.[profile];
@@ -66,6 +80,7 @@ function checkAppKindAndTierShapes(m, bad) {
             continue;
         bad.push(...tierMapProblems(profile, tiers));
     }
+    checkComponentLibraryTiers(m, bad);
 }
 function checkSlotShapes(m, bad) {
     if (!Array.isArray(m.slots) || !m.slots.length) {

package/runtime/scripts/work/draw/draw-dna.mjs

@@ -348,7 +348,7 @@ export function proposalNamesIn(files) {
 const RATIO_RX = /(?<![\d./])(\d{1,4})\s*\/\s*(\d{1,4})(?![\d./])/;
 const BAR_CLASS = /(?:^|[-_])(bar|bars|track|fill|segment|segments|progress|meter|gauge)(?:$|[-_])/i;
 const NOTICE_CLASS = /(?:^|[-_])(notice|callout|banner|attention|alert|toast|announcement)(?:$|[-_])/i;
-const CONTAINERS = new Set(['SurfaceCard', 'SurfaceListCard', 'SurfaceAccordionCard', 'SurfaceCopyGroup', 'PageContainer', 'EmptyNotice', 'Fieldset']);
+const CONTAINERS = new Set(['SurfaceCard', 'SurfaceCopyGroup', 'PageContainer', 'EmptyNotice', 'Fieldset']);
 const ACTION_COMPONENTS = new Set(['Button', 'IconButton', 'TextAction', 'Link', 'ButtonGroup']);
 const isAction = (el) => ACTION_COMPONENTS.has(componentNameOf(el)) || el.tag === 'button' || (el.tag === 'a' && el.attrs.href != null);
 // ---------------------------------------------------------------------------------------------------------

package/scaffold/add-fe-layout.mjs

@@ -4,7 +4,7 @@
 //   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`
+// component that composes a Grammar layout frame, `Grid kind="main-rail"`: 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/.
@@ -36,8 +36,8 @@ export function addFeLayout({ repoRoot, segment, options = {} }) {
         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'),
+            ? '<Grid kind="main-rail" primary={props.content} />'
+            : ['(', '    <Grid', '        kind="main-rail"', '        primary={props.content}', '        rail={', '            <>', parts.jsx, '            </>', '        }', '    />', ')'].join('\n'),
     };
     const created = [];
     writeNew(created, repoRoot, route, fill('layout/route-layout.tsx.tpl', vars));

package/scaffold/add-fe-overlay.mjs

@@ -7,7 +7,7 @@
 // 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
+// whose fields sit in a one-column `Grid kind="form"` (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';
@@ -42,7 +42,7 @@ function overlayVars({ nameKebab, shell, form }) {
     if (form) {
         const formId = `${nameKebab}-form`;
         return {
-            grammarImports: ['Button', shell, 'Form', 'FormGrid', 'Input'].sort().join(', '),
+            grammarImports: ['Button', shell, 'Form', 'Grid', 'Input'].sort().join(', '),
             labelMembers: '        readonly nameLabel: string\n',
             labelsResolved: '                nameLabel: t("name"),\n',
             labelsFixture: '    nameLabel: "Name",\n',
@@ -54,9 +54,9 @@ function overlayVars({ nameKebab, shell, form }) {
             footer: footer(`<Button type="submit" form="${formId}" intent="commit">`),
             body: [
                 `        <Form id="${formId}" label={props.props.title} onSubmit={props.on.submit}>`,
-                '            <FormGrid columns={1}>',
+                '            <Grid kind="form" columns={1}>',
                 `                <Input id="${nameKebab}-name" name="name" label={props.props.nameLabel} isRequired />`,
-                '            </FormGrid>',
+                '            </Grid>',
                 '        </Form>',
             ].join('\n'),
         };

package/scaffold/add-fe-page.mjs

@@ -11,7 +11,7 @@
 // `--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
+// owner also exports the route's loading view, the same page drawn with `isLoading` (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';

package/scaffold/add-fe-unit.d.mts

@@ -10,7 +10,7 @@ export interface FeDeclaration {
         };
     };
 }
-/** The options of `add block|composite|branch|leaf`. */
+/** The options of `add block|frame|composite|branch|leaf`. */
 export interface FeUnitOptions {
     readonly app?: string | undefined;
     readonly shapes?: string | readonly string[] | false | undefined;
@@ -19,6 +19,7 @@ export interface FeUnitOptions {
 /** The nouns this module answers, and the components layer each one writes into. */
 export declare const FE_UNIT_LAYERS: Readonly<{
     block: "blocks";
+    frame: "frames";
     composite: "composites";
     branch: "branches";
     leaf: "leaves";

package/scaffold/add-fe-unit.mjs

@@ -1,18 +1,18 @@
-// starci app add <block|composite|branch|leaf> <name> - one front-end unit, already in the shape-slot pattern.
+// starci app add <block|frame|composite|branch|leaf> <name> - one front-end unit, already in the shape-slot pattern.
 //
 // The bodies are templates/fe/units/<tier>/; this module only fills them and places them (contexts/code/fe function.md
 // FE-FUNCTION-2..4 and FE-FUNCTION-7, README.md FE-ERROR-1).
 //
 //   starci app add block handoff-block                                  HandoffBlock: one read folded into a DataSlot, no shape
 //   starci app add block handoff-block --shapes prepared,sent,returned  plus HANDOFF_BLOCK_SHAPES, HandoffBlockShape and an exhaustive switch
-//   starci app add composite term-value | branch disclosure | leaf status-label
+//   starci app add frame page-body | composite term-value | branch disclosure | leaf status-label
 //
 // A block reads `useQuery<Read>Swr` of hooks/swr (`--read`, default: the block name without its `Block` suffix; `add table --fe`
 // writes that hook). A block with shapes takes its shape from the read's `status` (the placeholder's own while the read loads), so
 // the read names its shape in that field. The first block of an app also writes the app's one copy of the status owners
-// (FE-ERROR-1): DataSlot and SlotLabels in modules/types, slotOfSwr/mapSlot/loadingSlot in hooks/slot/slot.shared.ts,
+// (FE-ERROR-1): DataSlot and SlotLabels in modules/types, slotOfSwr/slotOfReads/mapSlot/loadingSlot in hooks/slot/slot.shared.ts (and useSlotOfReads),
 // useSlotLabels, the SlotView composite and the shared `status` namespace of every catalog. Nothing that exists is overwritten.
-// A composite, branch or leaf, SlotView among them, is vocabulary that knows no feature: in a front end of two or more apps with
+// A frame, composite, branch or leaf, SlotView among them, is vocabulary that knows no feature: in a front end of two or more apps with
 // the shared ui package (slot fe.package.ui) it lives in that package and its barrel, DataSlot and SlotLabels are declared beside
 // SlotView there and modules/types re-exports them (R91 `monorepo-tier-belongs-to-its-side`); else it lives in the app's components.
 // A shape that names a data status is refused by the lint (R92 `no-data-status-shape`), which owns that word list.
@@ -23,7 +23,7 @@ import { ScaffoldError, camelOf, pascalOf } from './service.mjs';
 import { coreFeApps } from './app.mjs';
 const UNITS_DIR = path.join(path.dirname(fileURLToPath(import.meta.url)), '..', 'templates', 'fe', 'units');
 /** The nouns this module answers, and the components layer each one writes into. */
-export const FE_UNIT_LAYERS = Object.freeze({ block: 'blocks', composite: 'composites', branch: 'branches', leaf: 'leaves' });
+export const FE_UNIT_LAYERS = Object.freeze({ block: 'blocks', frame: 'frames', composite: 'composites', branch: 'branches', leaf: 'leaves' });
 /** The shared status copy of FE-ERROR-1, by catalog locale; any other locale takes the English sentences. */
 const STATUS_COPY = Object.freeze({
     en: { forbidden: 'You do not have access to this.', error: 'This could not be loaded.', retry: 'Try again' },
@@ -133,7 +133,9 @@ function ensureSlotOwners(created, { repoRoot, appBase, ui }) {
     }
     writeOnce(created, repoRoot, `${appBase}/src/hooks/slot/slot.shared.ts`, fill('slot/slot.shared.ts.tpl', {}));
     writeOnce(created, repoRoot, `${appBase}/src/hooks/slot/useSlotLabels.ts`, fill('slot/useSlotLabels.ts.tpl', {}));
-    exportFrom(created, repoRoot, `${appBase}/src/hooks/slot/index.ts`, 'export { loadingSlot, mapSlot, slotOfSwr } from "./slot.shared"');
+    writeOnce(created, repoRoot, `${appBase}/src/hooks/slot/useSlotOfReads.ts`, fill('slot/useSlotOfReads.ts.tpl', {}));
+    exportFrom(created, repoRoot, `${appBase}/src/hooks/slot/index.ts`, 'export { loadingSlot, mapSlot, slotOfReads, slotOfSwr } from "./slot.shared"');
+    exportFrom(created, repoRoot, `${appBase}/src/hooks/slot/index.ts`, 'export { useSlotOfReads } from "./useSlotOfReads"');
     exportFrom(created, repoRoot, `${appBase}/src/hooks/slot/index.ts`, 'export { useSlotLabels } from "./useSlotLabels"');
 }
 /**
@@ -173,8 +175,8 @@ function shapeParts({ Name, NAME_UPPER, shapes }) {
         `        case "${shape}":`,
         '            return (',
         '                <>',
-        `                    <Text isSkeleton={isSkeleton}>{shapeLabels.${shape}}</Text>`,
-        '                    <Text isSkeleton={isSkeleton}>{item.id}</Text>',
+        `                    <Text isLoading={isLoading}>{shapeLabels.${shape}}</Text>`,
+        '                    <Text isLoading={isLoading}>{item.id}</Text>',
         '                </>',
         '            )',
     ].join('\n')).join('\n');
@@ -191,7 +193,7 @@ function shapeParts({ Name, NAME_UPPER, shapes }) {
         shapeBody: [
             '',
             `/** The ready tree of one drawn shape: one case per member of ${Name}Shape, so a member nobody draws fails the lint. */`,
-            `const readyTreeOf = (shape: ${Name}Shape, shapeLabels: ${Name}BaseProps["props"]["shapeLabels"], item: ${Name}Item, isSkeleton: boolean) => {`,
+            `const readyTreeOf = (shape: ${Name}Shape, shapeLabels: ${Name}BaseProps["props"]["shapeLabels"], item: ${Name}Item, isLoading: boolean) => {`,
             '    switch (shape) {',
             cases,
             '    }',
@@ -223,12 +225,12 @@ function blockVars({ Name, nameCamel, nameKebab, Read, shapes, title, ui }) {
         shapeLabelsMember: shaped ? `        readonly shapeLabels: { ${shapes.map((shape) => `readonly ${shape}: string`).join('; ')} }\n` : '',
         placeholderShapeDoc: shaped ? ', and its shape is the block\'s while the read loads' : '',
         placeholderShape: shaped ? `, shape: "${shapes[0]}"` : '',
-        readyTree: shaped ? 'readyTreeOf(props.shape, props.props.shapeLabels, item, isSkeleton)' : '<Text isSkeleton={isSkeleton}>{item.id}</Text>',
+        readyTree: shaped ? 'readyTreeOf(props.shape, props.props.shapeLabels, item, isLoading)' : '<Text isLoading={isLoading}>{item.id}</Text>',
         componentImports: shaped ? `${NAME_UPPER}_PLACEHOLDER, ${NAME_UPPER}_SHAPES, ${Name}Base` : `${Name}Base`,
         componentTypeImport: shaped ? `import type { ${Name}Shape } from "./component"\n` : '',
         connectedDoc: shaped ? 'takes its shape from the read (the placeholder\'s while it loads), ' : '',
         itemShapeMapped: shaped ? ', shape: shapeOf(value.status)' : '',
-        shapeAttribute: shaped ? `            shape={(item.items ?? ${NAME_UPPER}_PLACEHOLDER).shape}\n` : '',
+        shapeAttribute: shaped ? `            shape={("items" in item ? item.items : ${NAME_UPPER}_PLACEHOLDER).shape}\n` : '',
         shapeLabelsResolved: shaped ? `                shapeLabels: { ${shapes.map((shape) => `${shape}: t("shapes.${shape}")`).join(', ')} },\n` : '',
         shapeLabelsFixture: shaped ? `    shapeLabels: { ${shapes.map((shape) => `${shape}: "${humanOf(shape)}"`).join(', ')} },\n` : '',
         fixtureShape: shaped ? `, shape: "${shapes[0]}"` : '',
@@ -256,7 +258,7 @@ function addBlock({ created, place, names, options }) {
     writeNew(created, place.repoRoot, stories, fill('block/stories.tsx.tpl', vars));
     addCatalogKeys(created, place, { nameCamel: names.nameCamel, title: humanOf(names.Name), shapes });
 }
-/** Writes one composite, branch or leaf: into the shared ui package and its barrel, or into the app's components. */
+/** Writes one frame, composite, branch or leaf: into the shared ui package and its barrel, or into the app's components. */
 function addVocabulary({ created, place, noun, Name }) {
     const layer = FE_UNIT_LAYERS[noun];
     const body = fill(`${noun}/index.tsx.tpl`, { Name });

package/scaffold/add.d.mts

@@ -22,7 +22,7 @@ export interface AddResult {
 /**
  * Generates the tree of one noun in the app at `repoRoot` (the folder of hfs.json).
  *
- * @param {{ repoRoot: string, noun: string, name: string, options?: object, now?: () => number }} input - The app root, the noun (job, reactor, queue, projection, ..., or a front-end unit: block, composite, branch, leaf, page, overlay, layout), the instance name and the options the noun needs.
+ * @param {{ repoRoot: string, noun: string, name: string, options?: object, now?: () => number }} input - The app root, the noun (job, reactor, queue, projection, ..., or a front-end unit: block, frame, composite, branch, leaf, page, overlay, layout), the instance name and the options the noun needs.
  * @returns {{ created: Array<string>, registered: { patterns: Array<string>, kinds: Array<string> } }} The files written (app-root relative) and what hfs.json gained.
  */
 export declare function addKind({ repoRoot, noun, name, options, now }: {

package/scaffold/add.mjs

@@ -45,7 +45,7 @@ const FE_OWNERS = Object.freeze({
 /**
  * Generates the tree of one noun in the app at `repoRoot` (the folder of hfs.json).
  *
- * @param {{ repoRoot: string, noun: string, name: string, options?: object, now?: () => number }} input - The app root, the noun (job, reactor, queue, projection, ..., or a front-end unit: block, composite, branch, leaf, page, overlay, layout), the instance name and the options the noun needs.
+ * @param {{ repoRoot: string, noun: string, name: string, options?: object, now?: () => number }} input - The app root, the noun (job, reactor, queue, projection, ..., or a front-end unit: block, frame, composite, branch, leaf, page, overlay, layout), the instance name and the options the noun needs.
  * @returns {{ created: Array<string>, registered: { patterns: Array<string>, kinds: Array<string> } }} The files written (app-root relative) and what hfs.json gained.
  */
 export function addKind({ repoRoot, noun, name, options = {}, now = Date.now }) {

package/src/main.mjs

@@ -72,7 +72,7 @@ var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExte
 //                                            exactly that kind's file tree, generated FROM the files: tree of its pattern topic (knowledge/patterns/be) with the
 //                                            one template body of each entry (templates/be/patterns), plus the platform capabilities it needs when they are missing;
 //                                            it registers the patterns and the trigger kind in hfs.json (sides.be.patterns, sides.be.kinds). Never overwrites a file (scaffold/add.mjs). In a lite app a noun whose slots lite does not have refuses: `add <noun>: full edition only`.
-//   starci app add <block|composite|branch|leaf> <name> [--shapes a,b,c] [--read <read>] [--app <fe app>] [--cwd <dir>]
+//   starci app add <block|frame|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 (page)] | overlay <name> --kind modal|drawer [--form]   a route page, segment layout
 //                                            or overlay owner (scaffold/add-fe-page.mjs, add-fe-layout.mjs, add-fe-overlay.mjs).
 //                                            one front-end unit in the shape-slot pattern from templates/fe/units (scaffold/add-fe-unit.mjs); the
@@ -129,7 +129,7 @@ import { BOOLEAN as CI_BOOLEAN, COMMANDS as CI_COMMANDS } from '../ci/cli.mjs';
 import { LOCAL_FLAGS as CI_LOCAL_FLAGS } from '../ci/local.mjs';
 import { USAGE as COVERAGE_USAGE } from '../coverage/cli.mjs';
 import { SYNC_USAGE } from '../sync/cli.mjs';
-import { codemodMain } from '../codemod/main.mjs';
+import { CODEMODS, codemodMain } from '../codemod/main.mjs';
 /** A value flag as parse stores it: the string given, else undefined. */
 const valueFlag = (opts, flag) => { const given = opts[flag]; return typeof given === 'string' ? given : undefined; };
 /** A boolean flag as parse stores it: true when given, else undefined. */
@@ -152,7 +152,7 @@ const PARSED = {
     add: {
         run: addMain, ...ADD_FLAGS, list: ['--inject'],
         forms: [
-            { operands: '<api|webhook|realtime|saga|job|reactor|queue|projection|cli|table|app|block|composite|branch|leaf|page|overlay|layout> <name>', only: ADD_FLAGS },
+            { operands: '<api|webhook|realtime|saga|job|reactor|queue|projection|cli|table|app|block|frame|composite|branch|leaf|page|overlay|layout> <name>', only: ADD_FLAGS },
             { operands: 'service <dir> <name>', only: { list: ['--inject'] } },
             { operands: 'spec <file>.service.ts', flags: [] },
             { operands: 'image', flags: [] },
@@ -192,7 +192,7 @@ const DATABASE_USAGE = [['new', '<kebab-name>', DB_NEW_FLAGS], ['baseline', '',
 const VERB_USAGE = {
     ...Object.fromEntries(Object.entries(PARSED).map(([verb, spec]) => [verb, spec.forms.map((form) => line(`starci app ${verb}`, form.operands, specUsage(form.only ?? (form.flags === undefined ? spec : { value: form.flags })), spec.edition && form.edition !== false ? flagUsage('--edition', { value: true }) : ''))])),
     lint: ['starci app lint [--changed <file>...] [--workspace <dir>] [--side be|fe] [--fix] [--full] [--full] [--json] [--out <file>]'],
-    codemod: ['starci app codemod button-intent [--execute] [--json] [--format json|markdown] [--out <file.json|file.md>]', 'starci app codemod spacing-roles [--execute] [--json] [--format json|markdown] [--out <file.json|file.md>]'],
+    codemod: CODEMODS.map((name) => `starci app codemod ${name} [--execute] [--json] [--format json|markdown] [--out <file.json|file.md>]`),
     upgrade: ['starci app upgrade [--execute]'],
     sync: [SYNC_USAGE.sync],
     world: ['starci app world <up|down|status> [--stack <dir>] [--services <list>] [--k3d] [--force] [--json] [--edition full|lite]'],

package/templates/fe/skeleton/apps/__app__/src/components/blocks/SignInForm/component.tsx

@@ -1,4 +1,4 @@
-import { Button, Form, Input, SectionHeader, Text } from "@starci/grammar/common"
+import { Button, Form, Input, Section, Text } from "@starci/grammar/common"
 
 /** Copy, the pending flag, the first error message and the action supplied by the connected sign-in block. */
 export interface SignInFormBaseProps {
@@ -17,8 +17,7 @@ export interface SignInFormBaseProps {
 
 /** Draws the sign-in form without reading navigation, copy or database state. */
 export const SignInFormBase = (props: SignInFormBaseProps) => (
-    <>
-        <SectionHeader title={props.props.title} level={2} />
+    <Section title={props.props.title}>
         <Form label={props.props.title} isPending={props.props.pending} onSubmit={props.on.submit}>
             <Input id="sign-in-email" name="email" label={props.props.emailLabel} kind="email" isRequired />
             <Input id="sign-in-password" name="password" label={props.props.passwordLabel} kind="password" isRequired />
@@ -27,5 +26,5 @@ export const SignInFormBase = (props: SignInFormBaseProps) => (
                 {props.props.submitLabel}
             </Button>
         </Form>
-    </>
+    </Section>
 )

package/templates/fe/skeleton/apps/app/src/app/[locale]/layout.tsx

@@ -15,11 +15,14 @@ export const generateMetadata = async (props: LayoutProps) => appLayoutMetadata(
 
 /** The locale segment's layout slot: the document of the address's language, the app's client providers and its chrome. */
 const Layout = async (props: LayoutProps) => (
-    <LocaleShell {...await appI18n.readLocaleSegment(props.params)}>
-        <AppProviders>
-            <AppLayout content={props.children} />
-        </AppProviders>
-    </LocaleShell>
+    <LocaleShell
+        {...await appI18n.readLocaleSegment(props.params)}
+        content={
+            <AppProviders>
+                <AppLayout content={props.children} />
+            </AppProviders>
+        }
+    />
 )
 
 export default Layout

package/templates/fe/skeleton/apps/landing/src/app/[locale]/layout.tsx

@@ -14,9 +14,7 @@ export const generateMetadata = async (props: LayoutProps) => landingLayoutMetad
 
 /** The locale segment's layout slot: the document of the address's language around the landing's chrome. */
 const Layout = async (props: LayoutProps) => (
-    <LocaleShell {...await landingI18n.readLocaleSegment(props.params)}>
-        <LandingLayout content={props.children} />
-    </LocaleShell>
+    <LocaleShell {...await landingI18n.readLocaleSegment(props.params)} content={<LandingLayout content={props.children} />} />
 )
 
 export default Layout

package/templates/fe/skeleton/packages/__project__-ui/src/branches/Providers/index.tsx

@@ -4,12 +4,12 @@ import { I18nProvider } from "@heroui/react"
 import { NextIntlClientProvider } from "next-intl"
 import type { ReactNode } from "react"
 
-/** What the provider stack takes: the locale resolved on the server, its catalog, the product time zone and the tree it wraps. */
+/** What the provider stack takes: the locale resolved on the server, its catalog, the product time zone and the tree it wraps (`content`). */
 type ProvidersProps = {
     readonly locale: string
     readonly messages: Record<string, unknown>
     readonly timeZone: string
-    readonly children: ReactNode
+    readonly content: ReactNode
 }
 
 /**
@@ -18,6 +18,6 @@ type ProvidersProps = {
  */
 export const Providers = (props: ProvidersProps) => (
     <NextIntlClientProvider locale={props.locale} messages={props.messages} timeZone={props.timeZone}>
-        <I18nProvider locale={props.locale}>{props.children}</I18nProvider>
+        <I18nProvider locale={props.locale}>{props.content}</I18nProvider>
     </NextIntlClientProvider>
 )

package/templates/fe/skeleton/packages/__project__-ui/src/composites/LocaleShell/index.tsx

@@ -6,16 +6,14 @@ type LocaleShellProps = {
     readonly locale: string
     readonly messages: Record<string, unknown>
     readonly timeZone: string
-    readonly children: ReactNode
+    readonly content: ReactNode
 }
 
-/** The document of one route language: `<html lang>` from the address and the provider stack; the app's own chrome is the children. */
+/** The document of one route language: `<html lang>` from the address and the provider stack; the app's own chrome is the content. */
 export const LocaleShell = (props: LocaleShellProps) => (
     <html lang={props.locale}>
         <body>
-            <Providers locale={props.locale} messages={props.messages} timeZone={props.timeZone}>
-                {props.children}
-            </Providers>
+            <Providers locale={props.locale} messages={props.messages} timeZone={props.timeZone} content={props.content} />
         </body>
     </html>
 )

package/templates/fe/skeleton/packages/__project__-ui/src/index.ts

@@ -3,5 +3,5 @@ export { GlobalErrorNotice } from "./composites/GlobalErrorNotice"
 export { LoadingNotice } from "./composites/LoadingNotice"
 export { LocaleShell } from "./composites/LocaleShell"
 export { NotFoundNotice } from "./composites/NotFoundNotice"
-export { SiteShell } from "./composites/SiteShell"
+export { SiteShell } from "./frames/SiteShell"
 export { Icon } from "./leaves/Icon"

package/templates/fe/skeleton-lite/apps/web/src/features/layouts/AppLayout/index.tsx

@@ -1,7 +1,7 @@
 import type { Metadata } from "next"
 import { getTranslations } from "next-intl/server"
 import type { ReactNode } from "react"
-import { SiteShell } from "@/components/composites/SiteShell"
+import { SiteShell } from "@/components/frames/SiteShell"
 import { siteUrl } from "@/modules/config"
 import { APP_ROUTES } from "@/modules/routes"
 

package/templates/fe/skeleton-lite/apps/web/src/modules/brand/brand.css

@@ -2,8 +2,7 @@
 :root,
 .light,
 .dark {
-    --starci-core-accent: #0d9488;
-    --accent: var(--starci-core-accent);
+    --accent: #0d9488;
     --accent-foreground: #051817;
     --font-sans: ui-sans-serif, system-ui, sans-serif;
 }

package/templates/fe/units/block/component.tsx.tpl

@@ -28,8 +28,7 @@ export const {{Name}}Base = (props: {{Name}}BaseProps) => (
             placeholder={{{NAME_UPPER}}_PLACEHOLDER}
             labels={props.props.slotLabels}
             onRetry={props.on.retry}
-        >
-            {(item, isSkeleton) => {{readyTree}}}
-        </SlotView>
+            render={(item, isLoading) => {{readyTree}}}
+        />
     </SurfaceCard>
 )