@agent-ui-kit/components 0.0.3

package/dist/controls/_surface/container.css

@@ -0,0 +1,156 @@
+/* container.css — the SHARED `UIContainerElement` surface seam (ADR-0015). The one stylesheet every
+ * container/layout `ui-*` element sits on; it is `@import`-ed FIRST (before any element sheet) by
+ * component-styles.css (wired in decomp s12). It owns NO per-element layout (display/flex/grid is each
+ * element's own `@scope` block) — only the cross-family surface. It does NOT establish query containers
+ * (ADR-0100 deleted the blanket `container-type: inline-size` this file used to set on the four layout
+ * primitives — see the seam's own banner below for why and where establishment moved).
+ *
+ * Role-purity (ADR-0008 / tokens.md): the CONSUMPTION (the two `background-*` declarations) reads ONLY the
+ * `--ui-container-*` seam — never a raw `--md-sys-color-*` role. The TOKEN repoints below (`--ui-container-bg:
+ * var(--md-sys-color-neutral-surface-high)`) are where the colour roles enter, exactly as button.css's `:where()`
+ * token block does — the `--md-sys-color-*` is confined to the variable-definition side, so a container holds zero
+ * colour opinion and forced-colors is handled in the role/system layer.
+ *
+ * Two surface axes (ADR-0015 cl.1–3), both signed `-3…3`, realized against the s1 token ladders:
+ *   • elevation → the scheme-INVERTING base PLANE: a SOLID `--md-sys-color-neutral-surface-{lowest…highest}` step.
+ *   • brightness → the scheme-CONSISTENT tonal shift. Two realizations (s1's AA-verified split):
+ *       – SOLO (brightness set, elevation 0/unset): the SOLID `--md-sys-color-neutral-surface-{dimmest…brightest}`
+ *         ladder is the base plane (no overlay) — ADR-0015 cl.1.
+ *       – COMPOSITION (elevation≠0 AND brightness≠0): the elevation plane is the base, and brightness becomes
+ *         a TRANSLUCENT wash (`--md-sys-color-neutral-tint-{step}`) composited alpha-over it — ADR-0015 cl.3 — so the
+ *         `−m` wash sits over the `+n` plane and neither axis overwrites the other. (The tint roles exist
+ *         ONLY for this case; s1 budgets their 14% alpha ceiling against the brightest dark elevation plane.)
+ *   The single `--ui-container-bg`/`--ui-container-tint` consumption seam is fixed regardless (ADR-0015 cl.2);
+ *   the SOLO/COMPOSITION choice is just which token each axis-state repoints to (source order below is
+ *   load-bearing — elevation overrides the brightness base plane when both axes are set).
+ *
+ * Default (no axis set) = transparent: an UNSET container is unchanged (it passes its parent's surface
+ * through), so a bare layout primitive adds no plane. Container elements that want a default surface
+ * (card/modal) set `--ui-container-bg` in their OWN sheet (specificity wins over this `:where()`); tabs
+ * left this trio in ADR-0104 — a bare `<ui-tabs>` is transparent like every other container, and a plane
+ * is an asked-for intent via the shipped `elevation`/`brightness` axes.
+ *
+ * Standalone sheet — linked via the component-styles barrel, NEVER injected from container.ts (behaviour
+ * `.ts` holds no runtime style; plan §2). */
+
+/* ════════════════ surface seam — the 8 surface-bearing container tags ════════════════ */
+
+:where(ui-row, ui-column, ui-list, ui-grid, ui-card, ui-tabs, ui-modal, ui-toolbar) {
+  /* The role-pure seam, default = transparent (an unset container is unchanged — ADR-0015 cl.1). */
+  --ui-container-bg: transparent; /* the base plane */
+  --ui-container-tint: transparent; /* the tonal wash (composition only); 0 ⇒ no-op */
+
+  /* elevation=0 — the explicit neutral base. Placed FIRST so an active axis (a brightness ladder step below,
+     or an elevation step) overrides it; an unset container stays transparent (this rule needs the attribute). */
+  &[elevation='0'] {
+    --ui-container-bg: var(--md-sys-color-neutral-surface);
+  }
+
+  /* brightness SOLO → the SOLID scheme-consistent ladder as the base plane (ADR-0015 cl.1). When elevation is
+     ALSO set, the elevation block below overrides this base (source order) and brightness moves to the wash. */
+  &[brightness='-3'] {
+    --ui-container-bg: var(--md-sys-color-neutral-surface-dimmest);
+  }
+  &[brightness='-2'] {
+    --ui-container-bg: var(--md-sys-color-neutral-surface-dimmer);
+  }
+  &[brightness='-1'] {
+    --ui-container-bg: var(--md-sys-color-neutral-surface-dim);
+  }
+  &[brightness='1'] {
+    --ui-container-bg: var(--md-sys-color-neutral-surface-bright);
+  }
+  &[brightness='2'] {
+    --ui-container-bg: var(--md-sys-color-neutral-surface-brighter);
+  }
+  &[brightness='3'] {
+    --ui-container-bg: var(--md-sys-color-neutral-surface-brightest);
+  }
+
+  /* elevation → the SOLID scheme-inverting base plane (-3..3 → lowest…highest). After the brightness block,
+     so elevation WINS the base plane when both axes are set (equal specificity → later source wins). */
+  &[elevation='-3'] {
+    --ui-container-bg: var(--md-sys-color-neutral-surface-lowest);
+  }
+  &[elevation='-2'] {
+    --ui-container-bg: var(--md-sys-color-neutral-surface-lower);
+  }
+  &[elevation='-1'] {
+    --ui-container-bg: var(--md-sys-color-neutral-surface-low);
+  }
+  &[elevation='1'] {
+    --ui-container-bg: var(--md-sys-color-neutral-surface-high);
+  }
+  &[elevation='2'] {
+    --ui-container-bg: var(--md-sys-color-neutral-surface-higher);
+  }
+  &[elevation='3'] {
+    --ui-container-bg: var(--md-sys-color-neutral-surface-highest);
+  }
+
+  /* COMPOSITION tonal WASH — brightness as a translucent overlay, ONLY when elevation is non-zero (s1: the
+     tint roles are composition-only). Composites alpha-over the elevation plane set above → the `−m` wash over
+     the `+n` plane (ADR-0015 cl.3). The `:is(non-zero elevation)` gate keeps SOLO brightness on the solid
+     ladder; the two-attribute selector (0,2,0) outranks the base-plane repoints, but it only sets the tint. */
+  &:is([elevation='-3'], [elevation='-2'], [elevation='-1'], [elevation='1'], [elevation='2'], [elevation='3']) {
+    &[brightness='-3'] {
+      --ui-container-tint: var(--md-sys-color-neutral-tint-dimmest);
+    }
+    &[brightness='-2'] {
+      --ui-container-tint: var(--md-sys-color-neutral-tint-dimmer);
+    }
+    &[brightness='-1'] {
+      --ui-container-tint: var(--md-sys-color-neutral-tint-dim);
+    }
+    &[brightness='1'] {
+      --ui-container-tint: var(--md-sys-color-neutral-tint-bright);
+    }
+    &[brightness='2'] {
+      --ui-container-tint: var(--md-sys-color-neutral-tint-brighter);
+    }
+    &[brightness='3'] {
+      --ui-container-tint: var(--md-sys-color-neutral-tint-brightest);
+    }
+  }
+
+  /* The CONSUMPTION — role-pure, reads ONLY the `--ui-container-*` seam. The base plane is the solid
+     `background-color`; the tonal wash is a flat same-colour `background-image` gradient stacked ABOVE it, so
+     the two axes composite (ADR-0015 cl.3). `:where()` keeps these at specificity 0 so an element's own
+     `@scope` surface (card/tabs/modal) cleanly overrides. */
+  background-color: var(--ui-container-bg);
+  background-image: linear-gradient(var(--ui-container-tint), var(--ui-container-tint));
+}
+
+/* ════════════════ container-query seam — RE-HOMED to externally-sized boundaries (ADR-0100) ═════════════ */
+
+/* NO blanket `container-type: inline-size` here — ADR-0100 DELETED it (it superseded ADR-0016 cl.4's
+   establishment sub-clause). `container-type: inline-size` applies inline-axis SIZE CONTAINMENT: the box's
+   intrinsic inline sizes compute AS IF IT HAD NO CONTENTS — the same anti-cycle rule that forbids an element
+   from size-querying itself. A layout primitive's sizing model is content-driven (shrink-wrap, no frame,
+   geometry.md Container/layout class), so an intrinsically-sized primitive CANNOT also be a query container:
+   making it one deterministically zeroes its own intrinsic size (a Row nested on a Row's main axis measured
+   0px; a contained primitive also contributes 0 intrinsic size through every content-sized ANCESTOR — the
+   pattern-dashboard-tiles cards crushed to ~36px chrome-only via their inner contained column). No selector
+   can repair this in place (the harm is non-local — safety is a whole-ancestor-chain property, invisible to
+   CSS), so establishment moves OFF the primitives entirely.
+   THE LAW (ADR-0100 cl.2): `container-type: inline-size` may be declared only on a box whose inline size is
+   EXTERNALLY determined — definite, stretched, or track-sized — never content-derived. The `@container` rules
+   in row.css/column.css keep their ADR-0096-gated selectors unchanged and now resolve, as they always
+   mechanically did, against the nearest ANCESTOR query container — one an externally-sized composition
+   boundary establishes (the A2UI mount surfaces: `site/lib/canvas-surface.css`'s `.canvas-surface`,
+   `site/lib/a2ui-gallery.css`'s `.seed-surface`, the various page `.surface` mounts, app-shell — ADR-0084 is
+   the shipped model case). `ui-grid`'s auto-fit/`minmax` responsiveness is track sizing, not a query, so it is
+   unaffected either way. */
+
+/* ════════════════ forced-colors (WHCM) ════════════════ */
+
+/* Keep the surface a system colour and drop the tonal wash. The colour ROLES already carry the WHCM mapping
+   in the token layer (tokens.md / s1 — the tint roles map to transparent under forced-colors), so this is
+   mostly belt-and-braces: it guarantees a container's surface survives as `Canvas` and the wash never paints
+   over system text. */
+@media (forced-colors: active) {
+  :where(ui-row, ui-column, ui-list, ui-grid, ui-card, ui-tabs, ui-modal, ui-toolbar) {
+    background-color: Canvas;
+    background-image: none;
+  }
+}

