@agent-ui-kit/components 0.0.3

package/dist/traits/form-registry.js

@@ -0,0 +1,108 @@
+// form-registry.ts — the reactive form-registry CONTROLLER (ADR-0050 §2/§3, LLD-C3): the aggregation half of
+// the connect-time registration mechanism form.ts's `ui-form-connect` protocol event feeds. Invoked from
+// `ui-form-provider`'s `connected()` — the connection scope + AbortSignal are live there, the same
+// `trackUserInvalid` controller pattern — NOT invoked from a plain control.
+//
+// Discovery rides the protocol event alone (no MutationObserver): a control connected under the provider
+// dispatches `ui-form-connect` at the END of its own `connectedCallback` (form.ts), the listener installed
+// here registers it, and `stopPropagation()` scopes membership to the NEAREST provider under nesting.
+// Teardown rides the event's connection-scoped `AbortSignal`, not a second event — a disconnected control
+// cannot dispatch, so the registry subscribes to the handle's `abort` instead (dual-lifetime: the control's
+// OWN disconnect aborts its handle → its entry alone is removed; the PROVIDER's disconnect aborts the HOST
+// signal every one of these listeners rides via `host.listen` → all per-member listeners die at once — zero
+// residue either way, no dead node ever lingers in `members`).
+//
+// The four aggregates (entries/values/invalid/valid) are `computed`s over the plain `members` signal —
+// UN-owned (not wrapped in `scope.run`): a computed's subscriber set lives only while a reading effect
+// subscribes to it (kernel semantics), so residue dies with the READERS, not with this controller. Every
+// add/remove writes a NEW frozen array into `members` (Object.is cutoff ⇒ fine-grained waking for anyone
+// reading a single aggregate, not all four).
+//
+// Layering: traits → reactive (L0) + dom (L1) — both downward, the import-layering trip-wire holds. The
+// runtime `instanceof UIFormElement` guard (not just the TS type) is defense: the event never fires from a
+// non-form child, but the guard makes that a proven negative control (s9), not an assumption.
+import { computed, signal } from "../reactive/index.js";
+import { UIFormElement, FORM_CONNECT_EVENT } from "../dom/index.js";
+/**
+ * Attach the reactive form registry to a `ui-form-provider` host. Invoke from `connected()` (connection
+ * scope + AbortSignal live). Listens for `ui-form-connect` on the host, registers each control at the
+ * NEAREST provider (`stopPropagation`), and deregisters on the control's connection-scoped `abort` — a
+ * late-added control is discovered by construction (its own connect dispatch re-fires), a removed one drops
+ * out with zero residue.
+ */
+export function formRegistry(host) {
+    let released = false;
+    const members = signal([]);
+    // ── the four aggregates — computeds over `members`, un-owned (kernel semantics; see the header note) ──
+    const entries = computed(() => {
+        const result = [];
+        for (const member of members.value) {
+            if (member.control.name === '' || member.control.effectiveDisabled())
+                continue;
+            const value = member.value();
+            if (value === null)
+                continue;
+            result.push([member.control.name, value]);
+        }
+        return result;
+    });
+    const values = computed(() => {
+        const result = {};
+        for (const [name, value] of entries.value)
+            result[name] = value; // last entry wins on a duplicate name
+        return result;
+    });
+    const invalid = computed(() => {
+        const result = [];
+        for (const member of members.value) {
+            if (member.control.effectiveDisabled())
+                continue; // native parity: disabled is barred from validation
+            if (!member.validity().valid)
+                result.push(member.control);
+        }
+        return result;
+    });
+    const valid = computed(() => invalid.value.length === 0);
+    // ── membership writes — always a NEW frozen array (Object.is cutoff) ──────────────────────────────────
+    const addMember = (member) => {
+        members.value = Object.freeze([...members.value, member]);
+    };
+    const removeMember = (control) => {
+        members.value = Object.freeze(members.value.filter((member) => member.control !== control));
+    };
+    // ── the connect listener (ADR-0050 §2/§3) ─────────────────────────────────────────────────────────────
+    const onConnect = (event) => {
+        if (released)
+            return;
+        const detail = event.detail;
+        // Defense, not the discovery path — the event never fires from a non-form child (s9 negative control).
+        if (!(detail?.control instanceof UIFormElement))
+            return;
+        event.stopPropagation(); // nearest-provider scoping — stopped even for a dup/aborted registration below
+        if (detail.signal.aborted)
+            return; // a stale reconnect handle can never register
+        if (members.value.some((member) => member.control === detail.control))
+            return; // idempotence guard
+        addMember({ control: detail.control, value: detail.value, validity: detail.validity });
+        // Dual-lifetime: the control's OWN disconnect aborts `detail.signal` → this fires → the entry is
+        // removed. The PROVIDER's disconnect aborts the connection signal `host.listen` rides → this listener
+        // itself is removed (no residue on a still-connected control's signal).
+        host.listen(detail.signal, 'abort', () => {
+            if (released)
+                return;
+            removeMember(detail.control);
+        }, { once: true });
+    };
+    host.listen(host, FORM_CONNECT_EVENT, onConnect);
+    return {
+        members,
+        entries,
+        values,
+        invalid,
+        valid,
+        release: () => {
+            released = true;
+            members.value = Object.freeze([]);
+        },
+    };
+}

