@agent-ui-kit/components 0.0.3

package/dist/traits/press-activation.js

@@ -0,0 +1,55 @@
+// press-activation.ts — the Space/Enter → click trait (plan §7). A light-DOM custom element does NOT
+// inherit the native button's keyboard activation, so a control opts in by calling this from `connected()`.
+//
+// Semantics (native-button parity):
+//  · Space — `preventDefault` on keydown (stop the page from scrolling), activate on key UP.
+//  · Enter — `preventDefault` on keydown, THEN activate (bug-B fix, cross-engine e2e-caught): a real
+//    `<button>` has no OTHER default action competing for Enter, so nothing ever leaks; ours activates via
+//    an explicit `host.click()` inside a keydown LISTENER, which does not itself consume the keydown's
+//    default action. Chromium evaluates that default action AFTER the listener returns, against WHATEVER
+//    is focused AT THAT POINT — and `host.click()` can synchronously cascade into focus moving elsewhere
+//    (e.g. Enter-on-submit → provider.submit() → reportValidity() refocusing an invalid sibling field)
+//    before default-action time. An unconsumed Enter then lands wherever focus ended up — a contenteditable
+//    editor's native default action for Enter is "insert a line break," corrupting it. WebKit does not
+//    reproduce this (its default-action timing/target resolution differs), but the underlying hazard —
+//    Enter's default action must not survive to chase a mid-dispatch focus change — is real in any engine;
+//    consuming it explicitly, matching Space's own already-explicit `preventDefault`, closes it fleet-wide.
+//  · activation = `host.click()` (fires a native-parity click) — a plain method call, NOT itself affected
+//    by `preventDefault()` on the keydown (that only suppresses the BROWSER's own default reaction to the
+//    key event, never an imperative call a listener makes).
+//  · disabled-inert — when `opts.disabled()` is true the trait does NOTHING (no preventDefault, no click).
+//
+// Listeners ride `host.listen` → the host's connection `AbortSignal`, so they auto-remove on disconnect;
+// `release()` is an early-teardown escape hatch (idempotent — it flips a guard the handlers check).
+//
+// `traits → dom` is the one allowed cross-layer direction (reactive ← dom ← traits); the host type only.
+const isSpace = (key) => key === ' ' || key === 'Spacebar';
+/**
+ * Wire Space/Enter → `host.click()` on a `UIElement`, native-button style. Invoke from the control's
+ * `connected()` (where the host connection is live). Returns `release()` for early teardown (idempotent);
+ * otherwise the listeners auto-remove when the host disconnects.
+ */
+export function pressActivation(host, opts) {
+    let released = false;
+    host.listen(host, 'keydown', (event) => {
+        if (released || opts.disabled())
+            return;
+        const e = event;
+        if (isSpace(e.key))
+            e.preventDefault(); // stop the page scrolling; activation waits for keyup
+        else if (e.key === 'Enter') {
+            e.preventDefault(); // consume the keydown's default action (bug-B fix) — see the header note
+            host.click(); // Enter activates on keydown
+        }
+    });
+    host.listen(host, 'keyup', (event) => {
+        if (released || opts.disabled())
+            return;
+        const e = event;
+        if (isSpace(e.key))
+            host.click(); // Space activates on keyup
+    });
+    return () => {
+        released = true;
+    };
+}

package/dist/traits/roving-focus.d.ts

