@agent-ui-kit/components 0.0.3

package/dist/controls/command-modal/command-modal.css

@@ -0,0 +1,226 @@
+/* command-modal.css — ui-command-modal, the single-file component stylesheet (ADR-0003 / ADR-0125 / LLD-C11).
+ * Two clearly-SECTIONED blocks, mirroring combo-box.css / modal.css:
+ *
+ *   [1] TOKEN BLOCK  — `:where(ui-command-modal)` (specificity 0,0,0) declares the `--ui-command-modal-*`
+ *       chain: the search field borrows the entry-control height register (--md-sys-height-md), item/group/active
+ *       geometry rides the `--md-sys-space` ladder (ambient under [scale]/[density]). Raw `--md-sys-color-*` roles
+ *       enter ONLY here.
+ *   [2] STYLES BLOCK — `@scope (ui-command-modal)` CONSUMES only `--ui-command-modal-*`. The host itself is
+ *       `display: contents` — it paints NOTHING; the nested `ui-modal` owns the whole surface (the modal's own
+ *       sheet supplies the dialog/backdrop/frame). This sheet styles only the parts THIS control creates:
+ *       search / list / status / empty / option / group, all rendered INSIDE the nested modal's <dialog>.
+ *
+ * Standalone stylesheet — NOT injected from command-modal.ts (behaviour-only `.ts`, plan §2). Linked via the
+ * component-styles barrel, appended after every other control (ADR-0003 append-only import order).
+ */
+
+/* ════════════════ [1] TOKEN BLOCK — :where(ui-command-modal) ════════════════ */
+
+:where(ui-command-modal) {
+  /* The search field borrows the entry-control height register (the combo-box/select trigger precedent) — no
+     new geometry row (Pattern class, geometry.md; no §1 control-height row of its own). */
+  --ui-command-modal-search-block-size: var(--md-sys-height-md);
+  --ui-command-modal-search-font: var(--md-sys-font-md);
+  --ui-command-modal-search-padding-inline: calc(var(--ui-command-modal-search-block-size) / 2); /* the fleet h/2 value-edge standard */
+
+  /* Frame — the §1b entry-control law applied DEGENERATELY (TKT-0068 item 4 ruling): the palette search
+     is always focused while the modal is open, so it wears §1b's FOCUS row permanently — container-low
+     bg · transparent border · on-surface ink (the field/panel bg contrast now carries the search/list
+     separation the old solid divider drew; the 1px border-block-end stays for layout, transparent).
+     The placeholder aliases the ink per §1b's alias shape (no sixth row). */
+  --ui-command-modal-search-border: transparent;
+  --ui-command-modal-search-bg: var(--md-sys-color-neutral-container-low);
+  --ui-command-modal-search-ink: var(--md-sys-color-neutral-on-surface);
+  --ui-command-modal-search-placeholder: var(--ui-command-modal-search-ink);
+
+  /* The bounded scroll viewport (the list is the dialog's body; scroll-fade wired in .ts). */
+  --ui-command-modal-list-max-block: 50vh;
+  /* Hidden-but-scrollable, the fleet's --ui-surface-host-scrollbar-width "hidden scroller, live scroll"
+     seam (TKT-0084 shape): a CMD-K overlay is app chrome, and a raw platform scrollbar reads as broken
+     chrome there — the scroll-fade edge treatment (wired in .ts, above) stays the scroll affordance.
+     Consumer-overridable (the same repoint pattern), never forced. */
+  --ui-command-modal-scrollbar-width: none;
+  /* TKT-0017 — the FIXED FRAME (the CMD-K convention): a set width and a top anchor so the search field
+     never moves as filtering changes the result count; only the list below grows/shrinks (downward, the
+     VS Code palette convention). command-modal.ts forwards these onto the nested ui-modal's frame dials. */
+  --ui-command-modal-inline-size: min(92vw, 36rem);
+  --ui-command-modal-block-anchor: 15svh;
+
+  /* Item/group geometry off the --md-sys-space ladder (ambient under [scale]/[density] — no new geometry row). */
+  --ui-command-modal-item-pad-inline: var(--md-sys-space-sm);
+  --ui-command-modal-item-pad-block: var(--md-sys-space-xs);
+  --ui-command-modal-item-gap: var(--md-sys-space-xs);
+  --ui-command-modal-group-gap: var(--md-sys-space-sm);
+  --ui-command-modal-caption-font: var(--md-sys-font-sm); /* group-label + shortcut display — a caption-weight read, off the live ramp (--ui-type-* is retired, ADR-0078 cl.2) */
+
+  --ui-command-modal-ink: var(--md-sys-color-neutral-on-surface);
+  --ui-command-modal-muted-ink: var(--md-sys-color-neutral-on-surface-variant);
+  --ui-command-modal-group-label-ink: var(--md-sys-color-neutral-on-surface-variant);
+  --ui-command-modal-radius: var(--md-sys-shape-corner-base);
+
+  /* The [data-active] active-descendant highlight — a background treatment paired with the ARIA/attribute
+     signifier itself (never color-only intent, ADR-0057). */
+  --ui-command-modal-active-bg: var(--md-sys-color-neutral-tint-dim);
+  --ui-command-modal-active-ink: var(--md-sys-color-neutral-on-surface);
+}
+
+/* ════════════════ [2] STYLES BLOCK — @scope (ui-command-modal) ════════════════ */
+
+@scope (ui-command-modal) {
+  /* The palette host paints nothing of its own — the nested ui-modal owns the entire surface. */
+  :scope {
+    display: contents;
+  }
+
+  /* ── Search field (role=combobox, Control-class height) ─────────────────────────────────────── */
+
+  :scope [data-part='search'] {
+    box-sizing: border-box;
+    display: flex;
+    align-items: center;
+    min-block-size: var(--ui-command-modal-search-block-size);
+    line-height: 1;
+    padding-block: 0;
+    padding-inline: var(--ui-command-modal-search-padding-inline);
+    font-size: var(--ui-command-modal-search-font);
+    background-color: var(--ui-command-modal-search-bg);
+    color: var(--ui-command-modal-search-ink);
+    border: none;
+    border-block-end: 1px solid var(--ui-command-modal-search-border);
+    cursor: text;
+    outline: none; /* the shared focus-ring convention — a palette search field is always focused while open */
+    /* single-line — the contenteditable UA default is pre-wrap; every fleet entry field overrides it */
+    white-space: nowrap;
+    overflow: hidden;
+  }
+
+  :scope [data-part='search'][data-empty]::before {
+    content: attr(data-placeholder);
+    color: var(--ui-command-modal-search-placeholder);
+    pointer-events: none;
+    user-select: none;
+  }
+
+  /* ── List (role=listbox) — the bounded scroll viewport, [data-box] region rhythm ─────────────── */
+
+  :scope [data-part='list'] {
+    box-sizing: border-box;
+    max-block-size: var(--ui-command-modal-list-max-block);
+    overflow-y: auto;
+    /* Hidden scroller, live scroll (token block, above) — both shipped engines support scrollbar-width
+       (Chromium 121+/Safari 18.2+), no ::-webkit-scrollbar leg (the split-pane.css note). */
+    scrollbar-width: var(--ui-command-modal-scrollbar-width);
+    padding: 0;
+    margin: 0;
+    list-style: none;
+  }
+
+  /* ── Groups + their heading ───────────────────────────────────────────────────────────────────── */
+
+  :scope [role='group'] {
+    display: block;
+    margin-block-end: var(--ui-command-modal-group-gap);
+  }
+  :scope [role='group'][hidden] {
+    display: none;
+  }
+  :scope [data-role='group-label'] {
+    padding-inline: var(--ui-command-modal-item-pad-inline);
+    padding-block: var(--ui-command-modal-item-pad-block);
+    font-size: var(--ui-command-modal-caption-font);
+    color: var(--ui-command-modal-group-label-ink);
+  }
+
+  /* ── Option rows ───────────────────────────────────────────────────────────────────────────────── */
+
+  :scope [role='option'] {
+    display: flex;
+    flex-wrap: wrap; /* TKT-0019 — lets [data-role=description] (flex-basis:100%, below) push onto its own line;
+                        the title row (icon/label/shortcut) is unaffected while it still fits one line */
+    align-items: center;
+    gap: var(--ui-command-modal-item-gap);
+    padding-inline: var(--ui-command-modal-item-pad-inline);
+    padding-block: var(--ui-command-modal-item-pad-block);
+    border-radius: var(--ui-command-modal-radius);
+    color: var(--ui-command-modal-ink);
+    cursor: pointer;
+  }
+  :scope [role='option'][hidden] {
+    display: none;
+  }
+  /* TKT-0047 — converges on the fleet's dominant disabled mechanism (token-repoint, not opacity): reuses
+     the EXISTING `--ui-command-modal-muted-ink` role (already used for the group-label ink, above) rather
+     than dimming via opacity, matching select.css's fully-repointed `[disabled]` precedent. */
+  :scope [role='option'][aria-disabled='true'] {
+    color: var(--ui-command-modal-muted-ink);
+    pointer-events: none;
+  }
+  /* The [data-active] active-descendant highlight — CSS face of aria-activedescendant (focus stays on search). */
+  :scope [role='option'][data-active] {
+    background-color: var(--ui-command-modal-active-bg);
+    color: var(--ui-command-modal-active-ink);
+  }
+  :scope [data-role='shortcut'] {
+    margin-inline-start: auto;
+    color: var(--ui-command-modal-muted-ink);
+    font-size: var(--ui-command-modal-caption-font);
+  }
+
+  /* TKT-0019 — the option's second line: a clamped, muted, single-line description below the title row.
+     flex-basis:100% is the wrap-forcing idiom (the sibling title-row content stays on line 1 as long as it
+     fits; this item never does, so it always starts a fresh flex line). min-inline-size:0 overrides the flex
+     default (min-width:auto, i.e. "never shrink below intrinsic content size") — without it, overflow/
+     text-overflow below would never actually engage and the line would just push the option wider instead of
+     clamping. Ink stays the muted role UNCONDITIONALLY (the [data-role=shortcut] precedent, two rules up) —
+     it does not re-color under [data-active]; the muted role is AA-proven against the active-bg wash by the
+     same composed-surface math tokens.test.ts already runs for --md-sys-color-neutral-on-surface-variant. */
+  :scope [data-role='description'] {
+    flex-basis: 100%;
+    min-inline-size: 0;
+    color: var(--ui-command-modal-muted-ink);
+    font-size: var(--ui-command-modal-caption-font);
+    overflow: hidden;
+    text-overflow: ellipsis;
+    white-space: nowrap;
+  }
+
+  /* ── Result-count live region — visually hidden, present to AT ───────────────────────────────────── */
+
+  :scope [data-part='status'] {
+    position: absolute;
+    inline-size: 1px;
+    block-size: 1px;
+    overflow: hidden;
+    clip-path: inset(50%);
+    white-space: nowrap;
+  }
+
+  /* ── Empty state (default row; an author [slot=empty]/[data-role=empty] overrides it) ────────────── */
+
+  :scope [data-part='empty'] {
+    padding-inline: var(--ui-command-modal-item-pad-inline);
+    padding-block: var(--ui-command-modal-item-pad-block);
+    color: var(--ui-command-modal-muted-ink);
+    cursor: default;
+    pointer-events: none;
+  }
+  :scope [data-part='empty'][hidden] {
+    display: none;
+  }
+
+  /* forced-colors (WHCM) — the active-option highlight becomes Highlight/HighlightText (not a faint bg that
+     vanishes under WHCM); the aria-activedescendant + [data-active] pairing is the non-color signifier, so no
+     color-only intent exists (the combo-box [data-active] forced-colors precedent). */
+  @media (forced-colors: active) {
+    :scope [data-part='search'] {
+      background-color: Field;
+      color: FieldText;
+      border-block-end-color: FieldText;
+    }
+    :scope [role='option'][data-active] {
+      background-color: Highlight;
+      color: HighlightText;
+      forced-color-adjust: none;
+    }
+  }
+}