package/dist/traits/index.d.ts

@@ -0,0 +1,24 @@
+export { tabbable } from './tabbable.js';
+export type { TabbableOptions } from './tabbable.js';
+export { trackUserInvalid } from './track-user-invalid.js';
+export type { TrackUserInvalidOptions, TrackUserInvalidController } from './track-user-invalid.js';
+export { formRegistry } from './form-registry.js';
+export type { FormRegistryController, FormMember } from './form-registry.js';
+export { rovingFocus } from './roving-focus.js';
+export type { RovingFocusOptions, RovingOrientation } from './roving-focus.js';
+export { overlay } from './overlay.js';
+export type { OverlayOptions, OverlayHandle, OverlayPlacement } from './overlay.js';
+export { selectionCommit } from './selection-commit.js';
+export type { SelectionCommitOptions, SelectionMode } from './selection-commit.js';
+export { valueDrag } from './value-drag.js';
+export type { ValueDragOptions } from './value-drag.js';
+export { paneResize } from './pane-resize.js';
+export type { PaneResizeOptions, PaneResizeHandle } from './pane-resize.js';
+export { valueCodec, numberCodecOptions, currencyCodecOptions } from './value-codec.js';
+export type { ValueCodecOptions, ValueCodecController } from './value-codec.js';
+export { scrollFade } from './scroll-fade.js';
+export type { ScrollFadeOptions } from './scroll-fade.js';
+export { pressActivation } from './press-activation.js';
+export type { PressActivationOptions } from './press-activation.js';
+export { areaDrag } from './area-drag.js';
+export type { AreaDragOptions } from './area-drag.js';

package/dist/traits/index.js

@@ -0,0 +1,19 @@
+// traits — stateless `(host, opts) => cleanup` behaviours and stateful controllers, invoked directly from a
+// control's `connected()` (e.g. `tabbable(this, …)`); there is no `host.use()`.
+export { tabbable } from "./tabbable.js";
+export { trackUserInvalid } from "./track-user-invalid.js";
+// The form registry controller (G7 — ADR-0050/ADR-0051, LLD-C3): the ui-form-provider discovery/aggregation
+// controller, invoked from a provider's `connected()` — the same trackUserInvalid controller pattern above.
+export { formRegistry } from "./form-registry.js";
+export { rovingFocus } from "./roving-focus.js";
+export { overlay } from "./overlay.js";
+export { selectionCommit } from "./selection-commit.js";
+export { valueDrag } from "./value-drag.js";
+// ui-split's N-separator drag gesture (app-surfaces-m4.lld.md LLD-C2) — a NEW sibling to `value-drag`,
+// deliberately not a generalization of it (axis+RTL+multi-separator+delta vs value-drag's 1-D/LTR/absolute
+// value contract; widening value-drag risks the shipped ui-slider/ui-slider-multi).
+export { paneResize } from "./pane-resize.js";
+export { valueCodec, numberCodecOptions, currencyCodecOptions } from "./value-codec.js";
+export { scrollFade } from "./scroll-fade.js";
+export { pressActivation } from "./press-activation.js";
+export { areaDrag } from "./area-drag.js";

package/dist/traits/overlay.d.ts