@@ -0,0 +1,52 @@
+import type { UIElement } from '../dom/index.js';
+/** The tab-stop-ownership marker this trait stamps on every item it manages (`applyTabindexes`) and strips
+ *  on release. `traits/tabbable.ts` checks for its presence to defer its own `tabIndex = 0` write — see the
+ *  ROVING-MARKER CONTRACT banner above. */
+export declare const ROVING_ITEM_ATTR = "data-roving";
+export type RovingOrientation = 'vertical' | 'horizontal';
+export interface RovingFocusOptions {
+    /** Live accessor returning the current ordered set of candidate items (re-read on each key event). */
+    items: () => HTMLElement[];
+    /** Arrow-key axis: Up/Down for `'vertical'`, Left/Right for `'horizontal'`. Default: `'vertical'`. */
+    orientation?: RovingOrientation;
+    /** Wrap from last → first and first → last. Default: `true`. */
+    loop?: boolean;
+    /**
+     * Focus the next item whose visible text starts with the typed buffer (200 ms reset between bursts).
+     * Default: `true`.
+     */
+    typeAhead?: boolean;
+    /**
+     * Called each time the roving index changes. Use to couple selection-follows-focus (listbox/tabs).
+     * NOT an active-descendant seam: `moveTo()` unconditionally transfers REAL focus to the item, which
+     * is exactly what active-descendant hosts must never do — combo-box/command-modal correctly hand-roll
+     * their focus-stays-on-editor navigation instead (their in-file records; TKT-0065 lateral review
+     * trued this header to the shipped reality).
+     */
+    onMove?: (index: number) => void;
+    /**
+     * Seed the initial roving index rather than defaulting to the first non-disabled item. A function
+     * is re-called at each invocation of `rovingFocus` (useful when calling from `connected()` so the
+     * currently-selected position after reconnect is honoured). Out-of-range values fall back to
+     * `findFirst`. Default: `findFirst(items())`.
+     */
+    initialIndex?: number | (() => number);
+    /**
+     * Called at the start of every keydown event to sync the internal roving index with external state.
+     * Use for selection-follows-focus hosts (tabs, listbox) where a click or programmatic selection
+     * change updates the host's own index without going through the trait's `onMove` callback.
+     * Returning a negative number or an out-of-range index is treated as "no update".
+     */
+    syncIndex?: () => number;
+    /**
+     * The element to attach the keydown (and type-ahead) listener to. Defaults to `host` itself.
+     * Set to a container sub-element (e.g. a `[data-part=tablist]` strip) when the host contains
+     * other focusable regions whose Arrow keys must NOT be intercepted by this trait.
+     */
+    container?: HTMLElement;
+}
+/**
+ * Wire keyboard + tabindex roving focus on a `UIElement` host. Invoke from `connected()` so the
+ * listeners ride the connection AbortSignal (auto-removed on disconnect). Returns cleanup (idempotent).
+ */
+export declare function rovingFocus(host: UIElement, opts: RovingFocusOptions): () => void;

package/dist/traits/roving-focus.js