package/dist/controls/_token-surface/token-surface.d.ts

@@ -0,0 +1,35 @@
+import type { PropConfig } from '../../dom/props.js';
+/** One token-surface entry — a `ui-ramp` step or a `ui-ladder` tier (SPEC-R2 Definitions). */
+export interface TokenEntry {
+    label: string;
+    value: string;
+}
+/**
+ * Harden an arbitrary input into the rendered entry set (SPEC-R7/R11): a non-array input yields `[]`; each
+ * entry survives only as a plain object with a `string` `label` AND a `string` `value` — drop, never coerce.
+ * Order is preserved (positional semantics — a duplicate-label row: both entries render, the list is
+ * positional, not keyed). The bar-chart `cleanData` construction, generalized to a string `value` (a color/
+ * length lane, not a number).
+ */
+export declare function cleanEntries(input: unknown): TokenEntry[];
+/** The `steps`/`tiers` prop config — a fresh `PropConfig` each call (default `[]`, never a SHARED mutable array). */
+export declare function tokenEntriesProp(): PropConfig<TokenEntry[]>;
+/**
+ * The `--var` lane (SPEC-R2), value-NEUTRAL: a value beginning `--` routes through `var(<value>)`; any other
+ * string (a literal color/length, or `''`) is returned VERBATIM. Pure string routing — no resolution, no
+ * `getComputedStyle` (the browser resolves the returned expression wherever it lands; the readback is an
+ * ADR-0118 cl.2 foreseen extension, out of v1). Used by BOTH swatch/ramp's `background` and ladder's `--_mag`
+ * (LLD-C6) — the ONE transform, so a `--`-prefixed value never reaches a CSS property as a bare dashed-ident
+ * (`min(100%, --md-sys-height-md)` is invalid at computed-value time; `min(100%, var(--md-sys-height-md))` is what we want).
+ */
+export declare function cssValue(value: string): string;
+/**
+ * The length-router (SPEC-R11): true iff `value` is a resolvable CSS length — a `--var` counts (its own
+ * resolution is the browser's job, so any `--`-prefixed name is treated as renderable; ladder still routes it
+ * through `cssValue` before use). Uses `CSS.supports('inline-size', v)` when available (browser + modern
+ * jsdom) for a real platform-truth answer; falls back to the conservative unit regex above so the plain jsdom
+ * unit tests still bite when `CSS.supports` is absent. NOT a drop gate (SPEC-R11) — LLD-C6 uses this to ROUTE
+ * a non-length value to a zero-length bar (`0px`) while KEEPING the row + its printed value, matching swatch's
+ * invalid-color-keeps-the-datum (SPEC-R3) and ramp's invalid-color-keeps-the-cell (SPEC-R7).
+ */
+export declare function isRenderableLength(value: string): boolean;

