@agent-ui-kit/components 0.0.3

package/dist/controls/list/list.d.ts

@@ -0,0 +1,84 @@
+import type { ReactiveProps } from '../../dom/index.js';
+import { UIContainerElement } from '../../dom/container.js';
+declare const props: {
+    align: {
+        default: "stretch";
+        reflect: true;
+        type: import("../../index.js").PropType<"end" | "start" | "center" | "stretch" | "baseline">;
+        attribute?: string | false;
+    };
+    justify: {
+        reflect: true;
+        type: import("../../index.js").PropType<"end" | "start" | "center" | "between" | "around" | "evenly">;
+        default: "end" | "start" | "center" | "between" | "around" | "evenly";
+        attribute?: string | false;
+    };
+    gap: {
+        reflect: true;
+        type: import("../../index.js").PropType<"none" | "sm" | "md" | "lg" | "xs" | "xl" | "2xl">;
+        default: "none" | "sm" | "md" | "lg" | "xs" | "xl" | "2xl";
+        attribute?: string | false;
+    };
+    wrap: {
+        reflect: true;
+        type: import("../../index.js").PropType<boolean>;
+        default: boolean;
+        attribute?: string | false;
+    };
+    elevation: {
+        reflect: true;
+        type: import("../../index.js").PropType<"0" | "1" | "2" | "3" | "-3" | "-2" | "-1">;
+        default: "0" | "1" | "2" | "3" | "-3" | "-2" | "-1";
+        attribute?: string | false;
+    };
+    brightness: {
+        reflect: true;
+        type: import("../../index.js").PropType<"0" | "1" | "2" | "3" | "-3" | "-2" | "-1">;
+        default: "0" | "1" | "2" | "3" | "-3" | "-2" | "-1";
+        attribute?: string | false;
+    };
+};
+export interface UIListElement extends ReactiveProps<typeof props> {
+}
+export declare class UIListElement extends UIContainerElement {
+    static props: {
+        align: {
+            default: "stretch";
+            reflect: true;
+            type: import("../../index.js").PropType<"end" | "start" | "center" | "stretch" | "baseline">;
+            attribute?: string | false;
+        };
+        justify: {
+            reflect: true;
+            type: import("../../index.js").PropType<"end" | "start" | "center" | "between" | "around" | "evenly">;
+            default: "end" | "start" | "center" | "between" | "around" | "evenly";
+            attribute?: string | false;
+        };
+        gap: {
+            reflect: true;
+            type: import("../../index.js").PropType<"none" | "sm" | "md" | "lg" | "xs" | "xl" | "2xl">;
+            default: "none" | "sm" | "md" | "lg" | "xs" | "xl" | "2xl";
+            attribute?: string | false;
+        };
+        wrap: {
+            reflect: true;
+            type: import("../../index.js").PropType<boolean>;
+            default: boolean;
+            attribute?: string | false;
+        };
+        elevation: {
+            reflect: true;
+            type: import("../../index.js").PropType<"0" | "1" | "2" | "3" | "-3" | "-2" | "-1">;
+            default: "0" | "1" | "2" | "3" | "-3" | "-2" | "-1";
+            attribute?: string | false;
+        };
+        brightness: {
+            reflect: true;
+            type: import("../../index.js").PropType<"0" | "1" | "2" | "3" | "-3" | "-2" | "-1">;
+            default: "0" | "1" | "2" | "3" | "-3" | "-2" | "-1";
+            attribute?: string | false;
+        };
+    };
+    protected connected(): void;
+}
+export {};

package/dist/controls/list/list.js

