@texuli/tools 0.0.0-stage → 0.1.0-next.0

package/dist/golden/axe.d.ts

@@ -0,0 +1,32 @@
+import type { GoldenAxeRunner } from './types.js';
+/**
+ * The axe rules the golden set checks: WCAG 2.0 and 2.1 A and AA plus best
+ * practice. `color-contrast` is off here because the paint has no theme CSS
+ * (an offline DOM computes no colors); contrast is gated by the token AA
+ * checks and the browser axe suites instead.
+ */
+export declare const GOLDEN_AXE_OPTIONS: Readonly<{
+    runOnly: {
+        type: string;
+        values: string[];
+    };
+    rules: {
+        'color-contrast': {
+            enabled: boolean;
+        };
+    };
+}>;
+/** The part of axe-core's API the runner needs. */
+export interface AxeLike {
+    run(context: Document | Element, options: object): Promise<{
+        violations: readonly {
+            id: string;
+            impact?: string | null;
+            nodes: readonly {
+                html?: string;
+            }[];
+        }[];
+    }>;
+}
+/** Wraps an axe-core instance (the caller supplies it) as a golden axe runner. */
+export declare function createAxeRunner(axe: AxeLike): GoldenAxeRunner;

package/dist/golden/axe.js

@@ -0,0 +1,22 @@
+/**
+ * The axe rules the golden set checks: WCAG 2.0 and 2.1 A and AA plus best
+ * practice. `color-contrast` is off here because the paint has no theme CSS
+ * (an offline DOM computes no colors); contrast is gated by the token AA
+ * checks and the browser axe suites instead.
+ */
+export const GOLDEN_AXE_OPTIONS = Object.freeze({
+    runOnly: { type: 'tag', values: ['wcag2a', 'wcag2aa', 'wcag21a', 'wcag21aa', 'best-practice'] },
+    rules: { 'color-contrast': { enabled: false } },
+});
+/** Wraps an axe-core instance (the caller supplies it) as a golden axe runner. */
+export function createAxeRunner(axe) {
+    return async (doc) => {
+        const result = await axe.run(doc, GOLDEN_AXE_OPTIONS);
+        return result.violations.map((violation) => ({
+            id: violation.id,
+            impact: violation.impact ?? null,
+            nodes: violation.nodes.length,
+            sample: violation.nodes[0]?.html?.slice(0, 160),
+        }));
+    };
+}

package/dist/golden/catalog.d.ts

@@ -0,0 +1,24 @@
+import type { CatalogManifest } from '@texuli/catalog/manifest';
+import { type GrammarComponentMeta, type GrammarRoleCatalog } from '@texuli/catalog/render/grammar';
+import { type RenderCatalog } from '@texuli/catalog/render/renderer';
+/**
+ * The agent surface the golden set targets: every agent-emittable catalog
+ * component (the content components and the five content layouts).
+ */
+export declare const GOLDEN_LAYOUT_MANIFESTS: readonly CatalogManifest[];
+export declare const GOLDEN_MANIFESTS: readonly CatalogManifest[];
+/** Layouts a golden interface starts from: each paints the page's `main`. */
+export declare const GOLDEN_FRAME_IDS: readonly ["layout-page", "layout-doc", "layout-deck"];
+export declare function goldenManifest(id: string): CatalogManifest | undefined;
+export declare function goldenRenderCatalog(): RenderCatalog;
+/**
+ * Heading rank each chart renders for its `title` (read from the components:
+ * cartesian and matrix charts use `h2`; flow, geo and part-whole charts `h3`).
+ * Compact charts render no heading.
+ */
+export declare const CHART_TITLE_LEVELS: Readonly<Record<string, 2 | 3>>;
+/** The id the heading projection uses for every outline entry. */
+export declare const GOLDEN_HEADING_ID = "golden-heading";
+/** Grammar roles for the projected golden tree (see `projectOutline`). */
+export declare const GOLDEN_GRAMMAR_ROLES: readonly GrammarComponentMeta[];
+export declare const goldenGrammarRoles: GrammarRoleCatalog;

package/dist/golden/catalog.js