package/dist/controls/_token-surface/token-surface.js

@@ -0,0 +1,97 @@
+// token-surface.ts — the shared value-lane helper for the token-surface family (ui-swatch/ui-ramp/ui-ladder;
+// LLD-C1, token-surfaces.lld.md §2; SPEC-R2/R7/R11; ADR-0118 cl.2). DOM-free, unit-testable in plain Vitest —
+// no color math, no getComputedStyle (the browser is the ONE resolver, ADR-0118 cl.2/3). A single shared folder,
+// not three divergent copies (the `_base`/`_surface` precedent): all three controls bind the SAME value-lane
+// contract, unlike the chart family's per-control math (bar-math.ts/sparkline math stay co-located there).
+//
+// Owns three things:
+//   1. `cleanEntries`/`tokenEntriesProp` — the hardened `{label,value}[]` codec (the bar-chart `cleanData`/
+//      `barDataProp` construction, generalized: `from(null) = []`, malformed JSON → `[]`, never a throw).
+//   2. `cssValue` — the value-NEUTRAL `--var` lane (SPEC-R2): a `--`-prefixed value routes through `var(<value>)`
+//      before it ever reaches a CSS property, so a bare dashed-ident (invalid at computed-value time inside
+//      `min(100%, …)`) never poisons ladder's `--_mag` or swatch/ramp's `background`.
+//   3. `isRenderableLength` — the length ROUTER (SPEC-R11): NOT a drop gate — ladder uses it to decide whether a
+//      tier's value drives a real bar or a `0px` zero-bar, the row + printed value surviving either way (the
+//      unified no-silent-state rule, matching swatch's invalid-color-keeps-the-datum).
+/**
+ * Harden an arbitrary input into the rendered entry set (SPEC-R7/R11): a non-array input yields `[]`; each
+ * entry survives only as a plain object with a `string` `label` AND a `string` `value` — drop, never coerce.
+ * Order is preserved (positional semantics — a duplicate-label row: both entries render, the list is
+ * positional, not keyed). The bar-chart `cleanData` construction, generalized to a string `value` (a color/
+ * length lane, not a number).
+ */
+export function cleanEntries(input) {
+    if (!Array.isArray(input))
+        return [];
+    const out = [];
+    for (const entry of input) {
+        if (entry !== null &&
+            typeof entry === 'object' &&
+            !Array.isArray(entry) &&
+            typeof entry.label === 'string' &&
+            typeof entry.value === 'string') {
+            const e = entry;
+            out.push({ label: e.label, value: e.value });
+        }
+    }
+    return out;
+}
+/**
+ * The safe `steps`/`tiers` codec (SPEC-R7/R11 row 1): `from(null)` (attribute absent/removed) → `[]`, NEVER
+ * `null`; malformed attribute JSON is caught and also falls back to `[]` — no throw ever reaches
+ * `attributeChangedCallback`. `dom/props.ts`'s generic `jsonType<T>()` is deliberately NOT used here — its bare
+ * `JSON.parse` throws on malformed attributes and maps a removed attribute to `null`, both of which the
+ * hardening rows forbid reaching the render path (the bar-chart `barDataProp` reasoning, restated for the
+ * token-surface family's string-valued entries).
+ */
+const tokenEntriesType = {
+    from(attr) {
+        if (attr === null)
+            return [];
+        try {
+            return cleanEntries(JSON.parse(attr));
+        }
+        catch {
+            return [];
+        }
+    },
+    to(value) {
+        return JSON.stringify(value);
+    },
+};
+/** The `steps`/`tiers` prop config — a fresh `PropConfig` each call (default `[]`, never a SHARED mutable array). */
+export function tokenEntriesProp() {
+    return { type: tokenEntriesType, default: [] };
+}
+/**
+ * The `--var` lane (SPEC-R2), value-NEUTRAL: a value beginning `--` routes through `var(<value>)`; any other
+ * string (a literal color/length, or `''`) is returned VERBATIM. Pure string routing — no resolution, no
+ * `getComputedStyle` (the browser resolves the returned expression wherever it lands; the readback is an
+ * ADR-0118 cl.2 foreseen extension, out of v1). Used by BOTH swatch/ramp's `background` and ladder's `--_mag`
+ * (LLD-C6) — the ONE transform, so a `--`-prefixed value never reaches a CSS property as a bare dashed-ident
+ * (`min(100%, --md-sys-height-md)` is invalid at computed-value time; `min(100%, var(--md-sys-height-md))` is what we want).
+ */
+export function cssValue(value) {
+    return value.startsWith('--') ? `var(${value})` : value;
+}
+// A conservative CSS-length unit regex — the jsdom fallback when `CSS.supports` is unavailable (older jsdom
+// builds no `CSS.supports`). Matches a signed/unsigned number (incl. a bare `0`, unitless per the CSS spec)
+// followed by one of the standard absolute/relative length units, OR a bare `0`.
+const LENGTH_RE = /^[+-]?\d*\.?\d+(px|em|rem|ex|ch|vw|vh|vmin|vmax|cm|mm|in|pt|pc|q|%)$|^0$/i;
+/**
+ * The length-router (SPEC-R11): true iff `value` is a resolvable CSS length — a `--var` counts (its own
+ * resolution is the browser's job, so any `--`-prefixed name is treated as renderable; ladder still routes it
+ * through `cssValue` before use). Uses `CSS.supports('inline-size', v)` when available (browser + modern
+ * jsdom) for a real platform-truth answer; falls back to the conservative unit regex above so the plain jsdom
+ * unit tests still bite when `CSS.supports` is absent. NOT a drop gate (SPEC-R11) — LLD-C6 uses this to ROUTE
+ * a non-length value to a zero-length bar (`0px`) while KEEPING the row + its printed value, matching swatch's
+ * invalid-color-keeps-the-datum (SPEC-R3) and ramp's invalid-color-keeps-the-cell (SPEC-R7).
+ */
+export function isRenderableLength(value) {
+    if (value.startsWith('--'))
+        return true; // a --var's resolution is the browser's job (cssValue routes it)
+    if (typeof CSS !== 'undefined' && typeof CSS.supports === 'function') {
+        return CSS.supports('inline-size', value);
+    }
+    return LENGTH_RE.test(value.trim());
+}

