@agent-ui-kit/components 0.0.3

package/dist/dom/watch.js

@@ -0,0 +1,82 @@
+// watch.ts — the `watch` directive (plan §6; G3 slice 2, per-hole scoped reactivity).
+//
+// `watch(source)` is a value-producing child directive: it owns ONE inner sub-`ChildPart` and ONE
+// connection-scope-owned effect. The effect reads `source` (a `ReadonlySignal`'s `.value`, or a thunk
+// `() => T`) UNDER ITS OWN tracking context and commits the value through the inner part — so the value can
+// be text, a `TemplateResult`, an array, or even a nested directive (full part machinery, including the
+// per-part `Object.is` skip). The headline invariant: a watched-signal change wakes ONLY this hole's effect;
+// the HOST render effect gains no source on the watched signal, so it does NOT re-run (rubric D5).
+//
+// The effect is installed via `ctx.effect` (the scope_seam from template.ts), NOT a bare `effect()`. This
+// makes it owned by the CONNECTION SCOPE: it survives unrelated host re-renders, dies on disconnect with
+// zero residue (the watched signal drops to zero subscribers), and respawns on reconnect. The `installed`
+// flag (reset by the effect's own cleanup when the scope disposes it) guarantees install-once — a host
+// re-render or a reconnect never double-installs. The directive instance persists in the (persisted)
+// `ChildPart` across disconnect/reconnect; only the scope-owned effect dies and is re-installed.
+//
+// Imports only `../reactive` (the `ReadonlySignal` type) + the directive seam from `./template.ts`; not
+// re-exported from this file — the dom barrel (S3) re-exports `watch`.
+import { Directive, directive, NO_COMMIT } from "./template.js";
+/** Read a source UNDER the caller's tracking context — `.value` for a signal, a call for a thunk. */
+function readSource(source) {
+    return typeof source === 'function' ? source() : source.value;
+}
+/**
+ * The `watch` directive instance. One inner sub-part + one scope-owned effect. `update` stores the current
+ * source/mapper (a host re-render may hand new ones) and installs the effect ONCE, via `ctx.effect`. The
+ * effect reads the source under its own tracking context — subscribing THIS effect, not the host render
+ * effect — and commits the (optionally mapped) value through the inner part. Returns `NO_COMMIT`: the
+ * directive owns its DOM (the inner sub-part), so the host part commits nothing.
+ */
+class WatchDirective extends Directive {
+    // The sub-`ChildPart` the effect commits into. Created in the field initializer (runs after the base
+    // constructor stored the host part), so it persists with the instance across disconnect/reconnect.
+    #inner = this.createPart();
+    #source;
+    #mapper;
+    #installed = false;
+    // The effect's disposer — kept so a LEAVE-directive-mode `dispose()` (while still connected) can stop the
+    // effect before it commits into the torn-down inner part. On DISCONNECT the connection scope disposes the
+    // effect directly (this disposer is not called); both paths are idempotent.
+    #disposeEffect;
+    update(args, ctx) {
+        this.#source = args[0];
+        this.#mapper = args[1];
+        // Install ONCE per connection. A host re-render re-runs `update` with `installed === true` → only the
+        // source/mapper fields above are refreshed; the effect is NOT re-installed (no per-render churn). Without
+        // a `ctx` (a bare 2-arg `render`, no host scope) there is no owner to install under — stay un-installed.
+        if (!this.#installed && ctx) {
+            this.#disposeEffect = ctx.effect(() => {
+                // Re-assert liveness at the TOP of every run. The kernel calls an effect's cleanup before EVERY
+                // re-run (not only on disposal), so resetting `installed` in the cleanup alone would wrongly mark a
+                // signal-driven re-run as un-installed and let the next host re-render double-install. The body runs
+                // only while the effect is alive, so a normal re-run nets `true` (cleanup false → body true) while a
+                // DISPOSAL nets `false` (cleanup false → body never runs) — the flag tracks true liveness.
+                this.#installed = true;
+                const raw = readSource(this.#source); // tracked by THIS effect (activeConsumer = this effect)
+                this.#inner.commit(this.#mapper ? this.#mapper(raw) : raw);
+                return () => {
+                    this.#installed = false;
+                };
+            });
+        }
+        return NO_COMMIT;
+    }
+    dispose() {
+        this.#disposeEffect?.(); // stop the effect first so it cannot commit into a torn-down inner part
+        this.#disposeEffect = undefined;
+        this.#inner.dispose();
+    }
+}
+const watchDirective = directive(WatchDirective);
+/**
+ * `watch(source, mapper?)` — bind a child hole to a reactive `source` so only that hole updates when the
+ * source changes (the host render effect never re-runs for it). `source` is a `ReadonlySignal<T>` (read via
+ * `.value`) or a thunk `() => T` (the general form; a thunk tracks whatever signals it reads at run time).
+ * An optional `mapper` transforms the value before it is committed. Use inside a `UIElement.render()` so the
+ * host threads its connection scope; outside a host (a bare 2-arg `render`) there is no scope to own the
+ * effect and the hole stays empty.
+ */
+export function watch(source, mapper) {
+    return watchDirective(source, mapper);
+}