@@ -0,0 +1,85 @@
+import { CONTENT_MANIFESTS } from '@texuli/catalog/manifests/content';
+import { DISPLAY_MANIFESTS } from '@texuli/catalog/manifests/display';
+import { FORMS_MANIFESTS } from '@texuli/catalog/manifests/forms';
+import { cardLayoutManifest, deckLayoutManifest, docLayoutManifest, gridLayoutManifest, LAYOUTS_MANIFESTS, pageLayoutManifest, } from '@texuli/catalog/manifests/layouts';
+import { OVERLAYS_MANIFESTS } from '@texuli/catalog/manifests/overlays';
+import { grammarRolesFromList, } from '@texuli/catalog/render/grammar';
+import { renderCatalogFromSpecs, } from '@texuli/catalog/render/renderer';
+/**
+ * The agent surface the golden set targets: every agent-emittable catalog
+ * component (the content components and the five content layouts).
+ */
+export const GOLDEN_LAYOUT_MANIFESTS = Object.freeze([
+    pageLayoutManifest,
+    docLayoutManifest,
+    deckLayoutManifest,
+    cardLayoutManifest,
+    gridLayoutManifest,
+]);
+export const GOLDEN_MANIFESTS = Object.freeze([
+    ...GOLDEN_LAYOUT_MANIFESTS,
+    ...CONTENT_MANIFESTS,
+]);
+/** Layouts a golden interface starts from: each paints the page's `main`. */
+export const GOLDEN_FRAME_IDS = ['layout-page', 'layout-doc', 'layout-deck'];
+export function goldenManifest(id) {
+    return GOLDEN_MANIFESTS.find((manifest) => manifest.id === id);
+}
+/**
+ * Every catalog component, so an agent that emits app chrome (a `dialog`, a
+ * `sidebar`) is told `tier-denied` rather than `unknown-id`. Only the agent
+ * surface (`GOLDEN_MANIFESTS`) is emittable under the `untrusted` tier.
+ */
+const CATALOG_MANIFESTS = [
+    ...CONTENT_MANIFESTS,
+    ...DISPLAY_MANIFESTS,
+    ...FORMS_MANIFESTS,
+    ...LAYOUTS_MANIFESTS,
+    ...OVERLAYS_MANIFESTS,
+];
+export function goldenRenderCatalog() {
+    return renderCatalogFromSpecs(CATALOG_MANIFESTS.map((manifest) => ({
+        id: manifest.id,
+        label: manifest.label,
+        props: manifest.props,
+        agentEmittable: manifest.agentEmittable === true,
+        emit: manifest.agentEmittable === true ? ['developer', 'untrusted'] : ['developer'],
+    })));
+}
+/**
+ * Heading rank each chart renders for its `title` (read from the components:
+ * cartesian and matrix charts use `h2`; flow, geo and part-whole charts `h3`).
+ * Compact charts render no heading.
+ */
+export const CHART_TITLE_LEVELS = Object.freeze({
+    'charts-area': 2,
+    'charts-bar': 2,
+    'charts-cartesian': 2,
+    'charts-combo': 2,
+    'charts-line': 2,
+    'charts-stacked-bar': 2,
+    'charts-bubble': 2,
+    'charts-heatmap': 2,
+    'charts-scatter': 2,
+    'charts-funnel': 3,
+    'charts-network': 3,
+    'charts-sankey': 3,
+    'charts-geo-map': 3,
+    'charts-geo-point-map': 3,
+    'charts-donut': 3,
+    'charts-pie': 3,
+    'charts-sunburst': 3,
+    'charts-treemap': 3,
+});
+/** The id the heading projection uses for every outline entry. */
+export const GOLDEN_HEADING_ID = 'golden-heading';
+/** Grammar roles for the projected golden tree (see `projectOutline`). */
+export const GOLDEN_GRAMMAR_ROLES = Object.freeze([
+    { id: GOLDEN_HEADING_ID, role: 'heading', headingLevelProp: 'level' },
+    { id: 'layout-page', role: 'landmark', landmark: 'main' },
+    { id: 'layout-doc', role: 'landmark', landmark: 'main' },
+    { id: 'layout-deck', role: 'landmark', landmark: 'main' },
+    { id: 'layout-card', role: 'container' },
+    { id: 'layout-grid', role: 'container' },
+]);
+export const goldenGrammarRoles = grammarRolesFromList(GOLDEN_GRAMMAR_ROLES);

package/dist/golden/cli.d.ts

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+/**
+ * `texuli-golden <outputs.json> [--json]`: scores a model run, an object of
+ * `{ "<task id>": <catalog tree> }`, and prints the report. Report-only: the
+ * exit code is 0 whatever the scores; only unreadable input exits 2. The axe
+ * check needs a DOM and is skipped here (the test suite runs it).
+ */
+declare function main(argv: readonly string[]): Promise<number>;
+export { main as runGoldenCli };