@@ -0,0 +1,50 @@
+import type { UIElement } from '../dom/index.js';
+export type OverlayPlacement = 'bottom-start' | 'bottom-end' | 'top-start' | 'top-end' | 'left-start' | 'left-end' | 'right-start' | 'right-end';
+export interface OverlayOptions {
+    /** The popup element (`[popover]` part — owned by the host control). */
+    popup: HTMLElement;
+    /** The trigger element the popup anchors to. */
+    anchor: HTMLElement;
+    /**
+     * Initial placement preference. The JS controller flips/shifts to keep the popup in-viewport.
+     * Default: `'bottom-start'`.
+     */
+    placement?: OverlayPlacement;
+    /**
+     * `true` → `popover=auto` (light-dismiss via Escape + outside-click).
+     * `false` → `popover=manual` (tooltip: dismiss on blur/leave). Default: `true`.
+     */
+    auto?: boolean;
+    /**
+     * Move focus into the popup on open (menu/listbox pattern). `false` for tooltip (no focus move).
+     * Focus is restored to `anchor` on close. Default: `true`.
+     */
+    focusOnOpen?: boolean;
+}
+/** The object returned by `overlay()` — imperative control + cleanup. */
+export interface OverlayHandle {
+    /** Show the popup (`showPopover()` + position); emits `toggle` on a real show (ADR-0101). No-op (no event) if already open. */
+    open: () => void;
+    /** Hide the popup (`hidePopover()` + restore focus); emits `close`+`toggle` on a real hide (ADR-0101). No-op (no event) if already closed. */
+    close: () => void;
+    /** Toggle the popup. */
+    toggle: () => void;
+    /** Remove all listeners/observers (idempotent); also called automatically on host disconnect. */
+    cleanup: () => void;
+}
+/**
+ * Measure the anchor + popup + viewport and compute the fixed `top`/`left` for the given `placement`.
+ * Flips to the opposite side when the preferred side lacks space (flip). Clamps the result to the
+ * viewport edges (shift). Returns the resolved placement for `data-placement`.
+ */
+export declare function computePosition(pref: OverlayPlacement, anchorRect: DOMRect, popupRect: DOMRect, vw: number, vh: number, gap?: number): {
+    top: number;
+    left: number;
+    placement: OverlayPlacement;
+};
+/**
+ * Wire a Popover API top-layer popup on a `UIElement` host. Invoke from `connected()` so listeners
+ * ride the connection AbortSignal (auto-removed on disconnect). Returns an `OverlayHandle`; `cleanup`
+ * is also called automatically on host disconnect via a scope-owned effect disposer.
+ */
+export declare function overlay(host: UIElement, opts: OverlayOptions): OverlayHandle;

package/dist/traits/overlay.js