package/dist/foundation-styles.css

@@ -0,0 +1,9 @@
+/* foundation-styles.css — the global foundation stylesheet barrel (ADR-0003). Aggregates the cross-package
+ * foundation layer from `@agent-ui-kit/shared`: the colour `tokens.css` FIRST, then the dimensional ramp
+ * `dimensions.css` (authored to load AFTER tokens). A host page links this BEFORE component-styles.css, so
+ * the `--md-sys-color-*` roles + `--ui-{height,font,gap}-*` ramp exist when a control's `:where()` block resolves them.
+ * Exposed as the package `./foundation-styles.css` export. `@agent-ui-kit/shared` is the one allowed
+ * cross-package dependency (ADR-0003 / the import-layering law). Order is load-bearing — do not reorder.
+ */
+@import '@agent-ui-kit/shared/tokens.css';
+@import '@agent-ui-kit/shared/dimensions.css';

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export * from './reactive/index.js';
+export * from './dom/index.js';

package/dist/index.js

@@ -0,0 +1,3 @@
+// @agent-ui-kit/components — package barrel. Re-exports each layer's public surface as it lands.
+export * from "./reactive/index.js";
+export * from "./dom/index.js";

package/dist/reactive/graph.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Thrown when a computed is read during its own recomputation — a reactive cycle.
+ * Without this guard a WARM cycle serves a stale value silently: the re-entrant
+ * refresh sees the sources the outer run just cleared, verification concludes
+ * "unchanged", and the stale value is returned with no error.
+ */
+export declare class CycleError extends Error {
+}
+/** A reactive value you can read (tracked) and peek (untracked) but not write. */
+export interface ReadonlySignal<T> {
+    readonly value: T;
+    peek(): T;
+}
+/** A writable reactive cell. */
+export interface Signal<T> extends ReadonlySignal<T> {
+    value: T;
+}
+/** Ownership container: every computed/effect created inside dies with it. */
+export interface Scope {
+    run<R>(fn: () => R): R;
+    dispose(): void;
+}
+/** A read-only, graph-inert snapshot of a node (the public face of the internals). */
+export type NodeSnapshot = Readonly<{
+    kind: 'signal';
+    value: unknown;
+    version: number;
+    subscribers: number;
+}> | Readonly<{
+    kind: 'computed';
+    value: unknown;
+    version: number;
+    subscribers: number;
+    sources: number;
+    dirty: boolean;
+    failed: boolean;
+    disposed: boolean;
+}>;
+/** Read without subscribing the current consumer. */
+export declare function untracked<T>(fn: () => T): T;
+/**
+ * Create reactive nodes OUTSIDE any ownership scope — the mirror of `untracked`.
+ * Module-singleton machinery created lazily on first touch must not be adopted by
+ * whichever component scope happened to trigger that first touch, or the component's
+ * disconnect freezes the singleton.
+ */
+export declare function unowned<T>(fn: () => T): T;
+/** A writable reactive cell. */
+export declare const signal: <T>(initial: T) => Signal<T>;
+/** A derived value: recomputed lazily, cut on equality. */
+export declare const computed: <T>(fn: () => T) => ReadonlySignal<T>;
+/**
+ * Runs synchronously once, then re-runs batched + deduped on dependency change.
+ * Returns a dispose function.
+ */
+export declare function effect(fn: () => void | (() => void)): () => void;
+/** A flat ownership scope: every computed/effect created inside dies with it. */
+export declare function createScope(): Scope;
+/**
+ * Read-only introspection of a graph node. PURE and graph-inert: it reads cached
+ * private state directly, so it NEVER subscribes, refreshes, or bumps a version —
+ * safe to call from anywhere, including inside a tracking context. It reports what
+ * the node CURRENTLY holds; it does not force a stale computed to evaluate.
+ */
+export declare function inspect(node: ReadonlySignal<unknown>): NodeSnapshot;

