@starci/hfs 4.16.4 → 4.17.0

package/codemod/tier-binding.d.mts

@@ -0,0 +1,50 @@
+/** The TypeScript compiler API of the app's own install (loadTypescript), typed by the version this package develops against. */
+type Ts = typeof import('typescript');
+/** One safe rewrite of the report. */
+export interface TierBindingChange {
+    file: string;
+    line: number;
+    column: number;
+    code: string;
+    from: string;
+    to: string;
+}
+/** One case left for a person. */
+export interface TierBindingFinding {
+    file: string;
+    line: number;
+    column: number;
+    code: string;
+    reason: string;
+    component?: string;
+    source?: string;
+}
+/** The report of a migration (`starci app codemod tier-binding`). */
+export interface TierBindingReport {
+    schema: string;
+    root: string;
+    write: boolean;
+    filesScanned: number;
+    filesChanged: string[];
+    changes: TierBindingChange[];
+    findings: TierBindingFinding[];
+}
+/** Migrate nested JSX children to named props and report the cases the types now refuse; a case with no mechanical rewrite keeps its source. */
+export declare function transformTierBinding({ ts, text, file }: {
+    ts: Ts;
+    text: string;
+    file?: string;
+}): {
+    text: string;
+    changes: TierBindingChange[];
+    findings: TierBindingFinding[];
+};
+/** Preview or apply the safe rewrites in one app's FE tree (`fe/`, or `src/` and `stories/` of a single-side app); every unresolved case is kept in the returned report. */
+export declare function migrateTierBinding({ root, write, ts }: {
+    root: string;
+    write?: boolean;
+    ts?: Ts | null;
+}): TierBindingReport;
+/** Render the migration and what is left for a person as Markdown; JSON consumers read the same report object. */
+export declare function tierBindingMarkdown(report: TierBindingReport): string;
+export {};

package/codemod/tier-binding.mjs