@@ -0,0 +1,48 @@
+// list.ts — UIListElement, the semantic vertical-stack layout primitive (goals.md §G9 / ADR-0016 cl.3;
+// decomp g9-containers slice s5). BEHAVIOUR + props + the list role + self-define ONLY; the flex layout +
+// surface seam live in list.css.
+//
+// `ui-list` is a `ui-column` SPECIALIZATION that adds LIST SEMANTICS: it is a `display:flex` vertical stack
+// (the surface base `UIContainerElement`, ADR-0015 — NOT form-associated) whose host carries the ARIA
+// `role="list"`. The role is set THROUGH the protected `internals` (the family discipline, ADR-0010 /
+// element.ts) — NEVER a host `role` attribute, so the host stays free of `role`/`aria-*`. The list imposes
+// NO item element: its children are the list items, composed by the agent as a ChildList (the A2UI child
+// model) — so `render()` stays the inherited VOID (returning nothing → the host render effect commits
+// nothing → the user's light-DOM children are never clobbered).
+//
+// It consumes the two shared spreadable prop sets the container family declares (no static-props prototype
+// merge — the ADR-0013 `formProps` precedent): `surfaceProps` (elevation/brightness, the surface axes) and
+// `flexProps` (align/justify/gap/wrap, the A2UI-faithful layout grammar). The literal-union → CSS-keyword
+// mapping is a role-pure repoint in list.css's `@scope` block; the base owns no flex/surface CSS.
+//
+// IS an A2UI catalog type — `List` (ADR-0087 Fork A, Wave C; supersedes ADR-0016's earlier non-catalog
+// exclusion) renders to `ui-list`. Reach for `List` over `Column` for a homogeneous, itemized collection where
+// list semantics matter to assistive tech; reach for `Row`/`Column` for a heterogeneous arrangement, and
+// `Grid` when the layout should reflow its column count responsively (a2ui-catalog.spec.md §5.2).
+//
+// Imports the surface base from the same-layer dom `../../dom/container.ts` (not re-exported from the dom
+// barrel until s12) + the typed-prop authoring types from the dom barrel. `controls → dom` is the allowed
+// import direction (the layering law: reactive ← dom ← controls).
+import { UIContainerElement } from "../../dom/container.js";
+// The full prop surface = the two shared spreadable sets folded into this control's own `static props` (each
+// already carries `reflect: true` from the base, so the `[elevation]`/`[align]`/etc. attribute selectors in
+// list.css apply to JS-set values too). No re-declaration of the surface/flex grammar — one home, ADR-0016.
+// ADR-0030: `align` default overridden from `start` to `stretch` (parity with ui-column — a ui-list IS a
+// ui-column specialization; its cross axis is inline/width; children should fill the width by default).
+const props = {
+    ...UIContainerElement.surfaceProps, // elevation / brightness (ADR-0015)
+    ...UIContainerElement.flexProps, // align / justify / gap / wrap (ADR-0016) — a vertical stack
+    align: { ...UIContainerElement.flexProps.align, default: 'stretch' }, // ADR-0030: override default ONLY; `as const` preserves the literal-union type (prevents string widening)
+};
+export class UIListElement extends UIContainerElement {
+    static props = props;
+    connected() {
+        // LIST SEMANTICS — `role=list` rides the host's ElementInternals, never a host `role` attribute (the
+        // family discipline). A constant semantic role, so it is set DIRECTLY (not in an effect); re-set on each
+        // connect (idempotent). The children are the list items — no item element is imposed, and `render()`
+        // stays void so the ChildList children flow through untouched.
+        this.internals.role = 'list';
+    }
+}
+if (!customElements.get('ui-list'))
+    customElements.define('ui-list', UIListElement);

package/dist/controls/menu/menu.css