package/dist/reactive/graph.js

@@ -0,0 +1,310 @@
+// graph.ts — the producer/consumer half of the reactivity kernel.
+//
+// Push possible-staleness, pull values, cut on equality (version-verified at both
+// computeds AND effects). Eager invalidation, lazy recomputation. Ownership scopes
+// make disposal provable: after scope.dispose(), no producer holds a reference to
+// any node created inside it. Its only import is the scheduler half, pulling exactly
+// { schedule, dequeue }.
+import { schedule, dequeue } from "./scheduler.js";
+const UNSET = Symbol('unset');
+/**
+ * Thrown when a computed is read during its own recomputation — a reactive cycle.
+ * Without this guard a WARM cycle serves a stale value silently: the re-entrant
+ * refresh sees the sources the outer run just cleared, verification concludes
+ * "unchanged", and the stale value is returned with no error.
+ */
+export class CycleError extends Error {
+}
+let activeConsumer = null;
+let activeOwner = null;
+/** Read without subscribing the current consumer. */
+export function untracked(fn) {
+    const prev = activeConsumer;
+    activeConsumer = null;
+    try {
+        return fn();
+    }
+    finally {
+        activeConsumer = prev;
+    }
+}
+/**
+ * Create reactive nodes OUTSIDE any ownership scope — the mirror of `untracked`.
+ * Module-singleton machinery created lazily on first touch must not be adopted by
+ * whichever component scope happened to trigger that first touch, or the component's
+ * disconnect freezes the singleton.
+ */
+export function unowned(fn) {
+    const prev = activeOwner;
+    activeOwner = null;
+    try {
+        return fn();
+    }
+    finally {
+        activeOwner = prev;
+    }
+}
+// ── producers / consumers ─────────────────────────────────────────────────────
+class SignalNode {
+    subs = new Set();
+    version = 0;
+    #value;
+    constructor(v) {
+        this.#value = v;
+    }
+    get value() {
+        activeConsumer?.track(this);
+        return this.#value;
+    }
+    set value(next) {
+        if (Object.is(next, this.#value))
+            return;
+        this.#value = next;
+        this.version++;
+        for (const c of [...this.subs])
+            c.markStale();
+    }
+    peek() {
+        return this.#value;
+    }
+    snapshot() {
+        return Object.freeze({ kind: 'signal', value: this.#value, version: this.version, subscribers: this.subs.size });
+    }
+}
+class ComputedNode {
+    subs = new Set();
+    sources = new Map(); // producer -> version seen
+    version = 0;
+    #dirty = true;
+    #failed = false;
+    #disposed = false;
+    #running = false;
+    #value = UNSET;
+    #fn;
+    constructor(fn) {
+        this.#fn = fn;
+        activeOwner?.add(this);
+    }
+    get value() {
+        if (!this.#disposed) {
+            // Settle BEFORE the consumer records our version — track-first records a
+            // stale version and forces one spurious downstream recompute per change.
+            this.refresh();
+            activeConsumer?.track(this);
+        }
+        return this.#value;
+    }
+    peek() {
+        if (!this.#disposed)
+            this.refresh();
+        return this.#value;
+    }
+    track(src) {
+        this.sources.set(src, src.version);
+        src.subs.add(this);
+    }
+    markStale() {
+        if (this.#dirty || this.#disposed)
+            return;
+        this.#dirty = true;
+        for (const c of [...this.subs])
+            c.markStale(); // propagate possible-staleness
+    }
+    refresh() {
+        if (this.#running)
+            throw new CycleError('reactive cycle: computed re-entered during its own recomputation');
+        if (!this.#dirty || this.#disposed)
+            return;
+        this.#running = true;
+        try {
+            this.#refreshInner();
+        }
+        finally {
+            this.#running = false;
+        }
+    }
+    #refreshInner() {
+        // `#dirty` clears only on a SUCCESSFUL path. A throwing computed stays stale and
+        // retries on the next read — it never silently serves a stale value after an error.
+        if (this.#value !== UNSET && !this.#failed) {
+            // Verification: recompute only if some source's VALUE changed. Skipped after a
+            // failure — the failed run partially re-tracked sources at their CURRENT versions,
+            // so verification would wrongly conclude "unchanged" and serve the stale value.
+            let changed = false;
+            for (const [src, seen] of this.sources) {
+                src.refresh?.(); // pull nested computeds fresh first (may throw → still dirty)
+                if (src.version !== seen) {
+                    changed = true;
+                    break;
+                }
+            }
+            if (!changed) {
+                this.#dirty = false; // sources were noisy, values unchanged
+                return;
+            }
+        }
+        for (const src of this.sources.keys())
+            src.subs.delete(this);
+        this.sources.clear();
+        const prev = activeConsumer;
+        activeConsumer = this;
+        let next;
+        try {
+            next = this.#fn();
+        }
+        catch (err) {
+            this.#failed = true; // poison verification: the retry must recompute
+            throw err;
+        }
+        finally {
+            activeConsumer = prev;
+        }
+        this.#failed = false;
+        this.#dirty = false;
+        if (!Object.is(next, this.#value)) {
+            this.#value = next;
+            this.version++; // equality cutoff: no bump → downstream never wakes
+        }
+    }
+    dispose() {
+        if (this.#disposed)
+            return;
+        this.#disposed = true;
+        for (const src of this.sources.keys())
+            src.subs.delete(this);
+        this.sources.clear();
+        this.subs.clear();
+    }
+    snapshot() {
+        return Object.freeze({
+            kind: 'computed',
+            value: this.#value === UNSET ? undefined : this.#value,
+            version: this.version,
+            subscribers: this.subs.size,
+            sources: this.sources.size,
+            dirty: this.#dirty,
+            failed: this.#failed,
+            disposed: this.#disposed,
+        });
+    }
+}
+class EffectNode {
+    sources = new Map();
+    #disposed = false;
+    #failed = false;
+    #cleanup = undefined;
+    #fn;
+    constructor(fn) {
+        this.#fn = fn;
+        activeOwner?.add(this);
+    }
+    track(src) {
+        this.sources.set(src, src.version);
+        src.subs.add(this);
+    }
+    markStale() {
+        if (!this.#disposed)
+            schedule(this);
+    }
+    run() {
+        if (this.#disposed)
+            return;
+        if (this.sources.size && !this.#failed) {
+            // Same verification as Computed: a scheduled effect whose sources verify
+            // unchanged skips its body — the equality cutoff reaches effects.
+            let changed = false;
+            for (const [src, seen] of this.sources) {
+                src.refresh?.();
+                if (src.version !== seen) {
+                    changed = true;
+                    break;
+                }
+            }
+            if (!changed)
+                return;
+        }
+        this.#cleanup?.();
+        this.#cleanup = undefined; // a throwing body must not leave a consumed cleanup re-callable
+        for (const src of this.sources.keys())
+            src.subs.delete(this);
+        this.sources.clear();
+        const prev = activeConsumer;
+        activeConsumer = this;
+        try {
+            const r = this.#fn();
+            this.#cleanup = typeof r === 'function' ? r : undefined;
+            this.#failed = false;
+        }
+        catch (err) {
+            this.#failed = true;
+            throw err;
+        }
+        finally {
+            activeConsumer = prev;
+        }
+    }
+    dispose() {
+        if (this.#disposed)
+            return;
+        this.#disposed = true;
+        dequeue(this); // the dispose-while-queued seam
+        this.#cleanup?.();
+        this.#cleanup = undefined;
+        for (const src of this.sources.keys())
+            src.subs.delete(this);
+        this.sources.clear();
+    }
+}
+// ── ownership ─────────────────────────────────────────────────────────────────
+class ScopeImpl {
+    #nodes = new Set();
+    add(node) {
+        this.#nodes.add(node);
+    }
+    run(fn) {
+        const prev = activeOwner;
+        activeOwner = this;
+        try {
+            return fn();
+        }
+        finally {
+            activeOwner = prev;
+        }
+    }
+    dispose() {
+        for (const n of this.#nodes)
+            n.dispose();
+        this.#nodes.clear();
+    }
+}
+// ── factories ───────────────────────────────────────────────────────────────
+/** A writable reactive cell. */
+export const signal = (initial) => new SignalNode(initial);
+/** A derived value: recomputed lazily, cut on equality. */
+export const computed = (fn) => new ComputedNode(fn);
+/**
+ * Runs synchronously once, then re-runs batched + deduped on dependency change.
+ * Returns a dispose function.
+ */
+export function effect(fn) {
+    const e = new EffectNode(fn);
+    e.run();
+    return () => e.dispose();
+}
+/** A flat ownership scope: every computed/effect created inside dies with it. */
+export function createScope() {
+    return new ScopeImpl();
+}
+/**
+ * Read-only introspection of a graph node. PURE and graph-inert: it reads cached
+ * private state directly, so it NEVER subscribes, refreshes, or bumps a version —
+ * safe to call from anywhere, including inside a tracking context. It reports what
+ * the node CURRENTLY holds; it does not force a stale computed to evaluate.
+ */
+export function inspect(node) {
+    if (node instanceof SignalNode)
+        return node.snapshot();
+    if (node instanceof ComputedNode)
+        return node.snapshot();
+    throw new TypeError('inspect: not a reactive node (expected a signal or computed)');
+}

package/dist/reactive/index.d.ts

@@ -0,0 +1,3 @@
+export { signal, computed, effect, createScope, untracked, unowned, inspect, CycleError } from './graph.js';
+export type { Signal, ReadonlySignal, Scope, NodeSnapshot } from './graph.js';
+export { whenFlushed } from './scheduler.js';

package/dist/reactive/index.js

@@ -0,0 +1,4 @@
+// reactive — the signals kernel. The bottom layer: imports nothing outside reactive/.
+// Public surface only; the Producer/Consumer protocol and the node classes stay internal.
+export { signal, computed, effect, createScope, untracked, unowned, inspect, CycleError } from "./graph.js";
+export { whenFlushed } from "./scheduler.js";

package/dist/reactive/scheduler.d.ts

@@ -0,0 +1,13 @@
+/** The queue's structural element type — anything that can be run once. Naming it
+ *  structurally (not Effect) is what keeps this module import-free. */
+export interface Schedulable {
+    run(): void;
+}
+/** Enqueue an effect; arm a microtask flush on the first add of a batch. */
+export declare function schedule(effect: Schedulable): void;
+/** Drop an effect from the pending queue — the dispose-while-queued seam. */
+export declare function dequeue(effect: Schedulable): void;
+/** Drain the queue now. Production flow is microtask-driven; probes call this. */
+export declare function flush(): void;
+/** Resolves after the current batch settles. */
+export declare const whenFlushed: () => Promise<void>;

package/dist/reactive/scheduler.js

@@ -0,0 +1,49 @@
+// scheduler.ts — the microtask-queue half of the reactivity kernel.
+//
+// Owns the effect queue, the ~100-wave write-loop budget, and the settled-promise
+// machinery behind whenFlushed(). Imports NOTHING: the queue's element type is the
+// structural `Schedulable` below, so this half never names the graph half. The
+// cross-module seam is inbound only — an Effect calls schedule(this) on staleness
+// and dequeue(this) on dispose.
+let queue = new Set(); // Set: structural dedupe — no `queued` flag to desync
+let scheduled = false;
+let settled = Promise.resolve();
+let resolveSettled = null;
+/** Enqueue an effect; arm a microtask flush on the first add of a batch. */
+export function schedule(effect) {
+    queue.add(effect);
+    if (!scheduled) {
+        scheduled = true;
+        settled = new Promise((r) => (resolveSettled = r));
+        queueMicrotask(flush);
+    }
+}
+/** Drop an effect from the pending queue — the dispose-while-queued seam. */
+export function dequeue(effect) {
+    queue.delete(effect);
+}
+/** Drain the queue now. Production flow is microtask-driven; probes call this. */
+export function flush() {
+    let waves = 0;
+    try {
+        while (queue.size) {
+            if (++waves > 100) {
+                queue.clear();
+                throw new Error('effect write-loop: queue failed to settle in 100 waves');
+            }
+            const wave = [...queue];
+            queue.clear();
+            for (const e of wave)
+                e.run();
+        }
+    }
+    finally {
+        // Runs on a normal drain, the budget throw, AND a throwing effect — the
+        // scheduler must never wedge in `scheduled = true`.
+        scheduled = false;
+        resolveSettled?.();
+        resolveSettled = null;
+    }
+}
+/** Resolves after the current batch settles. */
+export const whenFlushed = () => settled;

package/dist/traits/area-drag.d.ts

@@ -0,0 +1,12 @@
+import type { UIElement } from '../dom/index.js';
+export interface AreaDragOptions {
+    /** Live accessor returning the 2-axis area element. Re-read on each pointerdown. */
+    area: () => HTMLElement | null;
+    /** Called with the pointer-mapped ratios (both ∈ [0,1], clamped) during drag — x = left→right, y = top→bottom. */
+    onValue: (x: number, y: number) => void;
+}
+/**
+ * Wire pointer→(x,y) gesture tracking on a `UIElement` host. Invoke from `connected()` so listeners ride the
+ * connection AbortSignal (auto-removed on disconnect). Returns cleanup (idempotent).
+ */
+export declare function areaDrag(host: UIElement, opts: AreaDragOptions): () => void;

package/dist/traits/area-drag.js

@@ -0,0 +1,70 @@
+// area-drag.ts — the pointer→(x,y) gesture controller (LLD-C4, color-picker.lld.md · ADR-0123 cl.4). The
+// 2-axis sibling of value-drag.ts: maps pointer events on an area element's rect to a (ratioX, ratioY) pair
+// ∈ [0,1]², clamped, x = left→right and y = top→bottom. `value-drag` stays UNCHANGED (reused verbatim by the
+// composed `ui-slider` channels) — this is the honest new primitive the 2D pad needs, not an edit to it.
+//
+// Protocol — identical lifetime discipline to value-drag: pointerdown → setPointerCapture → pointermove (both
+// ratios re-computed from a re-read rect → onValue(x, y)) → pointerup / lostpointercapture / pointercancel
+// (drag end). The outer pointerdown listener rides host.listen (connection-signal-scoped, zero residue on
+// disconnect); per-drag listeners live on the area under a per-drag AbortController aborted on any drag-end
+// event, bounding their lifetime to the drag itself (the value-drag precedent, unchanged).
+//
+// `traits → dom` is the one allowed cross-layer direction; the host type only.
+/** Map a client point to a [0,1]² ratio pair along the area rect. */
+function ratiosFromPoint(clientX, clientY, rect) {
+    const x = rect.width <= 0 ? 0 : Math.max(0, Math.min(1, (clientX - rect.left) / rect.width));
+    const y = rect.height <= 0 ? 0 : Math.max(0, Math.min(1, (clientY - rect.top) / rect.height));
+    return { x, y };
+}
+/**
+ * Wire pointer→(x,y) gesture tracking on a `UIElement` host. Invoke from `connected()` so listeners ride the
+ * connection AbortSignal (auto-removed on disconnect). Returns cleanup (idempotent).
+ */
+export function areaDrag(host, opts) {
+    let released = false;
+    // Listen on the host so this listener auto-removes on disconnect (host.listen = connection-signal-scoped).
+    // A pointerdown on an area child bubbles up here; opts.area() is re-read on every press.
+    host.listen(host, 'pointerdown', (event) => {
+        if (released)
+            return;
+        const area = opts.area();
+        if (!area)
+            return;
+        const pe = event;
+        // Ignore presses that did not originate from within the area.
+        if (!area.contains(pe.target))
+            return;
+        area.setPointerCapture(pe.pointerId);
+        // Snapshot the rect on press; re-snapshot on each move (accounts for scroll / resize).
+        let rect = area.getBoundingClientRect();
+        const first = ratiosFromPoint(pe.clientX, pe.clientY, rect);
+        opts.onValue(first.x, first.y);
+        // Per-drag AbortController — aborted on any drag-end event, bounding all drag listeners.
+        const dragAc = new AbortController();
+        const endDrag = () => { dragAc.abort(); };
+        area.addEventListener('pointermove', (e) => {
+            const me = e;
+            if (me.pointerId !== pe.pointerId)
+                return;
+            rect = area.getBoundingClientRect();
+            const next = ratiosFromPoint(me.clientX, me.clientY, rect);
+            opts.onValue(next.x, next.y);
+        }, { signal: dragAc.signal });
+        area.addEventListener('pointerup', (e) => {
+            if (e.pointerId !== pe.pointerId)
+                return;
+            endDrag();
+        }, { signal: dragAc.signal });
+        area.addEventListener('lostpointercapture', (e) => {
+            if (e.pointerId !== pe.pointerId)
+                return;
+            endDrag();
+        }, { signal: dragAc.signal });
+        area.addEventListener('pointercancel', (e) => {
+            if (e.pointerId !== pe.pointerId)
+                return;
+            endDrag();
+        }, { signal: dragAc.signal });
+    });
+    return () => { released = true; };
+}

package/dist/traits/form-registry.d.ts

@@ -0,0 +1,36 @@
+import type { ReadonlySignal } from '../reactive/index.js';
+import { UIFormElement } from '../dom/index.js';
+import type { UIElement, FormValue, ValidityResult } from '../dom/index.js';
+/** One registered control's PUBLIC reactive surface — the `ui-form-connect` detail, minus the teardown
+ *  handle the registry has already consumed (its `abort` is wired to `removeMember` at registration). */
+export interface FormMember {
+    control: UIFormElement;
+    value: () => FormValue;
+    validity: () => ValidityResult;
+}
+export interface FormRegistryController {
+    /** Live members, registration order (≈ document order for parse/append; a re-slotted control re-enters
+     *  at the end — documented, not corrected). */
+    members: ReadonlySignal<readonly FormMember[]>;
+    /** Submission entries — native FormData parity: name ≠ '', not effectiveDisabled(), value() ≠ null;
+     *  duplicate names PRESERVED. */
+    entries: ReadonlySignal<ReadonlyArray<readonly [string, FormValue]>>;
+    /** Keyed convenience view of entries — LAST entry wins on a duplicate name (documented). */
+    values: ReadonlySignal<Readonly<Record<string, FormValue>>>;
+    /** Members whose merged verdict is invalid — unnamed controls INCLUDED (native: validation is
+     *  name-independent), effectiveDisabled() members EXCLUDED (native: disabled ⇒ barred from constraint
+     *  validation). */
+    invalid: ReadonlySignal<readonly UIFormElement[]>;
+    /** invalid().length === 0 */
+    valid: ReadonlySignal<boolean>;
+    /** Idempotent early teardown (the trait contract); otherwise everything dies with the connection. */
+    release: () => void;
+}
+/**
+ * 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 declare function formRegistry(host: UIElement): FormRegistryController;