@@ -0,0 +1,214 @@
+// roving-focus.ts — the keyboard + tabindex roving-focus trait (listbox-roving LLD-C1). Extracted
+// from ui-tabs' prior art (tabs.ts:130-168) to serve any "set of items with a moving focus" host:
+// ui-listbox, ui-menu, ui-select, ui-radio-group, ui-toolbar. Role-agnostic: `items` is a live
+// accessor; the host declares the item role in its own CSS/internals.
+//
+// Exactly ONE item holds `tabindex=0`; the rest `-1`. Arrow keys (Up/Down for vertical; Left/Right
+// for horizontal) + Home/End move the roving index AND transfer focus. `loop` wraps at the ends;
+// `typeAhead` searches by the typed buffer (200ms reset). `onMove(index)` notifies the host: couple
+// selection-follows-focus (listbox/tabs) or decouple (menu: focus moves, selection commits on Enter).
+//
+// THE ROVING-MARKER CONTRACT (ADR-0121 amendment, post-toolbar): custom-element connection is preorder
+// (a parent's `connectedCallback` fires before its children's, for a subtree connected all at once) — so
+// a host that roves over ITEMS WHICH OWN THEIR OWN TAB-STOP (e.g. `ui-button`'s `tabbable` trait,
+// traits/tabbable.ts) can lose the race: this trait's synchronous init runs first and sets the correct
+// tabindexes, but each item's OWN later-running `connected()` effect unconditionally re-asserts
+// `tabIndex = 0`, silently breaking the "exactly one tabindex=0" contract. `ui-radio-group` → `ui-radio`
+// carries this same latent bug (masked by jsdom's opposite child-then-parent connection order, which real
+// Chromium/WebKit do not share) — `ui-toolbar` → `ui-button` is what surfaced it. The fix is two-sided,
+// and BOTH traits document it:
+//   1. HERE — `applyTabindexes` stamps every item it manages with `ROVING_ITEM_ATTR` (`data-roving`), on
+//      init and on every move, so the marker is always current for whatever the live `items()` set is;
+//      `release()` strips it from the last-known set. A settle pass — one `requestAnimationFrame` tick past
+//      connect (the tabs.ts `ready`-gate precedent) — re-reads `items()` and re-applies once more, closing
+//      the race for any item whose OWN trait installs after this one's synchronous init.
+//   2. `traits/tabbable.ts` — its effect DEFERS the `tabIndex = 0` write while the host carries
+//      `ROVING_ITEM_ATTR` (checked on EVERY effect run, not just once), so a later re-enable mid-session
+//      still yields to the roving owner instead of reclaiming a second tab stop. `disabled`/`aria-disabled`
+//      semantics are untouched — only tab-stop OWNERSHIP yields. Absent the marker, tabbable is unchanged.
+//
+// `traits → dom` is the one allowed cross-layer direction; the host type only. `ROVING_ITEM_ATTR` is the
+// one same-layer (traits → traits) export this module carries — tabbable.ts imports it (layering.test.ts
+// permits same-layer imports; only an UPWARD import is a violation).
+/** The tab-stop-ownership marker this trait stamps on every item it manages (`applyTabindexes`) and strips
+ *  on release. `traits/tabbable.ts` checks for its presence to defer its own `tabIndex = 0` write — see the
+ *  ROVING-MARKER CONTRACT banner above. */
+export const ROVING_ITEM_ATTR = 'data-roving';
+// True if the item carries either the native `disabled` attribute or `aria-disabled="true"`.
+function isDisabled(item) {
+    return item.hasAttribute('disabled') || item.getAttribute('aria-disabled') === 'true';
+}
+// Apply roving tabindexes: the item at `index` gets 0; all others -1. When `index` is -1 (all
+// disabled) every item gets -1. Stamps ROVING_ITEM_ATTR on every item in `list` (the ownership marker
+// traits/tabbable.ts defers to — the ROVING-MARKER CONTRACT banner above); idempotent, cheap to re-apply
+// on every call (init + every move).
+function applyTabindexes(list, index) {
+    for (let i = 0; i < list.length; i++) {
+        list[i].tabIndex = i === index ? 0 : -1;
+        list[i].setAttribute(ROVING_ITEM_ATTR, '');
+    }
+}
+// Index of the first non-disabled item, or -1 if the set is all-disabled.
+function findFirst(list) {
+    return list.findIndex((item) => !isDisabled(item));
+}
+// Index of the last non-disabled item, or -1.
+function findLast(list) {
+    for (let i = list.length - 1; i >= 0; i--) {
+        if (!isDisabled(list[i]))
+            return i;
+    }
+    return -1;
+}
+// Walk from `from` in direction `dir` (+1 or -1), skipping disabled items. With `loop`, wraps
+// modulo the list length. Without loop, stops at the boundary. Returns -1 when no candidate found.
+function walkEnabled(list, from, dir, loop) {
+    const n = list.length;
+    for (let step = 1; step <= n; step++) {
+        const raw = from + dir * step;
+        const idx = loop ? ((raw % n) + n) % n : raw;
+        if (idx < 0 || idx >= n)
+            break;
+        if (!isDisabled(list[idx]))
+            return idx;
+    }
+    return -1;
+}
+/**
+ * Wire keyboard + tabindex roving focus on a `UIElement` host. Invoke from `connected()` so the
+ * listeners ride the connection AbortSignal (auto-removed on disconnect). Returns cleanup (idempotent).
+ */
+export function rovingFocus(host, opts) {
+    const { items, orientation = 'vertical', loop = true, typeAhead = true, onMove, syncIndex, container } = opts;
+    let released = false;
+    // The current roving index (-1 = none; arises when the initial item set is all-disabled).
+    let rovingIndex = -1;
+    // Type-ahead: accumulate printable characters; reset after 200 ms of inactivity.
+    let typeBuffer = '';
+    let typeTimer = null;
+    // Move roving focus to `next`: update tabindexes, transfer real focus, notify the host.
+    function moveTo(list, next) {
+        if (next === -1 || next >= list.length)
+            return;
+        rovingIndex = next;
+        applyTabindexes(list, next);
+        list[next].focus();
+        onMove?.(next);
+    }
+    // Initialise tabindexes: use `initialIndex` (if provided) to seed from the host's current selection
+    // rather than defaulting to the first non-disabled item. This is required when the host's selection
+    // effect has already placed tabindex=0 on a non-first item (e.g. tabs reconnecting with tab 1 active).
+    const init = items();
+    if (opts.initialIndex !== undefined) {
+        const seed = typeof opts.initialIndex === 'function' ? opts.initialIndex() : opts.initialIndex;
+        rovingIndex = (seed >= 0 && seed < init.length) ? seed : findFirst(init);
+    }
+    else {
+        rovingIndex = findFirst(init);
+    }
+    applyTabindexes(init, rovingIndex);
+    // Settle pass — one requestAnimationFrame tick past connect (the tabs.ts `ready`-gate precedent):
+    // re-reads the live item set and re-applies tabindexes once more, closing the preorder-connection race
+    // for any item whose OWN focus-owning trait (traits/tabbable.ts) installs AFTER this synchronous init
+    // and would otherwise win the tabIndex write (the ROVING-MARKER CONTRACT banner above). Cancelled on
+    // early release.
+    const settleHandle = requestAnimationFrame(() => {
+        if (released)
+            return;
+        const list = items();
+        if (list.length === 0)
+            return;
+        let idx = rovingIndex;
+        if (idx < 0 || idx >= list.length || isDisabled(list[idx]))
+            idx = findFirst(list);
+        rovingIndex = idx;
+        applyTabindexes(list, idx);
+    });
+    // Keydown handler — attached to `container` (default: host) so it can be scoped to a sub-region
+    // (e.g. a tablist strip) without intercepting arrow keys inside focusable panel content.
+    const listenerTarget = container ?? host;
+    host.listen(listenerTarget, 'keydown', (event) => {
+        if (released)
+            return;
+        const e = event;
+        const list = items(); // live re-read: handles dynamic item sets
+        if (list.length === 0)
+            return;
+        // Sync external selection state (e.g. click/programmatic) before any key-based navigation so the
+        // next Arrow move starts from the correct position even when the host updated its own index
+        // via a path that bypassed `onMove` (tabs' #commit() on click, for example).
+        if (syncIndex !== undefined) {
+            const synced = syncIndex();
+            if (synced >= 0 && synced < list.length)
+                rovingIndex = synced;
+        }
+        const isNextKey = orientation === 'vertical' ? e.key === 'ArrowDown' : e.key === 'ArrowRight';
+        const isPrevKey = orientation === 'vertical' ? e.key === 'ArrowUp' : e.key === 'ArrowLeft';
+        const isHomeKey = e.key === 'Home';
+        const isEndKey = e.key === 'End';
+        if (!isNextKey && !isPrevKey && !isHomeKey && !isEndKey) {
+            // Type-ahead: single printable character with no modifier key shortcuts active.
+            if (typeAhead && e.key.length === 1 && !e.ctrlKey && !e.metaKey && !e.altKey) {
+                typeBuffer += e.key.toLowerCase();
+                if (typeTimer !== null)
+                    clearTimeout(typeTimer);
+                typeTimer = setTimeout(() => {
+                    typeBuffer = '';
+                    typeTimer = null;
+                }, 200);
+                // Search from the item AFTER current (wrapping), including current only as the last resort.
+                const from = rovingIndex; // -1 is safe: ((-1+1) % n + n) % n = 0
+                const n = list.length;
+                for (let step = 1; step <= n; step++) {
+                    const idx = ((from + step) % n + n) % n;
+                    if (!isDisabled(list[idx])) {
+                        const label = (list[idx].textContent ?? '').trim().toLowerCase();
+                        if (label.startsWith(typeBuffer)) {
+                            e.preventDefault();
+                            moveTo(list, idx);
+                            break;
+                        }
+                    }
+                }
+            }
+            return;
+        }
+        e.preventDefault();
+        // Clamp rovingIndex to valid range in case items changed since the last move.
+        let current = rovingIndex;
+        if (current < 0 || current >= list.length) {
+            current = findFirst(list);
+            if (current === -1)
+                return; // all-disabled — nothing to do
+        }
+        let next;
+        if (isNextKey)
+            next = walkEnabled(list, current, 1, loop);
+        else if (isPrevKey)
+            next = walkEnabled(list, current, -1, loop);
+        else if (isHomeKey)
+            next = findFirst(list);
+        else
+            next = findLast(list); // isEndKey
+        moveTo(list, next);
+    });
+    // Strip the ownership marker (+ cancel a still-pending settle pass) — idempotent, so both the manual
+    // early-teardown call below AND the automatic disconnect path (next) can invoke it safely.
+    function cleanup() {
+        if (released)
+            return;
+        released = true;
+        cancelAnimationFrame(settleHandle);
+        // Best-effort — an item that has since left the DOM entirely needs no cleanup. A reconnect's fresh
+        // `rovingFocus()` call re-stamps it.
+        for (const item of items())
+            item.removeAttribute(ROVING_ITEM_ATTR);
+    }
+    // Auto-release on disconnect: the keydown LISTENER already dies via `host.listen`'s connection
+    // AbortSignal, but the marker is real DOM state with a real consumer (traits/tabbable.ts) — it must not
+    // outlive the roving host. A no-op-dependency `host.effect` is the scope-owned "run cleanup on dispose"
+    // idiom: it runs once (no signal reads to re-trigger it) and its RETURNED cleanup fires when the
+    // connection scope disposes at disconnect, exactly like every other scope-owned effect in this fleet.
+    host.effect(() => cleanup);
+    return cleanup;
+}