@@ -0,0 +1,195 @@
+/* menu.css — ui-menu, the single-file overlay-menu stylesheet (ADR-0003 · overlay-controller.lld.md).
+ * Two clearly-SECTIONED blocks, mirroring popover.css / modal.css:
+ *
+ *   [1] TOKEN BLOCK  — `:where(ui-menu)` (specificity 0,0,0) sets the menu's OWN default surface
+ *       tokens and DECLARES the `--ui-menu-*` chain from the colour roles (`--md-sys-color-{family}-{role}`)
+ *       and the dimensions (`--md-sys-space-*` / `--md-sys-shape-corner-base`). Raw `--md-sys-color-*` roles enter ONLY here;
+ *       `@scope` never reads them.
+ *   [2] STYLES BLOCK — `@scope (ui-menu)` CONSUMES only the role-pure `--ui-menu-*` chain.
+ *       The host is `display: contents` — a logical overlay wrapper that generates no box.
+ *       The trigger child stays in the document flow (the author provides it; we mark it but do
+ *       not style it — it is the author's to own). The panel part (`[data-part="panel"]`) is the
+ *       Container/surface: bg from `--ui-menu-bg`, `--md-sys-shape-corner-base`, `--md-sys-space-xs` padding
+ *       shell — NOT a control height (`--md-sys-height-*` is never read by the panel itself).
+ *       Menu items (`[role="menuitem"]`) use the LEGACY ITEM-PAD geometry (§4.6/§5.1 of the
+ *       listbox-roving LLD): vertical block padding (`--md-sys-space-xs`) + inline padding
+ *       (`--md-sys-space-md`), giving a comfortable row height without a fixed --md-sys-height-* frame.
+ *       A `min-inline-size` floor prevents panel collapse (ADR-0021 trap). A
+ *       `forced-color-adjust` block keeps the surface and highlighted items visible in WHCM.
+ *
+ * Standalone stylesheet — NOT injected from menu.ts (behaviour-only `.ts`, no runtime injection
+ * per plan §2). Linked via the component-styles barrel (s12); the barrel @imports foundation
+ * roles FIRST.
+ */
+
+/* ════════ [1] TOKEN BLOCK — :where(ui-menu) declares the surface default + --ui-menu-* ════════ */
+
+:where(ui-menu) {
+  /* Surface plane — the popup panel is an opaque neutral surface (like popover / card). */
+  --ui-menu-bg: var(--md-sys-color-neutral-surface);
+  --ui-menu-ink: var(--md-sys-color-neutral-on-surface);
+
+  /* Frame */
+  --ui-menu-outline: var(--md-sys-color-neutral-outline-variant);
+  --ui-menu-radius: var(--md-sys-shape-corner-base);
+
+  /* Shell spacing — panel-class geometry (Container/surface; NOT a control height). */
+  --ui-menu-padding: var(--md-sys-space-xs);
+
+  /* Size floor — prevents collapse when the menu has no items or all items are narrow (ADR-0021
+     lesson: a surface that can be empty / narrow needs a min-inline-size; the JS positioning
+     controller measures bounds on open, so a zero-width panel would mis-position too). */
+  --ui-menu-min-inline-size: 10rem;
+
+  /* Menu-item row geometry — the LEGACY ITEM-PAD (§4.6/§5.1, NOT the widget-box height).
+     A row is: vertical block padding + inline padding, giving a comfortable reading row.
+     STRUCTURAL DIVERGENCE from ui-select/ui-combo-box (flagged, not forced to fit — 2026-07-06
+     size-carrying-model pass): ui-menu has NO `[size]` attribute and renders NO trigger geometry
+     at all — the trigger is entirely author-owned content (menu.ts marks it but never sizes it,
+     unlike select's own <button data-part=trigger>). There is no `--ui-menu-height` to derive
+     against and no h/2 alignment target, so the select "listbox-padding + option-inline == h/2"
+     law does not have an analogue here. The item-pad stays its own fixed (`--md-sys-space-*`-scaled)
+     register — correct per ADR-0043 cl.5 / geometry.md's Pattern-class row, not a gap to close.
+     Adding a `[size]` axis to ui-menu would be a new-attribute contract change (its own decomp/ADR),
+     not a CSS-only geometry fix. */
+  --ui-menu-item-pad-block: var(--md-sys-space-xs);
+  --ui-menu-item-pad-inline: var(--md-sys-space-md);
+  --ui-menu-item-font: var(--md-sys-font-md);
+
+  /* Item row block-size — the REAL rendered row height (font + 2×block-pad; `line-height: 1` on
+     the item rule below, the same local derivation choice select/combo-box's option rows already
+     make, is what keeps this exact rather than font-metric-dependent). Feeds --ui-menu-max-block-size
+     below (TKT-0027) — there is no --ui-menu-height to reuse (the note above), so this is the
+     control's OWN public row-height fact, the item-pad siblings' geometry class. */
+  --ui-menu-item-block-size: calc(var(--ui-menu-item-font) + 2 * var(--ui-menu-item-pad-block));
+
+  /* Panel max-block-size (TKT-0027) — public dial, default min(50vh, 12 real item rows): the
+     smaller of half the viewport or a scannable dozen rows, so a short list never over-reserves
+     and a long list caps at a page instead of the old flat 40vh magic number. 12 rows = 12 item
+     boxes + 13 inset margins (leading + 11 collapsed inter-row + trailing) — the panel is
+     `[data-box]` (a BFC, container-box.css), which collapses adjacent siblings' block margins to
+     ONE inset rather than doubling them. Rides density naturally: --ui-menu-item-block-size reads
+     --md-sys-space-xs (rhythm-family, density-linked), so a denser/spacious theme repoints this dial
+     for free without a special case here. + 2px — the panel's border-box: max-block-size caps the
+     BORDER box (box-sizing: border-box below), but the row math above computed the CONTENT box
+     (12 rows + 13 insets, no border term) — without this the 12th row overflowed its own cap by
+     exactly the 1px+1px border width (FIXED 2026-07-12, TKT-0027 browser-leg finding). */
+  --ui-menu-max-block-size: min(50vh, calc(12 * var(--ui-menu-item-block-size) + 13 * var(--ui-box-inset, 0.375rem) + 2px));
+
+  /* One-level nested radius: item corners inset from the panel corner (ADR-0018). FIXED
+     (2026-07-06): was subtracting --md-sys-space-xs (4px), a DIFFERENT value than the --ui-box-inset
+     (6px, container-box.css) actually used for the item's own margin below — the nested-radius
+     law (ADR-0018: child radius = parent radius − the REAL inset) was inset-inconsistent. Now
+     subtracts the same --ui-box-inset the row margin reads. */
+  --ui-menu-item-radius: calc(var(--md-sys-shape-corner-base) - var(--ui-box-inset, 0.375rem));
+
+  /* Item state colours — hover fill + disabled muted ink.
+     FIXED (2026-07-07, overlay-list family-consistency pass): was --md-sys-color-neutral-tint-dimmer
+     (a translucent 10% alpha wash) — the ONLY row-hover in the fleet using the tint ladder; every
+     other interactive-row/control hover (ui-select's option, ui-button, ui-text-field, ui-checkbox,
+     ui-switch, ui-calendar's cell) reads the solid, scheme-inverting --md-sys-color-neutral-surface-high
+     role. ui-menu's translucent wash read as a visibly weaker/different hover than ui-select's listbox
+     right next to it (the reported inconsistency) — converged onto the existing fleet-wide role,
+     no new token minted. */
+  --ui-menu-item-bg-hover: var(--md-sys-color-neutral-surface-high);
+  --ui-menu-item-ink-disabled: var(--md-sys-color-neutral-outline);   /* muted, not invisible */
+
+}
+
+/* ════════ [2] STYLES BLOCK — @scope (ui-menu) consumes ONLY --ui-menu-* ════════ */
+
+@scope (ui-menu) {
+  /* The host is a logical disclosure wrapper — it generates no box; only the trigger (in flow)
+     and the panel (in the top layer when open) render as visible surfaces. */
+  :scope {
+    display: contents;
+  }
+
+  /* The menu panel — Container/surface in the Popover API top layer.
+     `position: fixed` and the inset are set by the JS positioning controller (overlay.ts) on open;
+     we do NOT fix a position here. `margin: 0` prevents UA-default centering from conflicting with
+     the controller's explicit inset. The panel is hidden by the UA `[popover]` rule until
+     showPopover() places it in the top layer — our CSS only applies when it is visible. */
+  :scope > [data-part='panel'] {
+    box-sizing: border-box;
+    margin: 0;
+    min-inline-size: var(--ui-menu-min-inline-size);
+    max-block-size: var(--ui-menu-max-block-size); /* TKT-0027 — public dial, default min(50vh, 12 item rows) */
+    overflow-y: auto;
+    padding: 0; /* the box-model menuitem margins provide the inset (container-box.css); no shell padding */
+
+    background-color: var(--ui-menu-bg);
+    color: var(--ui-menu-ink);
+    border: 1px solid var(--ui-menu-outline);
+    border-radius: var(--ui-menu-radius);
+  }
+
+  /* Menu-item rows — the LEGACY ITEM-PAD row (§4.6/§5.1). NOT --md-sys-height-* (a menuitem is a
+     list row, not a single-line fixed-height control widget). cursor + user-select mirror the
+     interactive-row standard (pointer for items, not-allowed for disabled). */
+  :scope [role='menuitem'] {
+    box-sizing: border-box;
+    display: flex;
+    align-items: center;
+    margin: var(--ui-box-inset, 0.375rem); /* the box-model inset — 6px from the panel edge + between rows */
+    padding-block: var(--ui-menu-item-pad-block);
+    padding-inline: var(--ui-menu-item-pad-inline);
+    /* line-height: 1 makes the --ui-menu-item-block-size calc exact (font + 2×pad == the rendered
+       row) — the same local derivation choice select/combo-box's option rows already make for the
+       identical reason (TKT-0027: a font-metric-dependent 'normal' line-height would make the
+       12-fit/13-scroll cross-engine proof flaky). */
+    line-height: 1;
+    border-radius: var(--ui-menu-item-radius);
+    font-size: var(--ui-menu-item-font);
+    color: var(--ui-menu-ink);
+    cursor: default;
+    user-select: none;
+    -webkit-user-select: none; /* WebKit honours selection-none only via the prefix */
+  }
+
+  /* Hover state — the fleet-wide solid elevated-surface fill (no border — like native menus). */
+  :scope [role='menuitem']:not([disabled]):not([aria-disabled='true']):hover {
+    background-color: var(--ui-menu-item-bg-hover);
+  }
+
+  /* Keyboard focus ring (ADR-0009) — reads fleet tokens directly (the documented family exception:
+     every control draws the identical ring; see button.css for the precedent). Outset (positive
+     offset), matching ui-select's option ring and the fleet-wide convention (button/checkbox/
+     text-field/select/etc. all use the positive offset; only ui-tabs' inline tab-strip is inset,
+     for a different reason — adjacent siblings with no margin). FIXED (2026-07-07,
+     family-consistency pass): was the inset (negative-offset) treatment — the item's own
+     --ui-box-inset margin (≥6px) comfortably clears an outset ring (width+offset = 4px) without
+     touching the panel edge or a neighbouring row. */
+  :scope [role='menuitem']:not([disabled]):not([aria-disabled='true']):focus-visible {
+    outline: var(--md-sys-state-focus-ring-width) solid var(--md-sys-color-focus-ring);
+    outline-offset: var(--md-sys-state-focus-ring-offset);
+  }
+
+  /* Disabled items — muted ink, no pointer, inert to hover/focus. */
+  :scope [role='menuitem'][disabled],
+  :scope [role='menuitem'][aria-disabled='true'] {
+    color: var(--ui-menu-item-ink-disabled);
+    cursor: not-allowed;
+    pointer-events: none;
+  }
+
+  /* Forced-colors (WHCM) — the surface, frame, and ink survive as system Canvas/CanvasText.
+     Hover + focus items use system Highlight/HighlightText so they remain visible.
+     `forced-color-adjust: none` on the item hover/focus block keeps the fill from being
+     overridden (the platform would discard the solid surface-high fill; we commit to Highlight instead). */
+  @media (forced-colors: active) {
+    :scope > [data-part='panel'] {
+      background-color: Canvas;
+      color: CanvasText;
+      border-color: CanvasText;
+    }
+
+    :scope [role='menuitem']:not([disabled]):not([aria-disabled='true']):hover,
+    :scope [role='menuitem']:not([disabled]):not([aria-disabled='true']):focus-visible {
+      forced-color-adjust: none;
+      background-color: Highlight;
+      color: HighlightText;
+      outline: none;
+    }
+  }
+}