package/dist/controls/attachment/attachment-meta.d.ts

@@ -0,0 +1,8 @@
+import type { IconName } from '@agent-ui-kit/icons';
+export type FileCategory = 'image' | 'audio' | 'video' | 'pdf' | 'text' | 'archive' | 'data' | 'default';
+/** SPEC-R9 AC1 — case-insensitive, `;`-parameter-stripped, TOTAL (unknown/empty → 'default'). */
+export declare function fileCategory(mimeType: string): FileCategory;
+export declare function categoryGlyph(c: FileCategory): IconName;
+export declare function categoryLabel(c: FileCategory): string;
+/** SPEC-R9 AC2 — null/non-finite/negative → null (cell absent). Decimal (1000-based) B/KB/MB/GB/TB steps. */
+export declare function formatBytes(size: number | null): string | null;

package/dist/controls/attachment/attachment-meta.js

@@ -0,0 +1,84 @@
+// attachment-meta.ts — the pure, DOM-free math for `ui-attachment` (LLD-C4, feed-family.lld.md §4;
+// SPEC-R8/R9; ADR-0112 cl.4). Plain functions over strings/numbers — no DOM, no signals, unit-testable
+// without a browser (the stat-model.ts / sparkline-math.ts pure-core precedent).
+//
+// `fileCategory` (SPEC-R9 AC1): case-insensitive, `;`-parameter-stripped mimeType → one of eight
+// categories. Exact/substring matches (`application/pdf`; the data-shaped types — json/xml/csv/
+// spreadsheet) are checked BEFORE the broad `image/`·`audio/`·`video/`·`text/` prefixes, because
+// `text/csv` is a data type, not a text type — an ordering the prefix pass alone cannot express. The
+// archive set follows, then `default` — a TOTAL function, never throws, unknown/empty mime included.
+//
+// `categoryGlyph`/`categoryLabel` (LLD-C4): the fixed per-category icon-name and name-fallback maps.
+//
+// `formatBytes` (SPEC-R9 AC2): `size` (bytes) → a decimal (1000-based) B/KB/MB/GB/TB string via the
+// module-memoized default-locale `Intl.NumberFormat` (≤ 1 fraction digit); `null`/non-finite/negative →
+// `null` (the size cell is absent, never a fabricated "0 B" or "NaN B").
+/** Data-shaped mimeTypes that are NOT read as their broad prefix (SPEC-R9 AC1: `text/csv` → data, not text). */
+const DATA_EXACT = new Set(['application/json', 'application/xml', 'text/xml']);
+/** A mimeType containing either substring is data-shaped (spreadsheet formats, any `csv` variant). */
+const DATA_SUBSTRING = /spreadsheet|csv/;
+/** Archive/compression formats (LLD-C4: zip|tar|gzip|x-7z|rar). */
+const ARCHIVE_MATCH = /zip|tar|gzip|x-7z|rar/;
+/** SPEC-R9 AC1 — case-insensitive, `;`-parameter-stripped, TOTAL (unknown/empty → 'default'). */
+export function fileCategory(mimeType) {
+    const mime = mimeType.trim().split(';', 1)[0].trim().toLowerCase();
+    if (mime === '')
+        return 'default';
+    if (mime === 'application/pdf')
+        return 'pdf';
+    if (DATA_EXACT.has(mime) || DATA_SUBSTRING.test(mime))
+        return 'data';
+    if (mime.startsWith('image/'))
+        return 'image';
+    if (mime.startsWith('audio/'))
+        return 'audio';
+    if (mime.startsWith('video/'))
+        return 'video';
+    if (mime.startsWith('text/'))
+        return 'text';
+    if (ARCHIVE_MATCH.test(mime))
+        return 'archive';
+    return 'default';
+}
+/** The glyph name per category (all vendored, SPEC-N5 — LLD-C9's icons PREP slice). */
+const CATEGORY_GLYPH = {
+    image: 'file-image',
+    audio: 'file-audio',
+    video: 'file-video',
+    pdf: 'file-pdf',
+    text: 'file-text',
+    archive: 'file-zip',
+    data: 'file-code',
+    default: 'file',
+};
+export function categoryGlyph(c) {
+    return CATEGORY_GLYPH[c];
+}
+/** The SPEC-R8 name fallback (never an empty title). */
+const CATEGORY_LABEL = {
+    image: 'Image',
+    audio: 'Audio',
+    video: 'Video',
+    pdf: 'PDF document',
+    text: 'Text document',
+    archive: 'Archive',
+    data: 'Data file',
+    default: 'File',
+};
+export function categoryLabel(c) {
+    return CATEGORY_LABEL[c];
+}
+const UNITS = ['B', 'KB', 'MB', 'GB', 'TB'];
+const byteFormat = new Intl.NumberFormat(undefined, { maximumFractionDigits: 1 }); // module-memoized
+/** SPEC-R9 AC2 — null/non-finite/negative → null (cell absent). Decimal (1000-based) B/KB/MB/GB/TB steps. */
+export function formatBytes(size) {
+    if (size === null || !Number.isFinite(size) || size < 0)
+        return null;
+    let value = size;
+    let unit = 0;
+    while (value >= 1000 && unit < UNITS.length - 1) {
+        value /= 1000;
+        unit++;
+    }
+    return `${byteFormat.format(value)} ${UNITS[unit]}`;
+}