@@ -0,0 +1,214 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { loadTypescript } from '../runtime/scripts/lib/package-at.mjs';
+import { sourceLocation } from '../runtime/scripts/lib/ts-ast.mjs';
+import { shadowed } from './small-renames.mjs';
+const PACKAGE_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const GRAMMAR = /^@starci\/grammar(?:\/|$)/;
+const GENERATED = new Set(['node_modules', '.next', '.turbo', 'dist', 'coverage', '.git']);
+/** Components whose child became a named prop: the JSX child moves into it. `text` takes a string, the rest a node. */
+const CHILD_TO_PROP = new Map([
+    ['Tooltip', { prop: 'trigger' }], ['Disclosure', { prop: 'body' }], ['DragItem', { prop: 'body' }], ['MessageBubble', { prop: 'body' }],
+    ['MediaFrame', { prop: 'media' }], ['Field', { prop: 'control' }], ['Quote', { prop: 'text', text: true }],
+]);
+/** Leaves whose only child is their text label (`LabelChild`). */
+const LABEL_ONLY = new Set(['Button', 'Badge', 'Heading', 'Link', 'TextAction', 'Code']);
+/** Components that take no children at all (`NoChildren`): their anatomy is fields and named slots. */
+const NO_CHILDREN = new Set([
+    'Avatar', 'AvatarButton', 'Checkbox', 'DateField', 'Divider', 'Icon', 'IconButton', 'IconTile', 'Image', 'Kbd', 'Mascot', 'Meter', 'NumberField', 'PressableField',
+    'Progress', 'ProgressCircle', 'RelativeTime', 'SearchField', 'Skeleton', 'Slider', 'Spinner', 'StatusDot', 'Switch', 'TimeField', 'Video',
+    'Accordion', 'BubbleMap', 'Calendar', 'ComboBox', 'CopyField', 'DataTable', 'DatePicker', 'DateRangePicker', 'DropdownMenu', 'FileDropzone', 'FlowGraph', 'Input', 'ListBox',
+    'OtpInput', 'Rating', 'Select', 'Tabs', 'Terminal', 'Textarea',
+    'Alert', 'AvatarGroup', 'ButtonGroup', 'CheckboxGroup', 'EmptyNotice', 'FilterButtonGroup', 'Footer', 'IdentityLockup', 'Pagination', 'RadioGroup',
+    'SegmentedControl', 'Sidebar', 'Stepper', 'TagGroup', 'Timeline', 'Toaster', 'TopBar',
+]);
+/** Components that lost `className`: the stylesheet and the structure decide the look. `Freestyle` is the one hole and keeps it. */
+const NO_CLASS_NAME = new Set([...NO_CHILDREN, ...LABEL_ONLY, ...CHILD_TO_PROP.keys(), 'Page', 'PaneGrid', 'NavLandmark', 'GrammarRoot', 'HorizontalScrollRegion', 'VerticalScrollRegion', 'WorkspaceShell', 'Stack', 'Cluster', 'Grid']);
+/** The JSX text between two tags as React reads it: lines trimmed and joined by one space, blank lines dropped. */
+function jsxText(raw) {
+    return raw.split(/\r?\n/).map(line => line.trim()).filter(Boolean).join(' ');
+}
+/** Migrate nested JSX children to named props and report the cases the types now refuse; a case with no mechanical rewrite keeps its source. */
+export function transformTierBinding({ ts, text, file = 'component.tsx' }) {
+    const changes = [];
+    const findings = [];
+    if (!text.includes('@starci/grammar'))
+        return { text, changes, findings };
+    const syntax = ts.transpileModule(text, { fileName: file, reportDiagnostics: true, compilerOptions: { jsx: ts.JsxEmit.Preserve, target: ts.ScriptTarget.Latest } }).diagnostics ?? [];
+    if (syntax.length)
+        return { text, changes, findings: [{ file, line: 1, column: 1, code: 'PARSE_ERROR', reason: ts.flattenDiagnosticMessageText(syntax[0]?.messageText ?? '', '\n') }] };
+    let current = text;
+    // A child moves into a prop of its parent; the parent's own parent may then be rewritten too, so passes run until nothing changes.
+    for (let pass = 0; pass < 12; pass += 1) {
+        const result = onePass({ ts, text: current, file });
+        if (pass === 0)
+            findings.push(...result.findings);
+        changes.push(...result.changes);
+        if (result.text === current)
+            break;
+        current = result.text;
+    }
+    return { text: current, changes, findings };
+}
+function onePass({ ts, text, file }) {
+    const changes = [];
+    const findings = [];
+    const source = ts.createSourceFile(file, text, ts.ScriptTarget.Latest, true, /\.jsx$/i.test(file) ? ts.ScriptKind.JSX : ts.ScriptKind.TSX);
+    const locals = new Map();
+    const namespaces = new Set();
+    for (const statement of source.statements) {
+        if (!ts.isImportDeclaration(statement) || !ts.isStringLiteral(statement.moduleSpecifier) || !GRAMMAR.test(statement.moduleSpecifier.text))
+            continue;
+        const named = statement.importClause?.namedBindings;
+        if (named && ts.isNamespaceImport(named))
+            namespaces.add(named.name.text);
+        if (named && ts.isNamedImports(named))
+            for (const specifier of named.elements)
+                locals.set(specifier.name.text, specifier.propertyName?.text ?? specifier.name.text);
+    }
+    if (!locals.size && !namespaces.size)
+        return { text, changes, findings };
+    const resolve = (tag) => {
+        if (ts.isIdentifier(tag)) {
+            const imported = locals.get(tag.text);
+            return imported !== undefined && !shadowed(ts, tag) ? { name: imported } : null;
+        }
+        if (ts.isPropertyAccessExpression(tag) && ts.isIdentifier(tag.expression) && namespaces.has(tag.expression.text) && !shadowed(ts, tag.expression))
+            return { name: tag.name.text };
+        return null;
+    };
+    const flag = (node, code, reason, component) => {
+        findings.push({ file, ...sourceLocation(source, node), code, reason, component, source: node.getText(source).slice(0, 200) });
+    };
+    const rewrites = [];
+    const visitElement = (element) => {
+        const opening = ts.isJsxElement(element) ? element.openingElement : element;
+        const resolved = resolve(opening.tagName);
+        if (resolved === null)
+            return;
+        const { name } = resolved;
+        const attributes = opening.attributes.properties;
+        const hasSpread = attributes.some(ts.isJsxSpreadAttribute);
+        if (NO_CLASS_NAME.has(name) && attributes.some(attribute => ts.isJsxAttribute(attribute) && attribute.name.getText(source) === 'className')) {
+            flag(opening, 'CLASS_NAME_REMOVED', `${name} takes no className: the structure and the role props decide the look; remove it, or state the role with the component that owns it`, name);
+        }
+        if (name === 'Tooltip' && attributes.some(attribute => ts.isJsxAttribute(attribute) && ['isDisabledTrigger', 'triggerDescribedBy'].includes(attribute.name.getText(source)))) {
+            flag(opening, 'TOOLTIP_DISABLED_TRIGGER', 'Tooltip no longer wraps a disabled control: give the Button `disabledReason`, which shows these words itself', name);
+        }
+        if (!ts.isJsxElement(element))
+            return;
+        const children = element.children.filter(child => !(ts.isJsxText(child) && child.containsOnlyTriviaWhiteSpaces));
+        if (!children.length)
+            return;
+        const toProp = CHILD_TO_PROP.get(name);
+        if (toProp !== undefined) {
+            if (hasSpread) {
+                flag(element, 'SPREAD_PROPS', `${name} takes a spread: move the child into \`${toProp.prop}\` by hand`, name);
+                return;
+            }
+            let value = null;
+            const only = children.length === 1 ? children[0] : undefined;
+            if (toProp.text === true) {
+                if (only !== undefined && ts.isJsxText(only))
+                    value = `{${JSON.stringify(jsxText(only.getText(source)))}}`;
+                else if (only !== undefined && ts.isJsxExpression(only) && only.expression !== undefined)
+                    value = `{${only.expression.getText(source)}}`;
+                else {
+                    flag(element, 'CHILD_NOT_TEXT', `${name} \`${toProp.prop}\` is a string: the child is not plain text, move it by hand`, name);
+                    return;
+                }
+            }
+            else if (only !== undefined && ts.isJsxExpression(only) && only.expression !== undefined)
+                value = `{${only.expression.getText(source)}}`;
+            else if (only !== undefined && ts.isJsxText(only))
+                value = `{${JSON.stringify(jsxText(only.getText(source)))}}`;
+            else
+                value = `{<>${element.children.map(child => source.text.slice(child.pos, child.end)).join('')}</>}`;
+            if (only !== undefined && (ts.isJsxElement(only) || ts.isJsxSelfClosingElement(only) || ts.isJsxFragment(only)))
+                value = `{${only.getText(source)}}`;
+            const head = opening.getText(source).replace(/>$/, '').trimEnd();
+            const replacement = `${head} ${toProp.prop}=${value} />`;
+            rewrites.push({ element, edit: { start: element.getStart(source), end: element.end, text: replacement }, change: { file, ...sourceLocation(source, element), code: 'CHILD_TO_PROP', from: `<${name}>…</${name}>`, to: `<${name} ${toProp.prop}={…} />` } });
+            return;
+        }
+        if (LABEL_ONLY.has(name)) {
+            const first = children[0];
+            const textual = children.length === 1 && first !== undefined && (ts.isJsxText(first) || ts.isJsxExpression(first));
+            if (!textual)
+                flag(element, 'LABEL_NOT_TEXT', `${name} takes one text label as its child; its content is not plain text, move the glyph to startContent or endContent and keep the words`, name);
+            return;
+        }
+        if (NO_CHILDREN.has(name))
+            flag(element, 'TAKES_NO_CHILDREN', `${name} draws a fixed anatomy from its props and takes no children: place the content in the prop or slot that names its role`, name);
+    };
+    const innermost = new Set();
+    const visit = (node) => {
+        if (ts.isJsxElement(node))
+            visitElement(node);
+        else if (ts.isJsxSelfClosingElement(node))
+            visitElement(node);
+        ts.forEachChild(node, visit);
+    };
+    visit(source);
+    // Only a rewrite with no other rewrite inside it runs in this pass; the next pass takes the parent.
+    for (const entry of rewrites)
+        if (!rewrites.some(other => other !== entry && other.edit.start >= entry.edit.start && other.edit.end <= entry.edit.end))
+            innermost.add(entry.element);
+    const applied = rewrites.filter(entry => innermost.has(entry.element)).sort((a, b) => b.edit.start - a.edit.start);
+    let output = text;
+    for (const entry of applied) {
+        output = output.slice(0, entry.edit.start) + entry.edit.text + output.slice(entry.edit.end);
+        changes.push(entry.change);
+    }
+    return { text: output, changes, findings };
+}
+function sourceFiles(directory) {
+    return fs.readdirSync(directory, { withFileTypes: true }).flatMap(entry => {
+        const target = path.join(directory, entry.name);
+        if (entry.isDirectory())
+            return GENERATED.has(entry.name) ? [] : sourceFiles(target);
+        return entry.isFile() && /\.[jt]sx$/i.test(entry.name) ? [target] : [];
+    }).sort();
+}
+/** Preview or apply the safe rewrites in one app's FE tree (`fe/`, or `src/` and `stories/` of a single-side app); every unresolved case is kept in the returned report. */
+export function migrateTierBinding({ root, write = false, ts = loadTypescript(root, PACKAGE_ROOT) }) {
+    if (!ts)
+        throw new Error('tier-binding needs TypeScript installed in the app or @starci/hfs development checkout');
+    const folders = ['fe', 'src', 'stories'].map(name => path.join(root, name)).filter(folder => fs.statSync(folder, { throwIfNoEntry: false })?.isDirectory());
+    if (!folders.length)
+        throw new Error('tier-binding runs at an app root with a fe/ directory');
+    const report = { schema: 'starci/tier-binding-report@1', root, write, filesScanned: 0, filesChanged: [], changes: [], findings: [] };
+    for (const target of folders.flatMap(sourceFiles)) {
+        const file = path.relative(root, target).split(path.sep).join('/');
+        const original = fs.readFileSync(target, 'utf8');
+        const result = transformTierBinding({ ts, text: original, file });
+        report.filesScanned += 1;
+        report.changes.push(...result.changes);
+        report.findings.push(...result.findings);
+        if (result.text !== original) {
+            report.filesChanged.push(file);
+            if (write)
+                fs.writeFileSync(target, result.text);
+        }
+    }
+    return report;
+}
+const cell = (value) => String(value).replaceAll('|', '\\|').replaceAll('\n', ' ');
+/** Render the migration and what is left for a person as Markdown; JSON consumers read the same report object. */
+export function tierBindingMarkdown(report) {
+    const out = ['# tier-binding', '', `Scanned ${report.filesScanned} files, ${report.filesChanged.length} ${report.write ? 'changed' : 'would change'}, ${report.changes.length} rewrites, ${report.findings.length} left for a person.`, ''];
+    if (report.findings.length) {
+        out.push('## Left for a person', '', '| location | code | reason |', '|---|---|---|');
+        for (const finding of report.findings)
+            out.push(`| ${cell(`${finding.file}:${finding.line}:${finding.column}`)} | ${finding.code} | ${cell(finding.reason)} |`);
+        out.push('');
+    }
+    if (report.changes.length) {
+        out.push('## Rewrites', '', '| location | code | from | to |', '|---|---|---|---|');
+        for (const item of report.changes)
+            out.push(`| ${cell(`${item.file}:${item.line}:${item.column}`)} | ${item.code} | \`${cell(item.from)}\` | \`${cell(item.to)}\` |`);
+        out.push('');
+    }
+    return `${out.join('\n')}\n`;
+}