package/dist/traits/scroll-fade.d.ts

@@ -0,0 +1,28 @@
+import type { UIElement } from '../dom/index.js';
+export interface ScrollFadeOptions {
+    /**
+     * The scrolling viewport — measured (scrollTop/Height/clientHeight) AND painted (the `data-fade-*` flags +
+     * the published bracket offsets all land here). Usually `host` itself, sometimes a control-owned part.
+     */
+    viewport?: HTMLElement;
+    /**
+     * The element whose DIRECT children are queried for a header/footer bracket — defaults to `viewport`. Set
+     * this when the brackets are NOT the viewport's own children (ui-card: `viewport` is `ui-card-content`
+     * itself, but the header/footer are the CARD's direct children, one level up).
+     */
+    brackets?: HTMLElement;
+    /**
+     * Reactively gate the trait — read inside the host's effect, so toggling the underlying signal turns the
+     * fade attributes on/off live (and tears down the listener/observer when it goes false). Default: always on.
+     */
+    enabled?: () => boolean;
+}
+/**
+ * Toggle `data-fade-top`/`data-fade-bottom` on `viewport` from its own live scroll position, with the bracket
+ * band queried off `brackets` (default `viewport`). Invoke from the control's `connected()` (e.g.
+ * `scrollFade(this, { viewport: dialog })`, or ui-card's `scrollFade(this, { brackets: card })` when the
+ * viewport IS the host but the brackets live on a distinct ancestor). Returns `release()` for early teardown
+ * (idempotent); otherwise the effect (and the listener/observer it installs) is disposed when the host
+ * disconnects.
+ */
+export declare function scrollFade(host: UIElement, opts?: ScrollFadeOptions): () => void;

