@agent-ui-kit/components 0.0.3

package/dist/controls/tabs/tabs.js

@@ -0,0 +1,176 @@
+// tabs.ts — UITabsElement, the tabs compound's coordinator (goals.md §G9 / decomp g9-containers s8 / ADR-0015
+// surface · ADR-0019 the bindable `selected` two-way). BEHAVIOUR + props + the tablist part + roving/keyboard +
+// the tab↔panel wiring + self-define ONLY; geometry/colour live in tabs.css, the contract in tabs.md.
+//
+// The container (the FIRST non-form family — extends UIContainerElement for the surface axes + the reused
+// protected `internals`; NOT form-associated). It owns a control-created `[data-part=tablist]` strip
+// (`role=tablist` on the PART div — allowed, like the text-field editor part; the HOST carries no role) into
+// which it REPARENTS its `ui-tab` children (the panels stay as siblings of the strip — a tablist must wrap only
+// the tabs). It then drives the whole widget from ONE place (a sibling cannot set another element's protected
+// internals): each tab↔panel pair is wired once (`aria-controls`/`aria-labelledby` via internals element-
+// reflection), and a single scope-owned effect re-applies selection — `aria-selected` + the roving tabindex
+// (exactly the selected tab is tabindex=0) + `:state(selected)` on the tabs, and the `hidden` attribute on the
+// panels (only the selected panel shows; the rest stay in the DOM). ArrowLeft/Right + Home/End move selection
+// AND focus together (selection-follows-focus), committing through the same path as a click. The keyboard
+// navigation is handled by the shared `rovingFocus` trait (listbox-roving LLD-C1).
+//
+// `selected` is a plain reflected string the renderer two-way-binds via LLD-C8 (ADR-0019): the agent SETS it
+// (programmatic → the effect applies it, NO event echoed), a user gesture COMMITS it (the ONE `select` event
+// emitted, the renderer reads the new tab back). The control stays renderer-agnostic — it knows nothing of A2UI.
+// `controls → dom` is the allowed import direction; importing this module registers all three tags (it imports
+// tab.ts/tab-panel.ts), so the s12 barrel needs only `export * from './tabs/tabs.ts'`.
+import { UIContainerElement } from "../../dom/container.js";
+import { prop } from "../../dom/index.js";
+import { rovingFocus } from "../../traits/roving-focus.js";
+import { UITabElement } from "./tab.js";
+import { UITabPanelElement } from "./tab-panel.js";
+// A per-instance id seed so each tabs' tab/panel pair gets unique IDREFs (the reverse aria-labelledby anchor).
+let tabsSeq = 0;
+const props = {
+    // The surface axes (ADR-0015) — elevation/brightness, spread from the base (no prototype merge; the ADR-0013
+    // formProps precedent). ui-tabs sets its OWN default --ui-container-bg in tabs.css (the base default is
+    // transparent), so a bare tabs still has a surface.
+    ...UIContainerElement.surfaceProps,
+    // `selected` — the active tab's identity (its `key`, or its DOM index as a string; '' ⇒ the first tab).
+    // OBSERVED + REFLECTED so the attribute mirrors the live selection, and BINDABLE: the renderer two-way-binds it
+    // via LLD-C8 (value:{prop:'selected',event:'select'}, ADR-0019). Typed `string` — the value crosses the
+    // attribute boundary as a string regardless (a numeric index is its string form); the descriptor records it so.
+    selected: { ...prop.string(), reflect: true },
+    // `fill` — ADR-0144 Q1 cl.1: ONE opt-in reflected boolean (the `ui-split-pane` `collapsible` shape), realized
+    // CSS-ONLY in tabs.css (`:scope[fill]`). Fills a height-bounded parent with a pinned tablist strip + an
+    // internally scrolling active panel — the exact composition `agent-admin.css` (TKT-0085) hand-rolled per
+    // consumer for lack of a shipped variant. Absent (the default), tabs stays byte-identical document-flow.
+    fill: { ...prop.boolean(false), reflect: true },
+};
+export class UITabsElement extends UIContainerElement {
+    static props = props;
+    // The control-created tablist strip + the captured tab/panel lists (light-DOM, persist across reconnect).
+    #tablist = null;
+    #tabs = [];
+    #panels = [];
+    #baseId = '';
+    // The resolved active index — the single source of truth for the keyboard delta; kept in sync by the effect
+    // and eagerly on commit (so a rapid second keypress before the effect flush still steps from the right place).
+    #activeIndex = -1;
+    connected() {
+        if (!this.#baseId)
+            this.#baseId = `ui-tabs-${++tabsSeq}`;
+        const strip = this.#ensureTablist();
+        // Reparent the tab children INTO the strip (idempotent — a tab already inside is skipped, so reconnect is a
+        // no-op). Recognised by instanceof so a probe subclass nests; the panels are left as strip siblings.
+        for (const child of [...this.children]) {
+            if (child instanceof UITabElement && child.parentNode !== strip)
+                strip.append(child);
+        }
+        this.#tabs = [...strip.children].filter((c) => c instanceof UITabElement);
+        this.#panels = [...this.children].filter((c) => c instanceof UITabPanelElement);
+        // Wire each tab↔panel pair ONCE (ids + the aria-controls/labelledby element-reflection). Pairs by DOM order.
+        this.#tabs.forEach((tab, i) => {
+            const panel = this.#panels[i];
+            if (!panel)
+                return;
+            const tabId = `${this.#baseId}-tab-${i}`;
+            const panelId = `${this.#baseId}-panel-${i}`;
+            tab.link(panel, tabId);
+            panel.link(tab, panelId);
+        });
+        // Click commit listener — delegated to the tablist strip (rides the connection AbortSignal).
+        // Keydown is handled by the rovingFocus trait below.
+        this.listen(strip, 'click', this.#onClick);
+        // The selection effect — re-applies on every `selected` change (and re-arms on reconnect). Runs once now
+        // (synchronously) so the initial roving tabindex + panel visibility are correct before first paint.
+        this.effect(() => {
+            const index = this.#resolveIndex(); // reads this.selected (tracked) + this.#tabs
+            this.#tabs.forEach((tab, i) => tab.setSelected(i === index));
+            this.#panels.forEach((panel, i) => {
+                panel.hidden = i !== index; // standard `hidden` (NOT ARIA) — only the selected panel shows; the rest stay in DOM
+            });
+            this.#activeIndex = index;
+        });
+        // Roving keyboard focus — the shared trait (listbox-roving LLD-C1) replaces the former inline #onKeydown.
+        // The effect above runs synchronously and sets #activeIndex before we get here, so initialIndex reads
+        // the correct position even after reconnect with a non-first tab selected. syncIndex reconciles on each
+        // keydown after a click or programmatic selection change that bypassed the trait's onMove.
+        rovingFocus(this, {
+            container: strip,
+            items: () => this.#tabs,
+            orientation: 'horizontal',
+            loop: true,
+            typeAhead: false,
+            initialIndex: () => this.#activeIndex,
+            syncIndex: () => this.#activeIndex,
+            onMove: (index) => this.#commit(index, false), // trait already moved focus; commit without re-focusing
+        });
+        // Motion gate (interaction-states standard) — arm `ready` ONE FRAME past first paint so the synchronous
+        // initial selection SNAPS and only later changes animate (tabs.css gates the transition behind
+        // :state(ready)). states optional-chained — jsdom has no CustomStateSet (the real motion is the browser smoke).
+        requestAnimationFrame(() => this.internals.states?.add('ready'));
+    }
+    /** Create the `[data-part=tablist]` strip ONCE (idempotent across reconnect — it is a persistent light-DOM
+     *  child) and keep it as the first child. `role=tablist` rides the PART div (text-field editor-part precedent),
+     *  so the HOST stays free of a role attribute. */
+    #ensureTablist() {
+        let strip = this.#tablist;
+        if (!strip) {
+            strip = document.createElement('div');
+            strip.setAttribute('data-part', 'tablist');
+            strip.setAttribute('role', 'tablist');
+            this.#tablist = strip;
+        }
+        if (strip.parentNode !== this)
+            this.insertBefore(strip, this.firstChild);
+        return strip;
+    }
+    /** Resolve `selected` → a tab index: '' ⇒ the first tab; a `key` match wins; else a numeric index in range;
+     *  else fall back to the first tab. Reads `this.selected` so the selection effect tracks it. */
+    #resolveIndex() {
+        const tabs = this.#tabs;
+        if (tabs.length === 0)
+            return -1;
+        const sel = this.selected;
+        if (sel === '')
+            return 0;
+        const byKey = tabs.findIndex((t) => t.key !== '' && t.key === sel);
+        if (byKey !== -1)
+            return byKey;
+        if (/^\d+$/.test(sel)) {
+            const n = Number(sel);
+            if (n >= 0 && n < tabs.length)
+                return n;
+        }
+        return 0;
+    }
+    // ── click commit — delegated: find the clicked tab among ours (instanceof-safe across subclasses) ──
+    #onClick = (event) => {
+        const target = event.target;
+        const index = this.#tabs.findIndex((t) => t === target || t.contains(target));
+        if (index === -1)
+            return;
+        this.#commit(index, true);
+    };
+    /**
+     * Commit a user-driven selection: write `selected` (→ the effect re-applies aria/roving/panels), move focus to
+     * the tab (roving), and emit `select` ONLY when the selection actually changed — so a programmatic `selected`
+     * set by the agent (the renderer's two-way write) never echoes an event back (binding hygiene). The commit
+     * value is the tab's `key` when it has one, else its index as a string (the addressable identity).
+     */
+    #commit(index, moveFocus) {
+        const tab = this.#tabs[index];
+        if (!tab)
+            return;
+        const changed = index !== this.#activeIndex;
+        const identity = tab.key !== '' ? tab.key : String(index);
+        this.#activeIndex = index; // eager — keep the keyboard delta correct before the effect flush
+        this.selected = identity; // → reflects + wakes the selection effect
+        if (moveFocus)
+            tab.focus();
+        if (changed) {
+            // `select` is the ONE commit event (the event-vocab's selection event). The s11 catalog binds
+            // value:{prop:'selected',event:'select'} and the renderer's LLD-C8 controller listens to exactly it to
+            // write `selected` back into the A2UI data model — NOT `change` (which is value-commit-flavored).
+            this.emit('select', { value: identity, index });
+        }
+    }
+}
+if (!customElements.get('ui-tabs'))
+    customElements.define('ui-tabs', UITabsElement);