package/package.json

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

package/runtime/knowledge/grammars/core/playbook.yaml

@@ -171,10 +171,6 @@ shapes:
           Both opener paths default visibility to wide; an explicit visibility also resolves to wide.
           Under viewport="fixed",
           navigationTrack defaults to intrinsic so a collapsed sidebar leaves no empty track.
-      - renderer: NavigationFeatureNav
-        role: |
-          The navbar may use this renderer or the WorkspaceShell header with TopBar. Its family CSS
-          supplies sticky top placement, a 4rem band, a solid surface and a full-width bottom separator.
       - renderer: Sidebar
         role: |
           Desktop navigation uses the expanded or collapsed rail; the left mobile Drawer composes
@@ -201,10 +197,10 @@ shapes:
       - id: workspace-identity
         implements: [FE-APP-SHELL-2]
         compose: |
-          IdentityLockup sits inside PlainPressable size="control". Its square logo mark has a
+          IdentityLockup is itself the pressable (size="control"). Its square logo mark has a
           transparent background, no radius and object-fit contain; without an image it uses Avatar's
           bundled DiceBear initials. The title
-          has a muted role subtitle and no caret. PlainPressable has no button shape or hover effect;
+          has a muted role subtitle and no caret. The lockup has no button shape or hover effect;
           press uses scale(0.96), focus remains visible and reduced motion removes the zoom.
       - id: navbar-right-cluster
         implements: [FE-APP-SHELL-3]