@@ -0,0 +1,277 @@
+// overlay.ts — the non-modal Overlay controller (overlay-controller LLD-C1..C4). Gives any host a
+// top-layer, light-dismissable, anchored popup via the native Popover API (`popup.showPopover()` /
+// `hidePopover()`) + a zero-dep JS positioning controller (measure-and-place; mechanism settled by
+// the team-lead, support-verified — see overlay-controller.lld.md).
+//
+// CSS anchor-positioning is a PROGRESSIVE ENHANCEMENT (`@supports (anchor-name: --x)` / feature-detect)
+// where available — NOT a v1 dual-path requirement; the JS controller is the reliable path.
+//
+// Boundary: a true MODAL (focus-trapped) stays on `ui-modal`'s `<dialog>` `showModal()` (ADR-0017).
+// This controller is the NON-MODAL path (select popup, menu, tooltip, popover).
+//
+// Announce contract (ADR-0101): the trait announces every ACTUAL open-state transition — platform-,
+// component-, or model-driven — `toggle` on a real show/hide, `close` alongside every real hide, fired
+// after the host's own `open` prop has settled. Native ToggleEvent timing fidelity; see `open()`/`close()`.
+//
+// `traits → dom` is the one allowed cross-layer direction; the host type only.
+// Opposite side map (as const + literal union — the pattern for erasableSyntaxOnly, no enum).
+const FLIP_SIDE = {
+    bottom: 'top',
+    top: 'bottom',
+    left: 'right',
+    right: 'left',
+};
+function splitPlacement(p) {
+    const i = p.indexOf('-');
+    return [p.slice(0, i), p.slice(i + 1)];
+}
+// ── Zero-dep JS positioning controller (LLD-C3) ─────────────────────────────────────────────────
+/**
+ * Measure the anchor + popup + viewport and compute the fixed `top`/`left` for the given `placement`.
+ * Flips to the opposite side when the preferred side lacks space (flip). Clamps the result to the
+ * viewport edges (shift). Returns the resolved placement for `data-placement`.
+ */
+export function computePosition(pref, anchorRect, popupRect, vw, vh, gap = 0) {
+    let [side, align] = splitPlacement(pref);
+    const pH = popupRect.height;
+    const pW = popupRect.width;
+    // Flip: switch to the opposite side when the preferred side lacks space but the opposite has room.
+    // The gap counts against the space needed, so a panel flips when the preferred side can't fit the
+    // panel PLUS its anchor gap (viewport-collision-aware placement).
+    const spaceFor = {
+        bottom: vh - anchorRect.bottom,
+        top: anchorRect.top,
+        right: vw - anchorRect.right,
+        left: anchorRect.left,
+    };
+    const needed = (side === 'bottom' || side === 'top' ? pH : pW) + gap;
+    if (spaceFor[side] < needed && spaceFor[FLIP_SIDE[side]] >= needed) {
+        side = FLIP_SIDE[side];
+    }
+    // Compute the anchored offset for the resolved side + alignment. The gap separates the panel edge
+    // from the anchor edge (a small breathing margin between the trigger and its dropdown).
+    let top;
+    let left;
+    if (side === 'bottom') {
+        top = anchorRect.bottom + gap;
+        left = align === 'start' ? anchorRect.left : anchorRect.right - pW;
+    }
+    else if (side === 'top') {
+        top = anchorRect.top - pH - gap;
+        left = align === 'start' ? anchorRect.left : anchorRect.right - pW;
+    }
+    else if (side === 'right') {
+        top = align === 'start' ? anchorRect.top : anchorRect.bottom - pH;
+        left = anchorRect.right + gap;
+    }
+    else {
+        // side === 'left'
+        top = align === 'start' ? anchorRect.top : anchorRect.bottom - pH;
+        left = anchorRect.left - pW - gap;
+    }
+    // Shift: clamp so no edge escapes the viewport (keeps the panel on-screen even after the gap offset).
+    top = Math.max(0, Math.min(top, vh - pH));
+    left = Math.max(0, Math.min(left, vw - pW));
+    return { top, left, placement: `${side}-${align}` };
+}
+/** Is the popup ACTUALLY in the top layer? `:popover-open` throws in engines that lack it — guard it. */
+function matchesPopoverOpen(popup) {
+    try {
+        return popup.matches(':popover-open');
+    }
+    catch {
+        return false; // pre-`:popover-open` engine — fall back to the internal flag at the call site
+    }
+}
+// ── The controller ───────────────────────────────────────────────────────────────────────────────
+/**
+ * Wire a Popover API top-layer popup on a `UIElement` host. Invoke from `connected()` so listeners
+ * ride the connection AbortSignal (auto-removed on disconnect). Returns an `OverlayHandle`; `cleanup`
+ * is also called automatically on host disconnect via a scope-owned effect disposer.
+ */
+export function overlay(host, opts) {
+    const { popup, anchor } = opts;
+    const prefPlacement = opts.placement ?? 'bottom-start';
+    const auto = opts.auto ?? true;
+    const focusOnOpen = opts.focusOnOpen ?? true;
+    // Set the popover type on the popup part (done once — the part is created once, ADR-0017 pattern).
+    popup.setAttribute('popover', auto ? 'auto' : 'manual');
+    let isOpen = false;
+    let opener = null;
+    // AbortController for positioning scroll/resize listeners (active only while the popup is open).
+    let positionAc = null;
+    let rafId = null;
+    let cleaned = false;
+    // ── Positioning (LLD-C3) ─────────────────────────────────────────────────────────────────────
+    function position() {
+        // The anchor↔panel gap = 0.25rem, resolved against the root font-size so it scales with the theme
+        // (a small breathing margin between a trigger and its dropdown; also counts toward flip collision).
+        const rootPx = parseFloat(getComputedStyle(document.documentElement).fontSize) || 16;
+        const gap = 0.25 * rootPx;
+        const { top, left, placement } = computePosition(prefPlacement, anchor.getBoundingClientRect(), popup.getBoundingClientRect(), window.innerWidth, window.innerHeight, gap);
+        popup.style.position = 'fixed';
+        popup.style.top = `${top}px`;
+        popup.style.left = `${left}px`;
+        popup.style.bottom = 'auto';
+        popup.style.right = 'auto';
+        popup.style.margin = '0';
+        popup.setAttribute('data-placement', placement);
+    }
+    function schedulePosition() {
+        if (rafId !== null)
+            return; // already scheduled — throttle
+        rafId = requestAnimationFrame(() => {
+            rafId = null;
+            position();
+        });
+    }
+    function startPositioning() {
+        positionAc?.abort(); // guard: re-open without a close should not stack ACs
+        positionAc = new AbortController();
+        position(); // immediate placement on open
+        const signal = positionAc.signal;
+        window.addEventListener('scroll', schedulePosition, { signal, capture: true, passive: true });
+        window.addEventListener('resize', schedulePosition, { signal, passive: true });
+    }
+    function stopPositioning() {
+        positionAc?.abort();
+        positionAc = null;
+        if (rafId !== null) {
+            cancelAnimationFrame(rafId);
+            rafId = null;
+        }
+    }
+    // ── Focus policy (LLD-C4: non-modal) ────────────────────────────────────────────────────────
+    function moveFocusIn() {
+        // Focus the first keyboard-focusable descendant; fall back to the popup itself if none present.
+        const focusable = popup.querySelector('a[href],area[href],button:not([disabled]),details>summary,' +
+            'input:not([disabled]),select:not([disabled]),textarea:not([disabled]),[tabindex]:not([tabindex="-1"])');
+        (focusable ?? popup).focus();
+    }
+    function restoreFocus() {
+        // Restore to the ANCHOR (the trigger) — the deterministic, DoD-expected target ("focus returns
+        // to the trigger on close"). `document.activeElement` at open() time is unreliable: WebKit does
+        // not focus a <button> on click (so it would be `body`), and it can be stale by the time the
+        // scope-owned effect runs. The captured `opener` is only a fallback for a non-focusable anchor.
+        const target = anchor && anchor.isConnected && typeof anchor.focus === 'function' ? anchor : opener;
+        opener = null;
+        if (target && target.isConnected && typeof target.focus === 'function')
+            target.focus();
+    }
+    // ── The shared "real hide has happened" tail (ADR-0101) ─────────────────────────────────────
+    //
+    // Stops positioning, restores focus, and announces `close`+`toggle` — the settle + announce work
+    // common to EVERY real hide, however it was driven. Pulled out of `close()` so the platform
+    // light-dismiss path (below) can share it WITHOUT re-invoking `hidePopover()` on a popup the
+    // platform already hid: calling `hidePopover()` a second time from inside its own native 'toggle'
+    // handler is a genuine cross-engine race (observed on both Chromium + WebKit) — some engines still
+    // consider the popup "showing" at that exact synchronous point, so the redundant call re-runs the
+    // platform's OWN hide algorithm and fires a SECOND real ToggleEvent, double-announcing. `close`
+    // fires first: any host-side listener that syncs its own `open` prop off `close` (the family
+    // pattern — menu.ts / select.ts / popover.ts / combo-box.ts all
+    // `this.listen(this, 'close', () => { this.open = false })`) runs synchronously inside this emit,
+    // so the prop is ALREADY false by the time `toggle` fires next (the ordering invariant, ADR-0101
+    // mechanic 3 — a renderer's two-way bind reads `el.open` at `toggle` listener time and gets the
+    // settled value on every path, commit or light-dismiss alike).
+    function announceHide() {
+        stopPositioning();
+        if (focusOnOpen)
+            restoreFocus();
+        host.emit('close');
+        host.emit('toggle'); // value:{prop:'open',event:'toggle'} two-way signal (ADR-0019)
+    }
+    // ── Platform → model: the Popover toggle listener (LLD-C2: light-dismiss) ──────────────────
+    //
+    // Rides the host's connection AbortSignal via `host.listen` — auto-removed on host disconnect.
+    // Discriminates a platform/light-dismiss close (isOpen is still true — WE never called close())
+    // from the platform's OWN ECHO of a close WE drove (isOpen was already set false before we called
+    // `hidePopover()`, so the platform's resulting toggle event is a no-op here — ADR-0101: we announce
+    // ourselves at the trait's transition points; the echo must not double-fire it).
+    host.listen(popup, 'toggle', (event) => {
+        if (cleaned)
+            return;
+        // ToggleEvent.newState is 'open' | 'closed'; cast safely for cross-engine compatibility.
+        const newState = event.newState;
+        if (newState === 'closed' && isOpen) {
+            // The platform closed the popup itself (Escape / outside-click) — WE never called close(), and
+            // the platform already hid it, so this path shares ONLY the settle+announce tail (ADR-0101
+            // mechanic 1: "the light-dismiss path flows through the same [announce] points") — NOT a
+            // redundant hidePopover() call (see announceHide()'s doc comment for why that would race).
+            isOpen = false;
+            announceHide();
+        }
+    });
+    // ── The imperative surface (OverlayHandle) ───────────────────────────────────────────────────
+    //
+    // ADR-0101 — the overlay trait announces EVERY actual open-state transition (platform-,
+    // component-, or model-driven): `open()` emits `toggle` on a real show; `close()` emits
+    // `close`+`toggle` on a real hide. Native ToggleEvent timing fidelity — ToggleEvents fire on
+    // programmatic showPopover()/hidePopover() too, not only platform light-dismiss. The no-transition
+    // early-returns below are the loop-breakers (mechanic 2: no transition ⇒ no event) — they also
+    // guard the echo-toggle from double-announcing what open()/close() already announced themselves.
+    function open() {
+        if (cleaned || isOpen)
+            return; // double-open is a no-op (idempotent) — the loop-breaker
+        if (focusOnOpen)
+            opener = document.activeElement;
+        // Set isOpen BEFORE showPopover() so the echo-toggle (newState:'open') is seen as already open
+        // (no re-entry from the toggle listener above, which only acts on newState:'closed').
+        isOpen = true;
+        popup.showPopover();
+        startPositioning();
+        if (focusOnOpen)
+            moveFocusIn();
+        host.emit('toggle'); // the real show, announced AFTER the host's own open-prop write has settled
+    }
+    function close() {
+        if (cleaned)
+            return;
+        // Idempotent, but resilient to flag desync: hide whenever the popup is ACTUALLY in the top layer,
+        // even if `isOpen` drifted false (a spurious/async platform toggle can desync the flag while the
+        // panel stays open — observed on the commit→close path). Basing the guard on `:popover-open`
+        // (with `isOpen` as the fallback for engines pre-`:popover-open`) makes model-driven close reliable.
+        const actuallyOpen = isOpen || matchesPopoverOpen(popup);
+        if (!actuallyOpen)
+            return; // no transition — the loop-breaker (ADR-0101 mechanic 2)
+        // Set isOpen BEFORE hidePopover() so the echo-toggle (newState:'closed') sees isOpen=false and
+        // skips re-entry (the toggle listener above only acts when isOpen is still true).
+        isOpen = false;
+        try {
+            popup.hidePopover(); // throws InvalidStateError only if not currently showing — a harmless no-op then
+        }
+        catch (_) {
+            // intentional: the popup was not in the top layer (already hidden) — nothing more to do
+        }
+        announceHide();
+    }
+    function toggle() {
+        if (isOpen)
+            close();
+        else
+            open();
+    }
+    function cleanup() {
+        if (cleaned)
+            return;
+        cleaned = true;
+        if (isOpen) {
+            isOpen = false;
+            try {
+                popup.hidePopover(); // may throw if the element is no longer a popover — guard it
+            }
+            catch (_) {
+                // intentional no-op: the popup is gone or no longer popover-typed; focus restore below
+            }
+        }
+        stopPositioning();
+        // restoreFocus() is intentionally NOT called here: on host disconnect the anchor is also
+        // leaving the document (it is a child of the same host). focus() on a detached element is a
+        // no-op; the browser correctly moves focus to body, which is the right behaviour on disconnect.
+        // This mirrors native <dialog>.close() co-removal: the trigger goes with the dialog.
+    }
+    // Register the cleanup as a scope-owned effect disposer so it fires automatically on host
+    // disconnect (scope.dispose() → effect disposed → cleanup()). Also usable as an early-teardown
+    // escape hatch via the returned handle's `cleanup` field.
+    host.effect(() => cleanup);
+    return { open, close, toggle, cleanup };
+}