package/dist/traits/scroll-fade.js

@@ -0,0 +1,120 @@
+// scroll-fade.ts — the edge-aware scroll-fade trait (container box-model revision, ADR-0046 follow-up).
+// A scroll viewport with a sticky header/footer bracket (container-box.css) has an inset gutter around the
+// bracket — the bracket's own `background: inherit` does not reach the frame edge (the region floats inside,
+// ADR-0046 revised 2026-07-04). Scrolled content can therefore show through that thin gutter. The fix is not
+// on the bracket: it is on the CONTENT — fade its own edges before they reach the gutter, so nothing hard ever
+// shows there. This trait supplies the "which edge" decision; container-box.css supplies the paint
+// (`[data-fade-top]`/`[data-fade-bottom]` → a `mask-image` gradient, the same recipe card.css already shipped
+// as a static, always-on fade).
+//
+// The BRACKET QUERY can differ from `viewport` (`opts.brackets`, added 2026-07-06 for ui-card, still needed):
+// `bandOf()` queries `brackets`' DIRECT children for the header/footer, independent of which element is being
+// measured/painted — ui-card-content IS the scroll viewport (and the masked element, below), but the header/
+// footer are the CARD's own direct children, one level up. Defaults to `viewport` (unchanged for every other
+// consumer, where the brackets genuinely are the viewport's own direct children).
+//
+// MEASURE and PAINT are always the SAME element (`viewport`) — a short-lived `opts.paintTarget` split existed
+// 2026-07-05/06 for an EARLIER ui-card shape (the card measured, a sibling `ui-card-content` painted; then a
+// nested `[scroll-wrapper]` measured while `ui-card-content` painted). REVISED 2026-07-07 (Kim): ui-card-content
+// now directly manages its own overflow AND carries the mask — one box, no split — so `paintTarget` is retired
+// (no remaining consumer ever set it distinct from `viewport`); this keeps the trait's surface to the two roles
+// that are still genuinely independent (`viewport`/`brackets`), not three.
+//
+// PRESENCE-AWARE: the fade must ADAPT to a sticky/overlaid header/footer — the gradient itself does the
+// occlusion (a bracket needs no background; a bit of gradient showing through it is fine), so the ramp reaches
+// PAST a present bracket. The trait publishes each edge's bracket band — `--ui-box-head`/`--ui-box-foot`, the
+// bracket's rendered block-size + its inset gutter, or 0px when that edge has none — and the consumer's own CSS
+// (container-box.css's mask rule, or ui-card-content's own block-padding) reads it. Content thus stays faded
+// until it has cleared a present bracket; a bracketless edge (0px) collapses to the exact pre-offset fade/padding.
+//
+// EDGE-AWARE, not symmetric: a flag is present only when content is genuinely hidden past THAT edge — a short
+// / non-scrolling viewport gets neither flag (never faded), and an at-top/at-bottom viewport only fades the
+// edge that still hides something.
+//
+// Deliberately JS-driven, not `animation-timeline: scroll()`: the decision is three comparisons against
+// scrollTop/scrollHeight/clientHeight — trivially unit-testable in jsdom and immune to scroll-driven-animation
+// engine-support gaps. The PAINT it drives is the well-proven `mask-image` mechanism already shipped (card.css).
+//
+// Reactive gate (mirrors tabbable.ts's `disabled: () => boolean` shape): `opts.enabled` is read inside the
+// host's own `host.effect`, so an author-facing opt-in prop (e.g. ui-card-content's `scroll-fade`) can turn the
+// whole mechanism on/off live. Omit it for an always-on internal viewport (a modal dialog, an overlay panel).
+//
+// `traits → dom` is the one allowed cross-layer direction; the host type only.
+// Direct-child brackets, per the container box-model: a `header`/`footer` (or `[data-region]`) region on a
+// `[data-box]` (modal / overlay panels), and `ui-card-header`/`ui-card-footer` on the ui-card that hosts a
+// `ui-card-content` viewport.
+const HEAD = ':scope > :is(header, [data-region="header"], ui-card-header)';
+const FOOT = ':scope > :is(footer, [data-region="footer"], ui-card-footer)';
+/** The rendered band a bracket occupies at its edge = its border-box block-size + the inset gutter (its margin
+ * to the frame). `'0px'` when that edge has NO bracket — the fade/padding then reaches the viewport edge. */
+function bandOf(brackets, sel, top) {
+    const el = brackets.querySelector(sel);
+    if (!(el instanceof HTMLElement))
+        return '0px';
+    const cs = getComputedStyle(el);
+    return `${el.offsetHeight + (parseFloat(top ? cs.marginBlockStart : cs.marginBlockEnd) || 0)}px`;
+}
+/** Publish each edge's bracket band as `--ui-box-head`/`--ui-box-foot` on `viewport` — the offset a consumer's
+ * CSS extends the fade ramp (or its own block-padding) PAST, so content stays clear of / faded until it has
+ * cleared a present bracket (a bracketless edge, 0px, collapses to the plain depth). The bracket query itself
+ * always runs against `brackets` (its direct children — not necessarily `viewport`'s own). Re-run on resize (a
+ * growing bracket/viewport), not on the scroll path. */
+function measure(brackets, viewport) {
+    viewport.style.setProperty('--ui-box-head', bandOf(brackets, HEAD, true));
+    viewport.style.setProperty('--ui-box-foot', bandOf(brackets, FOOT, false));
+}
+/** Zero out both fade flags + the published bracket offsets on `viewport` — the "not active" / "not scrollable" state. */
+function clear(viewport) {
+    viewport.removeAttribute('data-fade-top');
+    viewport.removeAttribute('data-fade-bottom');
+    viewport.style.removeProperty('--ui-box-head');
+    viewport.style.removeProperty('--ui-box-foot');
+}
+/**
+ * Toggle `data-fade-top`/`data-fade-bottom` on `viewport` from its own live scroll position, with the bracket
+ * band queried off `brackets` (default `viewport`). Invoke from the control's `connected()` (e.g.
+ * `scrollFade(this, { viewport: dialog })`, or ui-card's `scrollFade(this, { brackets: card })` when the
+ * viewport IS the host but the brackets live on a distinct ancestor). Returns `release()` for early teardown
+ * (idempotent); otherwise the effect (and the listener/observer it installs) is disposed when the host
+ * disconnects.
+ */
+export function scrollFade(host, opts = {}) {
+    const viewport = opts.viewport ?? host;
+    const brackets = opts.brackets ?? viewport;
+    const isEnabled = opts.enabled ?? (() => true);
+    const dispose = host.effect(() => {
+        if (!isEnabled()) {
+            clear(viewport);
+            return;
+        }
+        const update = () => {
+            const hasOverflow = viewport.scrollHeight > viewport.clientHeight + 1;
+            const atTop = viewport.scrollTop <= 1;
+            const atBottom = viewport.scrollTop + viewport.clientHeight >= viewport.scrollHeight - 1;
+            viewport.toggleAttribute('data-fade-top', hasOverflow && !atTop);
+            viewport.toggleAttribute('data-fade-bottom', hasOverflow && !atBottom);
+        };
+        const remeasure = () => {
+            update(); // the edge decision
+            measure(brackets, viewport); // the bracket offsets (presence + depth the fade ramp reaches past)
+        };
+        remeasure(); // the at-mount state (no scroll event has fired yet)
+        viewport.addEventListener('scroll', update, { passive: true }); // removed explicitly below — no AbortController
+        // needed (this trait is not riding host.listen); a plain remove keeps the marginal size down.
+        // The viewport's own box can resize independently of scrolling (a max-block-size cap, a card growing) —
+        // re-run both the edge decision and the bracket measurement whenever EITHER does (a bracket resize that
+        // reflows the viewport rides this too; `brackets` is observed separately since it can be a distinct element
+        // from `viewport`, e.g. ui-card). Feature-detected: every evergreen engine has ResizeObserver, but jsdom
+        // (the unit-test environment) does not — the scroll listener above still covers the decision there.
+        const ro = typeof ResizeObserver !== 'undefined' ? new ResizeObserver(remeasure) : null;
+        ro?.observe(viewport);
+        if (brackets !== viewport)
+            ro?.observe(brackets);
+        return () => {
+            viewport.removeEventListener('scroll', update);
+            ro?.disconnect();
+            clear(viewport);
+        };
+    });
+    return () => dispose();
+}