@@ -343,7 +339,7 @@ guidance:
       LAYOUT-1 case-10 (owner:joined-multi-pane): the selected family realizes one touching pane
       surface with vertical Dividers. SURFACE-1 case-4 (owner:scroll-region-background-tone):
       VerticalScrollRegion tone="background" under messages and log entries, with the header and
-      composer on the surface. ACTION-3 case-5 (owner:hover-actions-floating-toolbar): ChatBubble's
+      composer on the surface. ACTION-3 case-5 (owner:hover-actions-floating-toolbar): MessageBubble's
       public floating toolbar owns the IconButtons and tooltips beside the text; apps do not target
       starci-core internals. CTA-6 case-4 (owner:button-variant-follows-intent): ordinary repeated
       item commands are neutral and render ghost.
@@ -351,23 +347,22 @@ guidance:
     ownership: FE-RULE-OWNERSHIP
     implements: [ANATOMY-2, PADDING-0]
     requirement: |
-      SurfaceCard (always painted), SurfaceListCard, a painted SurfaceAccordionCard, Sidebar, Dialog,
-      AlertDialog, Drawer and Popover establish the surface nesting context; Rail and an unpainted
-      SurfaceAccordionCard pass their parent's context through. Input, SearchField, Textarea,
+      SurfaceCard (always painted, of any kind, the accordion kind when painted), Sidebar, Dialog,
+      AlertDialog, Drawer and Popover establish the surface nesting context; Rail and
+      an unpainted accordion SurfaceCard pass their parent's context through. Input, SearchField, Textarea,
       NumberField, DateField, TimeField, Select, ComboBox, DatePicker, DateRangePicker, Checkbox,
       CheckboxGroup, RadioGroup, OtpInput and PressableField resolve variant="secondary" inside it and
       variant="primary" outside. Compose the surface and omit the field variant.
       Switch and Slider have no layer variant; a Radio follows its RadioGroup. PaneGrid's