package/dist/golden/cli.js

@@ -0,0 +1,45 @@
+#!/usr/bin/env node
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { formatGoldenReport, scoreGoldenRun } from "./report.js";
+/**
+ * `texuli-golden <outputs.json> [--json]`: scores a model run, an object of
+ * `{ "<task id>": <catalog tree> }`, and prints the report. Report-only: the
+ * exit code is 0 whatever the scores; only unreadable input exits 2. The axe
+ * check needs a DOM and is skipped here (the test suite runs it).
+ */
+async function main(argv) {
+    const file = argv.find((arg) => !arg.startsWith('--'));
+    if (!file) {
+        process.stderr.write('usage: texuli-golden <outputs.json> [--json]\n');
+        return 2;
+    }
+    let outputs;
+    try {
+        outputs = JSON.parse(readFileSync(file, 'utf8'));
+    }
+    catch (error) {
+        process.stderr.write(`texuli-golden: cannot read ${file}: ${error.message}\n`);
+        return 2;
+    }
+    const report = await scoreGoldenRun(outputs);
+    process.stdout.write(argv.includes('--json') ? `${JSON.stringify(report, null, 2)}\n` : formatGoldenReport(report));
+    return 0;
+}
+function isMainModule(metaUrl) {
+    const entry = process.argv[1];
+    if (!entry)
+        return false;
+    try {
+        return fileURLToPath(metaUrl) === entry;
+    }
+    catch {
+        return false;
+    }
+}
+if (isMainModule(import.meta.url)) {
+    main(process.argv.slice(2)).then((code) => {
+        process.exitCode = code;
+    });
+}
+export { main as runGoldenCli };

package/dist/golden/guidance.d.ts

@@ -0,0 +1,12 @@
+import type { CatalogTreeInput } from '@texuli/catalog/render/renderer';
+export interface GuidanceDetector {
+    /** The exact `dontUseWhen` line, as the manifests write it. */
+    line: string;
+    /** Component ids whose manifests carry the line. */
+    appliesTo: (id: string) => boolean;
+    /** Returns why `node` breaks the guidance, or `null`. */
+    detect: (node: CatalogTreeInput) => string | null;
+}
+export declare const GUIDANCE_DETECTORS: readonly GuidanceDetector[];
+/** `dontUseWhen` findings for a tree, one line per node and broken guidance. */
+export declare function checkGuidance(tree: CatalogTreeInput): string[];

package/dist/golden/guidance.js