package/dist/controls/text/href.d.ts

@@ -0,0 +1,26 @@
+/** The fleet scheme allowlist — ONE constant, imported by every enforcement site (the component gate +
+ *  the a2ui validator's first line). Widening it is a one-line, gate-visible edit (ADR-0114 fork F1). */
+export declare const SAFE_HREF_SCHEMES: readonly ["https:", "http:", "mailto:"];
+/**
+ * The component gate (SPEC-R8, normative verdict procedure). Validates; NEVER rewrites — returns the
+ * author's string byte-identical on allow, `null` on deny OR no-destination:
+ *  - `raw.trim() === ''` → `null` (no destination — the default-`''`/whitespace self-link trap, SPEC-R8
+ *    AC7: `new URL('', base)` would otherwise mint a self-link, so this check runs BEFORE parsing).
+ *  - `new URL(raw, base)` throws → `null` (unparseable = denied, fail-closed).
+ *  - the resolved `url.protocol` is not in `SAFE_HREF_SCHEMES` → `null` (denied).
+ *  - else → `raw` (allowed — byte-identical, never rewritten; the anchor's own resolution equals this
+ *    parse by construction, since both resolve against the same `base`).
+ *
+ * Parsing with `new URL` is load-bearing (SPEC-R8): it applies the SAME control-character/whitespace
+ * normalizations navigation itself would, so `"java\nscript:…"` and `" JAVASCRIPT:…"` are denied as their
+ * normalized selves — a string-prefix check is non-conformant and would miss exactly this smuggling class.
+ *
+ * `base` is a parameter (the component passes `document.baseURI`) so this module stays DOM-free — the
+ * validator side reuses `SAFE_HREF_SCHEMES` without inheriting a `document` dependency.
+ */
+export declare function safeHref(raw: string, base: string): string | null;
+/** The fixed anchor policy (ADR-0114 fork F3 — no props at v1): component-set constants, applied ONLY
+ *  alongside an allowed `href`, never author-supplied. Exported alongside the gate so a future
+ *  `ui-attachment` href leg shares this one module instead of minting a second copy. */
+export declare const LINK_REL = "noopener noreferrer";
+export declare const LINK_TARGET = "_blank";