-      collapsed-pane drawer also establishes the context. SurfaceCard and bounded SurfaceAccordionCard derive
+      collapsed-pane drawer also establishes the context. SurfaceCard and a bounded accordion SurfaceCard derive
       data-grammar-surface-depth from the parent context. The top layer is raised and a nested layer is
       subordinate; never raise both. The family DNA owns their surface paint.
-      FE_NESTED_VARIANT rejects a static field variant
-      anywhere in app code and primary Tabs inside a painted surface; FE_GRAMMAR_LAYOUT_ONLY rejects
+      The field `variant` is not in the prop types, so an app cannot set it; FE_GRAMMAR_LAYOUT_ONLY rejects
       application paint utilities, arbitrary paint properties and inline style paint.
       DRAW_NESTED_VARIANT checks the corresponding rendered variant and
       surface stamps.
       ListBox resolves inset="panel" inside that context; callers may select the same value explicitly
-      elsewhere. Its rows and sections captions share the panel edge. SurfaceListCard owns its list
+      elsewhere. Its rows and sections captions share the panel edge. The list kind of SurfaceCard owns its list
       shell with no added inset; SurfaceCard composition="joined" owns flush bands. A grouping wrapper
       adds no padding. An extra px-*, ps-* or pe-* around ListBox or a section caption stacks the inset
       and fails FE_LIST_PANEL_PADDING.
@@ -440,27 +435,27 @@ guidance:
         uiRules: [STATE-2]
         render: |
           The ready tree, drawn from placeholder data of the slot's type, in the shape the unit's
-          `xDefaultState` names, with isSkeleton on every owner: same card, same bands, same row count
+          `xDefaultState` names, with isLoading on every owner: same card, same bands, same row count
           (idiom pending-same-tree). Never a spinner and never a different tree. The skeleton renders
           inert geometry and states no value; an unknown number is a bar, never a rendered zero.
         skeletonMap:
           - part: Text line or Heading
