@agent-ui-kit/components 0.0.3

package/dist/controls/timeline-item/timeline-item.js

@@ -0,0 +1,360 @@
+// timeline-item.ts — UITimelineItemElement, the timeline family's shared INERT visual atom
+// (timeline-family.lld.md §2 · SPEC-R1…R5 · ADR-0122 F1/F2/F3/F6; recursive nesting + the
+// collapsed-summary preview — ADR-0143 F1-F3/F7, TKT-0091). BEHAVIOUR + props + the control-built
+// marker/content/detail/nested anatomy + self-define ONLY. Anatomy/geometry per the LLD; styling lives
+// in timeline-item.css, the public contract in timeline-item.md.
+//
+// One rail row = a marker (dot/ring/pulse via CSS, OR a built-in check/x glyph, OR a consumer-slotted
+// marker) + the content roles (label · description · timestamp · trailing) + an optional collapsible
+// detail/nested pair. Inert: holds no transport, no live-region role, emits ONLY `toggle` (the composed
+// detail's own event — never a bespoke one). `internals.role = 'listitem'` is set in the CONSTRUCTOR
+// (the toast role precedent — semantics before insertion), extends `UIElement` (NOT form-associated).
+// Hosted by BOTH `ui-timeline` (durable) and `ui-status-stream` (live) — authored once, shared everywhere.
+//
+// Anatomy (#ensureAnatomy(), idempotent — ONCE, persists across reconnect, the toast/disclosure part-
+// persistence precedent): a `<span data-part="marker">` (dot/connector painted by timeline-item.css;
+// suppressed and replaced by a real glyph child when `icon` is set, a `[data-role="marker"]` consumer
+// child is present, or `status` is `done`/`error` — SPEC-R3/R4) + four content cells keyed by
+// `data-role` (`label`/`description`/`timestamp`/`trailing`). A pre-existing light-DOM child carrying one
+// of those `[data-role]`s is ADOPTED (kept, never cloned — ADR-0022) and marked consumer-owned so
+// `#renderContent()` never stamps over it (the adia wrapper-trap regression this build guards against);
+// otherwise a fresh cell is created and the reactive effect stamps it from the matching prop. `trailing`
+// has no prop source by default — it is consumer-content-only UNLESS the collapsed-summary preview
+// auto-fills it (ADR-0143 F3, below), which backs off the instant a consumer adopts it themselves.
+//
+// A pre-existing `[data-role="detail"]` AND/OR `[data-role="nested"]` child are moved into ONE shared
+// composed `ui-disclosure` (§2.3, ADR-0143 F1/F2) — NOT a bespoke caret+hidden reimplementation, and NOT
+// two independent disclosures: `detail` (free consumer content) is appended first, `nested` (a genuine
+// `<ui-timeline>` child — ADR-0143 F1, reusing `ui-timeline` itself rather than inventing a second
+// nesting primitive) second, into the SAME disclosure host, which materializes only when either exists.
+// A LIVE host (ui-status-stream's grouping, ADR-0146 F5) that needs a nested slot on an ALREADY-connected
+// item calls `ensureNestedSlot(factory)` — the ONE public method the ADR-0143 2026-07-18 amendment adds
+// (Kim's narrow, additive exception): it composes the EXACT SAME disclosure + nested slot + preview
+// mechanism lazily, on first call, instead of eagerly at connect. Dead code for the authored-markup case.
+// Recursion is authored-markup depth, not runtime-generated: a nested item can carry its OWN
+// `[data-role="nested"]` child, arbitrary levels deep, with zero extra code — `ui-timeline`'s own
+// `#markLastItem()` is already `:scope > ui-timeline-item`-scoped (verified against source, ADR-0143's
+// own finding), so a nested timeline's terminal-connector marking self-scopes per level with NO change
+// here; likewise `size` never cascades into a nested `<ui-timeline>` (ADR-0143 F7) — each level reads
+// its OWN `[size]` attribute, no forwarding mechanism exists or is added.
+// `this.append(marker, ...cells, [disclosure])` re-parents every node (fresh or adopted) into anatomy
+// order in one call — `Node.append` on an already-connected child simply repositions it, so adoption and
+// creation are handled uniformly by one assembly line.
+//
+// The marker glyph (#renderMarkerGlyph(), a SEPARATE effect from content — status/icon changes should
+// never re-stamp label/description/timestamp, and vice versa): a consumer-adopted `[data-role="marker"]`
+// child is NEVER touched. Otherwise: `icon` non-empty wins (F3, "a free marker coexists with status,
+// orthogonal") — `resolveIcon(icon)` is injected and tagged `data-role="marker"` so the SAME CSS
+// suppression rule fires; else a resolved-outcome `status` (`done`/`error`/`warning`, ADR-0146 F7) injects
+// its built-in glyph (`check`/`x`/`warning` — @agent-ui-kit/icons, already fleet-adopted; disclosure's chevron
+// / toast's close-x precedent) tagged the same way, each a DISTINCT shape (ADR-0057: warning's triangle is
+// never error's `x` recoloured); else (`''`/`pending`/`active`) the marker is cleared and CSS
+// `::before`/`::after` paint the dot/ring/pulse — the non-color SHAPE signifier (ADR-0057, SPEC-R4).
+//
+// The collapsed-summary preview (#renderTrailingPreview(), ADR-0143 F3): when `[data-role="nested"]`
+// content exists, a `MutationObserver` on that nested subtree tracks the LAST `<ui-timeline-item>` in
+// DOM order — recursing to the deepest leaf when THAT item itself nests further (last child wins, no
+// status-priority, matching the ticket's own resolved rule) — and a reactive effect reads the shared
+// disclosure's own `open` prop (a DIFFERENT element's reactive signal; reading it inside `this.effect()`
+// still tracks it — signals are not scoped to their declaring element) to gate whether the resolved
+// label+status is PAINTED into the item's own EXISTING `trailing` cell (closed) or left untouched
+// (open, where the real nested content is already visible — no duplicate). `trailing` remains
+// `#consumerOwned`-gated exactly as today: a consumer-authored `[data-role="trailing"]` child is NEVER
+// overwritten by this effect, at any open/closed state.
+//
+// `controls → dom + controls/disclosure/disclosure.ts + @agent-ui-kit/icons` — the allowed import direction
+// (cross-control, the segmented-control/radio + disclosure/icons precedents). The nested slot's content
+// is treated as generic `Element`/DOM (querySelector/MutationObserver/attributes only) — never importing
+// `ui-timeline`'s own module or type, so no `timeline-item → timeline → timeline-item` cycle is created
+// (timeline.ts already imports timeline-item.ts for registration).
+import { UIElement, prop } from "../../dom/index.js";
+import "../disclosure/disclosure.js"; // the collapse mechanism (F6) — composed, not reinvented
+import { resolveIcon } from '@agent-ui-kit/icons';
+const STATUS = ['', 'pending', 'active', 'done', 'error', 'warning'];
+const SIZE = ['sm', 'md', 'lg'];
+// The resolved-outcome states that inject a built-in marker glyph (the in-progress '' / pending / active
+// states paint a pure-CSS dot/ring/pulse instead). `warning` (ADR-0146 F7) joins done/error here with its
+// OWN distinct triangle-exclamation glyph — shape-coded, never hue-alone (ADR-0057): the shape alone,
+// never the colour, distinguishes warning from error's `x`.
+const STATUS_GLYPH = { done: 'check', error: 'x', warning: 'warning' };
+// A GROUP item's OWN glyph set (an item hosting a nested sub-timeline, `#nested` — ADR-0146 F5) — the
+// Figma "Claude Code Gateway" reasoning-chain card (node 21:1641-1643): a card-level marker reads as a
+// distinct, prominent status glyph (a spinning ring while working, a circled check when done, a circled
+// X on error), never the small plain dot/bare-check/cross a LEAF step's marker uses. `error` gets its OWN
+// `x-circle` glyph, NOT `warning`'s triangle reused (component-review finding, ADR-0057): the two states
+// must stay SHAPE-distinct, not ink-hue-distinct only, the same law the leaf glyph set already honors —
+// reusing `warning`'s shape for `error` at the group level would make them distinguishable by colour alone.
+const GROUP_STATUS_GLYPH = { active: 'circle-notch', done: 'check-circle', error: 'x-circle', warning: 'warning' };
+const props = {
+    // reflected (SPEC-R2 AC2: a JS-set status/size round-trips through getAttribute) — the LLD's frozen
+    // interface names the constructors; the CSS [status]/[size] repoint (and the AC2 round-trip itself)
+    // requires `reflect: true`, the container.ts/disclosure.ts convention for every attribute-selector-driven prop.
+    status: { ...prop.enum(STATUS, ''), reflect: true }, // '' = neutral marker (F3)
+    label: { ...prop.string(''), reflect: true },
+    description: prop.string(''),
+    timestamp: prop.string(''), // the consumer's string — NO codec (F6)
+    icon: prop.string(''), // a marker glyph name replacing the dot (adia icon-mode)
+    size: { ...prop.enum(SIZE, 'md'), reflect: true }, // first-class geometry (F2)
+};
+const CONTENT_ROLES = ['label', 'description', 'timestamp', 'trailing'];
+const STAMPED_ROLES = new Set(['label', 'description', 'timestamp']);
+export class UITimelineItemElement extends UIElement {
+    static props = props;
+    // The control-built parts — created ONCE (idempotent guard in #ensureAnatomy); persist through
+    // disconnect/reconnect (the toast/disclosure precedent). `#`-private: nothing outside can observe them.
+    #marker = null;
+    #cells = new Map();
+    #consumerOwned = new Set(); // roles adopted from a pre-existing consumer child — never stamped
+    #consumerMarker = false; // a consumer supplied a [data-role="marker"] child at connect — the item's own glyph logic backs off entirely
+    #disclosure = null;
+    #nested = null; // the adopted [data-role="nested"] child (ADR-0143 F1 — a genuine <ui-timeline>, treated as generic DOM)
+    #nestedObserver = null; // recomputes the collapsed-summary preview on any change to #nested's subtree
+    constructor() {
+        super();
+        this.internals.role = 'listitem'; // set in the CONSTRUCTOR (the toast role precedent) — semantics before insertion
+    }
+    connected() {
+        this.#ensureAnatomy(); // idempotent, ONCE (the toast/modal/disclosure part-persistence guard)
+        this.effect(() => this.#renderContent()); // re-stamps label/description/timestamp on prop change
+        this.effect(() => this.#renderMarkerGlyph()); // re-paints the marker glyph on status/icon change — a SEPARATE effect
+        if (this.#nested) {
+            this.#nestedObserver = new MutationObserver(() => this.#renderTrailingPreview());
+            this.#nestedObserver.observe(this.#nested, { subtree: true, childList: true, attributes: true, attributeFilter: ['status', 'label'], characterData: true });
+            // Reads `this.#disclosure!.open` — a DIFFERENT element's reactive prop — so this effect re-runs on
+            // every open/close (ADR-0143 F3's paint gate) in addition to every observer-triggered recompute above.
+            this.effect(() => this.#renderTrailingPreview());
+        }
+    }
+    disconnected() {
+        this.#nestedObserver?.disconnect();
+        this.#nestedObserver = null;
+    }
+    /** Reveal/collapse the detail region (used by ui-status-stream's update({detail})); no-op if no detail. */
+    toggleDetail(open) {
+        const disclosure = this.#disclosure;
+        if (!disclosure)
+            return;
+        disclosure.open = open ?? !disclosure.open;
+    }
+    /**
+     * ADR-0146 F5 (the ADR-0143 2026-07-18 amendment — Kim's narrow, additive exception) — LAZILY ensure a
+     * `[data-role="nested"]` slot exists on an ALREADY-CONNECTED item, for ui-status-stream's GROUPED entries.
+     * Returns the nested host, composing it into the SAME shared `ui-disclosure` `#ensureAnatomy()` uses at
+     * connect (ADR-0143 F1/F2) — never a second nesting mechanism (the family-coherence law the amendment
+     * preserves). The collapsed-summary preview + its `MutationObserver` (ADR-0143 F3) are armed here EXACTLY as
+     * `connected()` arms them for an authored nested slot, so the group's collapse + preview work with ZERO
+     * bespoke nesting code. This is the ONLY new public surface the amendment adds; it is a dead code path for
+     * the durable authored-markup host (which composes `nested` eagerly at connect) — a live host is its sole
+     * caller. `factory` mints the host (ui-status-stream passes a fresh `<ui-timeline>`) so THIS file stays
+     * import-free of `ui-timeline` (the cycle guard, file header). Idempotent: a second call returns the
+     * existing slot untouched. Must run while connected — it registers a scope-owned effect (`this.effect`
+     * throws outside the connected lifetime); ui-status-stream only calls it on an item already appended live.
+     */
+    ensureNestedSlot(factory) {
+        if (this.#nested)
+            return this.#nested;
+        const nested = factory();
+        nested.setAttribute('data-role', 'nested');
+        if (this.#disclosure) {
+            // The item already composed a disclosure (it was authored WITH `detail`) — append `nested` onto the
+            // disclosure host; its own childList heal observer (disclosure.ts `#heal`) relocates it into the body
+            // part (the ADR-0143 F2 two-hop adoption, just deferred to first-group time).
+            this.#disclosure.appendChild(nested);
+        }
+        else {
+            // No disclosure yet — compose one, adopting `nested` BEFORE the disclosure connects so its own
+            // `#ensureParts()` moves it into the body SYNCHRONOUSLY (the exact composition `#ensureAnatomy` runs at
+            // connect, deferred to the moment the first grouped child arrives).
+            const disclosure = document.createElement('ui-disclosure');
+            disclosure.setAttribute('data-part', 'detail');
+            disclosure.appendChild(nested);
+            this.#disclosure = disclosure;
+            this.append(disclosure);
+        }
+        this.#nested = nested;
+        // Re-evaluate the marker glyph NOW — this item just became a group parent, and GROUP_STATUS_GLYPH
+        // (#renderMarkerGlyph) only applies once `#nested` is set. The reactive effect that normally drives
+        // this reruns on a status/icon CHANGE, which may not happen at the moment nesting begins (a status
+        // unchanged by the new child's escalation would leave the OLD leaf-style glyph painted).
+        this.#renderMarkerGlyph();
+        // Arm the preview observer + paint-gate effect exactly as `connected()` does for an authored nested slot
+        // (ADR-0143 F3). On a later disconnect/reconnect, `connected()` re-arms both because `#nested` is now set
+        // — so the lazily-mounted slot survives reconnect identically to an authored one.
+        this.#nestedObserver = new MutationObserver(() => this.#renderTrailingPreview());
+        this.#nestedObserver.observe(nested, { subtree: true, childList: true, attributes: true, attributeFilter: ['status', 'label'], characterData: true });
+        this.effect(() => this.#renderTrailingPreview());
+        return nested;
+    }
+    /** Mark/unmark this item TRUNCATED — ui-status-stream's completion invariant (SPEC-R11): a distinct,
+     *  non-color-only interrupted affordance via a real custom state (`:state(truncated)` in CSS), never a
+     *  silent forever-spinner. `internals.states` is optional-chained (absent in jsdom, the fleet convention —
+     *  button.ts/checkbox.ts/text-field.ts). Imperative/CSS-state, not a `static props` field (LLD §7/§8). */
+    markTruncated(truncated) {
+        if (truncated)
+            this.internals.states?.add('truncated');
+        else
+            this.internals.states?.delete('truncated');
+    }
+    /**
+     * Build the light-DOM anatomy ONCE (idempotent — the toast/disclosure part-persistence precedent).
+     * Pre-existing `[data-role]` children are ADOPTED (kept in place, marked consumer-owned); everything
+     * else is created fresh. `this.append(...)` re-parents every node — adopted or fresh — into the final
+     * anatomy order in one call (a no-op reposition for an already-connected child, ADR-0022's move
+     * semantics via the platform's own `Node.append`).
+     */
+    #ensureAnatomy() {
+        if (this.#marker)
+            return;
+        const marker = document.createElement('span');
+        marker.setAttribute('data-part', 'marker');
+        const consumerMarker = this.querySelector(':scope > [data-role="marker"]');
+        if (consumerMarker) {
+            marker.appendChild(consumerMarker); // adopted, moved (ADR-0022)
+            this.#consumerMarker = true;
+        }
+        for (const role of CONTENT_ROLES) {
+            const existing = this.querySelector(`:scope > [data-role="${role}"]`);
+            if (existing instanceof HTMLElement) {
+                this.#cells.set(role, existing); // adopted in place — the wrapper-trap guard: never re-stamped
+                this.#consumerOwned.add(role);
+            }
+            else {
+                const cell = document.createElement('span');
+                cell.setAttribute('data-role', role);
+                this.#cells.set(role, cell);
+            }
+        }
+        // ONE shared disclosure adopts detail THEN nested, in that order (ADR-0143 F1/F2) — materializes
+        // only when either exists; an item with neither composes no disclosure at all (unchanged from today).
+        const detailContent = this.querySelector(':scope > [data-role="detail"]');
+        const nestedContent = this.querySelector(':scope > [data-role="nested"]');
+        if (detailContent || nestedContent) {
+            const disclosure = document.createElement('ui-disclosure');
+            disclosure.setAttribute('data-part', 'detail');
+            if (detailContent)
+                disclosure.appendChild(detailContent); // moved (ADR-0022)
+            if (nestedContent instanceof HTMLElement) {
+                disclosure.appendChild(nestedContent); // moved (ADR-0022) — the SAME two-hop adoption `detail` already used
+                this.#nested = nestedContent;
+            }
+            this.#disclosure = disclosure;
+            // NO re-emit — the composed ui-disclosure's own `toggle` (bubbles+composed, element.ts's `emit()`)
+            // already surfaces on the item host via natural light-DOM bubbling (the SAME event object, not a
+            // second one); an explicit re-emit here would double-fire. Allowlisted, no new event name (F6).
+        }
+        this.append(marker, ...CONTENT_ROLES.map((r) => this.#cells.get(r)), ...(this.#disclosure ? [this.#disclosure] : []));
+        this.#marker = marker;
+    }
+    /**
+     * ADR-0143 F3 — resolve the LAST `<ui-timeline-item>` in DOM order under `#nested`, recursing to the
+     * deepest leaf when that item itself carries a further `[data-role="nested"]` child (last child wins,
+     * no status-priority — the ticket's own resolved rule). Returns `null` when `#nested` has no items yet
+     * (a plain no-op source, never an error). Pure DOM traversal — `#nested`'s content is never assumed to
+     * be a real `<ui-timeline>` beyond "an element whose direct children may be `ui-timeline-item`s."
+     */
+    #resolveLastDescendant(root) {
+        const items = root.querySelectorAll(':scope > ui-timeline-item');
+        const last = items[items.length - 1];
+        if (!(last instanceof HTMLElement))
+            return null;
+        // NOT :scope-restricted to a DIRECT child: by the time this runs, `last`'s OWN connected() may already
+        // have moved its [data-role="nested"] child into its composed <ui-disclosure data-part="detail"> body
+        // (connectedCallback fires parent-before-child on a bulk insert, but this resolution runs from a
+        // deferred effect, which fires after the whole subtree's synchronous connect pass — so a deeper item can
+        // already be relocated). The second branch below still finds it as a direct child of the disclosure's
+        // OWN `[data-part="body"]` — narrower than a bare subtree query, so a consumer who (misusing the
+        // reserved `nested` role) plants `[data-role="nested"]` somewhere inside free-form `detail` prose is
+        // never mistaken for `last`'s real nested slot.
+        const deeper = last.querySelector(':scope > [data-role="nested"], :scope > [data-part="detail"] [data-part="body"] > [data-role="nested"]');
+        if (deeper instanceof HTMLElement) {
+            const recursed = this.#resolveLastDescendant(deeper);
+            if (recursed)
+                return recursed;
+        }
+        return last;
+    }
+    /** The SAME text-based, non-color status-shape glyph the fleet already uses elsewhere for a compact
+     *  inline status echo (the agent-admin client-message-echo precedent) — a distinct SHAPE per status,
+     *  never color alone (ADR-0057), with no new CSS/icon-injection machinery for a one-line preview cell. */
+    #previewGlyph(status) {
+        if (status === 'done')
+            return '✓ ';
+        if (status === 'error')
+            return '✕ ';
+        if (status === 'warning')
+            return '▲ '; // ADR-0146 F7 — a distinct SHAPE (a triangle), never hue alone (ADR-0057)
+        if (status === 'active')
+            return '● ';
+        if (status === 'pending')
+            return '○ ';
+        return '';
+    }
+    /**
+     * ADR-0143 F3 — the collapsed-summary paint gate: while the shared disclosure is CLOSED (or absent —
+     * a no-op then, since there is nothing to summarize), paint the resolved last-descendant's status-shape
+     * glyph + label into the item's OWN `trailing` cell, unless a consumer has adopted `trailing`
+     * themselves (`#consumerOwned`, checked exactly as `#renderContent()` already does — never overwritten).
+     * While OPEN, clear the auto-fill (the real nested content is already visible; no duplicate). A no-op
+     * entirely when `#nested` is absent.
+     */
+    #renderTrailingPreview() {
+        const nested = this.#nested;
+        if (!nested)
+            return;
+        const trailing = this.#cells.get('trailing');
+        if (!trailing || this.#consumerOwned.has('trailing'))
+            return;
+        const isOpen = this.#disclosure?.open ?? false;
+        if (isOpen) {
+            trailing.textContent = '';
+            return;
+        }
+        const last = this.#resolveLastDescendant(nested);
+        trailing.textContent = last ? `${this.#previewGlyph(last.getAttribute('status') ?? '')}${last.getAttribute('label') ?? ''}` : '';
+    }
+    /** Stamp label/description/timestamp from props onto their cells — SKIPPING any consumer-owned cell
+     *  (the wrapper-trap regression: a wrapped consumer child must suppress the default stamp, not duplicate). */
+    #renderContent() {
+        for (const role of STAMPED_ROLES) {
+            if (this.#consumerOwned.has(role))
+                continue;
+            this.#cells.get(role).textContent = this[role];
+        }
+    }
+    /** Paint the marker glyph: a consumer-adopted marker is untouched; `icon` wins over `status`; `done`/
+     *  `error` get a built-in glyph; everything else clears to let CSS `::before`/`::after` paint the
+     *  dot/ring/pulse (SPEC-R4). Every injected glyph is tagged `data-role="marker"` so ONE CSS suppression
+     *  rule (`:has([data-role="marker"])`) fires uniformly for consumer/icon/status-glyph markers alike. */
+    /** Inject `name` as the marker glyph, tagged the way BOTH resolution paths below need it (`data-role`
+     *  for the shared plain-dot suppression rule, `data-glyph` for the CSS spin-animation hook) — a single
+     *  paint site so the icon-prop path and the status/group path can never silently diverge on how an
+     *  injected glyph is tagged (code-review finding: the two branches had drifted into a hand-duplicated
+     *  4-line block each, already edited in lockstep once for `data-glyph`). */
+    #paintMarkerGlyph(name) {
+        const marker = this.#marker;
+        const svg = resolveIcon(name);
+        svg.setAttribute('data-role', 'marker');
+        svg.setAttribute('data-glyph', name);
+        marker.replaceChildren(svg);
+    }
+    #renderMarkerGlyph() {
+        const marker = this.#marker;
+        if (!marker || this.#consumerMarker)
+            return;
+        if (this.icon !== '') {
+            this.#paintMarkerGlyph(this.icon);
+            return;
+        }
+        // A group parent (`#nested` set — ADR-0146 F5) reads its OWN glyph set (GROUP_STATUS_GLYPH); a leaf
+        // step keeps the existing STATUS_GLYPH (bare check/x) + CSS dot/ring/pulse fallback.
+        const glyphMap = this.#nested ? GROUP_STATUS_GLYPH : STATUS_GLYPH;
+        const glyph = glyphMap[this.status];
+        if (glyph !== undefined) {
+            this.#paintMarkerGlyph(glyph);
+            return;
+        }
+        marker.replaceChildren(); // '' / pending / active(leaf) — pure CSS paints the dot/ring/pulse
+    }
+}
+if (!customElements.get('ui-timeline-item'))
+    customElements.define('ui-timeline-item', UITimelineItemElement);

package/dist/controls/toast/toast-region.css

@@ -0,0 +1,56 @@
+/* toast-region.css — ui-toast-region, the single-file component stylesheet (ADR-0003; feed-family.
+ * lld.md LLD-C8 · SPEC-R12). Two clearly-SECTIONED blocks:
+ *
+ *   [1] TOKEN BLOCK — `:where(ui-toast-region)` declares the `--ui-toast-region-*` chain: `inset`
+ *       (block-end/inline-end fixed inset off `--md-sys-space-lg`) + `gap` (the inter-toast stacking gap
+ *       off `--md-sys-space-sm`). No surface/radius/colour tokens AT ALL — the region paints NOTHING of
+ *       its own (LLD-C8; the ui-form-provider "layout, no colour voice" precedent) — each `ui-toast`
+ *       child supplies its own surface.
+ *   [2] STYLES BLOCK — `@scope (ui-toast-region)` consumes ONLY `--ui-toast-region-*`. The host IS
+ *       its own Popover-API top-layer element (`popover="manual"`, set in toast-region.ts) — the
+ *       `:popover-open` state selector overrides the UA's default popover centering with a
+ *       block-end/inline-end anchored FIXED position, then lays its `ui-toast` children out as a
+ *       normal-flow flex column (oldest→newest, top→bottom — newest nearest the block-end inset edge,
+ *       zero JS positioning; logical properties mirror RTL for free). `pointer-events: none` on the
+ *       empty region area means it never intercepts page clicks (SPEC-R12) — re-enabled per-toast so
+ *       each card (and its affordances) stays fully interactive.
+ *
+ * Standalone stylesheet — linked via the host page / component-styles barrel; NEVER injected from
+ * toast-region.ts (behaviour-only `.ts`, no runtime style injection — plan §2).
+ */
+
+/* ══════════ [1] TOKEN BLOCK — :where(ui-toast-region) declares --ui-toast-region-* ══════════ */
+
+:where(ui-toast-region) {
+  --ui-toast-region-inset: var(--md-sys-space-lg); /* block-end/inline-end fixed inset off the shell ramp */
+  --ui-toast-region-gap: var(--md-sys-space-sm); /* the inter-toast stacking gap */
+}
+
+/* ══════════ [2] STYLES BLOCK — @scope (ui-toast-region) consumes ONLY --ui-toast-region-* ══════════ */
+
+@scope (ui-toast-region) {
+  /* The host IS the popover (not a separate part) — override the UA's default popover centering with
+     a block-end/inline-end anchored fixed position once it enters the top layer. */
+  :scope:popover-open {
+    position: fixed;
+    inset: auto; /* clear the UA popover default before setting the two edges below */
+    inset-block-end: var(--ui-toast-region-inset);
+    inset-inline-end: var(--ui-toast-region-inset);
+
+    display: flex;
+    flex-direction: column; /* normal-flow stacking: oldest→newest, top→bottom (SPEC-R12 AC3) */
+    gap: var(--ui-toast-region-gap);
+
+    margin: 0;
+    border: 0;
+    padding: 0;
+    background: transparent; /* the region paints nothing of its own — each ui-toast is its own surface */
+    overflow: visible;
+
+    pointer-events: none; /* the empty region area never intercepts page clicks (SPEC-R12) */
+  }
+
+  :scope:popover-open > ui-toast {
+    pointer-events: auto; /* re-enabled per-toast — each card stays fully interactive */
+  }
+}

package/dist/controls/toast/toast-region.d.ts

@@ -0,0 +1,20 @@
+import { UIElement } from '../../dom/index.js';
+import { UIToastElement } from './toast.js';
+/** The `show()` input — a bare string shorthand normalizes to `{ message }`. */
+export interface ToastOptions {
+    message: string;
+    urgent?: boolean;
+    duration?: number;
+    action?: string;
+}
+export declare class UIToastRegionElement extends UIElement {
+    #private;
+    static props: {};
+    protected connected(): void;
+    protected disconnected(): void;
+    /**
+     * Create and show a toast (SPEC-R13). See the class doc for the full sequence. Throws if the region
+     * is not connected — a dev error, never a silent queue (ledger #10).
+     */
+    show(options: ToastOptions | string): UIToastElement;
+}

package/dist/controls/toast/toast-region.js

@@ -0,0 +1,113 @@
+// toast-region.ts — UIToastRegionElement, the top-layer host `ui-toast` instances stack inside
+// (feed-family.lld.md LLD-C8 · SPEC-R12/R13/R17 · ADR-0112 fork F1/F2). BEHAVIOUR + the `show()`
+// convenience + self-define ONLY; stacking geometry lives in toast-region.css, the public contract in
+// toast-region.md. Same folder as toast.ts (the radio/radio-group same-folder precedent) — NOT its own
+// package. NOT catalogued (ADR-0112 cl.6).
+//
+// Surface (fork F1): a platform `popover="manual"` attribute (set on the HOST at connect if absent —
+// a platform attribute, never ARIA) rides the top layer above ANY page stacking context — a completion
+// arriving while a modal is open must still show — while toasts stack inside via plain CSS flex/gap,
+// zero JS positioning (unlike the overlay-controller's anchored popups, this region has no anchor to
+// measure against). A childList `MutationObserver` drives visibility off child COUNT: ≥1 ⇒
+// showPopover() (guarded by a local `#isOpen` flag — the overlay.ts open()/close() idiom, jsdom-safe
+// since `:popover-open` matching is unavailable there); 0 ⇒ hidePopover() (SPEC-R12 AC1).
+//
+// Ownership (fork F2, "the ownership ruling" — feed-family.lld.md §5, resolved not left open): v1
+// ownership is CONSUMER-mounted — a page/app-shell declares `<ui-toast-region>` and holds the reference
+// it calls `show()` on. NO static singleton exists anywhere (ADR-0082's per-instance isolation); the
+// app-shell does NOT compose a default region this wave (a scope allocation inside F2's ratified
+// architecture, not a new fork — no ADR owed).
+//
+// `show()` (SPEC-R13): normalizes a string shorthand to `{ message }`, creates a `<ui-toast>`, assigns
+// urgent/duration/action, sets its message text BEFORE append (announcement-correct — SPEC-R15 AC2's
+// pre-insertion role covers the live-region HALF; this covers the CONTENT half), re-asserts top-layer
+// order (SPEC-R12 AC2 — a completion arriving while a LATER modal is open still paints above it:
+// hidePopover();showPopover() back-to-back, synchronous, one frame, no focus implications — manual
+// popovers never hold focus), appends, and returns the element. Throws on a disconnected region (a dev
+// error, never a silent queue — ledger #10).
+//
+// `controls → dom + controls/toast/toast.ts` — the allowed import direction (same-folder sibling).
+import { UIElement } from "../../dom/index.js";
+import { UIToastElement } from "./toast.js";
+export class UIToastRegionElement extends UIElement {
+    // EMPTY by design — placement is tokens in v1 (a `placement` prop is the named foreseen extension,
+    // LLD-C8). Present (not omitted) for the fleet convention + the descriptor trip-wire's empty
+    // bijection (the ui-form-provider precedent).
+    static props = {};
+    #isOpen = false;
+    #observer = null;
+    connected() {
+        if (!this.hasAttribute('popover'))
+            this.setAttribute('popover', 'manual'); // a platform attribute, never ARIA
+        this.#observer = new MutationObserver(() => this.#syncVisibility());
+        this.#observer.observe(this, { childList: true });
+        this.#syncVisibility(); // seed from any children already present (declarative markup)
+    }
+    disconnected() {
+        this.#observer?.disconnect();
+        this.#observer = null;
+        this.#isOpen = false;
+    }
+    /**
+     * Create and show a toast (SPEC-R13). See the class doc for the full sequence. Throws if the region
+     * is not connected — a dev error, never a silent queue (ledger #10).
+     */
+    show(options) {
+        if (!this.isConnected)
+            throw new Error('ui-toast-region: show() called while disconnected');
+        const opts = typeof options === 'string' ? { message: options } : options;
+        const toast = document.createElement('ui-toast');
+        if (opts.urgent !== undefined)
+            toast.urgent = opts.urgent;
+        if (opts.duration !== undefined)
+            toast.duration = opts.duration;
+        if (opts.action !== undefined)
+            toast.action = opts.action;
+        toast.textContent = opts.message; // BEFORE append — announcement-correct (SPEC-R13)
+        this.#reassertTopLayer();
+        this.appendChild(toast);
+        return toast;
+    }
+    #syncVisibility() {
+        if (this.childElementCount > 0)
+            this.#show();
+        else
+            this.#hide();
+    }
+    #show() {
+        if (this.#isOpen)
+            return;
+        this.#isOpen = true;
+        this.showPopover();
+    }
+    #hide() {
+        if (!this.#isOpen)
+            return;
+        this.#isOpen = false;
+        try {
+            this.hidePopover();
+        }
+        catch {
+            // already hidden — nothing more to do (a platform-drift guard, the overlay.ts idiom)
+        }
+    }
+    /**
+     * SPEC-R12 AC2 — when already open, re-enter the top layer so a completion arriving while a LATER
+     * modal is open still paints above it. A no-op when not currently open (the first-ever show path,
+     * where the childList observer's own showPopover() call — triggered by the append below — is the
+     * one that actually opens the region).
+     */
+    #reassertTopLayer() {
+        if (!this.#isOpen)
+            return;
+        try {
+            this.hidePopover();
+        }
+        catch {
+            // already hidden — proceed to re-show regardless
+        }
+        this.showPopover();
+    }
+}
+if (!customElements.get('ui-toast-region'))
+    customElements.define('ui-toast-region', UIToastRegionElement);

package/dist/controls/toast/toast.css

@@ -0,0 +1,96 @@
+/* toast.css — ui-toast, the single-file component stylesheet (ADR-0003; feed-family.lld.md LLD-C7 ·
+ * SPEC-R14/R15/R19). Two clearly-SECTIONED blocks:
+ *
+ *   [1] TOKEN BLOCK — `:where(ui-toast)` (specificity 0,0,0) declares the `--ui-toast-*` chain: a
+ *       FIXED `--ui-toast-inline-size` (20em — a notification card is not a control on the height
+ *       ramp; `max-inline-size: 100%` floors small viewports) + the surface roles (neutral
+ *       surface-brightest / outline / an inline elevation shadow). No `[variant]`/`[size]` repoint —
+ *       toast carries neither axis (SPEC-R19; a `[size]` selector would need a declared `size`
+ *       attribute — family-coherence A2b).
+ *   [2] STYLES BLOCK — `@scope (ui-toast)` consumes ONLY `--ui-toast-*` (∪ the shared `--md-sys-space-*`/
+ *       `--md-sys-shape-corner-base` shell-spacing tokens, the ui-menu panel precedent). A three-column grid
+ *       (`1fr auto auto` — message | action | close) laid out by the control-built parts in toast.ts;
+ *       `[data-part='message']` gets `min-inline-size: 0` (the flex/grid text-overflow floor — an
+ *       unbounded message must not blow out the fixed card width) + `overflow-wrap: anywhere` (an
+ *       unbroken token, e.g. a URL, must wrap inside the fixed inline-size rather than overflow it).
+ *       Forced-colors keeps the border in CanvasText once the box-shadow (a `rgb()` literal — WHCM
+ *       flattens arbitrary alpha colours) vanishes under high-contrast — the bar-chart fill lesson:
+ *       the border alone must carry the card's edge.
+ *
+ * No custom-state motion gate, no transitions — the LLD ships no entrance/exit animation in v1 (a
+ * fade/slide-in is a named foreseen extension, not this wave's contract). Standalone stylesheet —
+ * linked via the host page / component-styles barrel; NEVER injected from toast.ts (behaviour-only
+ * `.ts`, no runtime style injection — plan §2).
+ */
+
+/* ════════════════ [1] TOKEN BLOCK — :where(ui-toast) declares --ui-toast-* ════════════════ */
+
+:where(ui-toast) {
+  /* A notification card is a FIXED-width surface, not a control on the height ramp (geometry.md's
+     Pattern band — the ui-menu panel precedent, not a Control-band `--md-sys-height-*` lookup). */
+  --ui-toast-inline-size: 20em;
+
+  /* Surface — neutral roles (a toast carries no [intent]/[variant] colour channel in v1). */
+  --ui-toast-surface: var(--md-sys-color-neutral-surface-brightest);
+  --ui-toast-ink: var(--md-sys-color-neutral-on-surface); /* TKT-0066: was a direct role read in @scope */
+  --ui-toast-border: var(--md-sys-color-neutral-outline);
+  --ui-toast-shadow: 0 4px 12px rgb(0 0 0 / 0.15);
+
+  /* TKT-0066 item 5 ruling: dimensional constants route through the own chain, never read raw in @scope. */
+  --ui-toast-gap: var(--md-sys-space-sm); /* shared shell-spacing step — the ui-menu panel precedent */
+  --ui-toast-pad-inline: var(--md-sys-space-md);
+  --ui-toast-pad-block: var(--md-sys-space-sm);
+  --ui-toast-radius: var(--md-sys-shape-corner-base); /* the shared fleet radius (ui-menu/ui-card precedent) */
+}
+
+/* ════════════════ [2] STYLES BLOCK — @scope (ui-toast) consumes ONLY --ui-toast-* ════════════════ */
+
+@scope (ui-toast) {
+  :scope {
+    display: grid;
+    grid-template-columns: 1fr auto auto; /* message | action | close — the control-built parts (toast.ts) */
+    align-items: center;
+    gap: var(--ui-toast-gap);
+    box-sizing: border-box; /* the fixed inline-size below INCLUDES padding + border (button.css precedent) */
+
+    inline-size: var(--ui-toast-inline-size);
+    max-inline-size: 100%; /* floors small viewports — the card never overflows a narrow region */
+
+    padding-inline: var(--ui-toast-pad-inline);
+    padding-block: var(--ui-toast-pad-block);
+
+    background: var(--ui-toast-surface);
+    color: var(--ui-toast-ink);
+    border: 1px solid var(--ui-toast-border);
+    border-radius: var(--ui-toast-radius);
+    box-shadow: var(--ui-toast-shadow);
+  }
+
+  /* The message part — the fixed-width floor (an unbounded message must not blow out the card) + a
+     wrap escape for an unbroken token (e.g. a URL) that would otherwise overflow the fixed width. */
+  :scope [data-part='message'] {
+    min-inline-size: 0;
+    overflow-wrap: anywhere;
+  }
+
+  /* The close part is PINNED to the grid's third (last) column, always — the `action` part is only
+     appended when non-empty (toast.ts), so a non-actionable toast (the common case) has only TWO real
+     children (message, close) landing in auto-placement's columns 1 and 2, leaving the third (intended
+     close) column empty. Left unpinned, the close button rendered in the MIDDLE (action) track and the
+     genuinely-empty trailing track still consumed a `gap` between it and the padding edge — an extra
+     `--md-sys-space-sm` of phantom inset past the close button's own edge, reading as an off-standard
+     double-inset against the message's own left inset (TKT-0014). Explicit placement fixes both the
+     actionable AND non-actionable cases uniformly (a 3-child toast already lands here by auto-placement,
+     so this is a no-op for it). */
+  :scope [data-part='close'] {
+    grid-column: 3;
+  }
+
+  /* forced-colors — the box-shadow (an arbitrary-alpha rgb() literal) is flattened away under WHCM;
+     the border alone must carry the card's edge (the bar-chart fill lesson). */
+  @media (forced-colors: active) {
+    :scope {
+      border-color: CanvasText;
+    }
+  }
+}