@agent-ui-kit/components 0.0.3

package/dist/controls/modal/modal.css

@@ -0,0 +1,99 @@
+/* modal.css — ui-modal, the single-file component stylesheet (ADR-0003 / ADR-0017). Two clearly-SECTIONED
+ * blocks, mirroring button.css / text-field.css:
+ *
+ *   [1] TOKEN BLOCK  — `:where(ui-modal)` (specificity 0,0,0) sets the modal's OWN default surface and DECLARES
+ *       the `--ui-modal-*` chain from the colour roles (`--md-sys-color-{family}-{role}`, family = neutral) and the
+ *       dimensions (`--md-sys-space-*` / `--md-sys-shape-corner-base`). This is where roles enter, exactly as button.css's
+ *       `:where()` token block does. The container surface base defaults `--ui-container-bg` to TRANSPARENT (an
+ *       unset layout primitive is unchanged — ADR-0015 cl.1); a modal is an OPAQUE plane, so it repoints its own
+ *       default. The signed `elevation`/`brightness` axes still repoint `--ui-container-bg`/`-tint` on the HOST
+ *       via container.css (higher specificity), and the value INHERITS to the dialog part below.
+ *   [2] STYLES BLOCK — `@scope (ui-modal)` CONSUMES only the role-pure `--ui-container-*` surface seam + the own
+ *       `--ui-modal-*` chain (never a raw `--md-sys-color-*`). The host is `display: contents` — a logical wrapper that
+ *       generates no box; only the control-owned `<dialog data-part="dialog">` PART renders, in the platform TOP
+ *       LAYER when `showModal()` is called (ADR-0017). The native UA dialog frame (1em padding, solid border,
+ *       Canvas bg, centring margin) is fully repointed onto the surface seam + the space/radius tokens. The
+ *       `::backdrop` scrim is the platform-painted blocking layer. Geometry is the Pattern/container size-class
+ *       (geometry.md): the shell spaces off `--md-sys-space-*` × density — NO control height (`--md-sys-height-*`).
+ *
+ * Standalone stylesheet — linked via the component-styles barrel (s12); NEVER injected from modal.ts
+ * (behaviour-only `.ts`, no runtime style injection — plan §2). component-styles.css @imports container.css
+ * FIRST (the shared surface seam), then this sheet.
+ */
+
+/* ════════════════ [1] TOKEN BLOCK — :where(ui-modal) declares the surface default + --ui-modal-* ════════════════ */
+
+:where(ui-modal) {
+  /* The modal's OWN default surface (the container base defaults transparent — ADR-0015 cl.1; a modal is an
+     opaque plane). `[elevation]`/`[brightness]` on the host still win (container.css repoints at (0,1,0)), and
+     the seam value inherits down to the dialog part. */
+  --ui-container-bg: var(--md-sys-color-neutral-surface);
+
+  /* the own chain — @scope consumes ONLY these (+ the --ui-container-* seam), never a raw --md-sys-color-* role */
+  --ui-modal-ink: var(--md-sys-color-neutral-on-surface);
+  --ui-modal-outline: var(--md-sys-color-neutral-outline-variant); /* the faint dialog frame */
+  --ui-modal-radius: var(--md-sys-shape-corner-base); /* the shared fleet radius (ADR-0015 cl.5) */
+  --ui-modal-padding: var(--md-sys-space-lg); /* the shell pad off the density-responsive ladder (NOT a control height) */
+  --ui-modal-scrim: var(--md-sys-color-dialog-backdrop); /* the ::backdrop blocking wash — black 80% opacity (TKT-0019; was --md-sys-color-neutral-scrim, too light) */
+  /* The FRAME dials — ui-modal's public composition seam (TKT-0017): a composer that nests ui-modal (the
+     command-modal precedent) pins these via inline style on the element it owns (the slider --value-pct
+     JS-seam exemption, family-coherence B). Defaults reproduce the classic centered shrink-fit exactly. */
+  --ui-modal-inline-size: auto; /* set a length for a FIXED-width dialog (shrink-fit by default) */
+  --ui-modal-max-inline-size: min(92vw, 32rem);
+  --ui-modal-margin-block-start: auto; /* set a length (e.g. 15svh) to TOP-ANCHOR; auto = centered */
+}
+
+/* ════════════════ [2] STYLES BLOCK — @scope (ui-modal) consumes ONLY --ui-modal-* + the --ui-container-* seam ════════════════ */
+
+@scope (ui-modal) {
+  /* the host is a logical wrapper — it generates no box; only the dialog PART renders (in the top layer when
+     shown). The surface custom props set on the host inherit through display:contents to the dialog. */
+  :scope {
+    display: contents;
+  }
+
+  /* the dialog surface — the modal plane. The base plane (elevation) is the solid --ui-container-bg; the tonal
+     wash (brightness composition) is the flat same-colour background-image stacked above it (ADR-0015 cl.3), so
+     the two surface axes composite. Everything else is the own --ui-modal-* chain. The native UA frame is fully
+     overridden. `margin: auto` keeps the showModal centring; the size caps keep a long modal scrollable. */
+  :scope > [data-part='dialog'] {
+    box-sizing: border-box;
+    /* centre in the top layer by default (the showModal default — restated so a UA reset cannot drop it);
+       the block-start dial top-anchors when a composer sets it (TKT-0017). */
+    margin-inline: auto;
+    margin-block-start: var(--ui-modal-margin-block-start);
+    margin-block-end: auto;
+    inline-size: var(--ui-modal-inline-size);
+    max-inline-size: var(--ui-modal-max-inline-size);
+    max-block-size: 85svh;
+    overflow: auto; /* a tall modal scrolls within the cap, not off-screen */
+
+    background-color: var(--ui-container-bg); /* the base plane (elevation) */
+    background-image: linear-gradient(var(--ui-container-tint), var(--ui-container-tint)); /* the tonal wash (composition) */
+    color: var(--ui-modal-ink);
+    border: 1px solid var(--ui-modal-outline);
+    border-radius: var(--ui-modal-radius);
+    /* Box-model (container-box.css, REVISED 2026-07-04): the dialog is a [data-box] — no shell padding; its
+       children carry the inset (author header/content/footer regions get the 12/6 region padding PLUS a 6px
+       positional margin — regions are inset, not full-bleed; loose content gets the 6px box inset margin). */
+    padding: 0;
+  }
+
+  /* the ::backdrop scrim — the platform-painted blocking layer behind the modal (top layer). A translucent
+     neutral scrim role, so the page dims but is not fully hidden. */
+  :scope > [data-part='dialog']::backdrop {
+    background-color: var(--ui-modal-scrim);
+  }
+
+  /* forced-colors (WHCM) — keep the dialog surface + frame + ink visible as system colours (the wash drops; a
+     translucent overlay would paint over the forced Canvas base and defeat it). The ::backdrop is left to the
+     scrim role / UA so the blocking layer still paints (it must not vanish — the modal stays distinguishable). */
+  @media (forced-colors: active) {
+    :scope > [data-part='dialog'] {
+      background-color: Canvas;
+      background-image: none;
+      border-color: CanvasText;
+      color: CanvasText;
+    }
+  }
+}

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