-            render: "`isSkeleton` on the owner: one bar at that type-scale step's line height, as long as the placeholder text"
+            render: "`isLoading` on the owner: one bar at that type-scale step's line height, as long as the placeholder text"
           - part: Media (Image, MediaFrame viewport)
             render: "`Skeleton shape=\"rect\"` at the frame's `ratio` (square, landscape, wide); `shape=\"circle\"` for an avatar. A block at the ratio, never a collapsed box"
           - part: Button
             render: |
               A bar at the Button's height with the Button's pill corner (family.yaml button-pill):
-              `isSkeleton` where the installed Button publishes it, otherwise `Skeleton shape="rect"` in
+              `isLoading` where the installed Button publishes it, otherwise `Skeleton shape="rect"` in
               the Button's box. It never fires (idiom pending-same-tree action-must-not-fire)
           - part: A region that exists only on ready data (a disclosure of the loaded lines)
-            render: Absent while isSkeleton (STATE-3)
+            render: Absent while isLoading (STATE-3)
       - status: unauthorized
         uiRules: [STATE-3]
         render: |
           401 is its own status, never forbidden and never an error. The slot shows one sign-in prompt in
           place: `EmptyNotice message={labels.unauthorized} actionLabel={labels.signIn}
-          actionVariant="primary" onAction={signIn}`, where `signIn` opens the product's sign-in route and
+          onAction={signIn}`, where `signIn` opens the product's sign-in route and
           returns to this address. The prompt discloses none of the slot's data. A secondary slot hides, as
           forbidden does, so a page whose reads all need a session shows the prompt once, in its primary slot.
       - status: forbidden
@@ -475,7 +470,7 @@ guidance:
         render: |
           Retry at the slot, re-running that slot's read only (the query's `mutate`), never a page
           reload. Block form, where the slot is a region: `EmptyNotice message={labels.error}
-          actionLabel={labels.retry} actionVariant="secondary" onAction={retry}` with `isActionPending`
+          actionLabel={labels.retry} onAction={retry}` with `isActionPending`
           bound while the retry runs. Inline form, where the slot is one line inside a row or band too
           small for a notice: `Alert tone="negative"` in the slot's place, carrying the retry action. A
           command that is unsafe to repeat is not retried (FEEDBACK-2 case-4); a rejected field value
@@ -486,7 +481,7 @@ guidance:
           `EmptyNotice message={labels.empty}` with the slot's own empty sentence; `actionLabel` and
           `onAction` only when a real next step exists, otherwise both are omitted.
       - status: ready
-        render: The slot's items through the same tree, isSkeleton false.
+        render: The slot's items through the same tree, isLoading false.
     notFound: |
       A route whose resource does not exist calls `notFound()` in its route adapter (FE-FUNCTION-7
       case-2). 404 is never a page state, a shape or a slot status.
@@ -615,9 +610,6 @@ presentation:
         - component: HorizontalScrollRegion
           element: root
           rule: PADDING-1
-        - component: NavigationFeatureNav
-          element: primary
-          rule: PADDING-3
         - component: OtpInput
           element: root
           rule: PADDING-1
@@ -669,22 +661,22 @@ presentation:
         - component: Subnav
           element: root
           rule: PADDING-3
-        - component: SurfaceAccordionCard
+        - component: SurfaceCard (accordion kind)
           element: accordion panel
           rule: PADDING-0
-        - component: SurfaceAccordionCard
+        - component: SurfaceCard (accordion kind)
           element: accordion trigger
           rule: PADDING-4
-        - component: SurfaceAccordionCard
+        - component: SurfaceCard (accordion kind)
           element: body padding-top
           rule: PADDING-0
-        - component: SurfaceAccordionCard
+        - component: SurfaceCard (accordion kind)
           element: body padding-bottom
           rule: PADDING-3
-        - component: SurfaceAccordionCard
+        - component: SurfaceCard (accordion kind)
           element: body padding-right
           rule: PADDING-4
-        - component: SurfaceAccordionCard
+        - component: SurfaceCard (accordion kind)
           element: body padding-left
           rule: PADDING-5
         - component: SurfaceCard
@@ -693,7 +685,7 @@ presentation:
         - component: SurfaceCard
           element: content, composition="joined"
           rule: PADDING-0
-        - component: SurfaceListCard
+        - component: SurfaceCard (list kind)
           element: root
           rule: PADDING-0
         - component: Tabs