package/dist/traits/selection-commit.d.ts

@@ -0,0 +1,30 @@
+import type { UIElement } from '../dom/index.js';
+export type SelectionMode = 'single' | 'multi';
+export interface SelectionCommitOptions {
+    /**
+     * `'single'` — at most one selected key. `'multi'` — a Set with Shift/Ctrl range-toggle and
+     * Ctrl+Space per-item toggle. Default: `'single'`.
+     */
+    mode?: SelectionMode;
+    /**
+     * Called when the committed selection changes.
+     * Single mode: a `string` key, or `''` when nothing is selected.
+     * Multi mode: a `ReadonlySet<string>` of selected keys (may be empty).
+     */
+    onSelect?: (selection: string | ReadonlySet<string>) => void;
+    /**
+     * Live accessor returning the ordered option elements (re-read on each event for Shift-range
+     * ordering). Default: `[...host.querySelectorAll('[role=option]')]`.
+     */
+    items?: () => HTMLElement[];
+    /**
+     * Extract the string key from an option element. An empty string is treated as "no key" —
+     * items without a key are skipped. Default: `el.dataset['key'] ?? ''`.
+     */
+    keyOf?: (el: HTMLElement) => string;
+}
+/**
+ * Wire single/multi selection tracking on a `UIElement` host. Invoke from `connected()` so
+ * listeners ride the connection AbortSignal (auto-removed on disconnect). Returns cleanup (idempotent).
+ */
+export declare function selectionCommit(host: UIElement, opts: SelectionCommitOptions): () => void;