package/dist/controls/attachment/attachment.css

@@ -0,0 +1,91 @@
+/* attachment.css — ui-attachment, the Display-class FilePart-aligned file card (LLD-C5,
+ * feed-family.lld.md §4; SPEC-R9/R18/R19/R20; ADR-0112 cl.4, fork F4). Two sectioned blocks:
+ *
+ *   [1] TOKEN BLOCK — `:where(ui-attachment)` declares --ui-attachment-* from the colour roles
+ *       (--md-sys-color-{family}-{role}) + the content-icon register (--md-sys-icon-md, geometry.md's
+ *       "Affordance vs content-icon" taxonomy — the glyph is a CONTENT icon, not an inline affordance,
+ *       so it rides the icon ramp, never `= font`). Display class (SPEC-R20 AC2): no [size]/[scale]
+ *       control-band lookup, no --md-sys-height-* consumption — the border/radius/floor are frame constants,
+ *       the glyph is the fixed default icon-ramp tier (no ancestor [scale] repoint needed at v1).
+ *   [2] STYLES BLOCK — `@scope (ui-attachment)` consumes ONLY --ui-attachment-*.
+ *
+ * Posture (fork F4): a compact card with its OWN bordered surface (--md-sys-shape-corner-base, the entry/container
+ * radius kin) — one-row anatomy glyph | name+meta, inline-grid + max-inline-size:100% so N-up in a
+ * Row(wrap) or as ui-list children both hold with zero extra code (composability, SPEC-R9).
+ *
+ * Whole-shape floor (SPEC-R18 AC1) — --ui-attachment-min-inline-size guards the slider-dot collapse shape
+ * in an unstyled flex row. Rhythm (gap/padding) rides the space ladder — density-responsive for free
+ * (SPEC-R18 AC3); the border/radius/floor stay frame constants, unaffected by [density].
+ *
+ * Truncation (SPEC-R9 AC3): the name cell is single-line ellipsis (the ADR-0106 CSS-only mechanism,
+ * cited — its home use here) — `min-inline-size: 0` on the body cell is what lets the name actually
+ * shrink to trigger it inside a grid track, not just the property alone.
+ *
+ * Forced colors (SPEC-R19): the card's border repoints to CanvasText (the boxed identity survives); the
+ * glyph is `<ui-icon>` (an inline SVG using currentColor by the icon adapter's own contract) and the name/
+ * meta are real text — both survive WHCM with no dedicated rule here.
+ */
+
+/* ════════════════ [1] TOKEN BLOCK — :where(ui-attachment) declares --ui-attachment-* ════════════════ */
+
+:where(ui-attachment) {
+  --ui-attachment-min-inline-size: 12em; /* the whole-shape floor (SPEC-R18 AC1) */
+  --ui-attachment-gap: var(--md-sys-space-sm);
+  --ui-attachment-pad-inline: var(--md-sys-space-sm);
+  --ui-attachment-pad-block: var(--md-sys-space-xs);
+  --ui-attachment-border: var(--md-sys-color-neutral-outline);
+  --ui-attachment-surface: transparent; /* rides the ambient plane; a page may lift it */
+  --ui-attachment-glyph: var(--md-sys-icon-md); /* content-icon register (geometry.md taxonomy), fixed tier — Display class, no [scale] row */
+  --ui-attachment-name-ink: var(--md-sys-color-neutral-on-surface);
+  --ui-attachment-meta-ink: var(--md-sys-color-neutral-on-surface-variant);
+  --ui-attachment-radius: var(--md-sys-shape-corner-base); /* TKT-0066 item 5 ruling: constants route through the own chain */
+}
+
+/* ════════════════ [2] STYLES BLOCK — @scope (ui-attachment) consumes ONLY --ui-attachment-* ════════════════ */
+
+@scope (ui-attachment) {
+  :scope {
+    display: inline-grid;
+    grid-template-columns: auto 1fr;
+    align-items: center;
+    gap: var(--ui-attachment-gap);
+    padding-inline: var(--ui-attachment-pad-inline);
+    padding-block: var(--ui-attachment-pad-block);
+    border: 1px solid var(--ui-attachment-border);
+    border-radius: var(--ui-attachment-radius); /* the entry/container radius kin (F4) */
+    background: var(--ui-attachment-surface);
+    min-inline-size: var(--ui-attachment-min-inline-size);
+    max-inline-size: 100%; /* composability — never grows past its container (SPEC-R9 AC3) */
+  }
+
+  :scope [data-part='glyph'] {
+    font-size: var(--ui-attachment-glyph); /* <ui-icon> is a 1em box — this IS its size lever */
+    color: var(--ui-attachment-meta-ink);
+  }
+
+  :scope [data-part='body'] {
+    display: grid;
+    min-inline-size: 0; /* lets the name cell actually shrink to trigger the ellipsis truncation */
+  }
+
+  :scope [data-part='name'] {
+    color: var(--ui-attachment-name-ink);
+    white-space: nowrap;
+    overflow: hidden;
+    text-overflow: ellipsis; /* ADR-0106 mechanism, cited — its home use */
+    font-size: var(--md-sys-typescale-body-medium-size);
+    line-height: var(--md-sys-typescale-body-medium-line-height);
+  }
+
+  :scope [data-part='meta'] {
+    color: var(--ui-attachment-meta-ink);
+    font-size: var(--md-sys-typescale-body-small-size);
+    line-height: var(--md-sys-typescale-body-small-line-height);
+  }
+
+  @media (forced-colors: active) {
+    :scope {
+      border-color: CanvasText; /* the boxed identity survives; name/meta are real text, glyph is currentColor-based */
+    }
+  }
+}