package/dist/controls/command-modal/command-modal.d.ts

@@ -0,0 +1,42 @@
+import { UIElement, type ReactiveProps } from '../../dom/index.js';
+declare const props: {
+    open: {
+        reflect: true;
+        type: import("../../index.js").PropType<boolean>;
+        default: boolean;
+        attribute?: string | false;
+    };
+    label: {
+        reflect: true;
+        type: import("../../index.js").PropType<string>;
+        default: string;
+        attribute?: string | false;
+    };
+    placeholder: import("../../index.js").PropConfig<string>;
+    hotkey: import("../../index.js").PropConfig<string>;
+    filter: import("../../index.js").PropConfig<"substring" | "regex">;
+};
+export interface UICommandModalElement extends ReactiveProps<typeof props> {
+}
+export declare class UICommandModalElement extends UIElement {
+    #private;
+    static props: {
+        open: {
+            reflect: true;
+            type: import("../../index.js").PropType<boolean>;
+            default: boolean;
+            attribute?: string | false;
+        };
+        label: {
+            reflect: true;
+            type: import("../../index.js").PropType<string>;
+            default: string;
+            attribute?: string | false;
+        };
+        placeholder: import("../../index.js").PropConfig<string>;
+        hotkey: import("../../index.js").PropConfig<string>;
+        filter: import("../../index.js").PropConfig<"substring" | "regex">;
+    };
+    protected connected(): void;
+}
+export {};

