@agent-ui-kit/components 0.0.3

package/dist/descriptor/component-descriptor.js

@@ -0,0 +1,492 @@
+// component-descriptor.ts — the reusable {name}.md frontmatter reader + the descriptor schema (ADR-0004).
+//
+// A component's public surface is recorded as `{name}.md` YAML frontmatter (ADR-0004 — the descriptor
+// replaces the never-built `{name}.api.json`). Two artifacts live here, both consumed by the governance
+// slices that target that fence:
+//
+//   1. parseDescriptor(fence)            — the fence-scoped READER (factored out of the s8 button probe so
+//                                          the s10 contract↔props trip-wire + every future component reuse
+//                                          ONE parser, never a divergent copy — the drift the process kills).
+//   2. validateComponentDescriptor(desc) — the descriptor SCHEMA: a hand-rolled, TOTAL structural validator
+//                                          that IS the referential standard the frontmatter is checked
+//                                          against (process.md §4's "api-contract schema", now a frontmatter
+//                                          schema per ADR-0004). It is the STRUCTURAL standard only — it does
+//                                          NOT compare the frontmatter against the live class.
+//   3. compareDescriptorToProps(a, p)    — the contract↔props TRIP-WIRE (process.md §1): asserts the
+//                                          descriptor's `attributes[]` and the live `static props` table
+//                                          (what `finalize(Class)` installs from) are a faithful BIJECTION,
+//                                          so the descriptor cannot drift from the real component. Fleet-wide
+//                                          (any component runs it); kept import-free by reading the live props
+//                                          STRUCTURALLY (LivePropConfig) instead of pulling the dom layer.
+//
+// Zero-dep by ruling: no YAML parser is installed and the descriptor is a CONTROLLED format, so the reader is
+// a small indentation-scoped parser over the subset the descriptor uses (top-level scalars · `- ` sequences ·
+// nested maps · inline `[a, b]` arrays · trailing `#` comments). It never executes the file; it reads text.
+// ── reader ──────────────────────────────────────────────────────────────────────────────────────────────
+/** Split the leading `---`…`---` frontmatter fence from the prose body. Throws if there is no fence. */
+export function splitFrontmatter(src) {
+    const m = /^---\n([\s\S]*?)\n---\n?([\s\S]*)$/.exec(src);
+    if (!m)
+        throw new Error('source has no leading --- frontmatter fence');
+    return { fence: m[1], body: m[2] };
+}
+const COMMENT_OR_BLANK = /^\s*#|^\s*$/;
+/** Strip a whitespace-led inline `#` comment. (Controlled format: values carry no literal `#`.) */
+const stripComment = (raw) => raw.replace(/\s+#.*$/, '').trim();
+/** Drop a single pair of surrounding quotes (e.g. `'null'` → `null`). */
+const unquote = (s) => /^(['"])([\s\S]*)\1$/.exec(s)?.[2] ?? s;
+/** A scalar value: comment-stripped, unquoted, trimmed. */
+const scalarValue = (raw) => unquote(stripComment(raw));
+/** Sentinel key a BARE-SCALAR sequence item (`- ready`, no `key:` of its own) stores its value under. `#` can
+ *  never be a real field name (fields match `[A-Za-z][\w]*`), so it cannot collide — and `scalarSeq` reads it back. */
+const BARE_SCALAR_KEY = '#scalar';
+/** Group the fence into top-level (column-0) `key:` blocks with their indented child lines. */
+function toBlocks(fence) {
+    const blocks = [];
+    let current = null;
+    for (const line of fence.split('\n')) {
+        if (COMMENT_OR_BLANK.test(line))
+            continue;
+        const top = /^([A-Za-z][\w]*):(.*)$/.exec(line); // `^[A-Za-z]` ⇒ column 0, no leading whitespace
+        if (top) {
+            current = { key: top[1], inline: top[2], childLines: [] };
+            blocks.push(current);
+        }
+        else if (current) {
+            current.childLines.push(line);
+        }
+    }
+    return blocks;
+}
+/** Parse a `key: value` field line into a sequence item (inline `[a, b]` → string[]); a bare scalar with no
+ *  `key:` of its own (e.g. customStates `- ready`) is kept under BARE_SCALAR_KEY (was DROPPED before this fix).
+ *  An inline array element ELEMENT is `.filter`ed for blank/trailing-comma ARTIFACTS (an empty split segment,
+ *  e.g. `[a, b, ]`'s trailing slot) BEFORE it is `unquote()`d — in that order, so a genuinely-quoted empty
+ *  string (`''`/`""`, 2 characters pre-unquote, needed for ADR-0083's `landmark` enum whose first member IS
+ *  the empty string) survives the artifact filter and only THEN unquotes to a real `''`, rather than being
+ *  indistinguishable from a blank artifact and dropped. Every existing bare (unquoted) token is unaffected —
+ *  `unquote` is a no-op unless the WHOLE element is wrapped in one matching quote pair. */
+function addField(item, text) {
+    const m = /^\s*([A-Za-z][\w]*):\s*([\s\S]*)$/.exec(text);
+    if (!m) {
+        const bare = scalarValue(text);
+        if (bare !== '')
+            item.set(BARE_SCALAR_KEY, bare);
+        return;
+    }
+    const value = scalarValue(m[2]);
+    // Quoted-default marker (TKT-0070, closing TKT-0069's String(default) gate hole): `unquote` erases the
+    // authored quoting, but a QUOTED scalar default on a boolean/number/integer attribute is exactly the
+    // YAML mis-typing the contract↔props trip-wire cannot see (it compares String(config.default), so
+    // 'false' == false). Record quotedness under a sentinel key (the BARE_SCALAR_KEY trick — `#` can never
+    // be a real field name) for the validator's rule 5b below. Only `default` needs it.
+    if (m[1] === 'default' && /^(['"])[\s\S]*\1$/.test(stripComment(m[2])))
+        item.set('#quoted:default', 'true');
+    if (/^\[.*\]$/.test(value)) {
+        item.set(m[1], value.replace(/^\[|\]$/g, '').split(',').map((s) => s.trim()).filter((s) => s !== '').map((s) => unquote(s)));
+    }
+    else {
+        item.set(m[1], value);
+    }
+}
+/** Parse an indented `- ` sequence block into a list of field mappings. */
+function parseSequence(lines) {
+    const items = [];
+    let current = null;
+    for (const line of lines) {
+        const dash = /^\s*-\s*(.*)$/.exec(line);
+        if (dash) {
+            current = new Map();
+            items.push(current);
+            addField(current, dash[1]);
+        }
+        else if (current) {
+            addField(current, line);
+        }
+    }
+    return items;
+}
+/** Parse an indented nested-mapping block (e.g. `face`/`aria`/`geometry`) into a key→scalar map. */
+function parseMap(lines) {
+    const map = new Map();
+    for (const line of lines) {
+        const m = /^\s*([A-Za-z][\w]*):\s*([\s\S]*)$/.exec(line);
+        if (m)
+            map.set(m[1], scalarValue(m[2]));
+    }
+    return map;
+}
+/** Shape one raw `attributes[]` item into a typed ParsedAttribute. */
+function toAttribute(item) {
+    const name = item.get('name');
+    const type = item.get('type');
+    const values = item.get('values');
+    const def = item.get('default');
+    const reflect = item.get('reflect');
+    return {
+        name: typeof name === 'string' ? name : undefined,
+        type: typeof type === 'string' ? type : undefined,
+        values: Array.isArray(values) ? values : typeof values === 'string' ? [values] : undefined,
+        default: typeof def === 'string' ? def : undefined,
+        reflect: reflect === 'true' ? true : reflect === 'false' ? false : undefined,
+    };
+}
+/** Read a frontmatter fence into the structured descriptor (top-level keys · scalars · sequences · maps). */
+export function parseDescriptor(fence) {
+    const scalars = new Map();
+    const sequences = new Map();
+    const maps = new Map();
+    for (const block of toBlocks(fence)) {
+        const inline = scalarValue(block.inline);
+        if (inline === '[]')
+            sequences.set(block.key, []);
+        else if (inline === '{}')
+            maps.set(block.key, new Map());
+        else if (inline !== '')
+            scalars.set(block.key, inline);
+        else if (block.childLines.length > 0 && /^\s*-/.test(block.childLines[0]))
+            sequences.set(block.key, parseSequence(block.childLines));
+        else
+            maps.set(block.key, parseMap(block.childLines));
+    }
+    const topLevelKeys = new Set([...scalars.keys(), ...sequences.keys(), ...maps.keys()]);
+    const attributes = (sequences.get('attributes') ?? []).map(toAttribute);
+    return { topLevelKeys, scalars, sequences, maps, attributes };
+}
+/**
+ * Read a BARE-SCALAR sequence field as the list of values its items carry (e.g. customStates `- ready` →
+ * `['ready']`). A bare-scalar item parses to a single-entry map keyed by BARE_SCALAR_KEY (the addField fix);
+ * this reads those back. Items that are full `key: value` mappings (e.g. attributes/slots) contribute nothing.
+ */
+export function scalarSeq(desc, field) {
+    const out = [];
+    for (const item of desc.sequences.get(field) ?? []) {
+        const v = item.get(BARE_SCALAR_KEY);
+        if (typeof v === 'string')
+            out.push(v);
+    }
+    return out;
+}
+// ── schema ──────────────────────────────────────────────────────────────────────────────────────────────
+/** The structural defects validateComponentDescriptor reports. */
+export const DESCRIPTOR_CODES = ['MISSING_FIELD', 'BAD_SHAPE', 'BAD_TAG', 'BAD_TIER', 'BAD_EXTENDS', 'BAD_ATTRIBUTE', 'BAD_FACE'];
+// The descriptor field set (ADR-0004 / plan §10) and the shape each field MUST parse into.
+const FIELD_SHAPE = {
+    tag: 'scalar',
+    tier: 'scalar',
+    extends: 'scalar',
+    attributes: 'sequence',
+    properties: 'sequence',
+    events: 'sequence',
+    slots: 'sequence',
+    parts: 'sequence',
+    customStates: 'sequence',
+    face: 'map',
+    aria: 'map',
+    keyboard: 'sequence',
+    geometry: 'map',
+    forcedColors: 'scalar',
+};
+const SIZE_CLASSES = ['control', 'indicator', 'range', 'pattern', 'container', 'layout', 'display']; // geometry.md size-class set (range added for Wave-2 Range family)
+const ATTR_TYPES = ['enum', 'boolean', 'number', 'string', 'json']; // the attribute codec set
+const BASE_CLASSES = [
+    'UIElement',
+    'UIFormElement',
+    'UIContainerElement',
+    // Wave 0/1 control-suite bases (controls/_base/); each is a direct-extends target for leaf controls.
+    'UIIndicatorElement', // checkbox / switch / radio (ADR-0042)
+    'UIRangeElement', // slider family
+    'UIListboxElement', // listbox / select options (listbox-roving LLD-C3)
+];
+const BOOLEANS = ['true', 'false'];
+const has = (set, v) => set.includes(v);
+/**
+ * Validate a parsed frontmatter against the component-descriptor schema (ADR-0004). TOTAL — never throws;
+ * every defect is a structured DescriptorFailure. This is the structural referential standard the contract
+ * trip-wire (s10) builds on; it does NOT compare against the live class.
+ */
+export function validateComponentDescriptor(d) {
+    const failures = [];
+    const add = (code, path, message) => void failures.push({ code, path, message });
+    // 1 — every required field is present and parsed into its declared shape.
+    for (const field of Object.keys(FIELD_SHAPE)) {
+        if (!d.topLevelKeys.has(field)) {
+            add('MISSING_FIELD', field, `required field "${field}" is absent`);
+            continue;
+        }
+        const shape = FIELD_SHAPE[field];
+        const present = shape === 'scalar' ? d.scalars.has(field) : shape === 'sequence' ? d.sequences.has(field) : d.maps.has(field);
+        if (!present)
+            add('BAD_SHAPE', field, `field "${field}" must be a ${shape}`);
+    }
+    // 2 — tag is a ui-{name} custom-element tag.
+    const tag = d.scalars.get('tag');
+    if (tag !== undefined && !/^ui-[a-z][a-z0-9-]*$/.test(tag))
+        add('BAD_TAG', 'tag', `tag "${tag}" must match ui-{name}`);
+    // 3 — tier is one of the geometry size-classes.
+    const tier = d.scalars.get('tier');
+    if (tier !== undefined && !has(SIZE_CLASSES, tier))
+        add('BAD_TIER', 'tier', `tier "${tier}" is not a size-class`);
+    // 4 — extends is a known base element.
+    const ext = d.scalars.get('extends');
+    if (ext !== undefined && !has(BASE_CLASSES, ext))
+        add('BAD_EXTENDS', 'extends', `extends "${ext}" is not a known base element`);
+    // 5 — each attributes[] entry is a well-formed attributes-as-API row.
+    const seen = new Set();
+    for (const [i, item] of (d.sequences.get('attributes') ?? []).entries()) {
+        const at = (sub) => `attributes[${i}].${sub}`;
+        const name = item.get('name');
+        if (typeof name !== 'string' || name === '') {
+            add('BAD_ATTRIBUTE', at('name'), `attribute #${i} is missing a name`);
+        }
+        else {
+            if (seen.has(name))
+                add('BAD_ATTRIBUTE', at('name'), `duplicate attribute name "${name}"`);
+            seen.add(name);
+        }
+        const type = item.get('type');
+        if (typeof type !== 'string' || !has(ATTR_TYPES, type)) {
+            add('BAD_ATTRIBUTE', at('type'), `attribute "${name ?? i}" has an invalid type "${typeof type === 'string' ? type : ''}"`);
+        }
+        else if (type === 'enum' && !(Array.isArray(item.get('values')) && item.get('values').length > 0)) {
+            add('BAD_ATTRIBUTE', at('values'), `enum attribute "${name ?? i}" needs a non-empty values list`);
+        }
+        if (!item.has('default'))
+            add('BAD_ATTRIBUTE', at('default'), `attribute "${name ?? i}" is missing a default`);
+        // 5b (TKT-0070): a QUOTED scalar default on a typed attribute is a YAML mis-typing the downstream
+        // String(config.default) comparison is structurally blind to — reject at the schema (`default: false`,
+        // never `default: 'false'`; a STRING attribute's quoted default — `''` — stays legal).
+        if (item.has('#quoted:default') && typeof type === 'string' && (type === 'boolean' || type === 'number')) {
+            add('BAD_ATTRIBUTE', at('default'), `attribute "${name ?? i}" has a QUOTED default for type ${type} — unquote it (the trip-wire compares String(default) and cannot catch this)`);
+        }
+        const reflect = item.get('reflect');
+        if (typeof reflect !== 'string' || !has(BOOLEANS, reflect))
+            add('BAD_ATTRIBUTE', at('reflect'), `attribute "${name ?? i}" reflect must be true|false`);
+    }
+    // 6 — face records a boolean formAssociated (FACE form-control participation).
+    const face = d.maps.get('face');
+    if (face !== undefined) {
+        const fa = face.get('formAssociated');
+        if (fa === undefined || !has(BOOLEANS, fa))
+            add('BAD_FACE', 'face.formAssociated', 'face.formAssociated must be true|false');
+    }
+    return failures;
+}
+/** The drift defects compareDescriptorToProps reports (the descriptor disagrees with the live class). */
+export const DRIFT_CODES = ['DRIFT_MISSING', 'DRIFT_EXTRA', 'DRIFT_TYPE', 'DRIFT_DEFAULT', 'DRIFT_REFLECT', 'DRIFT_VALUES'];
+/** A sentinel attribute string that is never a valid enum member nor valid JSON (probes the codec fallback). */
+const NON_MEMBER = '\u0000__agent-ui-non-member__';
+/** Run a codec probe, swallowing throws (an opaque codec may throw on input it cannot parse, e.g. JSON). */
+function probe(fn) {
+    try {
+        return { ok: true, value: fn() };
+    }
+    catch {
+        return { ok: false };
+    }
+}
+/**
+ * Recover a live codec's KIND by behaviour (the codecs carry no kind tag — props.ts). Each branch keys off
+ * `config.type.from` on a few probe inputs: boolean maps absence→false / presence→true; number and json both
+ * map absence→null but split on `from('5')` vs `from('"x"')` (json parses, number does not); a STRING/ENUM
+ * codec both map absence→a string, so the two are told apart by a SECOND probe: `from(NON_MEMBER)` (a garbage
+ * sentinel no real enum contains) — a plain string codec is a passthrough (`attr ?? ''`), so it returns
+ * NON_MEMBER UNCHANGED; an enum SNAPS a non-member back to its fixed `values[0]`, so it returns something
+ * OTHER than NON_MEMBER (even when that fixed member is itself `''` — ADR-0083's `landmark`, whose enum
+ * `values[0]` is the empty string, would otherwise be indistinguishable from a plain string prop: both read
+ * `from(null) === ''`. Only the NON_MEMBER probe's OUTCOME, never its literal value, tells them apart — a bare
+ * `nul.value === ''` shortcut checked BEFORE this probe was the pre-ADR-0083 bug). Returns 'unknown' when no
+ * branch matches (the natural DRIFT_TYPE signal).
+ */
+function kindOf(config) {
+    const from = (a) => probe(() => config.type.from(a));
+    const nul = from(null);
+    if (!nul.ok)
+        return 'unknown';
+    // A HARDENED array codec (SPEC-R3/R7, the chart family's safe values/data codecs) maps a removed/absent
+    // attribute to `[]`, never `null` — the generic `jsonType<T>()` shape below never produces this. An array
+    // result is unambiguous (never `false`/string/`null`), so it is classified "json" directly, ahead of the
+    // null-keyed branches that would otherwise miss it and fall through to 'unknown'.
+    if (Array.isArray(nul.value))
+        return 'json';
+    if (nul.value === false) {
+        const empty = from('');
+        return empty.ok && empty.value === true ? 'boolean' : 'unknown';
+    }
+    if (typeof nul.value === 'string') {
+        const fallback = from(NON_MEMBER);
+        if (fallback.ok && fallback.value !== NON_MEMBER)
+            return 'enum';
+        if (nul.value === '')
+            return 'string';
+    }
+    if (nul.value === null) {
+        const empty = from('');
+        const five = from('5');
+        if (empty.ok && empty.value === null && five.ok && five.value === 5)
+            return 'number';
+        const quoted = from('"x"');
+        return quoted.ok && quoted.value === 'x' ? 'json' : 'unknown';
+    }
+    return 'unknown';
+}
+/**
+ * Probe whether a live enum codec accepts EXACTLY the descriptor's `values` (order-significant): every
+ * declared member must round-trip (be a real live member) and the fallback for a non-member must equal
+ * `values[0]` (so the first member — the codec's snap target — agrees). NOTE the one asymmetry probing an
+ * opaque closure cannot close: a live member the descriptor OMITS while preserving the prefix is invisible
+ * (you cannot enumerate the closure), so values[] must be the declared contract a human keeps complete.
+ */
+function enumMembersMatch(config, values) {
+    if (values.length === 0)
+        return false;
+    const from = (a) => probe(() => config.type.from(a));
+    const everyMember = values.every((v) => {
+        const r = from(v);
+        return r.ok && r.value === v;
+    });
+    const fallback = from(NON_MEMBER);
+    return everyMember && fallback.ok && fallback.value === values[0];
+}
+/**
+ * The contract↔props trip-wire: assert the descriptor `attributes[]` and the live `static props` are a
+ * faithful BIJECTION. TOTAL — never throws; every disagreement is a structured DriftFailure. Checks: (NAME)
+ * every live prop has a descriptor attribute and vice-versa (DRIFT_MISSING / DRIFT_EXTRA); then per matched
+ * name the (TYPE) live codec behaves as the declared kind (DRIFT_TYPE), the (DEFAULT) `String(config.default)`
+ * equals the descriptor token (DRIFT_DEFAULT), the (REFLECT) `config.reflect ?? false` equals the flag
+ * (DRIFT_REFLECT), and (VALUES) an enum's declared members are the live member set (DRIFT_VALUES). The
+ * descriptor is assumed schema-valid first (validateComponentDescriptor); nameless attributes are that
+ * validator's concern and are skipped here.
+ */
+export function compareDescriptorToProps(attributes, props) {
+    const failures = [];
+    const add = (code, path, message) => void failures.push({ code, path, message });
+    const byName = new Map();
+    for (const a of attributes)
+        if (a.name !== undefined && a.name !== '')
+            byName.set(a.name, a);
+    const liveNames = Object.keys(props);
+    const liveSet = new Set(liveNames);
+    // 1 — NAME bijection: a live prop with no descriptor row is MISSING; a descriptor row with no live prop is EXTRA.
+    for (const name of liveNames) {
+        if (!byName.has(name))
+            add('DRIFT_MISSING', `attributes.${name}`, `live prop "${name}" has no descriptor attribute`);
+    }
+    for (const name of byName.keys()) {
+        if (!liveSet.has(name))
+            add('DRIFT_EXTRA', `attributes.${name}`, `descriptor attribute "${name}" has no live prop`);
+    }
+    // 2 — per matched name: type kind · default · reflect · enum members consistent with the live PropConfig.
+    for (const name of liveNames) {
+        const attr = byName.get(name);
+        if (attr === undefined)
+            continue;
+        const config = props[name];
+        const at = (sub) => `attributes.${name}.${sub}`;
+        const liveKind = kindOf(config);
+        if (attr.type !== liveKind) {
+            add('DRIFT_TYPE', at('type'), `descriptor type "${attr.type ?? ''}" != live codec kind "${liveKind}"`);
+        }
+        else if (liveKind === 'enum' && !enumMembersMatch(config, attr.values ?? [])) {
+            add('DRIFT_VALUES', at('values'), `enum "${name}" values [${(attr.values ?? []).join(', ')}] are not the live member set`);
+        }
+        const liveDefault = String(config.default);
+        if (attr.default !== liveDefault) {
+            add('DRIFT_DEFAULT', at('default'), `descriptor default "${attr.default ?? ''}" != live default "${liveDefault}"`);
+        }
+        const descReflect = attr.reflect ?? false;
+        const liveReflect = config.reflect ?? false;
+        if (descReflect !== liveReflect) {
+            add('DRIFT_REFLECT', at('reflect'), `descriptor reflect ${descReflect} != live reflect ${liveReflect}`);
+        }
+    }
+    return failures;
+}
+// ── contract↔source trip-wire ───────────────────────────────────────────────────────────────────────────
+//
+// compareDescriptorToProps closes the props gap, but two facts the descriptor records have NO `static props`
+// row to compare against — they are not class fields at all:
+//
+//   • customStates — a control's custom states are added IMPERATIVELY and conditionally (button.ts:
+//     `requestAnimationFrame(() => this.internals.states?.add('ready'))`, optional-chained, behind rAF), and a
+//     state may also be referenced ONLY by the stylesheet (`:state(ready)`). Neither is a statically-inspectable
+//     field, so the truth lives in the .ts/.css source text.
+//   • slots — light-DOM, host-as-grid components place slotted children purely in CSS (`[slot='leading']`);
+//     there is no slot manifest in the class. The truth lives in the .css selectors.
+//
+// compareDescriptorToSource cross-checks the descriptor against that SOURCE USAGE (the caller passes the .ts and
+// .css TEXT — this module stays import-free; it never reads the filesystem). It is a NAME-BIJECTION trip-wire,
+// like compareDescriptorToProps, but states/slots carry no codec, so there is no TYPE/DEFAULT/REFLECT — only the
+// name sets are compared. STATES are bidirectional (used ≡ documented); SLOTS are one-directional — every
+// CSS-styled slot must be documented, but a documented slot need NOT be CSS-selected (`label`, button.md's
+// default centre cell, is a real slot the grid never selects by name — the one asymmetry, mirroring the live
+// member the enum probe cannot enumerate in enumMembersMatch).
+/**
+ * The custom states a component USES — the union of the imperative `internals.states` mutations in the .ts
+ * (`.states?.add('X')` / `.delete` / `.toggle` / `.replace` / `.has`, optional-chain tolerant) AND the
+ * `:state(X)` selectors in the .css. A state is "used" if EITHER source references it.
+ */
+export function collectUsedStates(ts, css) {
+    const names = new Set();
+    for (const m of ts.matchAll(/\.states\??\.(?:add|delete|toggle|replace|has)\(\s*['"]([^'"]+)['"]/g))
+        names.add(m[1]);
+    for (const m of css.matchAll(/:state\(\s*([A-Za-z][\w-]*)\s*\)/g))
+        names.add(m[1]);
+    return names;
+}
+/** The slot POSITIONS the .css styles — every `[slot='X']` attribute selector (quoting optional, `:has()`-nested or not). */
+export function collectStyledSlots(css) {
+    const names = new Set();
+    for (const m of css.matchAll(/\[slot\s*=\s*['"]?([A-Za-z][\w-]*)['"]?\s*\]/g))
+        names.add(m[1]);
+    return names;
+}
+/** The content ROLES the .css styles — every `[data-role='X']` attribute selector (quoting optional). Reused by the /site dead-name guard (s12). */
+export function collectStyledRoles(css) {
+    const names = new Set();
+    for (const m of css.matchAll(/\[data-role\s*=\s*['"]?([A-Za-z][\w-]*)['"]?\s*\]/g))
+        names.add(m[1]);
+    return names;
+}
+/** The drift defects compareDescriptorToSource reports (the descriptor disagrees with the component .ts/.css). */
+export const SOURCE_DRIFT_CODES = ['STATE_UNDOCUMENTED', 'STATE_UNUSED', 'SLOT_UNDOCUMENTED'];
+/** The slot names a descriptor declares (the `slots[]` sequence rows' `name:` values). */
+function declaredSlotNames(desc) {
+    const names = new Set();
+    for (const item of desc.sequences.get('slots') ?? []) {
+        const name = item.get('name');
+        if (typeof name === 'string' && name !== '')
+            names.add(name);
+    }
+    return names;
+}
+/**
+ * The contract↔source trip-wire: assert the descriptor's customStates/slots tell the truth about where the fact
+ * ACTUALLY lives (the component .ts/.css). TOTAL — never throws; every disagreement is a structured
+ * SourceDriftFailure. STATES (bidirectional): used-states (collectUsedStates) ≡ descriptor.customStates —
+ * STATE_UNDOCUMENTED for a used state the descriptor omits, STATE_UNUSED for a documented state no source uses.
+ * SLOTS (one-directional): every CSS-styled slot (collectStyledSlots) must be IN descriptor.slots —
+ * SLOT_UNDOCUMENTED otherwise; a documented-but-unstyled slot (`label`, the default cell) is NOT a defect.
+ */
+export function compareDescriptorToSource(desc, source) {
+    const failures = [];
+    const add = (code, path, message) => void failures.push({ code, path, message });
+    // STATES — bijection between source usage (.ts add + .css :state) and the documented customStates.
+    const usedStates = collectUsedStates(source.ts, source.css);
+    const declaredStates = new Set(scalarSeq(desc, 'customStates'));
+    for (const s of usedStates) {
+        if (!declaredStates.has(s))
+            add('STATE_UNDOCUMENTED', `customStates.${s}`, `state "${s}" is used in source but absent from customStates`);
+    }
+    for (const s of declaredStates) {
+        if (!usedStates.has(s))
+            add('STATE_UNUSED', `customStates.${s}`, `customStates declares "${s}" but no source (.ts/.css) uses it`);
+    }
+    // SLOTS — one-directional: every CSS-styled slot must be documented (an undocumented styled slot is the drift).
+    const declaredSlots = declaredSlotNames(desc);
+    for (const s of collectStyledSlots(source.css)) {
+        if (!declaredSlots.has(s))
+            add('SLOT_UNDOCUMENTED', `slots.${s}`, `slot "${s}" is styled in css but absent from slots`);
+    }
+    return failures;
+}

package/dist/descriptor/index.d.ts

@@ -0,0 +1 @@
+export * from './component-descriptor.js';

package/dist/descriptor/index.js

@@ -0,0 +1,5 @@
+// descriptor — the component-descriptor public surface (ADR-0004). This barrel exposes the CANONICAL
+// `{name}.md` frontmatter reader + schema + contract↔props trip-wire as the package subpath
+// `@agent-ui-kit/components/descriptor`, so a second consumer (the /site doc page, A4) reuses the SAME parser
+// the contract trip-wire is built on — one parser, two consumers, never a forked frontmatter dialect.
+export * from "./component-descriptor.js";

package/dist/dom/container.d.ts

@@ -0,0 +1,45 @@
+import { UIElement } from './element.js';
+export declare class UIContainerElement extends UIElement {
+    /** The spreadable surface axes — `elevation`/`brightness` (ADR-0015). Subclasses fold into `static props`. */
+    static surfaceProps: {
+        elevation: {
+            reflect: true;
+            type: import("./props.js").PropType<"0" | "1" | "2" | "3" | "-3" | "-2" | "-1">;
+            default: "0" | "1" | "2" | "3" | "-3" | "-2" | "-1";
+            attribute?: string | false;
+        };
+        brightness: {
+            reflect: true;
+            type: import("./props.js").PropType<"0" | "1" | "2" | "3" | "-3" | "-2" | "-1">;
+            default: "0" | "1" | "2" | "3" | "-3" | "-2" | "-1";
+            attribute?: string | false;
+        };
+    };
+    /** The spreadable layout grammar — `align`/`justify`/`gap`/`wrap` (ADR-0016). Subclasses fold into `static props`. */
+    static flexProps: {
+        align: {
+            reflect: true;
+            type: import("./props.js").PropType<"end" | "start" | "center" | "stretch" | "baseline">;
+            default: "end" | "start" | "center" | "stretch" | "baseline";
+            attribute?: string | false;
+        };
+        justify: {
+            reflect: true;
+            type: import("./props.js").PropType<"end" | "start" | "center" | "between" | "around" | "evenly">;
+            default: "end" | "start" | "center" | "between" | "around" | "evenly";
+            attribute?: string | false;
+        };
+        gap: {
+            reflect: true;
+            type: import("./props.js").PropType<"none" | "sm" | "md" | "lg" | "xs" | "xl" | "2xl">;
+            default: "none" | "sm" | "md" | "lg" | "xs" | "xl" | "2xl";
+            attribute?: string | false;
+        };
+        wrap: {
+            reflect: true;
+            type: import("./props.js").PropType<boolean>;
+            default: boolean;
+            attribute?: string | false;
+        };
+    };
+}

package/dist/dom/container.js

@@ -0,0 +1,60 @@
+// container.ts — `UIContainerElement`, the FACE container surface base (ADR-0015 / ADR-0016; decomp
+// g9-containers slice s2).
+//
+// The base every container/layout `ui-*` element extends — the FIRST non-form family. It is a plain
+// `UIElement` (NOT form-associated: no `static formAssociated`, no `setFormValue`/validity — a container
+// contributes nothing to a form), and it reuses the inherited single `ElementInternals` handle (acquired
+// ONCE in the `UIElement` constructor) so the stateful subclasses (`ui-tabs`, `ui-modal`) set ARIA roles +
+// custom states THROUGH `this.internals`, never host attributes.
+//
+// The base owns NO layout/surface CSS opinion in TypeScript — every visual decision lives in the CSS layer.
+// What it owns is the two SPREADABLE prop sets the container family shares (the ADR-0013 `formProps`
+// precedent — props.ts has no static-props prototype merge, so a base cannot hand props down by inheritance;
+// instead it exposes a schema each subclass folds into its OWN `static props`):
+//   • `surfaceProps` — the two signed surface axes `elevation`/`brightness` (ADR-0015): each a reflected
+//     literal-union `'-3'…'3'`, default `'0'` (the neutral base). The CSS `[elevation=n]`/`[brightness=m]`
+//     selectors (controls/_surface/container.css) repoint the one role-pure `--ui-container-bg`/`-tint`
+//     consumption seam; the component holds zero colour opinion.
+//   • `flexProps` — the shared A2UI-faithful layout grammar `align`/`justify`/`gap`/`wrap` (ADR-0016), each a
+//     reflected literal-union (or boolean) the layout primitives (`ui-row`/`ui-column`/`ui-list`/`ui-grid`)
+//     map 1:1 onto a CSS flex property in their OWN `@scope` block. One grammar, four consumers — no drift.
+// A subclass spreads them: `static props = { ...UIContainerElement.surfaceProps, ...flexProps, … }`.
+//
+// Imports only same-layer `./element.ts` / `./props.ts` (the dom layer; the layering law holds —
+// `reactive ← dom`). The kernel is reached transitively through `UIElement` / `prop`; nothing here touches
+// `../reactive` directly. `ElementInternals` is an ambient DOM global, inherited via `UIElement`.
+import { UIElement } from "./element.js";
+import { prop } from "./props.js";
+// The two surface axes (ADR-0015 clause 1). Both are SIGNED literal unions `'-3'…'3'` (typed strings, not
+// `number` — matching `size: 'sm'|'md'|'lg'`, so a `@ts-expect-error` proves a bare number is rejected) and
+// both REFLECT, so the `[elevation=n]`/`[brightness=m]` attribute selectors in container.css apply to
+// JS-set values too. `'0'` LEADS the value array so an out-of-range attribute snaps back to the neutral base
+// (`enumType.from` falls to `values[0]`), not a surprise elevation — the literal-union TYPE is order-independent.
+const SURFACE_STEPS = ['0', '1', '2', '3', '-1', '-2', '-3'];
+const surfaceProps = {
+    // elevation → the scheme-INVERTING plane (`--md-sys-color-neutral-surface-{lowest…highest}`); 0 = the neutral surface.
+    elevation: { ...prop.enum(SURFACE_STEPS, '0'), reflect: true },
+    // brightness → the scheme-CONSISTENT tonal wash; 0 = no wash (the neutral surface).
+    brightness: { ...prop.enum(SURFACE_STEPS, '0'), reflect: true },
+};
+// The shared layout grammar (ADR-0016 clause 1). Each maps 1:1 onto a CSS flex property; the literal-union →
+// CSS-keyword mapping lives in each primitive's `@scope` block (a role-pure repoint, never an inline style),
+// so this set is the TYPED vocabulary only — the base owns no flex CSS. All REFLECT so the `[align]`/etc.
+// selectors apply to JS-set values. `values[0]` is each prop's default (consistent snap + default).
+const flexProps = {
+    // align (cross-axis) → `align-items`
+    align: { ...prop.enum(['start', 'center', 'end', 'stretch', 'baseline'], 'start'), reflect: true },
+    // justify (main-axis distribution) → `justify-content` (`between`/`around`/`evenly` → `space-*` in the CSS)
+    justify: { ...prop.enum(['start', 'center', 'end', 'between', 'around', 'evenly'], 'start'), reflect: true },
+    // gap → `gap: var(--md-sys-space-{step})` — the density-responsive layout-spacing ladder (ADR-0015 cl.4), NEVER a
+    // control dimension. The step vocabulary mirrors s1's `--md-sys-space-{none,xs,sm,md,lg,xl,2xl}` ramp 1:1.
+    gap: { ...prop.enum(['none', 'xs', 'sm', 'md', 'lg', 'xl', '2xl'], 'none'), reflect: true },
+    // wrap → `flex-wrap` (boolean presence: present ⇒ wrap)
+    wrap: { ...prop.boolean(false), reflect: true },
+};
+export class UIContainerElement extends UIElement {
+    /** The spreadable surface axes — `elevation`/`brightness` (ADR-0015). Subclasses fold into `static props`. */
+    static surfaceProps = surfaceProps;
+    /** The spreadable layout grammar — `align`/`justify`/`gap`/`wrap` (ADR-0016). Subclasses fold into `static props`. */
+    static flexProps = flexProps;
+}