package/dist/traits/pane-resize.d.ts

@@ -0,0 +1,26 @@
+import type { UIElement } from '../dom/index.js';
+export interface PaneResizeOptions {
+    /** Live accessor for the CURRENT separator elements, in order (re-read on every `pointerdown`). */
+    separators: () => HTMLElement[];
+    /** Live accessor for the resize axis — selects `clientX` (horizontal) vs `clientY` (vertical). */
+    axis: () => 'horizontal' | 'vertical';
+    /** Live accessor for whether the horizontal sense is right-to-left (invert the delta). */
+    rtl: () => boolean;
+    /** Called with the separator's index and the ratio delta since press. `commit=false` on each live
+     *  pointermove (drives an `input`); `commit=true` on drag-end (drives a `change`). */
+    onResize: (separatorIndex: number, deltaRatio: number, commit: boolean) => void;
+}
+export interface PaneResizeHandle {
+    /** Idempotent: stop the trait entirely (removes the outer pointerdown listener's effect + ends any
+     *  in-flight drag without committing). Call from `disconnected()`. */
+    release: () => void;
+    /** End any IN-FLIGHT drag without emitting a resize (SPEC-R2 M2) — a no-op when no drag is active. The
+     *  element's MutationObserver calls this FIRST on a mid-drag pane-count change, before re-deriving. */
+    abortDrag: () => void;
+}
+/**
+ * Wire the N-separator pointer-drag gesture on a `UIElement` host (the host IS the track — its own
+ * `getBoundingClientRect()` supplies the axis extent, the `ui-slider` precedent). Invoke from `connected()`
+ * so the outer listener rides the connection AbortSignal (auto-removed on disconnect via `host.listen`).
+ */
+export declare function paneResize(host: UIElement, opts: PaneResizeOptions): PaneResizeHandle;