package/dist/controls/text/href.js

@@ -0,0 +1,48 @@
+// href.ts — the fleet's hyperlink SCHEME GATE (ADR-0114, SPEC-R8/R12; LLD-C1). DOM-free (no `document`
+// import — `base` is a parameter): the canonical home BOTH text.ts's component gate AND a2ui's static
+// validator (`conformance.ts`) import from, and the shared module a future feed-family `ui-attachment`
+// href leg reuses (ADR-0114's cross-family reconciliation) — one policy constant, every enforcement site
+// imports it rather than re-declaring it.
+//
+// Widening the scheme set is a ONE-LINE, gate-visible edit (ADR-0114 fork F1) — never a per-call-site
+// change. Do not rename any export: `SAFE_HREF_SCHEMES` / `safeHref` / `LINK_REL` / `LINK_TARGET` are the
+// frozen shape a concurrent build imports verbatim.
+/** The fleet scheme allowlist — ONE constant, imported by every enforcement site (the component gate +
+ *  the a2ui validator's first line). Widening it is a one-line, gate-visible edit (ADR-0114 fork F1). */
+export const SAFE_HREF_SCHEMES = ['https:', 'http:', 'mailto:'];
+/**
+ * The component gate (SPEC-R8, normative verdict procedure). Validates; NEVER rewrites — returns the
+ * author's string byte-identical on allow, `null` on deny OR no-destination:
+ *  - `raw.trim() === ''` → `null` (no destination — the default-`''`/whitespace self-link trap, SPEC-R8
+ *    AC7: `new URL('', base)` would otherwise mint a self-link, so this check runs BEFORE parsing).
+ *  - `new URL(raw, base)` throws → `null` (unparseable = denied, fail-closed).
+ *  - the resolved `url.protocol` is not in `SAFE_HREF_SCHEMES` → `null` (denied).
+ *  - else → `raw` (allowed — byte-identical, never rewritten; the anchor's own resolution equals this
+ *    parse by construction, since both resolve against the same `base`).
+ *
+ * Parsing with `new URL` is load-bearing (SPEC-R8): it applies the SAME control-character/whitespace
+ * normalizations navigation itself would, so `"java\nscript:…"` and `" JAVASCRIPT:…"` are denied as their
+ * normalized selves — a string-prefix check is non-conformant and would miss exactly this smuggling class.
+ *
+ * `base` is a parameter (the component passes `document.baseURI`) so this module stays DOM-free — the
+ * validator side reuses `SAFE_HREF_SCHEMES` without inheriting a `document` dependency.
+ */
+export function safeHref(raw, base) {
+    if (raw.trim() === '')
+        return null; // no destination — never parsed (the self-link trap)
+    let url;
+    try {
+        url = new URL(raw, base);
+    }
+    catch {
+        return null; // unparseable — denied, fail-closed
+    }
+    if (!SAFE_HREF_SCHEMES.includes(url.protocol))
+        return null; // denied scheme
+    return raw; // allowed — byte-identical, never rewritten
+}
+/** The fixed anchor policy (ADR-0114 fork F3 — no props at v1): component-set constants, applied ONLY
+ *  alongside an allowed `href`, never author-supplied. Exported alongside the gate so a future
+ *  `ui-attachment` href leg shares this one module instead of minting a second copy. */
+export const LINK_REL = 'noopener noreferrer';
+export const LINK_TARGET = '_blank';