@@ -776,7 +768,7 @@ presentation:
             render: '`composition="joined"` already sets `0`'
           - id: case-3
             when: A Grammar list sits inside a panel or its rows own their own inset
-            owner: "`SurfaceListCard` / `ListBox`"
+            owner: "`SurfaceCard` list kind / `ListBox`"
             render: ListBox resolves inset="panel" in a surface nesting context, or callers select it explicitly. Its
               row boxes align with the panel content edge, like the search field and tabs boxes, without
               negative-margin bleed (owner:panel-list-box-edge). The list retains HeroUI p-1; items retain
@@ -842,7 +834,7 @@ presentation:
             render: Compose the card; no padding
           - id: case-3
             when: A disclosure trigger and its expanded panel
-            owner: "`SurfaceAccordionCard`"
+            owner: "`SurfaceCard` accordion kind"
             render: Compose the card; no padding
           - id: case-4
             when: An empty-state notice
@@ -995,9 +987,6 @@ presentation:
         - component: Text
           element: root, size="md"
           rule: FONT-3
-        - component: Text
-          element: root, size="metric-lead"
-          rule: FONT-5
         - component: Text
           element: root, size="sm"
           rule: FONT-2
@@ -1016,10 +1005,10 @@ presentation:
         - component: Tooltip
           element: content
           rule: FONT-1
-        - component: SurfaceListCard
+        - component: SurfaceCard (list kind)
           element: fact, label is visible and fact is present, depth="nested"
           rule: FONT-1
-        - component: SurfaceListCard
+        - component: SurfaceCard (list kind)
           element: fact, label is visible and fact is present, depth!="nested"
           rule: FONT-2
     guidance:
@@ -1029,11 +1018,14 @@ presentation:
           Weight is a second axis, not a position on the size scale. Its public set is closed.
           | Prop | Rendered | Use for |
           | --- | --- | --- |
-          | `weight="normal"` | `font-normal`, the default | Reading copy and ordinary facts |
-          | `weight="medium"` | `font-medium` | A compact label, or a title above its own description |
-          | `weight="semibold"` | `font-semibold` | A fact that must be found first within its region |
+          | Where | Rendered | Use for |
+          | --- | --- | --- |
+          | `Text`, no prop | `font-normal`, the default | Reading copy and ordinary facts |
+          | `Heading` levels 3 and 4, and labels | `font-medium` | A compact label, or a title above its own description |
+          | `Text isStrong` | `font-semibold` | A value or a term that must be found first inside its line |
           Weight refines a rank the application has already chosen. It never manufactures a new hierarchy
-          level, and it never substitutes for a heading. `Heading` applies its own weight per level and takes
+          level, and it never substitutes for a heading: a group is headed by its `Section` title or its
+          card label, never by a strong `Text`. `Heading` applies its own weight per level and takes
           no weight prop.
           Bold beyond `semibold` has no public prop. Treat an intent that needs it as a gap rather than writing
           a class.
@@ -1089,8 +1081,8 @@ presentation:
         cases:
           - id: case-1
             when: The single leading metric or short value that is the main fact of its region
-            owner: "`Text`"
-            render: '`<Text size="metric-lead" weight="semibold">84%</Text>`'
+            owner: "`DescriptionList` layout=\"stat-strip\""
+            render: '`<DescriptionList layout="stat-strip" items={[{ id: "rate", term: "Resolved", description: "84%" }]} />`'
         notThisRule: sentences, decoration, or imitating a heading. It creates no heading semantics.
       - rule: FONT-6
         title: "`text-4xl` / `leading-tight`"
@@ -1105,7 +1097,7 @@ anatomyObservations:
     lane: ui
     kind: proven-template
     summary: |-
-      Verified in the draw lab against the real SurfaceListCard render — the prompt shape that
+      Verified in the draw lab against the real list SurfaceCard render — the prompt shape that
       produced a direction both faithful and beautiful:
       1. Frame: flat product UI screenshot, size, light theme.
       2. SUBJECT: screen name + product name.
@@ -1122,11 +1114,9 @@ anatomyObservations:
     lane: ui
     kind: anatomy-detail
     summary: |-