package/dist/controls/menu/menu.d.ts

@@ -0,0 +1,44 @@
+import { type ReactiveProps } from '../../dom/index.js';
+import { UIElement } from '../../dom/index.js';
+import { type OverlayHandle } from '../../traits/overlay.js';
+declare const props: {
+    open: {
+        reflect: true;
+        type: import("../../index.js").PropType<boolean>;
+        default: boolean;
+        attribute?: string | false;
+    };
+    placement: {
+        reflect: true;
+        type: import("../../index.js").PropType<"bottom-start" | "bottom-end" | "top-start" | "top-end" | "left-start" | "left-end" | "right-start" | "right-end">;
+        default: "bottom-start" | "bottom-end" | "top-start" | "top-end" | "left-start" | "left-end" | "right-start" | "right-end";
+        attribute?: string | false;
+    };
+};
+export interface UIMenuElement extends ReactiveProps<typeof props> {
+}
+export declare class UIMenuElement extends UIElement {
+    #private;
+    static props: {
+        open: {
+            reflect: true;
+            type: import("../../index.js").PropType<boolean>;
+            default: boolean;
+            attribute?: string | false;
+        };
+        placement: {
+            reflect: true;
+            type: import("../../index.js").PropType<"bottom-start" | "bottom-end" | "top-start" | "top-end" | "left-start" | "left-end" | "right-start" | "right-end">;
+            default: "bottom-start" | "bottom-end" | "top-start" | "top-end" | "left-start" | "left-end" | "right-start" | "right-end";
+            attribute?: string | false;
+        };
+    };
+    /**
+     * Protected overlay handle — accessible to test probes (C10 idempotent-cleanup DoD).
+     * Replaced on each reconnect (connected() re-runs); the old handle's cleanup fires via the
+     * scope effect disposer at disconnect before this is re-assigned.
+     */
+    protected _overlayHandle: OverlayHandle | null;
+    protected connected(): void;
+}
+export {};