package/dist/traits/pane-resize.js

@@ -0,0 +1,103 @@
+// pane-resize.ts — the axis+RTL-aware N-separator drag gesture controller (app-surfaces-m4.lld.md LLD-C2,
+// SPEC-R3/R4). A NEW, sibling trait to `value-drag.ts` — DELIBERATELY not a generalization of it (LLD §2.2
+// fork F2): `value-drag` is 1-D/horizontal/LTR-only (one track → one [min,max] value); `ui-split` needs an
+// axis-aware (`clientX`/`clientY`) + RTL-aware (inverted horizontal sense) + per-separator DELTA (not an
+// absolute value) mapping. Widening `value-drag`'s contract would risk the shipped `ui-slider`/
+// `ui-slider-multi` (the test-the-whole-shape law); this sibling trait is zero-risk and independently
+// testable. Mirrors `value-drag`'s host-scoped-pointerdown + per-drag-AbortController lifetime shape.
+//
+// Protocol (LLD §2.2): `pointerdown` on a `[data-separator]` element → identify its index (`indexOf` in the
+// live `separators()` list — the slider-multi nearer-handle-gate precedent, here a straight lookup since
+// each separator owns exactly one drag) → `setPointerCapture` → `pointermove` computes `deltaRatio` along
+// `axis()` (RTL-inverted for horizontal) SINCE THE PRESS POINT, against the HOST's own live extent (the
+// host IS the track — the `ui-slider` precedent, `track: () => this`) → `onResize(i, delta, false)` (live)
+// → `pointerup`/`lostpointercapture`/`pointercancel` → `onResize(i, delta, true)` (commit).
+//
+// Mid-drag mutation (SPEC-R2 M2): the returned handle exposes a DISTINCT `abortDrag()` — not the release
+// fn doubling as it (the review nit this LLD names) — so the element's MutationObserver can end an
+// in-flight drag on a pane-count change WITHOUT emitting a resize against the now-stale separator index.
+// `abortDrag()` is a silent stop (no `onResize` call): the caller's ratios are left exactly where the last
+// LIVE update put them — "settle at pre-mutation ratios" (LLD §2.2) falls out for free, since the element's
+// re-derive logic runs against whatever ratios currently stand, untouched by the aborted drag.
+//
+// Test-drive (SPEC-R3 INSTRUMENT-BRIDGE): the browser gate cannot exercise REAL `setPointerCapture` — a
+// synthetic PointerEvent is not an active pointer (Playwright/WebKit throws NotFoundError) — so every drag
+// is driven via synthetic `dispatchEvent(new PointerEvent(...))` with `setPointerCapture` stubbed to a
+// no-op (the `slider.browser.test.ts` `stubCapture` precedent). Capture-continuity (a `pointermove` after a
+// `pointerleave`, before `pointerup`, still resizes) is proven STRUCTURALLY: the move/up listeners live on
+// the per-drag `AbortController`, bound to the SEPARATOR element (not the connection scope), so they never
+// unbind on hover/leave — only on `pointerup`/`pointercancel`/`abortDrag()`.
+//
+// `traits → dom` is the one allowed cross-layer direction; the host type only.
+/**
+ * Wire the N-separator pointer-drag gesture on a `UIElement` host (the host IS the track — its own
+ * `getBoundingClientRect()` supplies the axis extent, the `ui-slider` precedent). Invoke from `connected()`
+ * so the outer listener rides the connection AbortSignal (auto-removed on disconnect via `host.listen`).
+ */
+export function paneResize(host, opts) {
+    let released = false;
+    let dragAc = null;
+    const endDrag = () => {
+        dragAc?.abort();
+        dragAc = null;
+    };
+    host.listen(host, 'pointerdown', (event) => {
+        if (released)
+            return;
+        const pe = event;
+        const originEl = pe.target?.closest('[data-separator]');
+        if (!originEl)
+            return;
+        const separators = opts.separators();
+        const index = separators.indexOf(originEl);
+        if (index === -1)
+            return;
+        originEl.setPointerCapture(pe.pointerId);
+        const axis = opts.axis();
+        const rtl = opts.rtl();
+        const startCoord = axis === 'horizontal' ? pe.clientX : pe.clientY;
+        // Ratio delta since the press point, against the HOST's live extent — re-measured on every call
+        // (accounts for scroll/resize mid-drag, the value-drag `re-snapshot the rect on each move` precedent).
+        const deltaFor = (clientCoord) => {
+            const rect = host.getBoundingClientRect();
+            const extent = axis === 'horizontal' ? rect.width : rect.height;
+            if (extent <= 0)
+                return 0;
+            let px = clientCoord - startCoord;
+            if (axis === 'horizontal' && rtl)
+                px = -px; // RTL inverts the horizontal sense (SPEC-R3 AC3)
+            return px / extent;
+        };
+        const localAc = new AbortController();
+        dragAc = localAc;
+        originEl.addEventListener('pointermove', (e) => {
+            const me = e;
+            if (me.pointerId !== pe.pointerId)
+                return;
+            const coord = axis === 'horizontal' ? me.clientX : me.clientY;
+            opts.onResize(index, deltaFor(coord), false);
+        }, { signal: localAc.signal });
+        const commitEnd = (e) => {
+            const me = e;
+            if (me.pointerId !== pe.pointerId)
+                return;
+            const coord = axis === 'horizontal' ? me.clientX : me.clientY;
+            opts.onResize(index, deltaFor(coord), true);
+            endDrag();
+        };
+        // Deliberately NO `pointerleave` listener — binding drag-end to hover/leave is exactly the bug SPEC-R3
+        // AC2's capture-continuity assertion bites on. The drag ends ONLY on an explicit end signal or abort.
+        originEl.addEventListener('pointerup', commitEnd, { signal: localAc.signal });
+        originEl.addEventListener('lostpointercapture', commitEnd, { signal: localAc.signal });
+        originEl.addEventListener('pointercancel', commitEnd, { signal: localAc.signal });
+    });
+    return {
+        release: () => {
+            released = true;
+            endDrag();
+        },
+        abortDrag: () => {
+            endDrag(); // silent — no onResize call, so the caller's ratios stay at their last LIVE value
+        },
+    };
+}

package/dist/traits/press-activation.d.ts

@@ -0,0 +1,11 @@
+import type { UIElement } from '../dom/index.js';
+export interface PressActivationOptions {
+    /** True ⇒ the control is disabled and the trait is inert. Read fresh on each key event. */
+    disabled: () => boolean;
+}
+/**
+ * Wire Space/Enter → `host.click()` on a `UIElement`, native-button style. Invoke from the control's
+ * `connected()` (where the host connection is live). Returns `release()` for early teardown (idempotent);
+ * otherwise the listeners auto-remove when the host disconnects.
+ */
+export declare function pressActivation(host: UIElement, opts: PressActivationOptions): () => void;