package/dist/controls/attachment/attachment.d.ts

@@ -0,0 +1,40 @@
+import { UIElement, type ReactiveProps } from '../../dom/index.js';
+import '../icon/icon.js';
+declare const props: {
+    filename: import("../../index.js").PropConfig<string>;
+    mimeType: {
+        attribute: string;
+        type: import("../../index.js").PropType<string>;
+        default: string;
+        reflect?: boolean;
+    };
+    sizeBytes: {
+        attribute: string;
+        type: import("../../index.js").PropType<number | null>;
+        default: number | null;
+        reflect?: boolean;
+    };
+    href: import("../../index.js").PropConfig<string>;
+};
+export interface UIAttachmentElement extends ReactiveProps<typeof props> {
+}
+export declare class UIAttachmentElement extends UIElement {
+    static props: {
+        filename: import("../../index.js").PropConfig<string>;
+        mimeType: {
+            attribute: string;
+            type: import("../../index.js").PropType<string>;
+            default: string;
+            reflect?: boolean;
+        };
+        sizeBytes: {
+            attribute: string;
+            type: import("../../index.js").PropType<number | null>;
+            default: number | null;
+            reflect?: boolean;
+        };
+        href: import("../../index.js").PropConfig<string>;
+    };
+    protected connected(): void;
+}
+export {};