package/dist/controls/command-modal/command-modal.js

@@ -0,0 +1,315 @@
+// command-modal.ts — UICommandModalElement, the CMD-K command palette (ADR-0125; command-modal.lld.md LLD-C1..C10;
+// command-modal.spec.md SPEC-R1..R10). A Pattern-class UIElement COORDINATOR — it nests a `ui-modal` for the whole
+// modal surface + dismissal contract (ADR-0017/0019/0020), and inside that modal renders a control-created
+// role=combobox search field over a control-created role=listbox list built from the consumer's author-declared
+// [role=option]/[role=group] children (ADR-0017 child-move), re-deriving `ui-combo-box`'s active-descendant
+// filter pattern (ADR-0085; the ~60 lines are re-implemented — combo-box's own methods are private). Choosing a
+// command emits `select` + closes. It owns no form value, no command registry, no router, and no recents state.
+//
+// Composes on: UIElement (the coordinator base — the ui-theme-provider/ui-form-provider precedent, no surface of
+// its own) + a nested ui-modal (a sanctioned sibling-control import, avatar.ts:25 precedent) + the scroll-fade
+// trait over the list viewport. No new package, no new trait, no new base class, no new event, no new geometry row.
+//
+// Layer: controls → dom + traits (inward-only ✓).
+import { UIElement, prop } from "../../dom/index.js";
+import { UIModalElement } from "../modal/modal.js"; // sanctioned sibling-control import — self-defines ui-modal (avatar.ts:25 precedent)
+import { scrollFade } from "../../traits/scroll-fade.js";
+let _nextId = 0;
+const props = {
+    // `open` — whether the palette is shown. Reflected + bindable two-way (drives the nested modal's `open`; synced
+    // back on the modal's platform dismissal). The ui-modal `open` shape.
+    open: { ...prop.boolean(false), reflect: true },
+    // `label` — the accessible name for BOTH the search field (reactive → aria-label) and the dialog (connect-time
+    // → forwarded onto the nested ui-modal). NOT reflected (an a11y hint, not a styling hook).
+    label: { ...prop.string(''), reflect: true },
+    // `placeholder` — the search field placeholder (shown via [data-empty]::before, the combo-box CSS read-back).
+    placeholder: prop.string(''),
+    // `hotkey` — the F2 opt-in convenience. '' = NO document listener. A non-empty chord (e.g. 'mod+k') binds ONE
+    // per-instance document keydown that toggles THIS instance's open. NOT a global singleton (ADR-0082).
+    hotkey: prop.string(''),
+    // `filter` — ADR-0127: the match-test mode. 'substring' (default) is the original, byte-identical hay.includes(q)
+    // test; 'regex' runs a case-insensitive RegExp test over the SAME haystack, falling back to the substring test
+    // for that keystroke only when the pattern is invalid (never throws — SPEC-R5 AC5). NOT reflected (a behavior
+    // switch, not a styling hook).
+    filter: prop.enum(['substring', 'regex'], 'substring'),
+};
+export class UICommandModalElement extends UIElement {
+    static props = props;
+    #modal = null;
+    #search = null;
+    #list = null;
+    #status = null;
+    #emptyRow = null;
+    #activeIdx = -1;
+    connected() {
+        const { modal, search, list } = this.#ensureParts();
+        // LLD-C3 — the nested-modal surface seam. open → modal.open + aria-expanded; the modal owns showModal/backdrop/
+        // Escape/focus-restore (NO own dialog machinery here — SPEC-R3 AC1).
+        this.effect(() => {
+            const isOpen = this.open;
+            modal.open = isOpen;
+            search.setAttribute('aria-expanded', String(isOpen));
+            if (isOpen)
+                requestAnimationFrame(() => search.focus()); // focus the search field on open (SPEC-R4 AC2)
+        });
+        // modal → model: a platform dismissal (Escape/backdrop) — the modal emits `close`+`toggle`; sync open back and
+        // re-emit at the palette level (the two-way `open` pattern one level up, ADR-0019). `open` is the discriminator:
+        // if it is still true, the platform closed it; guard the re-emit so a palette-driven close does not double-fire.
+        // stopPropagation is load-bearing here: `emit()` (element.ts:172) dispatches a BUBBLING CustomEvent, and the
+        // nested modal is a light-DOM DESCENDANT of the palette host — its bubbled `close` would otherwise ALSO reach
+        // any `close` listener on the palette itself, on top of this handler's own re-emit (a genuine double-fire; the
+        // fleet's first stateful nested-control relay, so no earlier precedent needed this guard).
+        this.listen(modal, 'close', (event) => {
+            if (this.open) {
+                event.stopPropagation();
+                this.open = false;
+                this.emit('close');
+                this.emit('toggle');
+            }
+        });
+        // The modal emits `close` THEN `toggle` as a pair (ADR-0019) — the `toggle` half needs the SAME containment
+        // (it always rides alongside `close`, never alone), so it is stopped unconditionally rather than re-guarded.
+        this.listen(modal, 'toggle', (event) => { event.stopPropagation(); });
+        // LLD-C4 — search field: reactive aria-label (falls back to a default name when label=''), placeholder.
+        this.effect(() => {
+            search.setAttribute('aria-label', this.label || 'Search commands');
+            search.setAttribute('data-placeholder', this.placeholder);
+        });
+        this.listen(search, 'input', () => { this.#filter(search.textContent ?? ''); });
+        this.listen(search, 'keydown', (event) => this.#onKeydown(event, search));
+        // LLD-C7 — option click commits (listen on the list; disabled/hidden guarded).
+        this.listen(list, 'click', (event) => {
+            const opt = event.target.closest('[role=option]');
+            if (!opt || opt.hidden || opt.getAttribute('aria-disabled') === 'true' || opt.hasAttribute('disabled'))
+                return;
+            this.#commit(opt);
+        });
+        // LLD-C8/C11 — the list is a bounded scroll viewport; wire the edge fade (combo-box/modal precedent).
+        scrollFade(this, { viewport: list });
+        // LLD-C10 — the opt-in hotkey: a TEARDOWN-RETURNING effect installs ONE document keydown ONLY while hotkey is
+        // non-empty; the returned cleanup aborts it on hotkey change AND on disconnect (scope-owned). '' ⇒ no listener
+        // is ever added (SPEC-R10 AC1) — NOT an always-on gated listener.
+        this.effect(() => {
+            const chord = this.hotkey;
+            if (chord === '')
+                return;
+            const controller = new AbortController();
+            document.addEventListener('keydown', (e) => {
+                if (this.#matchesChord(e, chord)) {
+                    e.preventDefault();
+                    this.open = !this.open;
+                }
+            }, { signal: controller.signal });
+            return () => controller.abort();
+        });
+        this.#filter(''); // initial: all options visible, status seeded, empty-state resolved
+    }
+    // LLD-C2 — create the nested modal + parts ONCE, child-move author items in. ORDER IS LOAD-BEARING (see the LLD
+    // §3 note: `ui-modal`'s #ensureDialog() moves its OWN children into its <dialog> at ITS connect, so the parts
+    // must go INTO the ui-modal element while it is still detached, and only THEN get appended to the host).
+    #ensureParts() {
+        if (this.#modal && this.#search && this.#list)
+            return { modal: this.#modal, search: this.#search, list: this.#list };
+        const seq = ++_nextId;
+        const search = document.createElement('div');
+        search.setAttribute('data-part', 'search');
+        search.setAttribute('contenteditable', 'plaintext-only');
+        search.setAttribute('role', 'combobox');
+        search.setAttribute('aria-autocomplete', 'list');
+        search.setAttribute('aria-expanded', 'false');
+        for (const a of ['autocorrect', 'autocapitalize', 'autocomplete'])
+            search.setAttribute(a, 'off');
+        search.setAttribute('spellcheck', 'false');
+        search.toggleAttribute('data-empty', true);
+        this.#search = search;
+        const list = document.createElement('div');
+        list.setAttribute('data-part', 'list');
+        list.setAttribute('data-box', ''); // adopt the shared container box-model (ADR-0046)
+        list.setAttribute('role', 'listbox');
+        list.setAttribute('tabindex', '-1');
+        list.id = `ui-cmd-list-${seq}`;
+        search.setAttribute('aria-controls', list.id);
+        this.#list = list;
+        // Child-move author [role=option]/[role=group] (and the [slot=empty]) into the list (ADR-0017). Stable ids
+        // for aria-activedescendant, assigned once.
+        let node = this.firstChild;
+        while (node) {
+            const next = node.nextSibling;
+            list.appendChild(node);
+            node = next;
+        }
+        let optSeq = 0;
+        for (const opt of list.querySelectorAll('[role=option]'))
+            if (!opt.id)
+                opt.id = `ui-cmd${seq}-opt-${++optSeq}`;
+        const status = document.createElement('div');
+        status.setAttribute('data-part', 'status');
+        status.setAttribute('aria-live', 'polite');
+        status.setAttribute('role', 'status'); // visually hidden in CSS
+        this.#status = status;
+        const emptyRow = document.createElement('div'); // default empty-state (LLD-C9) — an authored [slot=empty] wins
+        emptyRow.setAttribute('data-part', 'empty');
+        emptyRow.setAttribute('role', 'presentation');
+        emptyRow.textContent = 'No results';
+        emptyRow.hidden = true;
+        list.append(emptyRow);
+        this.#emptyRow = emptyRow;
+        // The nested ui-modal — accessible name forwarded from the INITIAL label (the modal forwards aria-label→dialog
+        // ONCE at its ensureDialog; a reactive label updates the SEARCH field name, not the dialog's — LLD §3 note).
+        const modal = document.createElement('ui-modal');
+        if (this.label)
+            modal.setAttribute('aria-label', this.label);
+        // TKT-0017 — the FIXED FRAME: pin the nested modal's frame dials to this control's own tokens so the
+        // palette holds a set width and a top anchor (the search field never moves as filtering resizes the
+        // list). Inline custom properties on the element we OWN — the slider --value-pct JS-seam exemption
+        // (family-coherence B); the var() references resolve through inheritance from :where(ui-command-modal).
+        modal.style.setProperty('--ui-modal-inline-size', 'var(--ui-command-modal-inline-size)');
+        modal.style.setProperty('--ui-modal-margin-block-start', 'var(--ui-command-modal-block-anchor)');
+        // ORDER: put the parts inside the modal BEFORE appending the modal to the host, so when ui-modal connects it
+        // moves search/status/list into its <dialog> together (identity preserved; our refs stay valid). LLD §3 note.
+        modal.append(search, status, list);
+        this.#modal = modal;
+        this.append(modal);
+        return { modal, search, list };
+    }
+    // LLD-C6 — the visible+enabled option set; active-descendant move (focus NEVER leaves the search field).
+    #options() { return this.#list ? [...this.#list.querySelectorAll('[role=option]')] : []; }
+    #getVisibleOptions() {
+        return this.#options().filter((o) => !o.hidden && o.getAttribute('aria-disabled') !== 'true' && !o.hasAttribute('disabled'));
+    }
+    #setActive(idx) {
+        const opts = this.#getVisibleOptions();
+        for (const o of opts)
+            o.removeAttribute('data-active');
+        if (idx < 0 || idx >= opts.length) {
+            this.#activeIdx = -1;
+            this.#search?.removeAttribute('aria-activedescendant');
+            return;
+        }
+        this.#activeIdx = idx;
+        const opt = opts[idx];
+        opt.setAttribute('data-active', '');
+        if (!opt.id)
+            opt.id = `ui-cmd-opt-${++_nextId}`; // lazy stable id for options added after connect (combo-box.ts:436 guard)
+        // scrollIntoView is absent in jsdom (the status-stream.ts precedent) — a real browser always has it.
+        if (typeof opt.scrollIntoView === 'function')
+            opt.scrollIntoView({ block: 'nearest' });
+        this.#search?.setAttribute('aria-activedescendant', opt.id);
+    }
+    #moveActive(delta) {
+        const opts = this.#getVisibleOptions();
+        if (opts.length === 0)
+            return;
+        const next = this.#activeIdx < 0 ? (delta === 1 ? 0 : opts.length - 1) : (this.#activeIdx + delta + opts.length) % opts.length;
+        this.#setActive(next);
+    }
+    // The option's PRIMARY label text — excludes decorative descendants ([data-role=shortcut]/[data-role=icon]/
+    // aria-hidden and <ui-icon>) so a `⌘H` shortcut is neither in select.detail.label nor matchable by the filter
+    // (SPEC §2 Item label). TKT-0019 — [data-role=description] joins the exclusion for the SAME reason (`select`
+    // detail.label and the `^ui-` anchored labelText must stay the title, never the second line); unlike the
+    // shortcut this is a labelText-ONLY exclusion — the description carries no aria-hidden and stays fully in
+    // the accessibility tree (a visible line SHOULD be announced; only its ROLE in this control's own label/
+    // filter text is excluded). Filterability is unaffected — the site's own data-keywords already folds the
+    // description text into the (separate) filter haystack. Iterates childNodes: skips decorative element
+    // children, keeps text + real label spans.
+    #labelText(opt) {
+        let s = '';
+        for (const node of opt.childNodes) {
+            if (node.nodeType === Node.ELEMENT_NODE) {
+                const el = node;
+                if (el.tagName === 'UI-ICON' || el.matches('[data-role=shortcut],[data-role=icon],[data-role=description],[aria-hidden=true]'))
+                    continue;
+                s += el.textContent ?? '';
+            }
+            else if (node.nodeType === Node.TEXT_NODE) {
+                s += node.textContent ?? '';
+            }
+        }
+        return s.trim();
+    }
+    // LLD-C5 — substring/keyword filter (or ADR-0127 regex, mode-gated); hide empty group headings; reset active;
+    // update status + empty-state.
+    #filter(text) {
+        const raw = text.trim();
+        const q = raw.toLowerCase();
+        // ADR-0127 — build the regex ONCE per keystroke, not per option, from the RAW (un-lowercased) text: the 'i'
+        // flag alone delivers case-insensitivity (SPEC-R5 AC4) — lowercasing the PATTERN text first would corrupt
+        // case-sensitive regex metacharacters (\D/\S/\W/\B → \d/\s/\w/\b), a materially different match, not merely
+        // a case change. An invalid pattern throws a SyntaxError at `new RegExp`, caught here and never retried
+        // per-option, then EVERY option falls back to the substring test for this keystroke (SPEC-R5 AC5 — degrade
+        // gracefully, never throw, never surface an error to the user).
+        let re = null;
+        if (this.filter === 'regex' && raw !== '') {
+            try {
+                re = new RegExp(raw, 'i');
+            }
+            catch {
+                re = null;
+            } // invalid pattern ⇒ fall back to substring below
+        }
+        for (const opt of this.#options()) {
+            const hay = (this.#labelText(opt) + ' ' + (opt.getAttribute('data-keywords') ?? '')).toLowerCase();
+            const matches = q === '' || (re ? re.test(hay) : hay.includes(q)); // item label + data-keywords ONLY (shortcut excluded — SPEC-R5 AC1)
+            opt.hidden = !matches;
+        }
+        for (const group of this.#list?.querySelectorAll('[role=group]') ?? []) {
+            group.hidden = ![...group.querySelectorAll('[role=option]')].some((o) => !o.hidden);
+        }
+        this.#setActive(-1);
+        const n = this.#getVisibleOptions().length;
+        if (this.#status)
+            this.#status.textContent = n === 0 ? 'No results' : `${n} result${n === 1 ? '' : 's'}`;
+        // Empty-state (LLD-C9): an author [slot=empty]/[data-role=empty] child was child-moved into the list at
+        // connect, so the CONTROL must toggle its visibility — it is a bare attribute in light DOM, nothing hides it
+        // implicitly. The author element wins over the default row; both gate on the visible count (SPEC-R8).
+        const authorEmpty = this.#list?.querySelector('[slot=empty],[data-role=empty]') ?? null;
+        if (authorEmpty)
+            authorEmpty.hidden = n > 0;
+        if (this.#emptyRow)
+            this.#emptyRow.hidden = n > 0 || authorEmpty !== null;
+        this.#search?.toggleAttribute('data-empty', text === '');
+    }
+    #onKeydown(e, _search) {
+        // NO Escape branch — the nested modal owns dismissal (SPEC-R9). Only Arrow/Home/End/Enter here.
+        if (e.key === 'ArrowDown') {
+            e.preventDefault();
+            this.#moveActive(1);
+        }
+        else if (e.key === 'ArrowUp') {
+            e.preventDefault();
+            this.#moveActive(-1);
+        }
+        else if (e.key === 'Home') {
+            e.preventDefault();
+            this.#setActive(0);
+        }
+        else if (e.key === 'End') {
+            e.preventDefault();
+            this.#setActive(this.#getVisibleOptions().length - 1);
+        }
+        else if (e.key === 'Enter') {
+            e.preventDefault();
+            const opt = this.#getVisibleOptions()[this.#activeIdx];
+            if (opt)
+                this.#commit(opt);
+        }
+    }
+    // LLD-C7 — emit select {value,label,group} then close. NO router import, NO command bus.
+    #commit(opt) {
+        const label = this.#labelText(opt); // primary label (shortcut/icon excluded — SPEC-R6)
+        const value = opt.getAttribute('value') ?? label;
+        const group = opt.closest('[role=group]')?.querySelector('[data-role=group-label]')?.textContent?.trim() ?? '';
+        this.emit('select', { value, label, group });
+        this.open = false; // closes the nested modal; the modal's `close` fires with open already false ⇒ no re-emit
+    }
+    #matchesChord(e, chord) {
+        // Minimal chord parse: 'mod+k' → (metaKey||ctrlKey) && key==='k'. Extend per the builder's needs; the CONTRACT
+        // is per-instance + preventDefault + toggle (SPEC-R10), not an exhaustive chord grammar.
+        const parts = chord.toLowerCase().split('+');
+        const key = parts.at(-1);
+        const needMod = parts.includes('mod');
+        return (!needMod || e.metaKey || e.ctrlKey) && e.key.toLowerCase() === key;
+    }
+}
+if (!customElements.get('ui-command-modal'))
+    customElements.define('ui-command-modal', UICommandModalElement);