package/dist/controls/menu/menu.js

@@ -0,0 +1,248 @@
+// menu.ts — UIMenuElement, the Wave-4 S3 menu overlay control
+// (control-suite-wave4-overlay.decomp.md S3 · overlay-controller.lld.md LLD-C1..C4 · ADR-0043).
+//
+// Composition: a `UIElement` host + `overlay()` (Popover API + JS positioning + two-way `open`) +
+// `rovingFocus()` over [role=menuitem] items (Arrow roves focus; type-ahead; Enter/click commits).
+// NOT form-associated — ui-menu emits an action (`select` with {value,index}), carrying NO form
+// value. Like ui-tabs (non-value commit→select), but in an overlay. A trigger (first element child,
+// marked `data-part="trigger"`) opens the panel; commit closes it.
+//
+// Anatomy (light-DOM, created once — idempotent across reconnect):
+//   <ui-menu>
+//     <button data-part="trigger" aria-expanded="…" aria-controls="ui-menu-panel-N"
+//             aria-haspopup="menu">…</button>
+//     <div data-part="panel" role="menu" popover="auto" id="ui-menu-panel-N" tabindex="-1">
+//       <!-- author-provided item children moved in at connect; auto-get role=menuitem if absent -->
+//       <div role="menuitem" tabindex="-1">Item 1</div>
+//       <div role="menuitem" tabindex="-1">Item 2</div>
+//     </div>
+//   </ui-menu>
+//
+// Two-way `open` (ADR-0019): a scope-owned effect drives model→overlay; the overlay controller's
+// `close` event listener drives overlay→model (light-dismiss syncs the prop back). The overlay
+// trait emits `close` + `toggle` on EVERY real open-state transition — platform dismiss (Escape /
+// outside-click), a commit's programmatic close, or a model-driven `open=false` alike (ADR-0101 —
+// native ToggleEvent timing fidelity; the trait is the sole, uniform announcer for the family).
+//
+// Events: `select` ({value, index}) on commit; `toggle` + `close` on every real close, including a
+// commit's programmatic close (ADR-0101 — see traits/overlay.ts).
+//
+// ARIA: host has no explicit role (logical wrapper); panel has `role=menu` set on the div part
+// directly (a created part, not the host — the FACE rule "internals.role, never host attributes"
+// applies to the HOST element; direct parts use setAttribute). The trigger gets `aria-expanded`,
+// `aria-controls`, `aria-haspopup="menu"`. Item children auto-get `role=menuitem` if absent.
+//
+// `controls → dom → traits` is the one allowed import direction.
+import { prop } from "../../dom/index.js";
+import { UIElement } from "../../dom/index.js";
+import { overlay } from "../../traits/overlay.js";
+import { rovingFocus } from "../../traits/roving-focus.js";
+import { scrollFade } from "../../traits/scroll-fade.js";
+// ── Placement enum values (mirrors the OverlayPlacement union from overlay.ts) ─────────────────
+const PLACEMENTS = [
+    'bottom-start',
+    'bottom-end',
+    'top-start',
+    'top-end',
+    'left-start',
+    'left-end',
+    'right-start',
+    'right-end',
+];
+// ── Props ────────────────────────────────────────────────────────────────────────────────────────
+const props = {
+    // `open` — whether the menu panel is shown. Reflected + BINDABLE: the catalog declares
+    // value:{prop:'open',event:'toggle'} so the renderer two-way-binds it (ADR-0019). Drives the
+    // overlay handle via a scope-owned effect.
+    open: { ...prop.boolean(false), reflect: true },
+    // `placement` — the preferred panel placement relative to the trigger (captured once per
+    // connection; changing it after connect takes effect on the next reconnect).
+    placement: { ...prop.enum(PLACEMENTS, 'bottom-start'), reflect: true },
+};
+// ── Module-level stable-id counter (one per panel, never reused) ─────────────────────────────────
+let _nextPanelId = 0;
+export class UIMenuElement extends UIElement {
+    static props = props;
+    // The control-created panel PART — created ONCE (idempotent guard in #ensureParts()) and
+    // NEVER re-created. Persists through disconnect/reconnect (like the modal/popover panel parts).
+    #panel = null;
+    /**
+     * Protected overlay handle — accessible to test probes (C10 idempotent-cleanup DoD).
+     * Replaced on each reconnect (connected() re-runs); the old handle's cleanup fires via the
+     * scope effect disposer at disconnect before this is re-assigned.
+     */
+    _overlayHandle = null;
+    connected() {
+        const { panel, trigger, items } = this.#ensureParts();
+        // Wire the overlay controller (LLD-C1..C4) — popover=auto (Escape + outside-click
+        // light-dismiss), focusOnOpen=true (focus moves INTO the menu on open, restored to trigger
+        // on close by the overlay handle).
+        const handle = overlay(this, {
+            popup: panel,
+            anchor: trigger,
+            placement: this.placement,
+            auto: true,
+            focusOnOpen: true,
+        });
+        this._overlayHandle = handle;
+        // Trigger click → toggle the panel.
+        //
+        // ADR-0101 erratum fix: flip the PROP (`this.open`), not `handle.toggle()` directly — see
+        // select.ts's click handler for the full race trace (identical mechanics here: a raw
+        // `handle.toggle()` never writes `this.open`, so `#commit`'s later `this.open = false` was a
+        // same-value no-op and the panel stuck open after picking a menu item — ticket #28's residual).
+        // The prop is the single source of truth; the model→overlay effect below drives
+        // `handle.open()`/`handle.close()` and the trait announces (ADR-0101) — the combo-box pattern.
+        this.listen(trigger, 'click', () => {
+            this.open = !this.open;
+        });
+        // overlay→model: when the Popover API light-dismisses (Escape / outside-click), the overlay
+        // controller emits `close` on the host. Sync the prop back so the two-way bind stays
+        // consistent (ADR-0019 — the renderer reads `toggle`, but `open` must be false by then).
+        this.listen(this, 'close', () => {
+            this.open = false;
+        });
+        // model→overlay: a scope-owned effect drives open/close from the prop and keeps aria-expanded
+        // in sync. Runs immediately on creation (eager first run): open=false → handle.close() (no-op,
+        // not yet open) + aria-expanded='false'. Re-runs whenever this.open changes.
+        this.effect(() => {
+            const isOpen = this.open;
+            if (isOpen)
+                handle.open();
+            else
+                handle.close();
+            trigger.setAttribute('aria-expanded', String(isOpen));
+        });
+        // Delegated click on the panel → commit the clicked menuitem. Handles mouse clicks AND
+        // keyboard-activated button items (Enter/Space on a <button> fires a native click event).
+        this.listen(panel, 'click', (ev) => {
+            const target = ev.target;
+            const list = items();
+            const index = list.findIndex((item) => item === target || item.contains(target));
+            if (index === -1)
+                return;
+            const item = list[index];
+            if (item.hasAttribute('disabled') || item.getAttribute('aria-disabled') === 'true')
+                return;
+            this.#commit(index, item);
+        });
+        // Keydown on the panel → Enter/Space on focused menuitems that are NOT native buttons or
+        // links (those convert Enter/Space → click natively, which our click listener then commits).
+        // For non-interactive elements (`<div role=menuitem>`), we must commit on keydown.
+        // DELIBERATE selectionCommit bypass (ratified, TKT-0065 lateral review): that trait reflects
+        // `aria-selected` on items — invalid on `role=menuitem` (action semantics, no selected state) —
+        // and carries no Space leg; this hand-rolled click+Enter/Space path IS the menu commit contract.
+        this.listen(panel, 'keydown', (ev) => {
+            const e = ev;
+            if (e.key !== 'Enter' && e.key !== ' ')
+                return;
+            const focused = document.activeElement;
+            if (!focused)
+                return;
+            // Buttons and links fire click on Enter/Space natively — the click listener handles them.
+            if (focused instanceof HTMLButtonElement || focused.tagName === 'A')
+                return;
+            const list = items();
+            const index = list.findIndex((item) => item === focused || item.contains(focused));
+            if (index === -1)
+                return;
+            const item = list[index];
+            if (item.hasAttribute('disabled') || item.getAttribute('aria-disabled') === 'true')
+                return;
+            e.preventDefault();
+            this.#commit(index, item);
+        });
+        // Roving keyboard focus — vertical (Arrow Up/Down), loop, type-ahead. Container = panel so
+        // only Arrow keys inside the panel are intercepted (not the trigger's own keyboard events).
+        rovingFocus(this, {
+            container: panel,
+            items,
+            orientation: 'vertical',
+            loop: true,
+            typeAhead: true,
+        });
+        // Edge-aware scroll fade (the gutter-exposure fix, 2026-07-04) — always on, no opt-in prop. The panel
+        // is now a bounded scroll viewport (menu.css: max-block-size: 40vh + overflow-y: auto, matching ui-select).
+        scrollFade(this, { viewport: panel });
+    }
+    /**
+     * Create the control's two light-DOM parts ONCE (idempotent across disconnect/reconnect):
+     *   - trigger: the first element child, marked with `data-part="trigger"` + ARIA affordances.
+     *   - panel: a `<div data-part="panel" role="menu">` appended to the host; non-trigger children
+     *     are moved in and auto-assigned `role=menuitem` + `tabindex=-1` if they lack a role.
+     *
+     * The overlay controller sets `popover="auto"` on the panel. `render()` stays the inherited
+     * VOID — the parts are created once and never re-created.
+     */
+    #ensureParts() {
+        if (this.#panel) {
+            // Parts persist through disconnect/reconnect — return the existing ones.
+            const trigger = this.querySelector('[data-part="trigger"]');
+            if (!trigger)
+                throw new Error('ui-menu: trigger part lost on reconnect');
+            const panel = this.#panel;
+            return { panel, trigger, items: () => this.#itemsIn(panel) };
+        }
+        // Identify the menu trigger — the first element child provided by the author.
+        const trigger = this.firstElementChild;
+        if (!trigger) {
+            throw new Error('ui-menu: provide a trigger as the first child (e.g. <button>) before the menu items');
+        }
+        trigger.setAttribute('data-part', 'trigger');
+        // Create the menu panel. The overlay controller sets popover="auto" via setAttribute
+        // (single-ownership, ADR-0017 pattern — we do NOT set it here).
+        // `role=menu` is set on the div part directly (a created element, NOT the host — the FACE
+        // internals.role rule applies to the host element only).
+        const panel = document.createElement('div');
+        panel.setAttribute('data-part', 'panel');
+        panel.setAttribute('data-box', ''); // adopt the shared container box-model (inset margins)
+        panel.setAttribute('role', 'menu');
+        // tabindex="-1" lets moveFocusIn() (overlay LLD-C4) land on the panel itself when there
+        // are no enabled menuitems — the fallback panel.focus() requires the element to be focusable.
+        panel.setAttribute('tabindex', '-1');
+        // Stable id for aria-controls (created once, never reused).
+        panel.id = `ui-menu-panel-${++_nextPanelId}`;
+        // Move all non-trigger children into the panel (the menu items live in the top-layer surface,
+        // not beside the trigger in the document flow — the modal/popover child-move pattern).
+        let node = trigger.nextSibling;
+        while (node) {
+            const next = node.nextSibling;
+            panel.appendChild(node);
+            node = next;
+        }
+        // Auto-assign role=menuitem + tabindex=-1 to direct element children that do not already
+        // carry a role. The roving-focus trait then manages the tabindexes from this base state.
+        for (const child of panel.children) {
+            if (child instanceof HTMLElement) {
+                if (!child.hasAttribute('role'))
+                    child.setAttribute('role', 'menuitem');
+                if (!child.hasAttribute('tabindex'))
+                    child.setAttribute('tabindex', '-1');
+            }
+        }
+        this.appendChild(panel);
+        this.#panel = panel;
+        // Wire the trigger's ARIA affordances.
+        trigger.setAttribute('aria-controls', panel.id);
+        trigger.setAttribute('aria-haspopup', 'menu');
+        return { panel, trigger, items: () => this.#itemsIn(panel) };
+    }
+    /** Return the live ordered set of [role=menuitem] elements within the panel. */
+    #itemsIn(panel) {
+        return [...panel.querySelectorAll('[role="menuitem"]')];
+    }
+    /**
+     * Commit a user-driven item selection: emit `select` with {value, index}, then close the panel.
+     * The value is the item's `data-value` attribute, falling back to trimmed text content.
+     * Close is driven programmatically (open=false → effect → handle.close()); the overlay trait
+     * announces exactly one close+toggle pair for this transition too (ADR-0101), with `el.open`
+     * already `false` by the time a listener observes either event (the ordering invariant).
+     */
+    #commit(index, item) {
+        const value = item.dataset['value'] ?? item.textContent?.trim() ?? String(index);
+        this.emit('select', { value, index });
+        this.open = false;
+    }
+}
+if (!customElements.get('ui-menu'))
+    customElements.define('ui-menu', UIMenuElement);