package/dist/controls/text/text.css

@@ -0,0 +1,328 @@
+/* text.css — ui-text, the Display-class text primitive (ADR-0078, supersedes ADR-0025 cl.3/cl.3a's
+ * --ui-type-* single-axis ramp). Two clearly-SECTIONED blocks:
+ *
+ *   [1] TOKEN BLOCK  — `:where(ui-text)` (specificity 0,0,0) DECLARES the five `--ui-text-*` component
+ *       tokens from the fleet `--md-sys-typescale-{role}-{size}-*` scale (`@agent-ui-kit/shared/dimensions.css`).
+ *       Base = body-medium (`variant=body size=md`, the defaults). Then the 9×3 repoint matrix (cl.3): 8
+ *       ROLE blocks (`[variant='display']` → display-medium, one per non-body role at its size=md default)
+ *       + 18 SIZE-OVERRIDE blocks (`[variant='display'][size='lg']` → display-large, …; 9 roles × sm/lg).
+ *       Attribute-absence law: `variant`/`size` do NOT auto-reflect their default, so bare `<ui-text
+ *       size='lg'>` (no [variant] attribute) must ALSO hit the body row — the two body size-override
+ *       blocks below cover the `:not([variant])` case. `--ui-text-color` ties to the AA-gated surface-text
+ *       ink role. `:where()` keeps every repoint at specificity 0 — LATER declaration wins a tie, so this
+ *       file's ORDER (base → role → size-override → [emphasis]) is load-bearing: do not reorder the blocks
+ *       below. `[emphasis]` (ADR-0109, the fifth axis) is declared LAST — one line, `--ui-text-weight: 700`
+ *       (the platform bold register), beating every role/size-override row on the tie.
+ *   [2] STYLES BLOCK — `@scope (ui-text)` CONSUMES only `--ui-text-*` (font-size/-weight/line-height/
+ *       letter-spacing/color) plus the variant TREATMENTS (structural, not scale, opinions): uppercase for
+ *       kicker/overline, italic + a rule + an indent for quote, and the ADR-0078 cl.4 stamp-transparency
+ *       reset (the light-DOM stamp inherits all typography from the host, so `as` changes semantics with
+ *       zero geometry delta). `display: block`, `user-select: text`, and forced-colors stand unchanged.
+ *       ADR-0106 adds a fourth axis, `[truncate]` — two legs mirroring the stamp-reset's own two-legged
+ *       shape: the host leg (the 80% unstamped case) and a stamp leg (declared AFTER the stamp-
+ *       transparency reset so its overflow/text-overflow win the cascade on the shared selector surface)
+ *       — text-overflow/overflow must sit on whichever box holds the text; white-space: nowrap on the
+ *       host is enough on its own, it inherits into the stamp for free. ADR-0109's `emphasis` (the fifth
+ *       axis) needs ZERO styles-block change and no stamp leg — `font-weight` inherits, so the existing
+ *       `font-weight: var(--ui-text-weight)` declaration + the cl.4 stamp-transparency reset already carry
+ *       the [1]-block repoint into any stamped element for free.
+ *
+ *   The hyperlink capability (ADR-0114, SPEC-R13; LLD-C3) — the stamp-transparency reset's `:is()` gains
+ *   `a` (so an anchor stamp inherits typography/geometry, zero geometry delta — SPEC-R7 AC1); the link leg
+ *   is declared AFTER it, attribute-gated on `:scope > a[href]` — a DENIED stamp (no `href`) keeps prose
+ *   rendering, underline-free, by construction; the CSS needs no knowledge of the gate's verdict. Underline
+ *   is ALWAYS present, never hue-only (ADR-0057) — `--ui-text-link-ink` is the one new component token.
+ *
+ * Standalone stylesheet — linked via the host page / component-styles barrel (Phase 2); NEVER injected
+ * from text.ts (behaviour-only `.ts`, no runtime style injection — plan §2).
+ */
+
+/* ════════════════ [1] TOKEN BLOCK — :where(ui-text) declares --ui-text-* ════════════════ */
+
+:where(ui-text) {
+  --ui-text-quote-border: var(--md-sys-color-neutral-outline-variant); /* TKT-0066: was a direct role read in @scope */
+  /* Typography tokens — default = body-medium (variant=body, size=md). The role/size-override blocks
+     below repoint these five to the matching --md-sys-typescale-{role}-{size}-* row (cl.3's role-pure
+     seam). The component reads only --ui-text-* (never --md-sys-typescale-* directly), so a fleet
+     type-scale value change never touches the control logic. */
+  --ui-text-size: var(--md-sys-typescale-body-medium-size);
+  --ui-text-weight: var(--md-sys-typescale-body-medium-weight);
+  --ui-text-line-height: var(--md-sys-typescale-body-medium-line-height);
+  --ui-text-tracking: var(--md-sys-typescale-body-medium-tracking);
+  /* Color — the AA-gated surface-text ink role (the ONLY --md-sys-color-* role ui-text needs). */
+  --ui-text-color: var(--md-sys-color-neutral-on-surface);
+
+  /* TKT-0066 item 5 ruling: dimensional constants route through the own chain, never read raw in @scope. */
+  --ui-text-quote-pad: var(--md-sys-space-md); /* the ≈12px rhythm step — density-responsive, cl.2b */
+}
+
+/* ── 8 ROLE blocks (cl.3) — [variant] alone, at the size=md default (…-medium). body is the base above,
+   so it has none here; its size overrides (sm/lg) are covered in the size-override group below. ── */
+
+:where(ui-text[variant='display']) {
+  --ui-text-size: var(--md-sys-typescale-display-medium-size);
+  --ui-text-weight: var(--md-sys-typescale-display-medium-weight);
+  --ui-text-line-height: var(--md-sys-typescale-display-medium-line-height);
+  --ui-text-tracking: var(--md-sys-typescale-display-medium-tracking);
+}
+:where(ui-text[variant='headline']) {
+  --ui-text-size: var(--md-sys-typescale-headline-medium-size);
+  --ui-text-weight: var(--md-sys-typescale-headline-medium-weight);
+  --ui-text-line-height: var(--md-sys-typescale-headline-medium-line-height);
+  --ui-text-tracking: var(--md-sys-typescale-headline-medium-tracking);
+}
+:where(ui-text[variant='title']) {
+  --ui-text-size: var(--md-sys-typescale-title-medium-size);
+  --ui-text-weight: var(--md-sys-typescale-title-medium-weight);
+  --ui-text-line-height: var(--md-sys-typescale-title-medium-line-height);
+  --ui-text-tracking: var(--md-sys-typescale-title-medium-tracking);
+}
+:where(ui-text[variant='label']) {
+  --ui-text-size: var(--md-sys-typescale-label-medium-size);
+  --ui-text-weight: var(--md-sys-typescale-label-medium-weight);
+  --ui-text-line-height: var(--md-sys-typescale-label-medium-line-height);
+  --ui-text-tracking: var(--md-sys-typescale-label-medium-tracking);
+}
+:where(ui-text[variant='kicker']) {
+  --ui-text-size: var(--md-sys-typescale-kicker-medium-size);
+  --ui-text-weight: var(--md-sys-typescale-kicker-medium-weight);
+  --ui-text-line-height: var(--md-sys-typescale-kicker-medium-line-height);
+  --ui-text-tracking: var(--md-sys-typescale-kicker-medium-tracking);
+}
+:where(ui-text[variant='overline']) {
+  --ui-text-size: var(--md-sys-typescale-overline-medium-size);
+  --ui-text-weight: var(--md-sys-typescale-overline-medium-weight);
+  --ui-text-line-height: var(--md-sys-typescale-overline-medium-line-height);
+  --ui-text-tracking: var(--md-sys-typescale-overline-medium-tracking);
+}
+:where(ui-text[variant='quote']) {
+  --ui-text-size: var(--md-sys-typescale-quote-medium-size);
+  --ui-text-weight: var(--md-sys-typescale-quote-medium-weight);
+  --ui-text-line-height: var(--md-sys-typescale-quote-medium-line-height);
+  --ui-text-tracking: var(--md-sys-typescale-quote-medium-tracking);
+}
+:where(ui-text[variant='lead']) {
+  --ui-text-size: var(--md-sys-typescale-lead-medium-size);
+  --ui-text-weight: var(--md-sys-typescale-lead-medium-weight);
+  --ui-text-line-height: var(--md-sys-typescale-lead-medium-line-height);
+  --ui-text-tracking: var(--md-sys-typescale-lead-medium-tracking);
+}
+
+/* ── 18 SIZE-OVERRIDE blocks (cl.3) — 9 roles × {sm,lg}; declared AFTER the role blocks so a tied
+   specificity (:where() = 0) resolves to the override on declaration order. body's two covers ALSO match
+   the absent-[variant] case (:not([variant])) — the attribute-absence law. ── */
+
+:where(ui-text[variant='display'][size='sm']) {
+  --ui-text-size: var(--md-sys-typescale-display-small-size);
+  --ui-text-weight: var(--md-sys-typescale-display-small-weight);
+  --ui-text-line-height: var(--md-sys-typescale-display-small-line-height);
+  --ui-text-tracking: var(--md-sys-typescale-display-small-tracking);
+}
+:where(ui-text[variant='display'][size='lg']) {
+  --ui-text-size: var(--md-sys-typescale-display-large-size);
+  --ui-text-weight: var(--md-sys-typescale-display-large-weight);
+  --ui-text-line-height: var(--md-sys-typescale-display-large-line-height);
+  --ui-text-tracking: var(--md-sys-typescale-display-large-tracking);
+}
+:where(ui-text[variant='headline'][size='sm']) {
+  --ui-text-size: var(--md-sys-typescale-headline-small-size);
+  --ui-text-weight: var(--md-sys-typescale-headline-small-weight);
+  --ui-text-line-height: var(--md-sys-typescale-headline-small-line-height);
+  --ui-text-tracking: var(--md-sys-typescale-headline-small-tracking);
+}
+:where(ui-text[variant='headline'][size='lg']) {
+  --ui-text-size: var(--md-sys-typescale-headline-large-size);
+  --ui-text-weight: var(--md-sys-typescale-headline-large-weight);
+  --ui-text-line-height: var(--md-sys-typescale-headline-large-line-height);
+  --ui-text-tracking: var(--md-sys-typescale-headline-large-tracking);
+}
+:where(ui-text[variant='title'][size='sm']) {
+  --ui-text-size: var(--md-sys-typescale-title-small-size);
+  --ui-text-weight: var(--md-sys-typescale-title-small-weight);
+  --ui-text-line-height: var(--md-sys-typescale-title-small-line-height);
+  --ui-text-tracking: var(--md-sys-typescale-title-small-tracking);
+}
+:where(ui-text[variant='title'][size='lg']) {
+  --ui-text-size: var(--md-sys-typescale-title-large-size);
+  --ui-text-weight: var(--md-sys-typescale-title-large-weight);
+  --ui-text-line-height: var(--md-sys-typescale-title-large-line-height);
+  --ui-text-tracking: var(--md-sys-typescale-title-large-tracking);
+}
+:where(ui-text[variant='label'][size='sm']) {
+  --ui-text-size: var(--md-sys-typescale-label-small-size);
+  --ui-text-weight: var(--md-sys-typescale-label-small-weight);
+  --ui-text-line-height: var(--md-sys-typescale-label-small-line-height);
+  --ui-text-tracking: var(--md-sys-typescale-label-small-tracking);
+}
+:where(ui-text[variant='label'][size='lg']) {
+  --ui-text-size: var(--md-sys-typescale-label-large-size);
+  --ui-text-weight: var(--md-sys-typescale-label-large-weight);
+  --ui-text-line-height: var(--md-sys-typescale-label-large-line-height);
+  --ui-text-tracking: var(--md-sys-typescale-label-large-tracking);
+}
+:where(ui-text[variant='kicker'][size='sm']) {
+  --ui-text-size: var(--md-sys-typescale-kicker-small-size);
+  --ui-text-weight: var(--md-sys-typescale-kicker-small-weight);
+  --ui-text-line-height: var(--md-sys-typescale-kicker-small-line-height);
+  --ui-text-tracking: var(--md-sys-typescale-kicker-small-tracking);
+}
+:where(ui-text[variant='kicker'][size='lg']) {
+  --ui-text-size: var(--md-sys-typescale-kicker-large-size);
+  --ui-text-weight: var(--md-sys-typescale-kicker-large-weight);
+  --ui-text-line-height: var(--md-sys-typescale-kicker-large-line-height);
+  --ui-text-tracking: var(--md-sys-typescale-kicker-large-tracking);
+}
+:where(ui-text[variant='overline'][size='sm']) {
+  --ui-text-size: var(--md-sys-typescale-overline-small-size);
+  --ui-text-weight: var(--md-sys-typescale-overline-small-weight);
+  --ui-text-line-height: var(--md-sys-typescale-overline-small-line-height);
+  --ui-text-tracking: var(--md-sys-typescale-overline-small-tracking);
+}
+:where(ui-text[variant='overline'][size='lg']) {
+  --ui-text-size: var(--md-sys-typescale-overline-large-size);
+  --ui-text-weight: var(--md-sys-typescale-overline-large-weight);
+  --ui-text-line-height: var(--md-sys-typescale-overline-large-line-height);
+  --ui-text-tracking: var(--md-sys-typescale-overline-large-tracking);
+}
+:where(ui-text[variant='quote'][size='sm']) {
+  --ui-text-size: var(--md-sys-typescale-quote-small-size);
+  --ui-text-weight: var(--md-sys-typescale-quote-small-weight);
+  --ui-text-line-height: var(--md-sys-typescale-quote-small-line-height);
+  --ui-text-tracking: var(--md-sys-typescale-quote-small-tracking);
+}
+:where(ui-text[variant='quote'][size='lg']) {
+  --ui-text-size: var(--md-sys-typescale-quote-large-size);
+  --ui-text-weight: var(--md-sys-typescale-quote-large-weight);
+  --ui-text-line-height: var(--md-sys-typescale-quote-large-line-height);
+  --ui-text-tracking: var(--md-sys-typescale-quote-large-tracking);
+}
+:where(ui-text[variant='lead'][size='sm']) {
+  --ui-text-size: var(--md-sys-typescale-lead-small-size);
+  --ui-text-weight: var(--md-sys-typescale-lead-small-weight);
+  --ui-text-line-height: var(--md-sys-typescale-lead-small-line-height);
+  --ui-text-tracking: var(--md-sys-typescale-lead-small-tracking);
+}
+:where(ui-text[variant='lead'][size='lg']) {
+  --ui-text-size: var(--md-sys-typescale-lead-large-size);
+  --ui-text-weight: var(--md-sys-typescale-lead-large-weight);
+  --ui-text-line-height: var(--md-sys-typescale-lead-large-line-height);
+  --ui-text-tracking: var(--md-sys-typescale-lead-large-tracking);
+}
+/* body's pair ALSO matches a bare <ui-text size='sm'|'lg'> (no [variant] attribute — the absence law). */
+:where(ui-text[size='sm']:not([variant]), ui-text[variant='body'][size='sm']) {
+  --ui-text-size: var(--md-sys-typescale-body-small-size);
+  --ui-text-weight: var(--md-sys-typescale-body-small-weight);
+  --ui-text-line-height: var(--md-sys-typescale-body-small-line-height);
+  --ui-text-tracking: var(--md-sys-typescale-body-small-tracking);
+}
+:where(ui-text[size='lg']:not([variant]), ui-text[variant='body'][size='lg']) {
+  --ui-text-size: var(--md-sys-typescale-body-large-size);
+  --ui-text-weight: var(--md-sys-typescale-body-large-weight);
+  --ui-text-line-height: var(--md-sys-typescale-body-large-line-height);
+  --ui-text-tracking: var(--md-sys-typescale-body-large-tracking);
+}
+
+/* ── [emphasis] (ADR-0109, the fifth orthogonal axis) — declared LAST: :where() keeps every repoint at
+   specificity 0, so source order is what lets this one beat every role/size-override block above on a tie.
+   700 is the platform's bold register (the CSS `bold` keyword) — a platform constant, not a new fleet
+   token and not a typescale-row edit; no-ops honestly on kicker (already 700). ── */
+:where(ui-text[emphasis]) {
+  --ui-text-weight: 700;
+}
+
+/* ── The hyperlink capability (ADR-0114, LLD-C3) — the link ink role. Declared after [emphasis] (order
+   is not load-bearing here — this token is consumed only by the `a[href]` selector below, never by the
+   base :scope rule, so it cannot lose a specificity-0 tie against anything above). ── */
+:where(ui-text) {
+  --ui-text-link-ink: var(--md-sys-color-primary);
+}
+
+/* ════════════════ [2] STYLES BLOCK — @scope (ui-text) consumes ONLY --ui-text-* ════════════════ */
+
+@scope (ui-text) {
+  :scope {
+    display: block; /* a text primitive is a block element — lays out like <p>/<h*> */
+    font-size: var(--ui-text-size);
+    font-weight: var(--ui-text-weight);
+    line-height: var(--ui-text-line-height);
+    letter-spacing: var(--ui-text-tracking);
+    color: var(--ui-text-color);
+    /* user-select ENABLED — display text is selectable (the deliberate inverse of ui-button, which disables it) */
+    user-select: text;
+    /* NO block-size / padding-block / min-inline-size — Display class has no frame law (ADR-0025 cl.1) */
+  }
+
+  /* Editorial-extra TREATMENTS (cl.2b) — structural opinions, not scale; the four editorial roles each add
+     one on top of the token-driven size/weight/line-height/tracking above. */
+  :scope[variant='kicker'],
+  :scope[variant='overline'] {
+    text-transform: uppercase;
+  }
+  :scope[variant='quote'] {
+    font-style: italic;
+    border-inline-start: 3px solid var(--ui-text-quote-border);
+    padding-inline-start: var(--ui-text-quote-pad);
+  }
+
+  /* The stamp-transparency reset (ADR-0078 cl.4) — the `as` real element inherits ALL typography from the
+     host, so stamping/unstamping changes semantics with ZERO geometry delta (same rendered box either way,
+     asserted in the browser tests). Covers every tag `as` can stamp. */
+  :scope > :is(h1, h2, h3, h4, h5, h6, p, blockquote, span, a) {
+    margin: 0;
+    font: inherit;
+    letter-spacing: inherit;
+    color: inherit;
+  }
+
+  /* The hyperlink capability (ADR-0114, SPEC-R13; LLD-C3) — declared AFTER the stamp-transparency reset so
+     its `color`/`text-decoration` win the cascade on the shared `a` selector. Attribute-gated on `[href]`:
+     a DENIED stamp (no `href` — `#syncLink` never set one) keeps plain prose rendering; the CSS needs no
+     knowledge of the gate's verdict. Underline is ALWAYS present, never hue-only (ADR-0057). */
+  :scope > a[href] {
+    color: var(--ui-text-link-ink);
+    text-decoration-line: underline;
+    text-underline-offset: 0.15em;
+    text-decoration-thickness: from-font;
+  }
+  :scope > a[href]:hover {
+    text-decoration-thickness: 2px;
+  }
+  /* the fleet's shared focus treatment (ADR-0009) — the SAME ring every control draws, read directly from
+     the fleet tokens rather than repointed through the component chain (the button.css precedent). */
+  :scope > a[href]:focus-visible {
+    outline: var(--md-sys-state-focus-ring-width) solid var(--md-sys-color-focus-ring);
+    outline-offset: var(--md-sys-state-focus-ring-offset);
+  }
+  /* :visited shares the link ink at v1 — no visited role minted (SPEC-R13, stated not hidden). */
+
+  /* ADR-0106 — `[truncate]`, the fourth orthogonal axis: single-line + ellipsis, CSS-only (no
+     ResizeObserver, no clipped-state measurement — text.ts's unconditional `title` mirror is the reveal).
+     Two legs, the SAME two-legged shape as the stamp-transparency reset above: the host leg covers the 80%
+     unstamped case (`as="none"`); `white-space: nowrap` there is enough on its own — it inherits into the
+     stamp for free. The stamp leg re-applies `overflow`/`text-overflow` on whichever real element (h1…span)
+     is currently holding the text, since THAT box is what actually clips; it is declared after the
+     stamp-transparency reset above so it wins the shared-selector cascade. Toggling `as` under truncation
+     keeps the rendered box identical (the ADR-0078 cl.4 invariant extends to the clipped box). */
+  :scope[truncate] {
+    white-space: nowrap;
+    overflow: hidden;
+    text-overflow: ellipsis;
+  }
+  :scope[truncate] > :is(h1, h2, h3, h4, h5, h6, p, blockquote, span) {
+    overflow: hidden;
+    text-overflow: ellipsis;
+  }
+
+  /* forced-colors — keep the text visible (CanvasText maps to the platform high-contrast text ink) */
+  @media (forced-colors: active) {
+    :scope {
+      color: CanvasText;
+    }
+    /* the link keeps the platform's own link ink under forced-colors — underline survives above (SPEC-R13
+       AC2); LinkText is the system role every UA maps real anchors to, so this reads correctly even though
+       the stamp is a custom-element child, not a native navigation context. */
+    :scope > a[href] {
+      color: LinkText;
+    }
+  }
+}