@intentic/extension-ui 1.345.0 → 1.346.0

package/README.md

@@ -27,7 +27,22 @@ flowchart LR
   `engines.intentic` range the host satisfies then finds every name it was built with. One that asks for a name anyway
   is stopped before it links: the editor's loader reads the bundle's imports and says which name is missing and that
   the extension needs updating, where the browser would only say the module "does not provide an export named …".
-- `RepoRail` and `errorMessage` are deprecated and stay until 3.0.0 (`RepoPicker` and `messageOr` replace them).
+- What an extension may no longer take from the kit is recorded once, in `names.mjs`: `extensionUiDeprecated` for
+  names that still link (`RepoRail` → `RepoPicker`, `errorMessage` → `messageOr`, and from 2.33.0 `SkeletonSnapshot`,
+  `vSkeletonSource` and `useLoadingReveal` → `Await`, all removable in 3.0.0), and `extensionUiRetired` for props and
+  recipe members that no longer do anything a view should rely on (from 2.34.0 `RowGroup`'s `count`, `caption` and
+  `flat`, `NavRail`'s `stickyHeadings`, and `ui.sectionLabel` drawn by hand → `Section`/`SectionHeader`). Each entry
+  carries the extension API version it arrived in, and `surface.json` records the list per version (`uiKitDeprecated`).
+- `check/` is the kit's own judgement of an extension, published with it. `intentic-kit-check` (check/cli.mjs) reads an
+  extension's `src/` and fails on a deprecated name imported, a retired prop or member used, the decided looks the
+  editor is held to (check/kit-decisions.mjs: no header decision at a call site, no header drawn by hand, no card in a
+  card, no unspaced sections, no row height, no icon nudged by hand), and an `engines.intentic` floor below the version
+  that brought a name the extension imports, read off the installed extension-api's `surface.json`. Every extension
+  runs it in its `typecheck`; the monorepo's `extension-kit` check runs the same code over `_extensions/*` and the
+  standalone checkouts beside this repository, and `row-tiers`/`mark-alignment` read the same rules. A finding that is
+  right to keep says so in place with `allow(kit-check): <reason>`. (2026-10-20: the extensions shipped from their own
+  repositories still wired their waits by hand and wrote captions beside headers after the kit had decided both,
+  because these rules reached only this repository's templates.)
   (2026-10-15: `RepoRail` left the kit on 2026-10-12 with no version moving, and every installed extension still
   importing it stopped loading. It is back unchanged, and nothing recorded the kit's names before this.)
 - `./diff`, `./format`, `./i18n` and `./worker` skip the component barrel, for extension tests that run without a Vue
@@ -41,11 +56,14 @@ flowchart LR
 
 - [src/index.ts](src/index.ts) — the kit: every name an extension may import, with usage notes.
 - [scripts/build.mjs](scripts/build.mjs) — builds the published types and the host bridge from `_editor/ui`.
-- [names.mjs](names.mjs) — the runtime export names the shims and the host check read, and the deprecated ones.
+- [names.mjs](names.mjs) — the runtime export names the shims and the host check read, the deprecated ones and the retired props.
+- [check/extension.mjs](check/extension.mjs) — what an extension must change for the kit it builds against; [check/cli.mjs](check/cli.mjs) is `intentic-kit-check`.
 - [../../_editor/web/src/extension-host/hostModules.ts](../../_editor/web/src/extension-host/hostModules.ts) — where the shell publishes its instances to extension bundles.
 
 ## Commands
 
 ```sh
 pnpm --filter @intentic/extension-ui build
+node _tools/checks/extension-kit.mjs          # every workspace extension against the kit as it stands
+npx intentic-kit-check                        # inside an extension's own repository
 ```

package/check/cli.mjs

@@ -0,0 +1,61 @@
+#!/usr/bin/env node
+// `intentic-kit-check [dir]`: what an extension must change for the kit and API it builds against (check/extension.mjs),
+// run from the extension's own repository, where the intentic repository's checks never reach. Reads the extension's
+// `src/` and `intentic-extension.json`, and the surface record of the @intentic/extension-api it has installed. Exits 1
+// with one `path:line  why` per finding, so an author's typecheck fails where the host would otherwise refuse or the
+// look would drift. A finding that is right to keep says so in place: `allow(kit-check): <reason>`.
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import { join, relative, resolve } from "node:path";
+import { extensionFindings } from "./extension.mjs";
+
+const root = resolve(process.argv[2] ?? `.`);
+const SOURCE = /\.(?:vue|ts|mts|js|mjs)$/u;
+const SKIPPED = /\.(?:test|spec)\.\w+$|\.d\.m?ts$/u;
+
+const files = [];
+const walk = (dir) => {
+    for (const entry of readdirSync(dir, { withFileTypes: true })) {
+        const full = join(dir, entry.name);
+        if (entry.isDirectory()) {
+            if (entry.name !== `node_modules` && entry.name !== `dist` && !entry.name.startsWith(`.`)) {
+                walk(full);
+            }
+        } else if (SOURCE.test(entry.name) && !SKIPPED.test(entry.name)) {
+            files.push({ path: relative(root, full).replaceAll(`\\`, `/`), text: readFileSync(full, `utf8`) });
+        }
+    }
+};
+
+const manifestPath = join(root, `intentic-extension.json`);
+if (!existsSync(manifestPath) || !existsSync(join(root, `src`))) {
+    console.error(`intentic-kit-check: ${root} is not an extension (no intentic-extension.json beside a src/)`);
+    process.exit(2);
+}
+walk(join(root, `src`));
+
+// The API this extension builds against, as installed beside it: its record of every version's surface.
+// Undefined only when no extension-api that exports the record is installed; anything else is a real failure.
+const NOT_INSTALLED = new Set([`MODULE_NOT_FOUND`, `ERR_MODULE_NOT_FOUND`, `ERR_PACKAGE_PATH_NOT_EXPORTED`]);
+const surfaceOf = () => {
+    let path;
+    try {
+        path = createRequire(join(root, `package.json`)).resolve(`@intentic/extension-api/surface.json`);
+    } catch (error) {
+        if (NOT_INSTALLED.has(error?.code)) {
+            return undefined;
+        }
+        throw error;
+    }
+    return JSON.parse(readFileSync(path, `utf8`));
+};
+
+const findings = extensionFindings({ files, manifest: JSON.parse(readFileSync(manifestPath, `utf8`)), surface: surfaceOf() });
+if (findings.length > 0) {
+    for (const { at, why } of findings) {
+        console.error(`${at}  ${why}`);
+    }
+    console.error(`\nintentic-kit-check: ${findings.length} problem(s) in what this extension takes from the kit`);
+    process.exit(1);
+}
+console.log(`intentic-kit-check: ${files.length} source files use the kit as it stands, within what engines.intentic promises`);

package/check/extension.d.mts

@@ -0,0 +1,18 @@
+export interface KitFinding {
+    /** `path:line` relative to the extension's root, or `intentic-extension.json`. */
+    readonly at: string;
+    readonly why: string;
+}
+
+/** One version's record in extension-api's surface.json, the two grains a bundle links by name. */
+export interface RecordedLinks {
+    readonly uiKitExports?: readonly string[];
+    readonly moduleExports?: readonly string[];
+}
+
+/** What an extension's sources must change for the kit and API it builds against (check/extension.mjs). */
+export declare const extensionFindings: (input: {
+    readonly files: readonly { readonly path: string; readonly text: string }[];
+    readonly manifest: { readonly engines?: { readonly intentic?: string } } | undefined;
+    readonly surface: Readonly<Record<string, RecordedLinks>> | undefined;
+}) => KitFinding[];

package/check/extension.mjs

@@ -0,0 +1,166 @@
+// WHAT AN EXTENSION MUST CHANGE FOR THE KIT IT BUILDS AGAINST, judged where the extension is built. The kit's decisions
+// and deprecations were enforced only on the templates inside the intentic repository, so an extension shipped from its
+// own repository kept a retired look (a skeleton wired by hand, a caption beside a header, an icon nudged by a pixel) or
+// imported a name its `engines.intentic` floor did not promise, with nothing saying so until a host refused it. This
+// reads an extension's sources against the same records the host is held to:
+// - a deprecated kit name imported (names.mjs `extensionUiDeprecated`), with what replaced it;
+// - a retired prop passed or recipe member called (names.mjs `extensionUiRetired`), with why;
+// - the kit's decided looks (kit-decisions.mjs: a header decision at the call site, a header drawn by hand, a card in a
+//   card, sections nothing spaces, a row's own height, an icon nudged by hand);
+// - a name imported from the kit or the API that the manifest's `engines.intentic` floor does not have, read off the
+//   API's surface record (surface.json), so a bundle never reaches a host whose link would fail.
+// Pure: the caller hands in the files, the manifest and the surface record. check/cli.mjs is the command around it.
+import { extensionUiDeprecated, extensionUiNames, extensionUiRetired } from "../names.mjs";
+import { glyphFindings, sectionFindings } from "./kit-decisions.mjs";
+import { blank } from "./scan.mjs";
+
+const KIT = `@intentic/extension-ui`;
+const API = `@intentic/extension-api`;
+
+// A finding at a line excused by `allow(kit-check): <reason>` on that line or the one above it, in any comment form.
+const ALLOW = /allow\(kit-check\):\s*\S/u;
+const excused = (lines, line) => ALLOW.test(lines[line - 1] ?? ``) || ALLOW.test(lines[line - 2] ?? ``);
+
+const lineOf = (text, index) => text.slice(0, index).split(`\n`).length;
+
+// The value names one `import { … } from "<pkg>[/sub]"` brings in (type-only imports and members link nothing).
+const IMPORT = /import\s+(type\s+)?\{([^}]*)\}\s*from\s*["'](@intentic\/extension-(?:ui|api))(?:\/[\w-]+)?["']/gu;
+const importsOf = (text) =>
+    [...text.matchAll(IMPORT)].flatMap((match) =>
+        match[1] !== undefined
+            ? []
+            : match[2]
+                  .split(`,`)
+                  .map((entry) => entry.trim())
+                  .filter((entry) => entry !== `` && !entry.startsWith(`type `))
+                  .map((entry) => ({ name: entry.split(/\s+as\s+/u)[0].trim(), from: match[3], index: match.index })),
+    );
+
+// `^2.34.0` or `2.34.0`, the two forms the host's matcher (extension-api engines.ts) accepts; its floor, or undefined.
+const floorOf = (range) => {
+    const match = /^\s*\^?\s*(\d+)(?:\.(\d+))?(?:\.(\d+))?\s*$/u.exec(range ?? ``);
+    return match === null ? undefined : `${match[1]}.${match[2] ?? 0}.${match[3] ?? 0}`;
+};
+const parts = (version) => version.split(`.`).map(Number);
+const compare = (a, b) => {
+    const [x, y] = [parts(a), parts(b)];
+    return x[0] - y[0] || x[1] - y[1] || x[2] - y[2];
+};
+
+// The first recorded version each name of one grain appears in, and the version the grain was first recorded at (a name
+// already there may be older than the record, so it says nothing about a floor below it).
+const firstSeen = (surface, grain) => {
+    const versions = Object.keys(surface)
+        .filter((version) => Array.isArray(surface[version]?.[grain]))
+        .toSorted(compare);
+    const seen = new Map();
+    for (const version of versions) {
+        for (const name of surface[version][grain]) {
+            if (!seen.has(name)) {
+                seen.set(name, version);
+            }
+        }
+    }
+    return { seen, start: versions[0] };
+};
+
+const DEPRECATED = new Map(extensionUiDeprecated.map((entry) => [entry.name, entry]));
+const KIT_NAMES = new Set(extensionUiNames);
+// A recipe member called by its name (`ui.sectionLabel(`), from a template binding or a script alike.
+const MEMBERS = extensionUiRetired
+    .filter((entry) => entry.name.startsWith(`ui.`))
+    .map((entry) => ({ ...entry, pattern: new RegExp(`\\b${entry.name.replace(`.`, `\\.`)}(?:Sm)?\\b`, `gu`) }));
+
+const MANIFEST = `intentic-extension.json`;
+
+// One file's findings at a source offset, unless the line (or the one above it) excuses them.
+const sourceFindings = ({ path, text }, found) => {
+    const lines = text.split(`\n`);
+    return found
+        .map(({ index, why }) => ({ line: lineOf(text, index), why }))
+        .filter(({ line }) => !excused(lines, line))
+        .map(({ line, why }) => ({ at: `${path}:${line}`, why }));
+};
+
+// A deprecated kit name, or one the kit does not have, imported.
+const importFindings = (file) =>
+    sourceFindings(
+        file,
+        importsOf(file.text)
+            .filter(({ from }) => from === KIT)
+            .flatMap(({ name, index }) => {
+                const deprecated = DEPRECATED.get(name);
+                return [
+                    ...(deprecated === undefined
+                        ? []
+                        : [{ index, why: `\`${name}\` is deprecated since extension API ${deprecated.since}, removable in ${deprecated.removableIn}: use \`${deprecated.use}\`` }]),
+                    ...(KIT_NAMES.has(name) ? [] : [{ index, why: `\`${name}\` is not a name the kit exports, so the bundle fails to link: see names.mjs in ${KIT}` }]),
+                ];
+            }),
+    );
+
+// A retired recipe member called, in a template binding or a script.
+const memberFindings = (file) =>
+    sourceFindings(
+        file,
+        MEMBERS.flatMap((member) =>
+            [...file.text.matchAll(member.pattern)].map((match) => ({ index: match.index, why: `\`${member.name}\` is retired since extension API ${member.since}: ${member.why}` })),
+        ),
+    );
+
+// The kit's decided looks, read off a template.
+const templateFindings = ({ path, text }) => {
+    if (!path.endsWith(`.vue`)) {
+        return [];
+    }
+    const lines = text.split(`\n`);
+    const scan = blank(text);
+    return [...sectionFindings(path, scan), ...glyphFindings(path, scan)].filter(
+        (finding) => !excused(lines, Number(finding.at.slice(finding.at.lastIndexOf(`:`) + 1))),
+    );
+};
+
+// Whether `engines.intentic` is a range the host reads, and whether its floor has every name the sources import.
+const enginesFindings = (files, range, surface) => {
+    const floor = floorOf(range);
+    if (range === undefined) {
+        return [];
+    }
+    if (floor === undefined) {
+        return [{ at: MANIFEST, why: `engines.intentic "${range}" is neither an exact version nor a caret range, the two the host reads: it refuses the extension` }];
+    }
+    const imports = files.flatMap((file) => importsOf(file.text).map((entry) => ({ ...entry, file })));
+    if (surface === undefined) {
+        return imports.length === 0
+            ? []
+            : [{ at: MANIFEST, why: `${API}'s surface record (surface.json) could not be read, so whether engines.intentic "${range}" promises every name imported is unjudged: install the extension's dependencies` }];
+    }
+    const newest = Object.keys(surface).toSorted(compare).at(-1);
+    if (surface[floor] === undefined && compare(floor, newest) > 0) {
+        return [{ at: MANIFEST, why: `engines.intentic "${range}" asks for an extension API newer than the ${API} installed here records: update ${API}` }];
+    }
+    const grains = { [KIT]: firstSeen(surface, `uiKitExports`), [API]: firstSeen(surface, `moduleExports`) };
+    // Names the floor's host lacks, each with where it is imported and the version that brought it. A name already there
+    // when its grain was first recorded may be older than the record, so it says nothing about a floor below it.
+    const needs = imports
+        .map(({ name, from, index, file }) => ({ name, at: `${file.path}:${lineOf(file.text, index)}`, since: grains[from].seen.get(name), start: grains[from].start }))
+        .filter(({ since, start }) => since !== undefined && since !== start && compare(since, floor) > 0);
+    const highest = needs.map(({ since }) => since).toSorted(compare).at(-1);
+    if (highest === undefined) {
+        return [];
+    }
+    const lacked = needs.map(({ name, at, since }) => `\`${name}\` (${at}, from ${since})`).join(`, `);
+    return [{ at: MANIFEST, why: `engines.intentic "${range}" admits hosts from ${floor}, which lack ${lacked}: such a host refuses the bundle at link, so raise it to "^${highest}"` }];
+};
+
+/**
+ * Every place an extension's sources leave the kit's decisions or its engines floor, as `{ at: "path:line", why }`.
+ * `files` are `{ path, text }` (.vue and .ts/.mts/.js/.mjs; tests and declarations are the caller's to leave out),
+ * `manifest` the parsed intentic-extension.json, `surface` the parsed surface.json of the extension API it builds
+ * against, or undefined when that cannot be read (the engines rule then says so instead of judging).
+ */
+export const extensionFindings = ({ files, manifest, surface }) =>
+    [
+        ...enginesFindings(files, manifest?.engines?.intentic, surface),
+        ...files.flatMap((file) => [...importFindings(file), ...memberFindings(file), ...templateFindings(file)]),
+    ].toSorted((a, b) => a.at.localeCompare(b.at, undefined, { numeric: true }));

package/check/kit-decisions.mjs

@@ -0,0 +1,278 @@
+// THE KIT'S DECIDED LOOKS, read off one template: the rules row-tiers, mark-alignment, kit-substitutes and recipe-tiers
+// judge every view by, in one place so their tests read the same functions the checks run. Each refuses a decision the
+// owner made once, and had re-made view by view while a view could still state it: a header's count, caption, fill or
+// spacing; a card laid in a card; rows of different heights; an icon nudged onto its line by a pixel that is right for
+// one type size only; a section label, a tab strip, a search field or an open row drawn by hand; a chip's own box.
+import { extensionUiRetired } from "../names.mjs";
+import { at, classWordsOf, tags, VOID } from "./scan.mjs";
+
+// ── Sections ─────────────────────────────────────────────────────────────────────────────────────────────────────
+
+// The look the header owns (`ui.sectionLabel`, drawn only by <SectionHeader>): an uppercase, tracked label, spelled out or
+// called for by the recipe's own name.
+const HEADER_LOOK = (words) =>
+    /\bui\.sectionLabel(?:Sm)?\b/u.test(words) ||
+    (/(?:^|\s)uppercase(?:\s|$)/u.test(words) && /(?:^|\s)tracking-(?:wide|wider|widest)(?:\s|$)/u.test(words));
+const SECTIONS = new Set([`RowGroup`, `Section`]);
+// A parent that spaces what it holds: a gap, a vertical rhythm, or hairlines between them.
+const SPACED = /(?:^|\s)(?:[\w@-]+:)*(?:gap-(?:y-)?[\d.[]|space-y-|divide-y)/u;
+// A height on a row, at any breakpoint.
+const ROW_HEIGHT = /(?:^|\s)(?:[\w@-]+:)*(?:min-h|max-h|h)-(?!0(?:\s|$))[\w.[\]/-]+/u;
+const ELSE = /(?:^|\s)v-else(?:-if)?(?:[\s=>]|$)/u;
+
+// What each removed prop was for, said where a call site still passes it: `extensionUiRetired` in names.mjs, the one
+// record of them, whose `Component.prop` entries are read here under both spellings a template may use.
+const kebab = (name) => name.replace(/[A-Z]/gu, (letter) => `-${letter.toLowerCase()}`);
+const RETIRED_PROPS = {};
+for (const { name, why } of extensionUiRetired) {
+    const [component, prop] = name.split(`.`);
+    if (/^[A-Z]/u.test(component) && prop !== undefined) {
+        RETIRED_PROPS[component] ??= {};
+        RETIRED_PROPS[component][prop] = why;
+        RETIRED_PROPS[component][kebab(prop)] = why;
+    }
+}
+
+// One walk over a template's open tags, with the stack of elements each sits in: `open` judges a tag (and says whether to
+// push it as a frame), `close` judges a frame as it closes, the SFC's own `<template>` included.
+const walk = (scan, open, close = () => {}) => {
+    const stack = [];
+    for (const tag of tags(scan)) {
+        if (tag.closing !== ``) {
+            const top = stack.findLastIndex((frame) => frame.name === tag.name);
+            if (top !== -1) {
+                stack.splice(top).forEach(close);
+            }
+            continue;
+        }
+        const frame = open(tag, stack);
+        if (frame !== undefined && tag.selfClosing === `` && !VOID.has(tag.name)) {
+            stack.push(frame);
+        }
+    }
+    stack.splice(0).forEach(close);
+};
+
+// `<template v-if>`/`v-for` draw nothing, so what is inside is still its parent's child.
+const parentOf = (stack) => stack.findLast((frame) => !frame.transparent);
+
+// ── 4 · a header decision taken at the call site
+const retiredProps = (name, attrs) => {
+    const retired = RETIRED_PROPS[name] ?? {};
+    return [...attrs.matchAll(/(?:^|\s)(?::|v-bind:)?([\w-]+)(?=[\s=>]|$)/gu)]
+        .filter((match) => retired[match[1]] !== undefined)
+        .map((match) => `<${name}> takes no \`${match[1]}\`: ${retired[match[1]]}`);
+};
+
+// ── 8, 10 · a group among another group's rows, a row's own height (a header drawn by hand, once rule 7 here, is
+// `substituteFindings`' first rule, on every element rather than only on `<h1>`–`<h6>`)
+const redecidedLooks = (name, words, parent) => [
+    ...(name === `RowGroup` && parent?.name === `RowGroup`
+        ? [
+              `a <RowGroup> laid straight among another group's rows nests one card in another: put groups side by side in a stack, or the inner one in a <RowNote variant="block"> where it lies on the outer card`,
+          ]
+        : []),
+    ...((name === `Row` || name === `DisclosureRow`) && ROW_HEIGHT.test(words)
+        ? [
+              `<${name}> is given a height of its own, so it stands taller or shorter than the rows beside it: a row is as tall as its tier, and a settings group whose rows share one height says so once with \`equal-rows\``,
+          ]
+        : []),
+];
+
+// How many sections a tag adds to its parent's stack (rule 9): one drawn several times (`v-for`) counts twice; an `else`
+// branch draws instead of its `if`; one that states its own distance from what precedes it (`mt-*`) is spaced already.
+const sectionWeight = (name, attrs, words) => {
+    if (!SECTIONS.has(name) || ELSE.test(attrs) || /(?:^|\s)m[ty]-(?!0(?:\s|$))/u.test(words)) {
+        return 0;
+    }
+    return /(?:^|\s)v-for=/u.test(attrs) ? 2 : 1;
+};
+
+// ── 9 · sections side by side, judged as their parent closes: it states their gap, or it is the template's root
+const unspaced = (frame) => {
+    if (frame.sections < 2 || (frame.name !== `#root` && SPACED.test(frame.words))) {
+        return undefined;
+    }
+    return frame.name === `#root`
+        ? `this template is several <RowGroup>/<Section>s side by side at its root, so whatever mounts it decides whether anything spaces them: wrap them in one box that states the gap (\`flex flex-col gap-6\`)`
+        : `<${frame.name}> holds several <RowGroup>/<Section>s and states no gap between them, so their headers touch the section above: give it the stack's gap (\`flex flex-col gap-6\`)`;
+};
+
+/**
+ * A blanked template's section findings: a header decision taken at the call site (4), a group among another group's
+ * rows (8), sections side by side with nothing spacing them (9), a row given a height (10).
+ */
+export const sectionFindings = (path, scan) => {
+    const findings = [];
+    walk(
+        scan,
+        ({ name, attrs, index }, stack) => {
+            const where = at(path, scan, index);
+            // The SFC's own `<template>` is the root every top-level element is a child of.
+            if (stack.length === 0 && name === `template`) {
+                return { name: `#root`, transparent: false, words: ``, sections: 0, at: where };
+            }
+            const words = classWordsOf(attrs);
+            const parent = parentOf(stack);
+            for (const why of [...retiredProps(name, attrs), ...redecidedLooks(name, words, parent)]) {
+                findings.push({ at: where, why });
+            }
+            if (parent !== undefined) {
+                parent.sections += sectionWeight(name, attrs, words);
+            }
+            return { name, transparent: name === `template` && !/(?:^|\s)(?:#|v-slot)/u.test(attrs), words, sections: 0, at: where };
+        },
+        (frame) => {
+            const why = unspaced(frame);
+            if (why !== undefined) {
+                findings.push({ at: frame.at, why });
+            }
+        },
+    );
+    return findings;
+};
+
+// ── Glyphs ───────────────────────────────────────────────────────────────────────────────────────────────────────
+
+// A utility that moves a box vertically, at any breakpoint.
+const ICON_OFFSET =
+    /(?:^|\s)(?:[\w@-]+:)*-?(?:mt|mb|my|translate-y|top)-[\w./[\]-]+|(?:^|\s)(?:[\w@-]+:)*align-(?:top|middle|bottom|text-top|text-bottom|sub|super|baseline|\[[^\]]*\])/u;
+const POSITIONED = /(?:^|\s)(?:absolute|fixed)(?:\s|$)/u;
+const SIZE = /(?:^|\s)((?:[\w@-]+:)*text-(?:4xs|3xs|2xs|xs|sm|base|lg|xl|2xl|\[[\d.]+rem\]))(?=\s|$)/gu;
+const sizesOf = (words) =>
+    [...words.matchAll(SIZE)]
+        .map((match) => match[1])
+        .toSorted()
+        .join(` `);
+
+// An `<Icon>` nudged by hand: a vertical utility on it that is not the placement of a positioned box.
+const nudgeOf = (words) => (POSITIONED.test(words) ? undefined : ICON_OFFSET.exec(words)?.[0].trim());
+
+// The first words after a glyph leading an `items-start` line, when they state a type size the line does not.
+const misreadLine = (line, words) => {
+    const stated = sizesOf(words);
+    const own = sizesOf(line.words);
+    return stated === `` || stated === own
+        ? undefined
+        : `the words this <Icon> leads state \`${stated}\` and their \`items-start\` line ${own === `` ? `states none` : `states \`${own}\``}: \`.ui-icon\` reads the line's height where its type is stated, so state the size on the line (the words inherit it)`;
+};
+
+/**
+ * A blanked template's glyph findings: an `<Icon>` nudged by hand, and a glyph-led `items-start` line whose first words
+ * state a type size the line does not (`.ui-icon` reads the line's height where its type is stated).
+ */
+export const glyphFindings = (path, scan) => {
+    const findings = [];
+    walk(scan, ({ name, attrs, index }, stack) => {
+        const words = classWordsOf(attrs);
+        const holder = stack.findLast((frame) => frame.name !== `template`);
+        const nudge = name === `Icon` ? nudgeOf(words) : undefined;
+        const why =
+            nudge === undefined
+                ? undefined
+                : `\`${nudge}\` nudges an <Icon> by hand: \`.ui-icon\` sits on the text it labels, and leading an \`items-start\` line it centres on the first row itself, at every size`;
+        // A line is read once, at the first element after its glyph: the words whose line the glyph centres on.
+        const led = holder?.glyphLed === true && holder.read !== true && name !== `Icon` && name !== `template`;
+        for (const said of [why, led ? misreadLine(holder, words) : undefined]) {
+            if (said !== undefined) {
+                findings.push({ at: at(path, scan, index), why: said });
+            }
+        }
+        if (holder !== undefined && holder.line) {
+            holder.glyphLed ||= name === `Icon` && holder.read !== true;
+            holder.read ||= led;
+        }
+        return { name, words, line: /(?:^|\s)items-start(?:\s|$)/u.test(words) };
+    });
+    return findings;
+};
+
+// ── Substitutes ──────────────────────────────────────────────────────────────────────────────────────────────────
+
+// Each kit primitive below was drawn by hand in a view before it existed, and was drawn by hand again after, by a view
+// that did not know it did. Where a rule's primitive is defined, the rule does not apply: it is that primitive's own
+// markup. `<th>`/`<tr>` are a table's column heads, which InfoTable draws in the label's type on purpose.
+const OWNERS = {
+    label: /(?:^|\/)_editor\/ui\/src\/components\/rows\/SectionHeader\.vue$/u,
+    tabs: /(?:^|\/)_editor\/ui\/src\/components\/forms\/SegmentedControl\.vue$/u,
+    search: /(?:^|\/)_editor\/ui\/src\/components\/forms\/SearchBar\.vue$/u,
+    open: /(?:^|\/)_editor\/ui\/src\/components\/rows\/DisclosureRow\.vue$/u,
+};
+const TABLE_HEAD = new Set([`th`, `tr`, `thead`]);
+const word = (name) => new RegExp(`(?:^|\\s)${name}(?:\\s|$)`, `u`);
+const SEARCH_DRESS = /(?:^|\s)ui-search(?:-band|-icon)?(?:\s|$)/u;
+const FIELD = new Set([`input`, `InputText`]);
+
+const SAYS = {
+    label: (name) =>
+        `<${name}> wears the section label's look (uppercase, tracked) by hand, so its size, spacing and what sits beside it are this view's to drift: a label over a part is <SectionHeader> (\`density="dense"\` in a menu, a drawer or a card), or <Section :label> around what it heads; words inside a row are not a heading and take no uppercase`,
+    tabs: `a tab strip drawn by hand: <SegmentedControl> owns the roving tab stop, the arrow keys and the selected mark (\`variant="underline"\` for tabs that switch the parts of a page)`,
+    search: `a search field drawn by hand: <SearchBar> (\`variant="panel"\` as a popover's first band, \`field\` above a list) owns the magnifier, the clear, Escape and the busy spin`,
+    open: `the open row's wash put on by hand: an expanding row is <DisclosureRow>, which owns \`ui-row-open\` behind its header and drawer as one surface`,
+};
+
+/**
+ * A blanked template's hand-drawn substitutes for a kit primitive, each as `{ index, rule, why }`: the section label's
+ * look on any element (`label`), a tab strip (`tabs`), a search field (`search`), and the open row's wash (`open`).
+ * The caller turns `index` into a line and reads `allow(substitutes)` there.
+ */
+export const substituteFindings = (path, scan) => {
+    const findings = [];
+    const owned = (rule) => OWNERS[rule].test(path);
+    const add = (index, rule, why) => {
+        if (!owned(rule)) {
+            findings.push({ index, rule, why });
+        }
+    };
+    // The open tag before this one, for a field that a magnifier glyph leads.
+    let previous;
+    for (const { closing, name, attrs, index } of tags(scan)) {
+        if (closing !== ``) {
+            previous = undefined;
+            continue;
+        }
+        const words = classWordsOf(attrs);
+        if (HEADER_LOOK(words) && !TABLE_HEAD.has(name)) {
+            add(index, `label`, SAYS.label(name));
+        }
+        if (/(?:^|\s)role="tablist"/u.test(attrs) || /\bui\.tab\(/u.test(attrs)) {
+            add(index, `tabs`, SAYS.tabs);
+        }
+        const ledByMagnifier = previous?.name === `Icon` && /(?:^|\s)name="search"/u.test(previous.attrs);
+        if (SEARCH_DRESS.test(words) || (FIELD.has(name) && (/(?:^|\s)type="search"/u.test(attrs) || ledByMagnifier))) {
+            add(index, `search`, SAYS.search);
+        }
+        if (word(`ui-row-open`).test(words)) {
+            add(index, `open`, SAYS.open);
+        }
+        previous = { name, attrs };
+    }
+    return findings;
+};
+
+// ── Chips and pills ──────────────────────────────────────────────────────────────────────────────────────────────
+
+// What a chip's or a pill's size owns: a padding, a height, a gap, a type size, a line height, a radius, at any variant.
+const BOX_WORD =
+    /^(?:p[xytblrse]?-|(?:min-|max-)?h-|size-|gap(?:-[xy])?-|leading-|rounded(?:-|$)|text-(?:4xs|3xs|2xs|xs|sm|base|lg|xl|2xl|\[[\d.]+r?em\]))/u;
+const bareWord = (token) => token.replace(/^!/u, ``).replace(/^(?:[\w@[\]&>*/-]+:)+/u, ``).replace(/^!/u, ``);
+
+/**
+ * The words of a class list that restate a chip's or a status pill's box, which utilities.css decides once per size
+ * (`ui.chip({ size, lead, trail })`, `ui-status-pill[-md|-inline]`): `kind` is which of the two the list draws, if
+ * either. A `ui.chip(…)` call's own arguments are left out, since the recipe check reads those on their own.
+ */
+export const boxOverrides = (classes) => {
+    const words = classes.replace(/ui\.chip\((?:[^()]|\([^()]*\))*\)/gu, ` ui-chip `);
+    const kind = /(?:^|\s)ui-chip(?=\s|$)/u.test(words) ? `chip` : /(?:^|\s)ui-status-pill(?=\s|$)/u.test(words) ? `pill` : undefined;
+    if (kind === undefined) {
+        return { kind, words: [] };
+    }
+    return {
+        kind,
+        words: words
+            .split(/\s+/u)
+            .map((token) => token.replace(/^[`'"([{]+|[`'")\]},]+$/gu, ``))
+            .filter((token) => BOX_WORD.test(bareWord(token))),
+    };
+};

package/check/scan.mjs

@@ -0,0 +1,42 @@
+// Markup reading without a parser, shared by the kit's own checks (check/kit-decisions.mjs, check/extension.mjs) and the
+// intentic repository's template gates (_tools/checks/lib/templates.mjs re-exports it), so an extension built outside the
+// repository is judged by the same walk as the editor. Needs nothing installed: checks run before `pnpm install`.
+
+// Blanks, not strips, `<script>`, `<style>` and `<!-- -->` regions so line numbers stay valid; each one's example
+// markup would otherwise misreport as real usage.
+const blanked = (m) => m.replace(/[^\n]/gu, ` `);
+export const blank = (source) =>
+    source
+        .replace(/<script\b[^>]*>[\s\S]*?<\/script>/gu, blanked)
+        .replace(/<style\b[^>]*>[\s\S]*?<\/style>/gu, blanked)
+        .replace(/<!--[\s\S]*?-->/gu, blanked);
+
+// A tag walk, not a parser: attribute values are consumed as units so a `>` inside `:class="{…}"` can't end a tag
+// early. A generator, not a shared regex, since `/g` carries `lastIndex` and callers would fight over one cursor.
+const TAG = /<(\/?)([A-Za-z][\w.-]*)((?:"[^"]*"|'[^']*'|`[^`]*`|[^>"'`])*?)(\/?)>/gu;
+export function* tags(scan, from = 0) {
+    const walk = new RegExp(TAG.source, TAG.flags);
+    walk.lastIndex = from;
+    let match;
+    while ((match = walk.exec(scan)) !== null) {
+        const [, closing, name, attrs, selfClosing] = match;
+        yield { closing, name, attrs, selfClosing, index: match.index, end: walk.lastIndex };
+    }
+}
+
+/** Elements with no closing tag, so a tag walk must not push them onto its stack. */
+export const VOID = new Set([`br`, `hr`, `img`, `input`, `source`]);
+
+/** `path:line` for an offset into the blanked scan, which shares the source's newlines. */
+export const at = (path, scan, index) => `${path}:${scan.slice(0, index).split(`\n`).length}`;
+
+/** Both `class="…"` and `:class="…"`, joined: geometry hidden in a bound class is the same geometry. */
+export const classesOf = (attrs) => [...attrs.matchAll(/:?class="([^"]*)"/gu)].map((m) => m[1]).join(` `);
+
+// Turns punctuation into whitespace: a bound class is often an array of template literals, so its first class is
+// preceded by a backtick, not a space, which a `(?:^|\s)`-anchored rule would otherwise miss.
+export const classWordsOf = (attrs) =>
+    classesOf(attrs)
+        .replace(/[`',]/gu, ` `)
+        .replace(/\s+/gu, ` `)
+        .trim();

package/dist/index.js

@@ -14,6 +14,7 @@ export const AddressField = m["AddressField"];
 export const AgentRunButton = m["AgentRunButton"];
 export const AnchoredOverlay = m["AnchoredOverlay"];
 export const Avatar = m["Avatar"];
+export const Await = m["Await"];
 export const BarChart = m["BarChart"];
 export const BottomSheet = m["BottomSheet"];
 export const BrandMark = m["BrandMark"];
@@ -36,6 +37,7 @@ export const ImageView = m["ImageView"];
 export const InfoDialog = m["InfoDialog"];
 export const InfoHint = m["InfoHint"];
 export const InfoTable = m["InfoTable"];
+export const InlineRename = m["InlineRename"];
 export const Markdown = m["Markdown"];
 export const MarkdownDocument = m["MarkdownDocument"];
 export const MarkdownFigure = m["MarkdownFigure"];
@@ -60,8 +62,11 @@ export const ResizeSeam = m["ResizeSeam"];
 export const ResponsiveOverlay = m["ResponsiveOverlay"];
 export const Row = m["Row"];
 export const RowGroup = m["RowGroup"];
+export const RowNote = m["RowNote"];
 export const ScrollFrame = m["ScrollFrame"];
 export const SearchBar = m["SearchBar"];
+export const Section = m["Section"];
+export const SectionHeader = m["SectionHeader"];
 export const SegmentedControl = m["SegmentedControl"];
 export const SkeletonRows = m["SkeletonRows"];
 export const SkeletonSnapshot = m["SkeletonSnapshot"];

package/dist/types/extension-ui/src/index.d.ts

@@ -1,4 +1,4 @@
-export { AgentRunButton, type AgentRunAttempt, type AgentRunChoice, type AgentRunPicker, type ModelPicking, useAgentRunPick, type FixStanceLook, fixStanceLook, AnchoredOverlay, Avatar, Button, vAction, BarChart, BottomSheet, BrandMark, Card, clipboardOf, browserOwnsClick, appLink, openForwardedPort, ChangeStatusMark, type ChangeStatus, ui, type IconButtonVariants, type TextButtonVariants, type InputVariants, type ChipVariants, type SectionLabelVariants, type ButtonTier, type ButtonTone, Code, CodeField, ConfirmDialog, ContextMenu, OverflowActions, ActionSheet, type ActionItem, CopyButton, AddressField, StatusTally, type TallyItem, DagEditor, DagGraph, type DagEdge, type DagNode, DiffStat, DisclosureRow, FilterBar, Icon, type IconName, ImageView, InfoDialog, InfoHint, InfoTable, type FileFormat, formatOf, Markdown, MarkdownDocument, MarkdownFigure, Modal, type NavGroup, NavRail, NoteEditor, type NoteDraft, type NoteDraftOptions, useNoteDraft, useKeyedDraft, type NoticeModel, type NoticeTone, type NoticeAction, Notice, NoticeStack, Page, PageAction, PageHeader, ScrollFrame, PersonaFace, type PersonaLike, Picker, ProjectChip, type PickerGroup, type PickerOption, type PickerOptions, ProgressRing, RepoPicker, type RepoPickerAll, RepoRail, type RepoRailAll, type RepoRailGroup, type RepoRailRow, ProseField, ResizeSeam, ResponsiveOverlay, Row, RowGroup, SearchBar, SegmentedControl, seriesColor, sinceOf, useLoadingReveal, SkeletonRows, SkeletonSnapshot, vSkeletonSource, SplitView, StatStrip, StatusBadge, type StatusVariant, StepSection, timeWindows, type TimeWindow, timeWindowWords, useCompact, useDevice, useListNavigation, useNow, useLatest, messageOr, messageOr as errorMessage, noticeFrom, noticeOf, useAsyncAction, useNarrow, useRailMemory, useScrollReset, type StickyTop, useStickyTop, useTheme, } from "../../ui/src/index.js";
+export { AgentRunButton, type AgentRunAttempt, type AgentRunChoice, type AgentRunPicker, type ModelPicking, useAgentRunPick, type FixStanceLook, fixStanceLook, AnchoredOverlay, Avatar, Button, vAction, BarChart, BottomSheet, BrandMark, Card, clipboardOf, browserOwnsClick, appLink, openForwardedPort, ChangeStatusMark, type ChangeStatus, ui, type IconButtonVariants, type TextButtonVariants, type InputVariants, type ChipVariants, type SectionLabelVariants, type ButtonTier, type ButtonTone, Code, CodeField, ConfirmDialog, ContextMenu, OverflowActions, ActionSheet, type ActionItem, CopyButton, AddressField, StatusTally, type TallyItem, DagEditor, DagGraph, type DagEdge, type DagNode, DiffStat, DisclosureRow, FilterBar, Icon, type IconName, ImageView, InfoDialog, InfoHint, InfoTable, InlineRename, type FileFormat, formatOf, Markdown, MarkdownDocument, MarkdownFigure, Modal, type NavGroup, NavRail, NoteEditor, type NoteDraft, type NoteDraftOptions, useNoteDraft, useKeyedDraft, type NoticeModel, type NoticeTone, type NoticeAction, Notice, NoticeStack, Page, PageAction, PageHeader, ScrollFrame, PersonaFace, type PersonaLike, Picker, ProjectChip, type PickerGroup, type PickerOption, type PickerOptions, ProgressRing, RepoPicker, type RepoPickerAll, RepoRail, type RepoRailAll, type RepoRailGroup, type RepoRailRow, ProseField, ResizeSeam, ResponsiveOverlay, Row, RowGroup, RowNote, Section, SectionHeader, SearchBar, SegmentedControl, seriesColor, sinceOf, useLoadingReveal, SkeletonRows, Await, SkeletonSnapshot, vSkeletonSource, SplitView, StatStrip, StatusBadge, type StatusVariant, StepSection, timeWindows, type TimeWindow, timeWindowWords, useCompact, useDevice, useListNavigation, useNow, useLatest, messageOr, messageOr as errorMessage, noticeFrom, noticeOf, useAsyncAction, useNarrow, useRailMemory, useScrollReset, type StickyTop, useStickyTop, useTheme, } from "../../ui/src/index.js";
 export { formatBytes, formatClock, formatCompact, formatCount, formatDate, formatDateLong, formatDateTime, formatDayMonth, formatDayMonthTime, formatDuration, formatElapsed, formatMoney, formatPercent, formatTime, formatTimestamp, formatTokens, formatWeekdayTime, formatWhen, freshness, timeAgo, } from "./format.js";
 export { type DiffMark, diffMark, type Signal, type TintWeight, type Tone, toneDot, toneFill, toneHover, toneInk, tonePlate, toneRim, toneTint, toneWash, } from "./tone.js";
 export { diffSequence, pairEdits, similarity, wordDiff } from "./diff.js";

package/dist/types/ui/src/components/feedback/Await.vue.d.ts

@@ -0,0 +1,36 @@
+import { type Loaded } from "@intentic/extension-api";
+import { type VNode } from "vue";
+declare const __VLS_export: <T>(__VLS_props: NonNullable<Awaited<typeof __VLS_setup>>["props"], __VLS_ctx?: __VLS_PrettifyLocal<Pick<NonNullable<Awaited<typeof __VLS_setup>>, "attrs" | "emit" | "slots">>, __VLS_exposed?: NonNullable<Awaited<typeof __VLS_setup>>["expose"], __VLS_setup?: Promise<{
+    props: import("vue").PublicProps & __VLS_PrettifyLocal<{
+        of: Loaded<T>;
+        imprint?: string | undefined;
+        label?: string | undefined;
+    }> & (typeof globalThis extends {
+        __VLS_PROPS_FALLBACK: infer P;
+    } ? P : {});
+    expose: (exposed: {}) => void;
+    attrs: any;
+    slots: {
+        default?(props: {
+            readonly data: T;
+            readonly refreshing: boolean;
+            readonly refreshError: string | undefined;
+        }): VNode[];
+        fallback?(): VNode[];
+        failed?(props: {
+            readonly error: string;
+            readonly retry: (() => void) | undefined;
+        }): VNode[];
+        idle?(): VNode[];
+    };
+    emit: {};
+}>) => import("vue").VNode & {
+    __ctx?: NonNullable<Awaited<typeof __VLS_setup>>;
+};
+declare const _default: typeof __VLS_export;
+export default _default;
+type __VLS_PrettifyLocal<T> = (T extends any ? {
+    [K in keyof T]: T[K];
+} : {
+    [K in keyof T as K]: T[K];
+}) & {};

package/dist/types/ui/src/components/feedback/InfoHint.vue.d.ts

@@ -1,6 +1,7 @@
 type __VLS_Props = {
     label: string;
     text?: string;
+    wide?: boolean;
 };
 declare var __VLS_1: {}, __VLS_14: {};
 type __VLS_Slots = {} & {

package/dist/types/ui/src/components/forms/InlineRename.vue.d.ts

@@ -0,0 +1,15 @@
+type __VLS_Props = {
+    value: string | undefined;
+    write: (name: string) => Promise<void>;
+    label: string;
+    action?: string;
+    fallback?: string;
+    editable?: boolean;
+    maxlength?: number;
+    failure?: string;
+};
+declare const __VLS_export: import("vue").DefineComponent<__VLS_Props, {
+    begin: () => void;
+}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<__VLS_Props> & Readonly<{}>, {}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
+declare const _default: typeof __VLS_export;
+export default _default;

package/dist/types/ui/src/components/forms/SearchBar.vue.d.ts

@@ -20,7 +20,7 @@ type __VLS_Slots = {} & {
     controls?: (props: typeof __VLS_6) => any;
 };
 declare const __VLS_base: import("vue").DefineComponent<__VLS_PublicProps, {
-    focus: (select?: boolean) => void;
+    focus: (select?: boolean | `end`) => void;
 }, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {
     clear: () => any;
     "update:modelValue": (value: string) => any;

package/dist/types/ui/src/components/layout/NavRail.vue.d.ts

@@ -3,7 +3,6 @@ declare const __VLS_export: <T>(__VLS_props: NonNullable<Awaited<typeof __VLS_se
     props: import("vue").PublicProps & __VLS_PrettifyLocal<({
         groups: readonly NavGroup<T>[];
         filterable?: boolean;
-        stickyHeadings?: boolean;
         placeholder?: string;
     } & {
         modelValue?: string;

package/dist/types/ui/src/components/rows/RowGroup.vue.d.ts

@@ -1,23 +1,23 @@
+import type { SectionLabelVariants } from "../../lib/ui.js";
 import { type RowDensity } from "./row.js";
 type __VLS_Props = {
     label?: string;
-    caption?: string;
-    flat?: boolean;
+    tone?: NonNullable<SectionLabelVariants[`tone`]>;
     undivided?: boolean;
     equalRows?: boolean;
     density?: RowDensity;
 };
-declare var __VLS_1: {}, __VLS_3: {}, __VLS_5: {}, __VLS_7: {}, __VLS_9: {};
+declare var __VLS_8: {}, __VLS_11: {}, __VLS_14: {}, __VLS_16: {}, __VLS_24: {};
 type __VLS_Slots = {} & {
-    label?: (props: typeof __VLS_1) => any;
+    label?: (props: typeof __VLS_8) => any;
 } & {
-    info?: (props: typeof __VLS_3) => any;
+    info?: (props: typeof __VLS_11) => any;
 } & {
-    actions?: (props: typeof __VLS_5) => any;
+    actions?: (props: typeof __VLS_14) => any;
 } & {
-    lead?: (props: typeof __VLS_7) => any;
+    lead?: (props: typeof __VLS_16) => any;
 } & {
-    default?: (props: typeof __VLS_9) => any;
+    default?: (props: typeof __VLS_24) => any;
 };
 declare const __VLS_base: import("vue").DefineComponent<__VLS_Props, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<__VLS_Props> & Readonly<{}>, {}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
 declare const __VLS_export: __VLS_WithSlots<typeof __VLS_base, __VLS_Slots>;

package/dist/types/ui/src/components/rows/RowNote.vue.d.ts

@@ -0,0 +1,35 @@
+import type { IconName } from "../../icons/iconSets.js";
+import { type RowTone } from "./row.js";
+type __VLS_Props = {
+    variant?: `note` | `empty` | `action` | `block`;
+    lead?: `icon` | `face`;
+    icon?: IconName;
+    tone?: RowTone;
+    label?: string;
+    disabled?: boolean;
+};
+declare var __VLS_1: {}, __VLS_3: {
+    mark: 22 | 18 | 28 | 36;
+}, __VLS_10: {}, __VLS_17: {};
+type __VLS_Slots = {} & {
+    default?: (props: typeof __VLS_1) => any;
+} & {
+    default?: (props: typeof __VLS_3) => any;
+} & {
+    default?: (props: typeof __VLS_10) => any;
+} & {
+    default?: (props: typeof __VLS_17) => any;
+};
+declare const __VLS_base: import("vue").DefineComponent<__VLS_Props, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {
+    click: (event: MouseEvent) => any;
+}, string, import("vue").PublicProps, Readonly<__VLS_Props> & Readonly<{
+    onClick?: ((event: MouseEvent) => any) | undefined;
+}>, {}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
+declare const __VLS_export: __VLS_WithSlots<typeof __VLS_base, __VLS_Slots>;
+declare const _default: typeof __VLS_export;
+export default _default;
+type __VLS_WithSlots<T, S> = T & {
+    new (): {
+        $slots: S;
+    };
+};

package/dist/types/ui/src/components/rows/Section.vue.d.ts

@@ -0,0 +1,27 @@
+import type { SectionLabelVariants } from "../../lib/ui.js";
+import { type RowDensity } from "./row.js";
+type __VLS_Props = {
+    label?: string;
+    tone?: NonNullable<SectionLabelVariants[`tone`]>;
+    heading?: 2 | 3 | 4;
+    density?: RowDensity;
+};
+declare var __VLS_8: {}, __VLS_11: {}, __VLS_14: {}, __VLS_16: {};
+type __VLS_Slots = {} & {
+    label?: (props: typeof __VLS_8) => any;
+} & {
+    info?: (props: typeof __VLS_11) => any;
+} & {
+    actions?: (props: typeof __VLS_14) => any;
+} & {
+    default?: (props: typeof __VLS_16) => any;
+};
+declare const __VLS_base: import("vue").DefineComponent<__VLS_Props, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<__VLS_Props> & Readonly<{}>, {}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
+declare const __VLS_export: __VLS_WithSlots<typeof __VLS_base, __VLS_Slots>;
+declare const _default: typeof __VLS_export;
+export default _default;
+type __VLS_WithSlots<T, S> = T & {
+    new (): {
+        $slots: S;
+    };
+};

package/dist/types/ui/src/components/rows/SectionHeader.vue.d.ts

@@ -0,0 +1,27 @@
+import { type SectionLabelVariants } from "../../lib/ui.js";
+import { type RowDensity } from "./row.js";
+type __VLS_Props = {
+    label?: string;
+    tone?: NonNullable<SectionLabelVariants[`tone`]>;
+    heading?: 2 | 3 | 4;
+    density?: RowDensity;
+};
+declare var __VLS_1: {}, __VLS_9: {}, __VLS_11: {}, __VLS_13: {};
+type __VLS_Slots = {} & {
+    mark?: (props: typeof __VLS_1) => any;
+} & {
+    label?: (props: typeof __VLS_9) => any;
+} & {
+    info?: (props: typeof __VLS_11) => any;
+} & {
+    actions?: (props: typeof __VLS_13) => any;
+};
+declare const __VLS_base: import("vue").DefineComponent<__VLS_Props, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<__VLS_Props> & Readonly<{}>, {}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
+declare const __VLS_export: __VLS_WithSlots<typeof __VLS_base, __VLS_Slots>;
+declare const _default: typeof __VLS_export;
+export default _default;
+type __VLS_WithSlots<T, S> = T & {
+    new (): {
+        $slots: S;
+    };
+};

package/dist/types/ui/src/components/rows/row.d.ts

@@ -11,6 +11,12 @@ export declare const ROW_TIERS: {
         readonly description: "text-xs";
         readonly headline: "basis-56";
         readonly mark: 28;
+        readonly heading: "sm";
+        readonly headingLine: "gap-x-2.5 gap-y-1";
+        readonly headingLabel: "min-w-0";
+        readonly headingInset: "px-1";
+        readonly headingGap: "mb-2.5";
+        readonly floor: "md:*:min-h-16";
     };
     readonly compact: {
         readonly pad: "px-4 py-2.5";
@@ -21,6 +27,12 @@ export declare const ROW_TIERS: {
         readonly description: "text-2xs";
         readonly headline: "basis-44";
         readonly mark: 22;
+        readonly heading: "sm";
+        readonly headingLine: "gap-x-2.5 gap-y-1";
+        readonly headingLabel: "min-w-0";
+        readonly headingInset: "px-1";
+        readonly headingGap: "mb-2.5";
+        readonly floor: "md:*:min-h-14";
     };
     readonly dense: {
         readonly pad: "px-2.5 py-2";
@@ -31,6 +43,12 @@ export declare const ROW_TIERS: {
         readonly description: "text-2xs";
         readonly headline: "basis-24";
         readonly mark: 18;
+        readonly heading: "xs";
+        readonly headingLine: "gap-x-2 gap-y-0.5";
+        readonly headingLabel: "min-w-0 truncate";
+        readonly headingInset: "pl-2 pr-1";
+        readonly headingGap: "mb-1";
+        readonly floor: "md:*:min-h-12";
     };
 };
 export declare const ROW_TONES: Record<RowTone, string>;

package/dist/types/ui/src/index.d.ts

@@ -32,6 +32,7 @@ export { type DagEdge, type DagNode } from "./components/charts/dagLayout.js";
 export { default as FilterBar } from "./components/forms/FilterBar.vue";
 export { default as Icon } from "./components/primitives/Icon.vue";
 export { default as ImageView } from "./components/primitives/ImageView.vue";
+export { default as InlineRename } from "./components/forms/InlineRename.vue";
 export { default as InfoDialog } from "./components/overlays/InfoDialog.vue";
 export { default as InfoHint } from "./components/feedback/InfoHint.vue";
 export { default as InfoTable } from "./components/feedback/InfoTable.vue";
@@ -66,10 +67,14 @@ export { default as ResizeSeam } from "./components/layout/ResizeSeam.vue";
 export { default as ResponsiveOverlay } from "./components/overlays/ResponsiveOverlay.vue";
 export { default as Row } from "./components/rows/Row.vue";
 export { default as RowGroup } from "./components/rows/RowGroup.vue";
+export { default as Section } from "./components/rows/Section.vue";
+export { default as SectionHeader } from "./components/rows/SectionHeader.vue";
+export { default as RowNote } from "./components/rows/RowNote.vue";
 export { default as SearchBar } from "./components/forms/SearchBar.vue";
 export { default as SegmentedControl } from "./components/forms/SegmentedControl.vue";
 export { seriesColor } from "./components/charts/seriesAccent.js";
 export { default as SkeletonRows } from "./components/feedback/SkeletonRows.vue";
+export { default as Await } from "./components/feedback/Await.vue";
 export { default as SkeletonSnapshot } from "./components/feedback/SkeletonSnapshot.vue";
 export { vSkeletonSource } from "./lib/skeleton/skeletonSource.js";
 export { default as SplitView } from "./components/layout/SplitView.vue";

package/dist/types/ui/src/lib/ui.d.ts

@@ -16,6 +16,9 @@ export interface InputVariants {
 }
 export interface ChipVariants {
     on?: boolean;
+    size?: `sm` | `md` | `lg`;
+    lead?: boolean;
+    trail?: boolean;
 }
 export interface SectionLabelVariants {
     size?: `sm` | `xs`;

package/names.d.mts

@@ -0,0 +1,22 @@
+export declare const extensionUiNames: readonly string[];
+
+export interface ExtensionUiDeprecation {
+    readonly name: string;
+    readonly use: string;
+    /** The extension API version an author first reads it as deprecated in. */
+    readonly since: string;
+    readonly deprecated: string;
+    readonly removableIn: string;
+}
+
+export declare const extensionUiDeprecated: readonly ExtensionUiDeprecation[];
+
+/** A prop (`Component.prop`) or recipe member (`ui.member`) a view may no longer use, though every name still links. */
+export interface ExtensionUiRetirement {
+    readonly name: string;
+    readonly use: string;
+    readonly since: string;
+    readonly why: string;
+}
+
+export declare const extensionUiRetired: readonly ExtensionUiRetirement[];

package/names.mjs

@@ -75,6 +75,7 @@ export const extensionUiNames = [
     "InfoDialog",
     "InfoHint",
     "InfoTable",
+    "InlineRename",
     "Markdown",
     "MarkdownDocument",
     "MarkdownFigure",
@@ -102,6 +103,9 @@ export const extensionUiNames = [
     "ResponsiveOverlay",
     "Row",
     "RowGroup",
+    "RowNote",
+    "Section",
+    "SectionHeader",
     "ScrollFrame",
     "SearchBar",
     "SegmentedControl",
@@ -109,6 +113,7 @@ export const extensionUiNames = [
     "similarity",
     "sinceOf",
     "SkeletonRows",
+    "Await",
     "SkeletonSnapshot",
     "vSkeletonSource",
     "SplitView",
@@ -140,13 +145,16 @@ export const extensionUiNames = [
     "wordDiff",
 ];
 
-// Names kept only so extensions built against them still link: what to use instead, when it was deprecated, and the
-// first extension API version that may drop it. A name leaves the kit only from this list, and only in a major at or
-// past its floor; the entry stays after it goes, as the record that its going was declared.
+// Names kept only so extensions built against them still link: what to use instead, when it was deprecated, the
+// extension API version an author first reads it as deprecated in (`since`, recorded per version in extension-api's
+// surface.json as `uiKitDeprecated`), and the first version that may drop it. A name leaves the kit only from this
+// list, and only in a major at or past its floor; the entry stays after it goes, as the record that its going was
+// declared. `intentic-kit-check` (check/cli.mjs) refuses an extension importing one.
 export const extensionUiDeprecated = [
     {
         name: "errorMessage",
         use: "messageOr",
+        since: "2.31.0",
         deprecated: "2026-10-06",
         removableIn: "3.0.0",
     },
@@ -154,7 +162,69 @@ export const extensionUiDeprecated = [
         // The repository column RepoPicker replaced on 2026-10-12, removed that day with no version moving and restored.
         name: "RepoRail",
         use: "RepoPicker",
+        since: "2.31.0",
         deprecated: "2026-10-15",
         removableIn: "3.0.0",
     },
+    {
+        // A view wired its own wait from these three, and each one it got wrong was a skeleton for ever, none at all, or
+        // the wrong one. <Await :of="loaded" imprint="…"> owns the reveal, the remembered look and what it is taken from.
+        name: "SkeletonSnapshot",
+        use: "Await",
+        since: "2.33.0",
+        deprecated: "2026-10-20",
+        removableIn: "3.0.0",
+    },
+    {
+        name: "vSkeletonSource",
+        use: "Await",
+        since: "2.33.0",
+        deprecated: "2026-10-20",
+        removableIn: "3.0.0",
+    },
+    {
+        name: "useLoadingReveal",
+        use: "Await",
+        since: "2.33.0",
+        deprecated: "2026-10-20",
+        removableIn: "3.0.0",
+    },
+];
+
+// What a view may no longer decide at a call site although the name it is on still links: a component's prop that was
+// removed (an older bundle passing it has it ignored, as a stray attribute) and a recipe drawn by hand where a component
+// now owns the look. `since` is the extension API version an author first reads it in (surface.json's
+// `uiKitDeprecated`); `why` is what the kit's own checks say where a call site still does it (check/kit-decisions.mjs
+// for props, check/extension.mjs for members), so the reason is written once.
+export const extensionUiRetired = [
+    {
+        name: "RowGroup.count",
+        use: "the rows themselves",
+        since: "2.34.0",
+        why: "the rows below are the tally, and a count beside a header is what a dozen views had removed one at a time",
+    },
+    {
+        name: "RowGroup.caption",
+        use: "RowNote",
+        since: "2.34.0",
+        why: "words beside a header were removed view by view as useless; a sentence a reader needs is a <RowNote> on the group's surface",
+    },
+    {
+        name: "RowGroup.flat",
+        use: "Section",
+        since: "2.34.0",
+        why: "a group draws no card on a surface (a dialog, a <Card>, another group's card, an overlay) by itself; a label over things that are not rows is a <Section>",
+    },
+    {
+        name: "NavRail.stickyHeadings",
+        use: "nothing: a rail's headers scroll with it",
+        since: "2.34.0",
+        why: "a pinned header needs a fill to scroll under, and that band is the dark box the documentation rail was fixed for three times",
+    },
+    {
+        name: "ui.sectionLabel",
+        use: "Section, or SectionHeader for a header alone",
+        since: "2.34.0",
+        why: "a header drawn in the section label's look by hand leaves its size, spacing and what sits beside it to the view, where they drift; <Section :label> (or <RowGroup :label> over rows) draws the kit's one header",
+    },
 ];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@intentic/extension-ui",
-  "version": "1.345.0",
+  "version": "1.346.0",
   "description": "The UI kit intentic extensions render with, host-provided at runtime (the app's own components via the import map), so extension UI is always native to the shell",
   "license": "MIT",
   "type": "module",
@@ -12,7 +12,9 @@
   "files": [
     "dist",
     "src",
-    "names.mjs"
+    "names.mjs",
+    "names.d.mts",
+    "check"
   ],
   "publishConfig": {
     "access": "public",
@@ -20,6 +22,9 @@
   },
   "main": "./dist/index.js",
   "types": "./dist/types/extension-ui/src/index.d.ts",
+  "bin": {
+    "intentic-kit-check": "./check/cli.mjs"
+  },
   "exports": {
     ".": {
       "@intentic/src": "./src/index.ts",
@@ -51,7 +56,8 @@
       "types": "./dist/types/extension-ui/src/i18n.d.ts",
       "default": "./dist/i18n.js"
     },
-    "./names": "./names.mjs"
+    "./names": "./names.mjs",
+    "./check": "./check/extension.mjs"
   },
   "dependencies": {
     "primevue": "4.5.5"

package/src/index.ts

@@ -81,6 +81,9 @@ export {
     InfoDialog,
     InfoHint,
     InfoTable,
+    // The app's one rename: the name in place with its pencil, the field in the same box, and its failure; never a
+    // field of an extension's own beside the name.
+    InlineRename,
     // What a file is by its name (category, label, whether it is ever text), the table the shell's own surfaces read.
     type FileFormat,
     formatOf,
@@ -139,19 +142,27 @@ export {
     // Use over `AnchoredOverlay` for a menu: anchored on desktop, a thumb-reachable sheet on a phone, one open flag.
     ResponsiveOverlay,
     Row,
+    // A list is a <RowGroup>: the one section header over the rows' card, on which <RowNote> says what is none of its
+    // rows. A label over things that are not rows is a <Section>; the header alone (a panel's title) is
+    // <SectionHeader>. None of them can carry a count, a caption or a fill, and their spacing is the tier's.
     RowGroup,
+    RowNote,
+    Section,
+    SectionHeader,
     SearchBar,
     SegmentedControl,
     seriesColor,
     sinceOf,
-    // Gates a skeleton placeholder so a flash on a fast read never shows; see its own note in the kit for the two
-    // thresholds.
+    // Deprecated (2026-10-20) with SkeletonSnapshot and vSkeletonSource: <Await> holds all three.
     useLoadingReveal,
     // Renders real `<Row>`s rather than divs, so its height matches what replaces it and the page doesn't jump.
     SkeletonRows,
-    // A placeholder drawn exactly as its content last looked in this sandbox: `v-skeleton-source="name"` on the
-    // content takes its imprint once settled, `<SkeletonSnapshot of="name">` draws it, its slot the fallback until then.
-    // Prefix the name with the extension's id, since every extension's imprints share the sandbox's store.
+    // A region's wait: `<Await :of="query.loaded" imprint="ext-id.list">`, where `loaded` is what `api.sandbox.query`
+    // returns. Nothing for a moment, then the region as it last looked in this sandbox (its `#fallback` until seen once),
+    // the answer in the default slot, or the failure in words. Prefix the name with the extension's id, since every
+    // extension's imprints share the sandbox's store. A view's first wait is its host's: every read joins it.
+    Await,
+    // Deprecated (2026-10-20): <Await>'s insides, kept so extensions built against them still link.
     SkeletonSnapshot,
     vSkeletonSource,
     SplitView,