@@ -0,0 +1,61 @@
+import { type ReactiveProps } from '../../dom/index.js';
+import { UIContainerElement } from '../../dom/container.js';
+declare const props: {
+    open: {
+        reflect: true;
+        type: import("../../index.js").PropType<boolean>;
+        default: boolean;
+        attribute?: string | false;
+    };
+    persistent: {
+        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 UIModalElement extends ReactiveProps<typeof props> {
+}
+export declare class UIModalElement extends UIContainerElement {
+    #private;
+    static props: {
+        open: {
+            reflect: true;
+            type: import("../../index.js").PropType<boolean>;
+            default: boolean;
+            attribute?: string | false;
+        };
+        persistent: {
+            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/modal/modal.js

@@ -0,0 +1,155 @@
+// modal.ts — UIModalElement, the FACE modal dialog on the native `<dialog>` (goals.md §G9 / ADR-0017;
+// decomp g9-containers slice s9). BEHAVIOUR + props + the control-owned `<dialog>` part + self-define ONLY;
+// surface/backdrop live in modal.css (s9), the public contract in modal.md (s9).
+//
+// Native `<dialog>` showModal() supplies the four hard modal behaviours FREE, in the platform top layer:
+// top-layer stacking (above any z-index/overflow/stacking context), a `::backdrop`, focus CONTAINMENT, and
+// Escape-to-dismiss. ADR-0017 takes the platform element and adds only the gaps it leaves — focus RESTORE on
+// close (cl.4) and the `open`↔platform sync (cl.2/3). A `<dialog>` is NOT a form widget (it submits nothing,
+// carries no value, is not form-associated), so it honours the "no native form elements" rule under the
+// ADR-0014 widgets-not-elements reading — `ui-modal` extends UIContainerElement (surface, NOT form-associated).
+//
+// The dialog is a control-owned light-DOM PART (`<dialog data-part="dialog">`), created ONCE (an idempotent
+// guard) and NEVER re-rendered — `render()` stays the inherited VOID, because re-creating the dialog would drop
+// the top-layer + focus state mid-session (ADR-0017 cl.1). Its three wires are scope-owned:
+//   • model→platform — an effect on `open`: true → `dialog.showModal()`, false → `dialog.close()` (idempotent
+//     guards; `showModal()` records the opener first so focus can be restored).
+//   • platform→model — the dialog's `close` event: a USER/platform close (Escape, backdrop, an external
+//     `.close()`) syncs `open=false` and emits the family `close` + `toggle` (the two-way bind, ADR-0019);
+//     a close WE drove (the prop already went false) only restores focus — no redundant emit. `this.open` is
+//     the discriminator (still true ⇒ the platform closed it), so no async flag is needed.
+//   • dismissal gate — `persistent` (default OFF); when set, the dialog's `cancel` event (Escape, the platform
+//     light-dismiss request) is preventDefault-ed, and a backdrop click is ignored. Backdrop click is detected
+//     rect-wise (a click whose target is the dialog box but lands OUTSIDE its content rect ⇒ the `::backdrop`).
+//
+// The HOST carries no role/aria-* attribute (the family `internals`-only ARIA discipline) — `aria-modal` is set
+// by `showModal()`, and an author accessible name (`aria-label`/`aria-labelledby`) is FORWARDED onto the dialog
+// PART (ADR-0017 cl.5), keeping the host attribute-clean.
+//
+// The dialog also wires `traits/scroll-fade.ts` (default-on, no separate opt-in prop) — the gutter-exposure
+// fix, 2026-07-04: once a [data-box] header/footer became INSET rather than full-bleed, its own background no
+// longer reaches the frame edge, so scrolled content can peek through the thin gutter around it. `controls →
+// dom + traits` is the allowed import direction.
+import { prop } from "../../dom/index.js";
+import { UIContainerElement } from "../../dom/container.js";
+import { scrollFade } from "../../traits/scroll-fade.js";
+const props = {
+    // The two surface axes (elevation/brightness) — SPREAD from the container base, not inherited (props.ts has
+    // no static-props prototype merge; the ADR-0013 formProps precedent). They style the dialog PART's surface.
+    ...UIContainerElement.surfaceProps,
+    // `open` — whether the modal is shown. Reflected (the [open] attribute drives nothing in CSS — the dialog's
+    // own [open] is the platform's — but reflecting keeps the host's declared state inspectable/serializable) and
+    // BINDABLE: the catalog declares value:{prop:'open',event:'toggle'} so the renderer two-way-binds it (ADR-0019).
+    open: { ...prop.boolean(false), reflect: true },
+    // `persistent` (default OFF) — when present, the modal is NON-dismissable: the dialog's `cancel` event (Escape)
+    // is preventDefault-ed and a backdrop click is ignored, so the agent owns the close (set open=false). Reflected
+    // (presence-boolean: <ui-modal persistent> ⇒ true, absent ⇒ false) — the declarative override the old default-on
+    // `dismissable` could not express (attribute presence always coerced true). See ADR-0020.
+    persistent: { ...prop.boolean(false), reflect: true },
+};
+export class UIModalElement extends UIContainerElement {
+    static props = props;
+    // The control-owned dialog PART — a light-DOM child that persists across disconnect/reconnect, so it is
+    // created ONCE (the idempotent guard in #ensureDialog) and never re-appended.
+    #dialog = null;
+    // The element focused when the modal opened — restored on close (the one platform gap, ADR-0017 cl.4).
+    #opener = null;
+    connected() {
+        const dialog = this.#ensureDialog();
+        // ── platform→model — a USER/platform close syncs the prop + announces; a close WE drove only restores ──
+        this.listen(dialog, 'close', () => {
+            if (this.open) {
+                // The platform closed it (Escape, backdrop, an external .close()) while the prop still reads open —
+                // sync the state down and announce, so the agent learns the user dismissed it (the two-way bind).
+                this.open = false; // reflects (drops the attribute) + re-runs the effect → #closeDialog no-ops (already closed)
+                this.emit('close');
+                this.emit('toggle'); // the value:{event:'toggle'} two-way signal (ADR-0019)
+            }
+            this.#restoreFocus(); // restore on EVERY close (platform-driven or our own) — the platform omits this
+        });
+        // ── dismissal gate — Escape / the platform light-dismiss request fires `cancel`; block it when persistent ──
+        this.listen(dialog, 'cancel', (event) => {
+            if (this.persistent)
+                event.preventDefault(); // the dialog stays open; no `close` follows
+        });
+        // ── backdrop click — a click on the dialog box OUTSIDE its content rect is the `::backdrop`; dismiss if allowed ──
+        this.listen(dialog, 'click', (event) => {
+            if (this.persistent)
+                return;
+            const e = event;
+            if (e.target !== dialog)
+                return; // a click on content targets the child; the backdrop/box targets the dialog
+            const r = dialog.getBoundingClientRect();
+            const insideContent = e.clientX >= r.left && e.clientX <= r.right && e.clientY >= r.top && e.clientY <= r.bottom;
+            if (!insideContent)
+                dialog.close(); // a true backdrop click → close (routes through the `close` user branch)
+        });
+        // ── model→platform — `open` drives showModal()/close() (scope-owned; re-arms on reconnect) ──
+        this.effect(() => {
+            if (this.open)
+                this.#openDialog(dialog);
+            else
+                this.#closeDialog(dialog);
+        });
+        // ── edge-aware scroll fade (the gutter-exposure fix, 2026-07-04) — always on ──
+        // The dialog IS the scroll viewport (modal.css: `overflow: auto` + `max-block-size: 85svh`) and a
+        // [data-box] region author may give it a sticky header/footer, whose inset background no longer reaches
+        // the frame edge. Unlike ui-card-content's `scroll-fade`, there is no separate opt-in prop here — a
+        // modal has no equivalent author-facing switch, so the fade is unconditionally wired (a no-op on a
+        // dialog that never overflows — scrollFade's own decision logic gates the flags, not this call site).
+        scrollFade(this, { viewport: dialog });
+    }
+    /** Open the dialog (idempotent) — record the opener FIRST (showModal moves focus in), then enter the top layer. */
+    #openDialog(dialog) {
+        if (dialog.open)
+            return; // already shown — do not re-enter the top layer / re-trap
+        this.#opener = document.activeElement; // the element to restore focus to on close
+        dialog.showModal(); // platform: top layer + ::backdrop + focus trap + Escape + aria-modal — all free
+    }
+    /** Close the dialog (idempotent). The `close` event fires with `open` already false ⇒ no redundant emit. */
+    #closeDialog(dialog) {
+        if (!dialog.open)
+            return;
+        dialog.close();
+    }
+    /** Restore focus to the recorded opener (ADR-0017 cl.4 — the platform traps but does not restore). */
+    #restoreFocus() {
+        const opener = this.#opener;
+        this.#opener = null;
+        if (opener && opener.isConnected && typeof opener.focus === 'function')
+            opener.focus();
+    }
+    /**
+     * Create the `<dialog data-part="dialog">` PART ONCE (idempotent across reconnect — it is a light-DOM child
+     * that persists through disconnect). The modal's children are MOVED into the dialog at creation (they render
+     * inside the top-layer surface, not beside it). An author accessible name (`aria-label`/`aria-labelledby`) is
+     * FORWARDED off the host onto the dialog part (ADR-0017 cl.5) so the host stays role/aria-clean and the name
+     * rides the semantic element. `render()` stays the inherited VOID — the dialog is never re-created.
+     */
+    #ensureDialog() {
+        if (this.#dialog)
+            return this.#dialog;
+        const dialog = document.createElement('dialog');
+        dialog.setAttribute('data-part', 'dialog');
+        dialog.setAttribute('data-box', ''); // adopt the shared container box-model (region padding + inset margins, ADR-0046 revised 2026-07-04)
+        // Forward the accessible name onto the dialog part, then strip it from the host (host carries no aria-*).
+        const labelledby = this.getAttribute('aria-labelledby');
+        if (labelledby !== null) {
+            dialog.setAttribute('aria-labelledby', labelledby);
+            this.removeAttribute('aria-labelledby');
+        }
+        const label = this.getAttribute('aria-label');
+        if (label !== null) {
+            dialog.setAttribute('aria-label', label);
+            this.removeAttribute('aria-label');
+        }
+        // Move the author content into the dialog (the dialog is detached here, so firstChild is real content).
+        while (this.firstChild)
+            dialog.appendChild(this.firstChild);
+        this.appendChild(dialog);
+        this.#dialog = dialog;
+        return dialog;
+    }
+}
+if (!customElements.get('ui-modal'))
+    customElements.define('ui-modal', UIModalElement);

package/dist/controls/popover/popover.css

@@ -0,0 +1,83 @@
+/* popover.css — ui-popover, the single-file component stylesheet (ADR-0003 · overlay-controller.lld.md).
+ * Two clearly-SECTIONED blocks, mirroring modal.css / button.css:
+ *
+ *   [1] TOKEN BLOCK  — `:where(ui-popover)` (specificity 0,0,0) sets the popover's OWN default
+ *       surface tokens and DECLARES the `--ui-popover-*` chain from the colour roles
+ *       (`--md-sys-color-{family}-{role}`, family = neutral) 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-popover)` CONSUMES only the role-pure `--ui-popover-*` chain.
+ *       The host is `display: contents` — a logical disclosure wrapper that generates no box.
+ *       The trigger child stays in the document flow (the author provides it; we mark it with
+ *       `data-part="trigger"` but do not style it — it is the author's to own). The panel part
+ *       (`[data-part="panel"]`) is the Container/surface: `--ui-container-bg` equivalent sourced
+ *       from `--ui-popover-bg`, `--md-sys-shape-corner-base`, `--md-sys-space-md` padding — NOT a control height
+ *       (`--md-sys-height-*` is never read). The panel needs a `min-inline-size` floor to prevent
+ *       collapse when content is absent (the ui-text-field #74 / ui-slider trap, ADR-0021).
+ *       A `forced-color-adjust: auto` block keeps the surface and frame in system colours.
+ *
+ * Standalone stylesheet — NOT injected from popover.ts (behaviour-only `.ts`, no runtime injection
+ * per plan §2). Linked via the component-styles barrel (s12); the barrel @imports foundation roles
+ * FIRST. The panel's `popover` attribute (set by the overlay controller) gives it `display: none`
+ * in the UA stylesheet until `showPopover()` places it in the top layer — our CSS only applies to
+ * the visible (open) panel, which is correct since `[popover]` elements are normally hidden.
+ */
+
+/* ════════════════ [1] TOKEN BLOCK — :where(ui-popover) declares the surface default + --ui-popover-* ════════════════ */
+
+:where(ui-popover) {
+  /* Surface plane — the popup panel is an opaque neutral surface (like a modal / card).
+     @scope consumes --ui-popover-bg, never the raw --md-sys-color-* role. */
+  --ui-popover-bg: var(--md-sys-color-neutral-surface);
+  --ui-popover-ink: var(--md-sys-color-neutral-on-surface);
+
+  /* Frame */
+  --ui-popover-outline: var(--md-sys-color-neutral-outline-variant);
+  --ui-popover-radius: var(--md-sys-shape-corner-base); /* the shared fleet radius (ADR-0015 cl.5) */
+
+  /* Shell spacing — panel-class geometry (Container/surface, NOT a control height) */
+  --ui-popover-padding: var(--md-sys-space-md);
+
+  /* Size floor — prevents collapse when content is absent or narrow (the ADR-0021 lesson:
+     a surface that can be empty needs a min-inline-size; the overlay JS positions against
+     the measured bounds so a zero-width panel would place at the wrong coords too). */
+  --ui-popover-min-inline-size: 8rem;
+}
+
+/* ════════════════ [2] STYLES BLOCK — @scope (ui-popover) consumes ONLY --ui-popover-* ════════════════ */
+
+@scope (ui-popover) {
+  /* 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 surface panel — a Container/surface in the top layer (the Popover API places it there).
+     The UA `[popover]` rule hides this with display:none until showPopover(); our padding / bg
+     only paint when the panel is in the top layer (already visible). `position: fixed` and the
+     inset are set by the JS positioning controller (overlay.ts) on open — we do NOT fix a position
+     here; the controller owns the placement completely. `margin: 0` prevents UA-default centering
+     from conflicting with the controller's explicit inset. */
+  :scope > [data-part='panel'] {
+    box-sizing: border-box;
+    margin: 0; /* the controller sets position:fixed + top/left — UA margin must not override */
+    min-inline-size: var(--ui-popover-min-inline-size);
+
+    background-color: var(--ui-popover-bg);
+    color: var(--ui-popover-ink);
+    border: 1px solid var(--ui-popover-outline);
+    border-radius: var(--ui-popover-radius);
+    padding: var(--ui-popover-padding);
+  }
+
+  /* forced-colors (WHCM) — the surface, frame, and ink stay visible as system colours.
+     The opacity-based overlay wash (if any) is not used here — the surface is a solid
+     Canvas plane so the paint cannot defeat the forced-color Canvas base. */
+  @media (forced-colors: active) {
+    :scope > [data-part='panel'] {
+      background-color: Canvas;
+      color: CanvasText;
+      border-color: CanvasText;
+    }
+  }
+}

package/dist/controls/popover/popover.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 UIPopoverElement extends ReactiveProps<typeof props> {
+}
+export declare class UIPopoverElement 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/popover/popover.js

@@ -0,0 +1,164 @@
+// popover.ts — UIPopoverElement, the Wave-4 S1 disclosure-popover overlay control
+// (control-suite-wave4-overlay.decomp.md S1 · overlay-controller.lld.md LLD-C1..C4 · ADR-0043).
+//
+// Composition: a `UIElement` host + `overlay(this, { popup, anchor, placement })` — the direct trait-call
+// pattern (there is no `host.use()`; traits are invoked directly, like `trackUserInvalid`/`rovingFocus`) — the BARE
+// overlay (Popover API surface + JS positioning + light-dismiss + two-way `open`, ADR-0019). NOT
+// form-associated — no value/validity. A disclosure trigger (first element child, default slot)
+// toggles a control-created surface panel part (`[popover]`).
+//
+// Two-way `open` (ADR-0019): a scope-owned effect drives model→overlay (open/close the handle);
+// a `close` event listener on the host drives overlay→model (light-dismiss syncs the prop back).
+// The overlay trait emits `close` + `toggle` on the host for EVERY real transition — platform
+// dismiss, a trigger-click close, or a model-driven `open=false` alike (ADR-0101); this control
+// listens for `close` and sets `this.open = false` so the prop stays consistent on the light-dismiss
+// path (the commit/model paths already set the prop first).
+//
+// Anatomy (light-DOM, created once — idempotent across reconnect):
+//   <ui-popover>
+//     <button data-part="trigger" aria-expanded="…" aria-controls="ui-popover-panel-N">…</button>
+//     <div data-part="panel" popover="auto" id="ui-popover-panel-N" tabindex="-1">…</div>
+//   </ui-popover>
+//
+// The trigger is the first element child provided by the author. Remaining children are moved
+// into the panel at connect time (like the modal's child-move pattern, ADR-0017). The overlay
+// controller sets `popover="auto"` on the panel. `render()` stays the inherited VOID — the parts
+// are created once and never re-created (re-creating would drop top-layer / focus state).
+//
+// Placement is fixed per connection: the overlay controller captures `prefPlacement` at call time.
+// Changing `placement` after connect takes effect on the NEXT reconnect (documented limitation).
+//
+// ARIA: minimal via internals — the host has no explicit role (a logical disclosure wrapper); the
+// trigger gets `aria-expanded` + `aria-controls` set directly (child attributes, not host internals).
+// The panel gets `tabindex="-1"` so `moveFocusIn()` can land on it when there are no interactive
+// descendants. `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";
+// ── 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 popover panel is currently shown. Reflected (the [open] attribute keeps the
+    // host's declared state inspectable) and BINDABLE: the catalog declares value:{prop:'open',
+    // event:'toggle'} so the renderer two-way-binds it (ADR-0019). Drives the overlay handle.
+    open: { ...prop.boolean(false), reflect: true },
+    // `placement` — the preferred popup placement (flip + shift at viewport edges — LLD-C3). Captured
+    // once per connection; changing it after connect takes effect on the next reconnect. Reflected so
+    // `<ui-popover placement="top-end">` works declaratively.
+    placement: { ...prop.enum(PLACEMENTS, 'bottom-start'), reflect: true },
+};
+// ── Module-level stable-id counter (one per panel, never reused across instances) ──────────────
+let _nextPanelId = 0;
+export class UIPopoverElement extends UIElement {
+    static props = props;
+    // The control-created popover panel PART — created ONCE (idempotent guard in #ensureParts()) and
+    // NEVER re-created. Persists through disconnect/reconnect just like the modal dialog part.
+    #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 } = this.#ensureParts();
+        // Wire the overlay controller (LLD-C1..C4) — this is the PROOF of the overlay controller.
+        // placement is read ONCE per connection (the controller captures prefPlacement at call time).
+        const handle = overlay(this, {
+            popup: panel,
+            anchor: trigger,
+            placement: this.placement,
+            auto: true, // popover=auto → Escape + outside-click light-dismiss (LLD-C2)
+            focusOnOpen: true, // disclosure popover: focus moves into the panel on open (LLD-C4)
+        });
+        this._overlayHandle = handle;
+        // Trigger click → toggle the panel (the disclosure interaction).
+        //
+        // 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 any later programmatic close via the prop was
+        // a same-value no-op, the model→overlay effect never re-ran, and the panel could stick open).
+        // 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 we need `open` to already be false by then).
+        // At the time this listener fires, the overlay's internal `isOpen` is already false (the toggle
+        // listener in overlay.ts ran first), so the subsequent effect re-run calls `handle.close()` as
+        // a no-op (the idempotent guard in overlay.ts: `if (cleaned || !isOpen) return`).
+        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));
+        });
+    }
+    /**
+     * 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">` appended to the host; non-trigger children are moved in.
+     * The overlay controller sets `popover="auto"` on the panel. `render()` stays the inherited VOID.
+     */
+    #ensureParts() {
+        if (this.#panel) {
+            // Parts persist through disconnect/reconnect — return the existing ones.
+            const trigger = this.querySelector('[data-part="trigger"]');
+            // The trigger must still be present (it's a light-DOM child, so it travels with the host).
+            if (!trigger)
+                throw new Error('ui-popover: trigger part lost on reconnect');
+            return { panel: this.#panel, trigger };
+        }
+        // Identify the disclosure trigger — the first element child provided by the author.
+        const trigger = this.firstElementChild;
+        if (!trigger) {
+            throw new Error('ui-popover: provide a trigger as the first child (e.g. <button>) before the panel content');
+        }
+        trigger.setAttribute('data-part', 'trigger');
+        // Create the surface panel. The overlay controller sets popover="auto" via
+        // `popup.setAttribute('popover', 'auto')` — we do NOT set it here (single-ownership, ADR-0017).
+        const panel = document.createElement('div');
+        panel.setAttribute('data-part', 'panel');
+        // tabindex="-1" lets `moveFocusIn()` (overlay LLD-C4) land on the panel itself when there are
+        // no interactive descendants — the fallback `popup.focus()` requires the element to be focusable.
+        panel.setAttribute('tabindex', '-1');
+        // Stable id for the trigger's `aria-controls` (created once, never reused).
+        panel.id = `ui-popover-panel-${++_nextPanelId}`;
+        // Move all non-trigger children into the panel (the disclosure content lives in the top-layer
+        // surface, not beside the trigger in the document flow — mirrors the modal child-move pattern).
+        let node = trigger.nextSibling;
+        while (node) {
+            const next = node.nextSibling;
+            panel.appendChild(node);
+            node = next;
+        }
+        this.appendChild(panel);
+        this.#panel = panel;
+        // Wire the trigger's ARIA affordances (present from the first render — the effect wires
+        // aria-expanded after connect, but aria-controls is stable and set here once).
+        trigger.setAttribute('aria-controls', panel.id);
+        return { panel, trigger };
+    }
+}
+if (!customElements.get('ui-popover'))
+    customElements.define('ui-popover', UIPopoverElement);