package/dist/controls/attachment/attachment.js

@@ -0,0 +1,70 @@
+// attachment.ts — UIAttachmentElement, the Display-class FilePart-aligned compact file card (LLD-C5,
+// feed-family.lld.md §4; SPEC-R8/R9/R10; ADR-0112 cl.4, fork F4). Non-interactive, non-form-associated
+// leaf (extends UIElement): no events, no keyboard contract, no `[size]`/`[scale]` control geometry
+// (Display class, SPEC-R20). Component-built light DOM only — `render()` stays the inherited no-op.
+//
+// Anatomy (SPEC-R9/R10): a decorative `<ui-icon data-part="glyph">` (aria-hidden by the icon's OWN
+// default — no label is ever set on it, so no attachment-side ARIA work is needed) followed by a
+// `<span data-part="body">` holding the `name` cell (falls back to the file category's label — never an
+// empty title, SPEC-R8 AC2) and, when a finite non-negative `sizeBytes` is present, a `meta` cell with the
+// formatted byte string (absent, not empty, when `sizeBytes` is null/non-finite/negative). One render effect,
+// whole-swap per change (the stat.ts / bar-chart posture — no interior state worth preserving on a
+// four-node card). The host mints NO internals ARIA (SPEC-R10): the name/meta are real DOM text, the
+// accessible datum; the glyph repeats what the name/mime already carry.
+//
+// SCOPE FENCE (feed-family build sequence, LLD §11 Wave M1-a vs M1-c): this file ships the METADATA
+// SURFACE ONLY (LLD-C4/C5). The `href` prop exists now because SPEC-R8 mints it as one of the four
+// wire-mirroring props, but its RENDERING leg — the name cell becoming a native `<a>` under the shared
+// ADR-0114 gate (`controls/text/href.ts`'s `safeHref`/`LINK_REL`/`LINK_TARGET`, LLD-C6) — is DEFERRED to
+// the M1-c wave (with-or-after that shared gate module is confirmed integrated fleet-wide). Until then
+// `href` is inert: read into no effect, rendered nowhere. Do not wire `safeHref` here — that is LLD-C6's
+// own slice, coordinated with the catalog wave (SPEC-R11 AC3's single-gate-module grep).
+import { UIElement, prop } from "../../dom/index.js";
+import "../icon/icon.js"; // side-effect: defines <ui-icon>, the glyph's declarative surface (the avatar/LLD-C5 sibling-control-import idiom)
+import { categoryGlyph, categoryLabel, fileCategory, formatBytes } from "./attachment-meta.js";
+const props = {
+    filename: prop.string(''), // optional on the A2aFilePart wire — empty falls back to the category label. Renamed from `name` (TKT-0069 item 1 ruling: `name` = the FORM name, reserved; the A2UI catalog keeps wire `name`, mapped in its bespoke factory)
+    // `attribute: 'mime-type'` is load-bearing, not stylistic: Element.setAttribute lowercases the name in
+    // an HTML document, so a camelCase observed-attribute name ('mimeType') would never match the always-
+    // lowercase real attribute and attributeChangedCallback would silently never fire (the fleet's existing
+    // multi-word props are either single-word or already reflect+kebab, e.g. slider-multi's valueLo/valueHi
+    // — this is the first non-reflected multi-word prop, so the same kebab discipline applies here too).
+    mimeType: { ...prop.string(''), attribute: 'mime-type' }, // drives the glyph + name fallback via fileCategory
+    // Named `sizeBytes`/`size-bytes`, NOT `size` (ADR-0112 Amendment 1): the fleet-wide law
+    // (family-coherence.test.ts's "a `size` attribute is always exactly [sm, md, lg]") reserves the literal
+    // name `size` for the widget-tier geometry enum every sized control shares — this is unrelated byte-count
+    // domain data (SPEC-R8), and reusing `size` would silently collide with that convention for any future
+    // reader/consumer. Same kebab-attribute discipline as `mimeType` above (multi-word, non-reflected).
+    sizeBytes: { ...prop.number(null), attribute: 'size-bytes' }, // bytes; NOT a wire field — embedder-supplied (SPEC-R8); null/non-finite/negative ⇒ no meta cell
+    // SPEC-R8's fourth wire-mirroring prop. Rendering leg DEFERRED — see the file header note (LLD-C6).
+    href: prop.string(''),
+};
+export class UIAttachmentElement extends UIElement {
+    static props = props;
+    connected() {
+        this.effect(() => {
+            const category = fileCategory(this.mimeType);
+            const title = this.filename || categoryLabel(category);
+            const size = formatBytes(this.sizeBytes);
+            const glyph = document.createElement('ui-icon');
+            glyph.setAttribute('data-part', 'glyph');
+            glyph.setAttribute('glyph', categoryGlyph(category));
+            // The name cell is a plain <span> in this pass — the LLD-C6 <a> leg is deferred (file header note).
+            const name = document.createElement('span');
+            name.setAttribute('data-part', 'name');
+            name.textContent = title;
+            const body = document.createElement('span');
+            body.setAttribute('data-part', 'body');
+            body.append(name);
+            if (size !== null) {
+                const meta = document.createElement('span');
+                meta.setAttribute('data-part', 'meta');
+                meta.textContent = size;
+                body.append(meta);
+            }
+            this.replaceChildren(glyph, body);
+        });
+    }
+}
+if (!customElements.get('ui-attachment'))
+    customElements.define('ui-attachment', UIAttachmentElement); // idempotent self-define