-      The two card components place their labels differently, and a prompt that treats them
-      alike invents one of them. `SurfaceCard` paints one material box around label AND
-      content — its label ("New task") sits inside the card at the top. `SurfaceListCard`
-      renders its label and fact as siblings on the page background ABOVE the list shell —
-      the card bounds only the rows, the footer sits below it.
+      Every `SurfaceCard` kind except `tile` places its label outside: an unpainted row above the material
+      with the fact and the end action, and the card bounds only the content, the footer note below it.
+      A prompt that draws the label inside the card invents a placement the grammar does not have.
   - id: list-separator-bleed
     lane: ui
     kind: anatomy-detail
@@ -1140,7 +1130,7 @@ anatomyObservations:
     lane: ui
     kind: anatomy-detail
     summary: |-
-      An interactive row in a SurfaceListCard is the grammar `ListRow` (@starci/grammar 0.9.1), never an
+      An interactive row in a list SurfaceCard is the grammar `ListRow` (@starci/grammar 0.9.1), never an
       app-owned `<li>` and never a second `<ul>` nested in the card (the card already renders the list,
       so a nested list loses the row inset and the separator - a defect that leaves rows flush against
       the card edge). Its slots, in reading order: `leading`

package/runtime/knowledge/grammars/offset-pop/playbook.yaml

@@ -69,8 +69,8 @@ shapes:
       Keep: which sections exist and which one is the next step. Never crosses over: layout grid, card
       chrome, or a section that would need a renderer the family does not publish.
     composition:
-      - renderer: SectionHeader
-        role: The greeting or section title; its eyebrow reads `accentText`, never the pink
+      - renderer: Section
+        role: The greeting or section title
       - renderer: SurfaceCard
         role: |
           One top-level sticker for the next step (`isHighlight` on that card only), holding the title
@@ -78,7 +78,7 @@ shapes:
           Button variant="primary" — the view's single pink fill
       - renderer: "Progress / ProgressCircle / Meter"
         role: Only a verified value with a truthful `label` (ACCENT-4); an unknown value is not drawn
-      - renderer: SurfaceListCard
+      - renderer: SurfaceCard (list kind)
         role: Peers (recent items, suggestions) as static rows; no second primary Button
       - renderer: "Skeleton / EmptyNotice"
         role: Pending is the same tree at rest (Skeleton in place of content); empty or failed is EmptyNotice
@@ -182,10 +182,10 @@ shapes:
         role: The query, labelled
       - renderer: TagGroup
         role: Filters as outlined chips; selected chips turn pink and lift
-      - renderer: "ListBox / SurfaceListCard"
+      - renderer: "ListBox / SurfaceCard (list kind)"
         role: |
           ListBox when picking is the task (yellow hover wash, pink focus ring, soft-pink selected row
-          with a pink leading edge); SurfaceListCard when rows only report facts
+          with a pink leading edge); the list kind of SurfaceCard when rows only report facts
       - renderer: Pagination
         role: Current page is the raised pink pill
       - renderer: "Skeleton / EmptyNotice"

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

@@ -31,42 +31,42 @@ 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.20.1
+    version: 0.21.0
     group: starci
     install: registry
     side: fe
     source: packages/grammar/package.json
     why: 'the grammar front ends read: the brand layer sets `--font-sans` and `--font-mono` and the grammar reads them; it carries the Input tel kind, the copyable and read-only Input, the IconButton disclosure props and count badge, ChatBubble, FillViewport, Textarea mentions and Enter-to-send, the leading PrimaryRailLayout rail, the plate-less Image, ListRow, the soft Alert, Progress steps, the floating primary IconButton, FlowGraph, the STATE-8 loading views and the bordered selectable TagGroup chips. The runtime source version wins for a @starci package.'
   '@starci/eslint-canon-be':
-    version: 3.11.5
+    version: 3.11.7
     group: starci
     install: registry
     side: be
     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.8.4
+    version: 9.9.0
     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.20.1
+    version: 0.21.0
     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.20.1
+    version: 0.21.0
     group: starci
     install: registry
     side: fe
     source: packages/eslint-grammar-offset-pop/package.json
     why: 'the Offset Pop Grammar component API lint, versioned with @starci/grammar; its shared component contract comes from the StarCi family lint without copying rules.'
   '@starci/stylelint-canon':
-    version: 2.4.0
+    version: 2.5.0
     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.16.4
+    version: 4.17.0
     group: starci
     install: registry
     side: both