package/dist/traits/selection-commit.js

@@ -0,0 +1,146 @@
+// selection-commit.ts — the selection model + commit controller (listbox-roving LLD-C2). Tracks
+// the selected key(s) for any "set of options" host: single or multi. Publishes `aria-selected`
+// via internals element-reflection and emits `select` on commit. Value-codec-agnostic: the host
+// maps its option elements to string keys.
+//
+// Consumer contract (trued by the TKT-0065 lateral review — the original header named hosts that
+// lawfully cannot consume this trait): the selection marker is an `aria-selected` ATTRIBUTE on each
+// item, so the trait fits attribute-reflected `[role=option]` hosts ONLY (ui-select is the shipped
+// consumer). `role=menuitem` hosts (ui-menu) must not carry aria-selected (action semantics — menu.ts
+// commits via its own click + Enter/Space path, which this trait also lacks a Space leg for), and
+// ui-tab items drive selection through ElementInternals, never host attributes (the fleet ARIA law).
+//
+// `traits → dom` is the one allowed cross-layer direction; the host type only.
+/**
+ * Wire single/multi selection tracking on a `UIElement` host. Invoke from `connected()` so
+ * listeners ride the connection AbortSignal (auto-removed on disconnect). Returns cleanup (idempotent).
+ */
+export function selectionCommit(host, opts) {
+    const mode = opts.mode ?? 'single';
+    const getItems = opts.items ??
+        (() => [...host.querySelectorAll('[role=option]')]);
+    const keyOf = opts.keyOf ??
+        ((el) => el.dataset['key'] ?? '');
+    // A disabled option is non-committable — guards BOTH commit paths (click + Enter) so a disabled
+    // option cannot be selected even where CSS `pointer-events:none` is absent (jsdom) or bypassed
+    // (keyboard). Matches the rovingFocus/menu disabled convention: the HTML `[disabled]` attribute OR
+    // `aria-disabled="true"`. (Selection-follows-focus hosts already skip disabled at the roving layer;
+    // this is the commit-layer backstop.)
+    const isDisabled = (el) => el.hasAttribute('disabled') || el.getAttribute('aria-disabled') === 'true';
+    // Single-mode cursor; multi-mode Set; anchor key held across moves for Shift-range extension.
+    let singleKey = '';
+    let multiKeys = new Set();
+    let anchorKey = '';
+    let released = false;
+    // Reflect aria-selected on every option element in the host. The attribute is set on the ITEMS
+    // (NOT on the host) — aria-selected belongs to each option, not the listbox container.
+    const reflectAriaSelected = () => {
+        for (const item of getItems()) {
+            const k = keyOf(item);
+            const selected = mode === 'single'
+                ? (k !== '' && k === singleKey)
+                : multiKeys.has(k);
+            item.setAttribute('aria-selected', String(selected));
+        }
+    };
+    // Reflect ARIA, invoke `onSelect`, and emit `select` with the current committed selection.
+    const publish = () => {
+        reflectAriaSelected();
+        const selection = mode === 'single' ? singleKey : new Set(multiKeys);
+        opts.onSelect?.(selection);
+        host.emit('select', selection);
+    };
+    // Resolve the closest [role=option] ancestor of a click target, constrained within the host.
+    const optionFromTarget = (target) => {
+        if (!(target instanceof HTMLElement))
+            return null;
+        const item = target.closest('[role=option]');
+        return item && host.contains(item) ? item : null;
+    };
+    host.listen(host, 'click', (event) => {
+        if (released)
+            return;
+        const e = event;
+        const item = optionFromTarget(e.target);
+        if (!item || isDisabled(item))
+            return;
+        const key = keyOf(item);
+        if (key === '')
+            return;
+        if (mode === 'single') {
+            singleKey = key;
+            anchorKey = key;
+            publish();
+            return;
+        }
+        // Multi mode — modifier keys determine how the selection evolves.
+        if (e.shiftKey && anchorKey !== '') {
+            // Range-extend: replace selection with the range from anchor to the clicked item (inclusive).
+            // The anchor itself does not move on Shift — it stays at the last plain click/Enter.
+            const items = getItems();
+            const ai = items.findIndex((el) => keyOf(el) === anchorKey);
+            const ci = items.indexOf(item);
+            if (ai >= 0 && ci >= 0) {
+                const lo = Math.min(ai, ci);
+                const hi = Math.max(ai, ci);
+                multiKeys = new Set(items.slice(lo, hi + 1).map(keyOf).filter((k) => k !== ''));
+                publish();
+            }
+        }
+        else if (e.ctrlKey || e.metaKey) {
+            // Toggle: flip this item's membership without moving the anchor.
+            const next = new Set(multiKeys);
+            if (next.has(key))
+                next.delete(key);
+            else
+                next.add(key);
+            multiKeys = next;
+            publish();
+        }
+        else {
+            // Plain click: replace the selection and set a new anchor.
+            multiKeys = new Set([key]);
+            anchorKey = key;
+            publish();
+        }
+    });
+    host.listen(host, 'keydown', (event) => {
+        if (released)
+            return;
+        const e = event;
+        if (e.key !== 'Enter')
+            return;
+        // Commit the currently focused option (set by rovingFocus or any active-descendant approach).
+        const active = document.activeElement;
+        if (!active || !host.contains(active))
+            return;
+        const item = active.closest('[role=option]');
+        if (!item || isDisabled(item))
+            return;
+        const key = keyOf(item);
+        if (key === '')
+            return;
+        // Enter COMMITS here — suppress its default action so a host that closes an overlay on commit and
+        // restores focus to a <button> trigger does NOT let the SAME Enter re-activate that button (which
+        // would re-toggle the popup open). Cross-engine bug caught by ui-select's commit-close smoke.
+        e.preventDefault();
+        if (mode === 'single') {
+            singleKey = key;
+            anchorKey = key;
+            publish();
+        }
+        else {
+            // Toggle the focused item; anchor stays.
+            const next = new Set(multiKeys);
+            if (next.has(key))
+                next.delete(key);
+            else
+                next.add(key);
+            multiKeys = next;
+            publish();
+        }
+    });
+    return () => {
+        released = true;
+    };
+}