package/dist/controls/avatar/avatar-initials.d.ts

@@ -0,0 +1,4 @@
+/** SPEC-R5: first grapheme of first word + first grapheme of last word (single word ⇒ one grapheme),
+ *  locale-uppercased. Grapheme-safe via Intl.Segmenter('grapheme') with an Array.from code-point
+ *  fallback (ledger §10.4). '' / whitespace-only ⇒ '' (the caller falls through to the glyph). */
+export declare function initialsFrom(name: string): string;

package/dist/controls/avatar/avatar-initials.js

@@ -0,0 +1,30 @@
+// avatar-initials.ts — the pure, DOM-free initials derivation for ui-avatar (LLD-C2, feed-family.lld.md
+// §3; SPEC-R5). A plain function over a string — no DOM, no signals, unit-testable without a browser
+// (the stat-model.ts / attachment-meta.ts pure-core precedent).
+//
+// SPEC-R5: first grapheme of the first word + first grapheme of the last word (a single word yields one
+// grapheme), locale-uppercased. Grapheme-safe via `Intl.Segmenter('grapheme')` with an `Array.from`
+// code-point fallback for environments where Segmenter is unavailable (failure mode #4, the LLD ledger).
+// '' / whitespace-only ⇒ '' — the caller (avatar.ts) falls through to the person-glyph link of the chain.
+const segmenter = typeof Intl !== 'undefined' && typeof Intl.Segmenter === 'function'
+    ? new Intl.Segmenter(undefined, { granularity: 'grapheme' })
+    : null;
+/** The first grapheme cluster of a non-empty string (code-point-safe fallback when Segmenter is absent). */
+function firstGrapheme(word) {
+    if (segmenter) {
+        const first = segmenter.segment(word)[Symbol.iterator]().next();
+        return first.done ? '' : first.value.segment;
+    }
+    return Array.from(word)[0] ?? '';
+}
+/** SPEC-R5: first grapheme of first word + first grapheme of last word (single word ⇒ one grapheme),
+ *  locale-uppercased. Grapheme-safe via Intl.Segmenter('grapheme') with an Array.from code-point
+ *  fallback (ledger §10.4). '' / whitespace-only ⇒ '' (the caller falls through to the glyph). */
+export function initialsFrom(name) {
+    const words = name.trim().split(/\s+/).filter(Boolean);
+    if (words.length === 0)
+        return '';
+    const first = firstGrapheme(words[0]);
+    const initials = words.length === 1 ? first : first + firstGrapheme(words[words.length - 1]);
+    return initials.toLocaleUpperCase();
+}