@@ -0,0 +1,171 @@
+import { goldenManifest } from "./catalog.js";
+/**
+ * Machine checks for the `dontUseWhen` guidance of the agent surface. Each
+ * detector is keyed by the exact manifest line it enforces; a test fails when
+ * a manifest gains a line no detector covers, so guidance never drifts silently.
+ */
+const NAV_LINK = /^\s*\[[^\]]+\]\([^)]+\)\s*$/;
+const LINK_LABEL = /\[([^\]]+)\]\([^)]*\)/g;
+const ACCOUNT = /\b(?:sign[\s-]?(?:in|out|up)|log[\s-]?(?:in|out)|my account|account settings|password)\b/i;
+const MUTATION = /^\s*(?:delete|remove|save|submit|pay|buy|purchase|subscribe|cancel|archive|approve|reject|send|upgrade)\b/i;
+const CHROME_TITLE = /\b(?:navigation|nav|menu|sidebar|top[\s-]?nav|toolbar|dialog|modal)\b/i;
+const SINK_KEY = /^(?:innerHTML|outerHTML|srcdoc|html|dangerouslySetInnerHTML)$/i;
+const CODE_TEXT = /\beval\s*\(|\bnew\s+Function\b|<script\b|javascript:/i;
+const IFRAME_TAG = /<iframe\b[^>]*>/gi;
+const ORIGIN_KEY = /^(?:targetOrigin|origin|origins|allowedOrigins|frameSrc|frame-src)$/i;
+/** Every key/value pair inside an embed-app block's `app` JSON, depth first. */
+function appEntries(block) {
+    if (block.type !== 'embed-app')
+        return [];
+    const out = [];
+    const visit = (value, key, depth) => {
+        if (depth > 12)
+            return;
+        out.push([key, value]);
+        if (Array.isArray(value)) {
+            for (const item of value)
+                visit(item, key, depth + 1);
+        }
+        else if (value && typeof value === 'object') {
+            for (const [k, v] of Object.entries(value))
+                visit(v, k, depth + 1);
+        }
+    };
+    visit(block.app, 'app', 0);
+    return out;
+}
+function asBlock(node) {
+    const block = node.props?.block;
+    return block && typeof block === 'object' && !Array.isArray(block) ? block : undefined;
+}
+function linkLabels(text) {
+    return [...text.matchAll(LINK_LABEL)].map((match) => match[1] ?? '');
+}
+/** Text a block shows as links: list items and Markdown link labels. */
+function blockLinks(block) {
+    const items = block.type === 'list' && Array.isArray(block.items)
+        ? block.items.map((item) => item && typeof item === 'object' ? String(item.text ?? '') : '')
+        : [];
+    const text = [block.markdown, block.body, ...items]
+        .filter((v) => typeof v === 'string')
+        .join('\n');
+    const ctaLabels = block.type === 'cta' && Array.isArray(block.actions)
+        ? block.actions.map((action) => action && typeof action === 'object' ? String(action.label ?? '') : '')
+        : [];
+    return { items, labels: [...linkLabels(text), ...ctaLabels] };
+}
+/** A list of three or more items that are each only a link: a navigation menu. */
+function isNavLinkList(block) {
+    const { items } = blockLinks(block);
+    return items.length >= 3 && items.every((item) => NAV_LINK.test(item));
+}
+export const GUIDANCE_DETECTORS = Object.freeze([
+    {
+        line: 'Application navigation, account controls or mutations.',
+        appliesTo: (id) => id.startsWith('blocks-') || id.startsWith('charts-') || id.startsWith('media-'),
+        detect(node) {
+            const block = asBlock(node);
+            if (!block)
+                return null;
+            if (isNavLinkList(block))
+                return 'a list of bare links is application navigation';
+            if (block.type === 'cta')
+                return 'call-to-action buttons are mutations';
+            const labels = blockLinks(block).labels;
+            const account = labels.find((label) => ACCOUNT.test(label));
+            if (account)
+                return `"${account}" is an account control`;
+            const mutation = labels.find((label) => MUTATION.test(label));
+            if (mutation)
+                return `"${mutation}" is a mutation`;
+            return null;
+        },
+    },
+    {
+        line: 'Running untrusted app JSON with innerHTML, eval, or an unsandboxed iframe.',
+        appliesTo: (id) => id === 'blocks-embed',
+        detect(node) {
+            const block = asBlock(node);
+            if (!block)
+                return null;
+            for (const [key, value] of appEntries(block)) {
+                if (SINK_KEY.test(key))
+                    return `app JSON asks for an HTML sink ("${key}")`;
+                if (typeof value !== 'string')
+                    continue;
+                if (CODE_TEXT.test(value))
+                    return 'app JSON carries code to evaluate';
+                const iframes = value.match(IFRAME_TAG) ?? [];
+                if (iframes.some((tag) => !/\bsandbox\b/i.test(tag))) {
+                    return 'app JSON embeds an iframe without a sandbox';
+                }
+            }
+            return null;
+        },
+    },
+    {
+        line: 'Relaxing iframe sandbox (especially adding allow-same-origin) or skipping CSP frame-src / postMessage origin checks.',
+        appliesTo: (id) => id === 'blocks-embed',
+        detect(node) {
+            const block = asBlock(node);
+            if (!block)
+                return null;
+            for (const [key, value] of appEntries(block)) {
+                if (/^sandbox$/i.test(key) &&
+                    typeof value === 'string' &&
+                    /allow-same-origin/i.test(value)) {
+                    return 'the sandbox adds allow-same-origin';
+                }
+                const wildcard = Array.isArray(value) ? value.includes('*') : value === '*';
+                if (ORIGIN_KEY.test(key) && wildcard)
+                    return `"${key}" accepts any origin`;
+            }
+            return null;
+        },
+    },
+    {
+        line: 'App chrome shells (sidebar, top-nav, dialogs)',
+        appliesTo: (id) => id.startsWith('layout-'),
+        detect(node) {
+            const title = node.props?.title;
+            if (typeof title === 'string' && CHROME_TITLE.test(title)) {
+                return `a layout titled "${title}" is app chrome`;
+            }
+            const children = node.children ?? [];
+            const navs = children.filter((child) => {
+                const block = asBlock(child);
+                return block !== undefined && isNavLinkList(block);
+            });
+            if (children.length > 0 && navs.length === children.length) {
+                return 'a layout that holds only link lists is a navigation shell';
+            }
+            return null;
+        },
+    },
+]);
+function walk(nodes, path, visit) {
+    nodes.forEach((node, index) => {
+        if (!node || typeof node !== 'object')
+            return;
+        const here = path ? `${path}.children.${index}` : String(index);
+        visit(node, here);
+        if (Array.isArray(node.children))
+            walk(node.children, here, visit);
+    });
+}
+/** `dontUseWhen` findings for a tree, one line per node and broken guidance. */
+export function checkGuidance(tree) {
+    const issues = [];
+    walk([tree], '', (node, path) => {
+        const id = typeof node.id === 'string' ? node.id : '';
+        const lines = goldenManifest(id)?.dontUseWhen ?? [];
+        for (const detector of GUIDANCE_DETECTORS) {
+            if (!detector.appliesTo(id) || !lines.includes(detector.line))
+                continue;
+            const why = detector.detect(node);
+            if (why)
+                issues.push(`${path} ${id}: ${why} ("${detector.line}")`);
+        }
+    });
+    return issues;
+}

package/dist/golden/index.d.ts

@@ -0,0 +1,17 @@
+/**
+ * `@texuli/tools/golden` (T-tool-golden): the agent golden set, 30
+ * pre-registered interface tasks with reference trees, and an offline scorer.
+ * A tree is checked for schema validity, `dontUseWhen` guidance, sinks,
+ * composition grammar, axe on a real DOM paint, and task coverage. Model runs
+ * are report-only (`scoreGoldenRun`, the `texuli-golden` CLI).
+ */
+export { type AxeLike, createAxeRunner, GOLDEN_AXE_OPTIONS } from './axe.js';
+export { CHART_TITLE_LEVELS, GOLDEN_FRAME_IDS, GOLDEN_GRAMMAR_ROLES, GOLDEN_MANIFESTS, goldenGrammarRoles, goldenManifest, goldenRenderCatalog, } from './catalog.js';
+export { checkGuidance, GUIDANCE_DETECTORS, type GuidanceDetector } from './guidance.js';
+export { projectOutline } from './outline.js';
+export { type GoldenPaint, type GoldenPaintOptions, paintGoldenTree } from './paint.js';
+export { formatGoldenReport, type GoldenRunReport, scoreGoldenRun } from './report.js';
+export { type GoldenScoreOptions, scoreGoldenTree } from './score.js';
+export { checkSinks } from './sinks.js';
+export { GOLDEN_TASKS, goldenTask } from './tasks.js';
+export { GOLDEN_CHECKS, type GoldenAxeRunner, type GoldenAxeViolation, type GoldenCheckId, type GoldenCheckResult, type GoldenCheckStatus, type GoldenScore, type GoldenTask, } from './types.js';

package/dist/golden/index.js

@@ -0,0 +1,17 @@
+/**
+ * `@texuli/tools/golden` (T-tool-golden): the agent golden set, 30
+ * pre-registered interface tasks with reference trees, and an offline scorer.
+ * A tree is checked for schema validity, `dontUseWhen` guidance, sinks,
+ * composition grammar, axe on a real DOM paint, and task coverage. Model runs
+ * are report-only (`scoreGoldenRun`, the `texuli-golden` CLI).
+ */
+export { createAxeRunner, GOLDEN_AXE_OPTIONS } from "./axe.js";
+export { CHART_TITLE_LEVELS, GOLDEN_FRAME_IDS, GOLDEN_GRAMMAR_ROLES, GOLDEN_MANIFESTS, goldenGrammarRoles, goldenManifest, goldenRenderCatalog, } from "./catalog.js";
+export { checkGuidance, GUIDANCE_DETECTORS } from "./guidance.js";
+export { projectOutline } from "./outline.js";
+export { paintGoldenTree } from "./paint.js";
+export { formatGoldenReport, scoreGoldenRun } from "./report.js";
+export { scoreGoldenTree } from "./score.js";
+export { checkSinks } from "./sinks.js";
+export { GOLDEN_TASKS, goldenTask } from "./tasks.js";
+export { GOLDEN_CHECKS, } from "./types.js";

package/dist/golden/outline.d.ts

@@ -0,0 +1,21 @@
+import type { RenderNode } from '@texuli/catalog/render/renderer';
+/**
+ * The heading outline of a golden interface. The grammar check and the DOM
+ * paint both use these rules, so the checked outline is the painted one:
+ *
+ * - a page, doc or deck `title` is the `h1`;
+ * - a card `title` is one rank below the nearest titled frame around it;
+ * - a heading text block keeps its own `level`;
+ * - a chart `title` renders at the chart's fixed rank (`CHART_TITLE_LEVELS`).
+ */
+export declare function isFrame(id: string): boolean;
+/** The rank a titled card renders its heading at, under `parentLevel`. */
+export declare function cardHeadingLevel(parentLevel: number): number;
+export declare function titleOf(node: RenderNode): string | undefined;
+/** A heading text block's level, or `undefined` for any other node. */
+export declare function textHeadingLevel(node: RenderNode): number | undefined;
+/**
+ * Rewrites a render tree so every outline entry is a `golden-heading` node
+ * with its rank, in document order, for `checkCompositionGrammar`.
+ */
+export declare function projectOutline(roots: readonly RenderNode[], parentLevel?: number): RenderNode[];

package/dist/golden/outline.js

@@ -0,0 +1,68 @@
+import { CHART_TITLE_LEVELS, GOLDEN_FRAME_IDS, GOLDEN_HEADING_ID } from "./catalog.js";
+/**
+ * The heading outline of a golden interface. The grammar check and the DOM
+ * paint both use these rules, so the checked outline is the painted one:
+ *
+ * - a page, doc or deck `title` is the `h1`;
+ * - a card `title` is one rank below the nearest titled frame around it;
+ * - a heading text block keeps its own `level`;
+ * - a chart `title` renders at the chart's fixed rank (`CHART_TITLE_LEVELS`).
+ */
+export function isFrame(id) {
+    return GOLDEN_FRAME_IDS.includes(id);
+}
+/** The rank a titled card renders its heading at, under `parentLevel`. */
+export function cardHeadingLevel(parentLevel) {
+    return Math.min(parentLevel + 1, 6);
+}
+export function titleOf(node) {
+    if (node.kind !== 'component')
+        return undefined;
+    const title = node.props.title;
+    return typeof title === 'string' && title.trim() !== '' ? title : undefined;
+}
+/** A heading text block's level, or `undefined` for any other node. */
+export function textHeadingLevel(node) {
+    if (node.kind !== 'component' || node.id !== 'blocks-text')
+        return undefined;
+    const block = node.props.block;
+    return block?.type === 'heading' && typeof block.level === 'number' ? block.level : undefined;
+}
+function heading(level) {
+    return { kind: 'component', id: GOLDEN_HEADING_ID, props: { level }, children: [] };
+}
+/**
+ * Rewrites a render tree so every outline entry is a `golden-heading` node
+ * with its rank, in document order, for `checkCompositionGrammar`.
+ */
+export function projectOutline(roots, parentLevel = 0) {
+    return roots.map((node) => {
+        if (node.kind !== 'component')
+            return node;
+        const textLevel = textHeadingLevel(node);
+        if (textLevel !== undefined)
+            return heading(textLevel);
+        const title = titleOf(node);
+        let level = parentLevel;
+        const lead = [];
+        if (isFrame(node.id)) {
+            if (title) {
+                level = 1;
+                lead.push(heading(1));
+            }
+        }
+        else if (node.id === 'layout-card') {
+            if (title) {
+                level = cardHeadingLevel(parentLevel);
+                lead.push(heading(level));
+            }
+        }
+        else if (title && CHART_TITLE_LEVELS[node.id]) {
+            lead.push(heading(CHART_TITLE_LEVELS[node.id]));
+        }
+        return {
+            ...node,
+            children: [...lead, ...projectOutline(node.children, level)],
+        };
+    });
+}

package/dist/golden/paint.d.ts

@@ -0,0 +1,21 @@
+import type { RenderNode } from '@texuli/catalog/render/renderer';
+import { type ElementComponentLoader } from '../elements/content.js';
+/**
+ * Paints a rendered golden tree into a document so axe can check it. Content
+ * components mount for real (the element loaders); the five content layouts
+ * become the semantic containers a host maps them to: a frame is `main` with
+ * its title as the `h1`, a card is a labelled `section`, a grid a plain group.
+ * Markup is never built from strings: `createElement` and `textContent` only.
+ */
+export interface GoldenPaint {
+    /** Components that failed to load or mount, or refused their props. */
+    issues: readonly string[];
+    destroy(): void;
+}
+export interface GoldenPaintOptions {
+    loaders?: Readonly<Record<string, ElementComponentLoader>>;
+    /** The document title and `lang` (axe checks both). */
+    title?: string;
+    lang?: string;
+}
+export declare function paintGoldenTree(roots: readonly RenderNode[], doc: Document, options?: GoldenPaintOptions): Promise<GoldenPaint>;

package/dist/golden/paint.js

@@ -0,0 +1,103 @@
+import { mount, tick, unmount } from 'svelte';
+import { CONTENT_ELEMENT_LOADERS } from "../elements/content.js";
+import { goldenManifest } from "./catalog.js";
+import { cardHeadingLevel, isFrame, titleOf } from "./outline.js";
+let sequence = 0;
+export async function paintGoldenTree(roots, doc, options = {}) {
+    const loaders = options.loaders ?? CONTENT_ELEMENT_LOADERS;
+    const issues = [];
+    const instances = [];
+    doc.documentElement.lang = options.lang ?? 'en';
+    doc.title = options.title ?? 'Golden interface';
+    doc.body.replaceChildren();
+    const headingEl = (level, text) => {
+        const el = doc.createElement(`h${Math.min(Math.max(level, 1), 6)}`);
+        el.textContent = text;
+        return el;
+    };
+    const paint = async (node, parent, level, path) => {
+        if (node.kind === 'placeholder') {
+            const note = doc.createElement('p');
+            note.setAttribute('role', 'note');
+            note.textContent = node.label;
+            parent.append(note);
+            return;
+        }
+        const title = titleOf(node);
+        let container = parent;
+        let childLevel = level;
+        if (isFrame(node.id)) {
+            container = doc.createElement('main');
+            if (title) {
+                container.append(headingEl(1, title));
+                childLevel = 1;
+            }
+            const description = node.props.description;
+            if (typeof description === 'string') {
+                const p = doc.createElement('p');
+                p.textContent = description;
+                container.append(p);
+            }
+            parent.append(container);
+        }
+        else if (node.id === 'layout-card') {
+            container = doc.createElement(title ? 'section' : 'div');
+            if (title) {
+                childLevel = cardHeadingLevel(level);
+                const h = headingEl(childLevel, title);
+                sequence += 1;
+                h.id = `golden-card-${sequence}`;
+                container.setAttribute('aria-labelledby', h.id);
+                container.append(h);
+            }
+            parent.append(container);
+        }
+        else if (node.id === 'layout-grid') {
+            container = doc.createElement('div');
+            container.setAttribute('data-golden-grid', '');
+            parent.append(container);
+        }
+        else {
+            const loader = loaders[node.id];
+            const target = doc.createElement('div');
+            target.setAttribute('data-golden-component', node.id);
+            parent.append(target);
+            if (!loader) {
+                issues.push(`${path} ${node.id}: no component to paint`);
+                return;
+            }
+            try {
+                const Component = await loader();
+                const props = { ...node.props };
+                // Blocks report a refused block through `oninvalid` instead of throwing.
+                if (goldenManifest(node.id)?.props.some((prop) => prop.name === 'oninvalid')) {
+                    props.oninvalid = (detail) => issues.push(`${path} ${node.id}: refused its props ${JSON.stringify(detail).slice(0, 200)}`);
+                }
+                instances.push(mount(Component, { target, props }));
+            }
+            catch (error) {
+                issues.push(`${path} ${node.id}: failed to render (${error instanceof Error ? error.message : String(error)})`);
+            }
+        }
+        for (let index = 0; index < node.children.length; index += 1) {
+            await paint(node.children[index], container, childLevel, `${path}.children.${index}`);
+        }
+    };
+    for (let index = 0; index < roots.length; index += 1) {
+        await paint(roots[index], doc.body, 0, String(index));
+    }
+    await tick();
+    // Lazy families resolve their own chunks after mount; let them settle.
+    for (let round = 0; round < 3; round += 1) {
+        await new Promise((resolve) => setTimeout(resolve, 0));
+        await tick();
+    }
+    return {
+        issues,
+        destroy() {
+            for (const instance of instances)
+                void unmount(instance);
+            doc.body.replaceChildren();
+        },
+    };
+}