@agent-ui-kit/components 0.0.3

package/dist/dom/element.d.ts

@@ -0,0 +1,98 @@
+import { TemplateResult } from './template.js';
+export declare class UIElement extends HTMLElement {
+    #private;
+    /** Light DOM by default; a subclass sets `static shadow = true` to render into a shadow root instead. */
+    static shadow: boolean;
+    static get observedAttributes(): string[];
+    constructor();
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    /**
+     * Inbound attribute → typed prop crossing. Maps the platform's ATTRIBUTE name to its PROP name, then
+     * hands off to the shipped `coerceAttribute` (string→typed via the prop's codec). The directional lock
+     * inside `coerceAttribute` owns loop suppression — both ways — so this adapter adds NO lock logic:
+     * a `reflect` write's own echo arrives here and is suppressed (outbound lock); an external change
+     * crosses to the value without reflecting back (inbound lock).
+     */
+    attributeChangedCallback(attr: string, _old: string | null, next: string | null): void;
+    /**
+     * Resolve one pre-upgrade property shadow. A `.prop=` set BEFORE the element upgraded (before `finalize`
+     * installed the accessor) created an OWN data property that MASKS the accessor — reads/writes hit the
+     * dead own property, never the signal. Replay the value THROUGH the accessor: prefer the value the
+     * CONSTRUCTOR captured (property-wins, ADR-0005 — it predates any initial-attribute write to the shadow);
+     * fall back to the current own-property value when nothing was captured (e.g. a manual array/object
+     * accessor a control upgrades by hand, or a shadow created after construction). No-op with neither.
+     */
+    protected upgradeProperty(name: string): void;
+    /**
+     * Replay every declared prop's pre-upgrade shadow. Run at the START of `connectedCallback`. Ordering
+     * note (the lazy-upgrade ↔ attributeChanged seam): an INITIAL observed attribute is applied during
+     * upgrade — before connect — while the shadow is still present, so its inbound write lands on the
+     * shadow; but the constructor already CAPTURED the pre-upgrade property value, so the replay restores
+     * the property over the attribute (property-wins, ADR-0005). See element-upgrade.test.ts.
+     */
+    protected upgradeProps(): void;
+    /**
+     * Register a connection-scoped effect: it runs now and re-runs on dependency change, and is disposed
+     * when the host disconnects (the scope owns it). This is the one effect-install primitive —
+     * `connectedCallback` routes the render effect through it too. Returns the effect's disposer (call it
+     * to end the effect early; otherwise disconnect ends it). Throws if called outside the connected
+     * lifetime, where there is no scope to own it.
+     */
+    effect(fn: () => void | (() => void)): () => void;
+    /**
+     * Add a platform event listener that rides the connection `AbortSignal`, so it is removed
+     * automatically on disconnect (`ac.abort()`) — zero live listeners after removal, no manual teardown.
+     * `type` stays an open string so custom event names are accepted; a control narrows at its call site.
+     * Throws if called outside the connected lifetime, where there is no signal to bind to.
+     */
+    listen(target: EventTarget, type: string, handler: (event: Event) => void, opts?: AddEventListenerOptions): void;
+    /**
+     * Dispatch a composed, bubbling, cancelable `CustomEvent`. Typed generically over the detail `D`, so a
+     * caller that pins `D` (today explicitly; via an event-detail map / `HTMLElementEventMap` augmentation
+     * once controls land) gets the detail type-checked. Returns `false` if a listener called
+     * `preventDefault()`, mirroring the platform's `dispatchEvent`.
+     */
+    emit<D = undefined>(type: string, detail?: D): boolean;
+    /** Resolves after the next render flush settles — `await el.updateComplete` waits for a pending render. */
+    get updateComplete(): Promise<void>;
+    /**
+     * The render target: the shadow root when `static shadow` opted one in, else the host itself (light DOM
+     * is the default). G3's render effect commits into this — the seam lands now so G3 + the barrel compose.
+     */
+    get renderRoot(): ShadowRoot | HTMLElement;
+    /**
+     * The single `ElementInternals` handle (acquired once in the constructor). ARIA is set THROUGH this —
+     * `this.internals.role = …`, `this.internals.ariaChecked = …` — NEVER host attributes, so the host
+     * stays free of `role`/`aria-*`. The protected seam the G4 form subclass + traits reuse without
+     * re-acquiring (a second `attachInternals()` throws).
+     */
+    protected get internals(): ElementInternals;
+    /**
+     * The connection `AbortSignal`: connection-scoped platform listeners ride it, so disconnect
+     * (`abort()`) frees them in one shot. Null while disconnected. The minimal protected seam by which
+     * subclasses / traits observe the connection lifetime; `this.listen` (e-helpers) rides it.
+     */
+    protected get connectionSignal(): AbortSignal | null;
+    /**
+     * Overridable connect hook. Runs on connect with the connection scope + `AbortSignal` live, so a
+     * `this.effect`/`this.listen` registered here is scope-owned and auto-removed on disconnect. It runs
+     * BEFORE the first render (the ordering: upgradeProps → scope/ac → `connected()` → render effect), so a
+     * control's host-level setup (traits, signals) is in place before the first commit. Override instead of
+     * `connectedCallback` — no `super` call needed. (Post-render DOM work belongs in `updateComplete`.)
+     */
+    protected connected(): void;
+    /**
+     * Overridable disconnect hook. Runs on disconnect BEFORE the connection scope is disposed / the signal
+     * aborted, so the control can act while its connected resources are still live. Override instead of
+     * `disconnectedCallback` — no `super` call needed.
+     */
+    protected disconnected(): void;
+    /**
+     * Overridable render hook. Return a `TemplateResult` (`html\`…\``) and the scope-owned render effect
+     * commits it into `renderRoot`; return nothing to render imperatively (or not at all). Runs inside the
+     * connection-scoped render effect, so any signal it reads re-runs only this render, committing only the
+     * holes whose values changed (the template engine's per-part `Object.is` skip).
+     */
+    protected render(): TemplateResult | void;
+}

package/dist/dom/element.js

@@ -0,0 +1,221 @@
+// element.ts — `UIElement`, the FACE custom-element host (plan §5).
+//
+// Maps the platform's connect/disconnect callbacks onto the kernel's two lifetimes: a connection
+// **scope** (every computed/effect created under it dies on disconnect) and an **AbortController**
+// (every platform listener riding its signal dies on disconnect). "Zero residue after removal" is then
+// provable, not aspirational (goals.md G2 DoD3; rubric D4). Built so far: the connection scope/abort
+// wiring + the ONE render effect (e-lifecycle), and the public helper surface — `this.effect` (scope-
+// owned), `this.listen` (rides the abort signal → auto-removed on disconnect), `this.emit` (typed
+// `CustomEvent`), `updateComplete` (e-helpers), and the attribute inbound crossing —
+// `observedAttributes` + `attributeChangedCallback` → `coerceAttribute` (e-attrs), the lazy-property
+// upgrade dance — `upgradeProps`/`upgradeProperty` at connect (e-upgrade), and internals-only ARIA + the
+// light-DOM-default render root (e-internals). Only the dom barrel remains to close G2; `render()` stays
+// a no-op hook until the template layer (G3).
+//
+// Imports only `../reactive` (the kernel) + `./props.ts` (same dom layer). `HTMLElement` /
+// `AbortController` / `AbortSignal` / `CustomEvent` / `ElementInternals` are ambient DOM globals, not imports.
+import { createScope, effect as createEffect, whenFlushed } from "../reactive/index.js";
+import { finalize, coerceAttribute, observedAttributesFor, propForAttribute } from "./props.js";
+import { render as commitTemplate, TemplateResult } from "./template.js";
+export class UIElement extends HTMLElement {
+    // The connection lifetimes. Null while disconnected; opened on connect, torn down + nulled on
+    // disconnect. `#`-private (real JS privacy) so nothing outside the host can hold or revive them.
+    #scope = null;
+    #ac = null;
+    // The single `ElementInternals` handle, acquired ONCE here (a second `attachInternals()` throws).
+    // Surfaced to subclasses via the protected `internals` getter — a `#private` field can't cross to one.
+    #internals = this.attachInternals();
+    // Pre-upgrade `.prop=` values captured in the constructor (property-wins, ADR-0005). See the constructor.
+    #captured = new Map();
+    /** Light DOM by default; a subclass sets `static shadow = true` to render into a shadow root instead. */
+    static shadow = false;
+    // The attribute names the platform watches, derived from `static props` (property-only props excluded;
+    // `attribute` overrides honoured). Read once by `customElements.define`, before any instance exists —
+    // so it reads the schema directly, not the finalize-installed accessors.
+    static get observedAttributes() {
+        return observedAttributesFor(this);
+    }
+    constructor() {
+        super();
+        // Opt-in shadow root (light DOM is the default), attached once here so `renderRoot` is a pure getter.
+        if (this.constructor.shadow)
+            this.attachShadow({ mode: 'open' });
+        // Light the props-as-signals subsystem on this host: install the signal-backed prototype accessors
+        // declared by `static props`. Idempotent per class (props.ts' FINALIZED set), so every instance
+        // calls it but only the first instance of a class finalizes it — no props.ts change needed.
+        const ctor = this.constructor;
+        finalize(ctor);
+        // Property-wins (ADR-0005): snapshot each declared prop's pre-upgrade own-property value HERE — the
+        // constructor runs during upgrade BEFORE attributeChangedCallback can overwrite the shadow — so an
+        // imperatively-set `.prop=` beats an initial attribute. `upgradeProperty` replays the captured value.
+        if (ctor.props) {
+            for (const name of Object.keys(ctor.props)) {
+                if (Object.hasOwn(this, name))
+                    this.#captured.set(name, this[name]);
+            }
+        }
+    }
+    connectedCallback() {
+        // FIRST: replay any pre-upgrade `.prop=` shadow into its signal — before the render effect installs
+        // and before anything reads a prop, so first render sees the assigned value, not the default.
+        this.upgradeProps();
+        this.#scope = createScope();
+        this.#ac = new AbortController();
+        // The connection scope + AbortController are now live, so a `this.effect`/`this.listen` registered in
+        // `connected()` is scope-owned + rides the abort signal. `connected()` runs BEFORE the first render so
+        // host-level setup (traits, signals) is in place before the first commit — see the ordering note below.
+        this.connected();
+        // The ONE render effect, installed through `this.effect` so there is a SINGLE scope-owned-effect
+        // path (no duplication). It is created inside the scope (the kernel's `activeOwner.add`) and
+        // disposed with it at disconnect — every render pass runs under the scope, so a directive attaching
+        // on a later conditional re-render is scope-owned too. The disposer is intentionally discarded.
+        // `render()` returns a `TemplateResult` (or nothing); when it returns one, commit it into `renderRoot`.
+        this.effect(() => {
+            const result = this.render();
+            // Pass `this` as the RenderContext (the scope_seam): `UIElement` structurally satisfies it via the
+            // scope-owned `effect`, so a per-hole directive (`watch`) installs its effect under the connection
+            // scope — surviving unrelated re-renders, dying on disconnect — not under this transient render effect.
+            if (result instanceof TemplateResult)
+                commitTemplate(result, this.renderRoot, this);
+        });
+    }
+    disconnectedCallback() {
+        // Let the control act while its connected resources are STILL live (scope/effects alive, listeners
+        // unaborted) — `disconnected()` runs BEFORE the teardown below.
+        this.disconnected();
+        this.#scope?.dispose(); // every computed/effect created under the scope dies → zero subscribers
+        this.#ac?.abort(); // every listener riding the connection signal dies → zero live listeners
+        this.#scope = null;
+        this.#ac = null;
+    }
+    /**
+     * Inbound attribute → typed prop crossing. Maps the platform's ATTRIBUTE name to its PROP name, then
+     * hands off to the shipped `coerceAttribute` (string→typed via the prop's codec). The directional lock
+     * inside `coerceAttribute` owns loop suppression — both ways — so this adapter adds NO lock logic:
+     * a `reflect` write's own echo arrives here and is suppressed (outbound lock); an external change
+     * crosses to the value without reflecting back (inbound lock).
+     */
+    attributeChangedCallback(attr, _old, next) {
+        const ctor = this.constructor;
+        const name = propForAttribute(ctor, attr);
+        if (name !== undefined)
+            coerceAttribute(this, ctor, name, next);
+    }
+    /**
+     * Resolve one pre-upgrade property shadow. A `.prop=` set BEFORE the element upgraded (before `finalize`
+     * installed the accessor) created an OWN data property that MASKS the accessor — reads/writes hit the
+     * dead own property, never the signal. Replay the value THROUGH the accessor: prefer the value the
+     * CONSTRUCTOR captured (property-wins, ADR-0005 — it predates any initial-attribute write to the shadow);
+     * fall back to the current own-property value when nothing was captured (e.g. a manual array/object
+     * accessor a control upgrades by hand, or a shadow created after construction). No-op with neither.
+     */
+    upgradeProperty(name) {
+        const hasCaptured = this.#captured.has(name);
+        const hasOwn = Object.hasOwn(this, name);
+        if (!hasCaptured && !hasOwn)
+            return;
+        const value = hasCaptured ? this.#captured.get(name) : this[name];
+        this.#captured.delete(name);
+        if (hasOwn)
+            delete this[name] // dissolve the shadow → reveal the accessor
+            ;
+        this[name] = value; // replay through the accessor → the signal (+ reflect once)
+    }
+    /**
+     * Replay every declared prop's pre-upgrade shadow. Run at the START of `connectedCallback`. Ordering
+     * note (the lazy-upgrade ↔ attributeChanged seam): an INITIAL observed attribute is applied during
+     * upgrade — before connect — while the shadow is still present, so its inbound write lands on the
+     * shadow; but the constructor already CAPTURED the pre-upgrade property value, so the replay restores
+     * the property over the attribute (property-wins, ADR-0005). See element-upgrade.test.ts.
+     */
+    upgradeProps() {
+        const props = this.constructor.props;
+        if (!props)
+            return;
+        for (const name of Object.keys(props))
+            this.upgradeProperty(name);
+    }
+    /**
+     * Register a connection-scoped effect: it runs now and re-runs on dependency change, and is disposed
+     * when the host disconnects (the scope owns it). This is the one effect-install primitive —
+     * `connectedCallback` routes the render effect through it too. Returns the effect's disposer (call it
+     * to end the effect early; otherwise disconnect ends it). Throws if called outside the connected
+     * lifetime, where there is no scope to own it.
+     */
+    effect(fn) {
+        const scope = this.#scope;
+        if (!scope)
+            throw new Error('UIElement.effect: no connection scope — call it during the connected lifetime');
+        return scope.run(() => createEffect(fn));
+    }
+    /**
+     * Add a platform event listener that rides the connection `AbortSignal`, so it is removed
+     * automatically on disconnect (`ac.abort()`) — zero live listeners after removal, no manual teardown.
+     * `type` stays an open string so custom event names are accepted; a control narrows at its call site.
+     * Throws if called outside the connected lifetime, where there is no signal to bind to.
+     */
+    listen(target, type, handler, opts) {
+        const ac = this.#ac;
+        if (!ac)
+            throw new Error('UIElement.listen: no connection signal — call it during the connected lifetime');
+        target.addEventListener(type, handler, { ...opts, signal: ac.signal });
+    }
+    /**
+     * Dispatch a composed, bubbling, cancelable `CustomEvent`. Typed generically over the detail `D`, so a
+     * caller that pins `D` (today explicitly; via an event-detail map / `HTMLElementEventMap` augmentation
+     * once controls land) gets the detail type-checked. Returns `false` if a listener called
+     * `preventDefault()`, mirroring the platform's `dispatchEvent`.
+     */
+    emit(type, detail) {
+        return this.dispatchEvent(new CustomEvent(type, { detail, bubbles: true, composed: true, cancelable: true }));
+    }
+    /** Resolves after the next render flush settles — `await el.updateComplete` waits for a pending render. */
+    get updateComplete() {
+        return whenFlushed();
+    }
+    /**
+     * The render target: the shadow root when `static shadow` opted one in, else the host itself (light DOM
+     * is the default). G3's render effect commits into this — the seam lands now so G3 + the barrel compose.
+     */
+    get renderRoot() {
+        return this.shadowRoot ?? this;
+    }
+    /**
+     * The single `ElementInternals` handle (acquired once in the constructor). ARIA is set THROUGH this —
+     * `this.internals.role = …`, `this.internals.ariaChecked = …` — NEVER host attributes, so the host
+     * stays free of `role`/`aria-*`. The protected seam the G4 form subclass + traits reuse without
+     * re-acquiring (a second `attachInternals()` throws).
+     */
+    get internals() {
+        return this.#internals;
+    }
+    /**
+     * The connection `AbortSignal`: connection-scoped platform listeners ride it, so disconnect
+     * (`abort()`) frees them in one shot. Null while disconnected. The minimal protected seam by which
+     * subclasses / traits observe the connection lifetime; `this.listen` (e-helpers) rides it.
+     */
+    get connectionSignal() {
+        return this.#ac?.signal ?? null;
+    }
+    /**
+     * Overridable connect hook. Runs on connect with the connection scope + `AbortSignal` live, so a
+     * `this.effect`/`this.listen` registered here is scope-owned and auto-removed on disconnect. It runs
+     * BEFORE the first render (the ordering: upgradeProps → scope/ac → `connected()` → render effect), so a
+     * control's host-level setup (traits, signals) is in place before the first commit. Override instead of
+     * `connectedCallback` — no `super` call needed. (Post-render DOM work belongs in `updateComplete`.)
+     */
+    connected() { }
+    /**
+     * Overridable disconnect hook. Runs on disconnect BEFORE the connection scope is disposed / the signal
+     * aborted, so the control can act while its connected resources are still live. Override instead of
+     * `disconnectedCallback` — no `super` call needed.
+     */
+    disconnected() { }
+    /**
+     * Overridable render hook. Return a `TemplateResult` (`html\`…\``) and the scope-owned render effect
+     * commits it into `renderRoot`; return nothing to render imperatively (or not at all). Runs inside the
+     * connection-scoped render effect, so any signal it reads re-runs only this render, committing only the
+     * holes whose values changed (the template engine's per-part `Object.is` skip).
+     */
+    render() { }
+}

package/dist/dom/form.d.ts

@@ -0,0 +1,240 @@
+import { UIElement } from './element.js';
+import { type ReactiveProps } from './props.js';
+/**
+ * The value a form control contributes to its owning form — exactly the platform's `setFormValue` value
+ * type. `null` contributes no entry (the base's default). The subclass's `formValue()` returns its typed
+ * value coerced into this shape (a string for text-field; a `File` / `FormData` for richer controls).
+ */
+export type FormValue = File | string | FormData | null;
+/**
+ * A control's validity VERDICT — a discriminated union the base maps onto `internals.setValidity`: valid
+ * clears it; invalid publishes the platform `flags` + the `message` (+ an optional `anchor` element the UA
+ * focuses on `reportValidity`). Distinct from the platform's `ValidityState` (the live IDL object the
+ * `validity` getter returns): this is the control's per-render assertion that DRIVES it.
+ */
+export type ValidityResult = {
+    valid: true;
+} | {
+    valid: false;
+    flags: ValidityStateFlags;
+    message: string;
+    anchor?: HTMLElement;
+};
+/** Fired once, at the end of `connectedCallback` — the control announcing full connection to the nearest
+ *  provider/field ancestor. */
+export declare const FORM_CONNECT_EVENT = "ui-form-connect";
+/** Fired from `formResetCallback`, after `formReset()` — detail: none (the target IS the resetting
+ *  control). Covers BOTH reset paths: native `form.reset()` and a provider's direct `formResetCallback()` call. */
+export declare const FORM_RESET_EVENT = "ui-form-reset";
+/** The `ui-form-connect` detail. The closures are the control's PUBLIC reactive surface, minted by the base
+ *  (ADR-0050 §4 realized without widening the class API): each read, inside a computed/effect, tracks
+ *  exactly the signals the underlying hook reads. */
+export interface FormConnectDetail {
+    control: UIFormElement;
+    /** The connection-scoped teardown handle — the control's live connection AbortSignal (ADR-0050 §3).
+     *  Aborts on disconnect; a NEW signal is minted per connection (reconnect ⇒ fresh handle). */
+    signal: AbortSignal;
+    /** Reactive read of the submission value — closes over the protected `formValue()`. */
+    value: () => FormValue;
+    /** Reactive read of the MERGED validity verdict — `formValidity()` ⊕ `setCustomValidity` (the same merge
+     *  the base publishes to internals; `#mergedValidity` is the single source feeding both). */
+    validity: () => ValidityResult;
+    /** Reactive read of the user-invalid gate — closes over the `formUserInvalid()` hook (below). jsdom
+     *  cannot match `:state(user-invalid)` (no CustomStateSet), so the field's error gate rides THIS read;
+     *  the browser smokes assert its equivalence with `:state(user-invalid)` (same tracker source). */
+    userInvalid: () => boolean;
+}
+/** The field-labelling handoff (ADR-0051 cl.1). ELEMENTS, not id strings — the internals path consumes
+ *  elements; the id path reads `.id` off the node (the field seeds ids before handing over). */
+export interface FieldLabelling {
+    label: HTMLElement | null;
+    description: HTMLElement | null;
+    error: HTMLElement | null;
+}
+declare const formProps: {
+    name: {
+        reflect: true;
+        type: import("./props.js").PropType<string>;
+        default: string;
+        attribute?: string | false;
+    };
+    disabled: {
+        reflect: true;
+        type: import("./props.js").PropType<boolean>;
+        default: boolean;
+        attribute?: string | false;
+    };
+    required: {
+        reflect: true;
+        type: import("./props.js").PropType<boolean>;
+        default: boolean;
+        attribute?: string | false;
+    };
+};
+export interface UIFormElement extends ReactiveProps<typeof formProps> {
+}
+export declare class UIFormElement extends UIElement {
+    #private;
+    /** Activates platform form association — `setFormValue`/`setValidity` + the form lifecycle callbacks (clause 1). */
+    static formAssociated: boolean;
+    /** The spreadable universal form attributes — the no-static-props-inheritance workaround (clause 2). */
+    static formProps: {
+        name: {
+            reflect: true;
+            type: import("./props.js").PropType<string>;
+            default: string;
+            attribute?: string | false;
+        };
+        disabled: {
+            reflect: true;
+            type: import("./props.js").PropType<boolean>;
+            default: boolean;
+            attribute?: string | false;
+        };
+        required: {
+            reflect: true;
+            type: import("./props.js").PropType<boolean>;
+            default: boolean;
+            attribute?: string | false;
+        };
+    };
+    /**
+     * Super-wrapped wiring (clause 4). `super.connectedCallback()` opens the connection scope + AbortController,
+     * runs the no-`super` `connected()` hook, and installs the render effect; the scope is now live, so the
+     * effects below are scope-owned and disposed on disconnect (zero residue). They install AFTER the render
+     * effect — harmless: the form family's `render()` is the inherited void. The subclass keeps the clean,
+     * no-`super` `connected()` hook — it never sees this wrapper.
+     */
+    connectedCallback(): void;
+    /**
+     * Re-announce full connection (F1 — the review-caught upgrade-order hole). "Ancestors connect before
+     * descendants" holds for INSERTION order but NOT custom-element UPGRADE order: pre-existing DOM whose
+     * control module registers/upgrades before the provider/field module does means the ONE connect dispatch
+     * in `connectedCallback` fires into the void — no listener is live yet — and registration would be lost
+     * forever without a catch-up path. Public so a provider/field's one-shot catch-up scan (built at their
+     * own build slice) can call it on every already-connected `UIFormElement` it discovers late, re-dispatching
+     * `ui-form-connect` with a FRESH detail (the same minting `#connectDetail()` uses, so a reconnect since
+     * the original dispatch is reflected — a NEW connection signal, current prop values).
+     *
+     * Guard: `connectionSignal === null`, NOT `isConnected` (a real bug an s9 repro caught — the bulk-insert
+     * hazard). `isConnected` reflects DOM tree membership, set the instant a subtree is spliced in; a custom
+     * element's OWN `connectedCallback` (which opens the connection scope + mints `#ac`) fires ASYNC to that,
+     * in a separate reaction-queue pass, ancestor-first. So on a bulk insert of a pre-built offline subtree
+     * (assemble, then one `append()` — the house test idiom), every descendant is already `isConnected` the
+     * moment the PARENT's `connectedCallback` runs (and could catch-up-scan its already-`isConnected`
+     * children) even though THEIR OWN `connectedCallback` — and so `connectionSignal` — hasn't fired yet.
+     * NOT a jsdom accommodation: atomic-subtree-connect ordering (ancestor-`connectedCallback`-before-
+     * descendant, all descendants already `isConnected` throughout) is SPEC-MANDATED and holds identically in
+     * every real engine (s8 confirmed with a plain-HTMLElement probe) — this is a real-browser correctness
+     * fix, not a test-environment workaround. `connectionSignal === null` is the correct predicate for "has
+     * this control's OWN connect wiring run yet": it is null before that control's first `connectedCallback`
+     * (nothing to announce — that `connectedCallback` will dispatch for itself momentarily) AND after its
+     * `disconnectedCallback` (`#ac` is nulled there too, element.ts) — one guard covers both the not-yet-mine
+     * and no-longer-mine legs; `isConnected` is redundant once this holds and is dropped to avoid it masking
+     * the real invariant.
+     *
+     * This guard closes TWO bugs, not one. The obvious one: the pre-fix crash (a `null` `signal` in the
+     * minted detail, `detail.signal.aborted` throwing in a registry/field listener). The SILENT one (s8-found):
+     * in the same-cascade race, `ui-field`'s association still applies `aria-labelledby` (the labelling signal
+     * write does not ride the connection scope), but the affected control's OWN `connectedCallback` — and so
+     * its abort listener — had not yet run, so `this.listen(detail.signal, 'abort', …)` in `#associate` would
+     * have wired against a signal that was never live, and a later removal would never dissociate (stale
+     * labelling, forever). This guard skips the same-cascade announce entirely and lets the descendant's OWN
+     * end-of-`connectedCallback` dispatch (below the guard here — see that dispatch's own signal, always live
+     * by construction) carry the association instead, once the field/provider is already listening — so the
+     * abort listener installs correctly, every time.
+     *
+     * Also routes through `#dispatchFormConnect`'s nested-member guard — a catch-up scan's
+     * `querySelectorAll('*')` finds every `UIFormElement` descendant indiscriminately (it cannot itself
+     * distinguish an internal part like a text-field's calendar from a real member), so the guard MUST live
+     * here too, not only on the initial dispatch, or a late-discovered internal part would still register.
+     */
+    announceFormConnect(): void;
+    /**
+     * Set a renderer-driven custom validity message (ADR-0029 §5 — the A2UI `checks` seam, native-parity name).
+     * An empty string clears the custom contribution (native parity: `el.setCustomValidity('')` = valid).
+     * A non-empty message drives `{valid:false, flags:{customError:true}, message}` unless `formValidity()`
+     * is already invalid (native wins — e.g. `valueMissing` takes the display slot over a custom message).
+     * The reactive effect in `connectedCallback` picks up the `#customValidity` signal change and re-publishes
+     * through `#applyValidity` without any direct caller → `internals.setValidity` call here.
+     */
+    setCustomValidity(message: string): void;
+    /** The value this control contributes to its form. Default: nothing (`null`); the subclass returns its value. */
+    protected formValue(): FormValue;
+    /**
+     * This control's validity verdict, published to `internals.setValidity` by a scope-owned effect. Default:
+     * always valid; the subclass computes it from its props (e.g. `required && value === '' → valueMissing`).
+     *
+     * NAMED `formValidity`, NOT `validity` (parallel to `formValue`): the public IDL `validity` GETTER below
+     * returns the platform's `ValidityState`, so the verdict hook cannot share that name. ADR-0013 clauses 3/6
+     * both wrote `validity`; this base resolves the collision in favour of native IDL parity for `validity`.
+     */
+    protected formValidity(): ValidityResult;
+    /**
+     * The disabled state a control should obey: its OWN `disabled` prop OR an ancestor `<fieldset disabled>` /
+     * form-disabled state (`formDisabledCallback`). Reactive — read it inside an effect and it re-runs when
+     * either source flips. (The form-disabled channel is the ADR-0013 divergence from ADR-0010's `ariaDisabled`
+     * for non-form controls.)
+     */
+    effectiveDisabled(): boolean;
+    /**
+     * Platform reset → the `formReset()` hook (the subclass restores value ← its defaultValue; clause 2), THEN
+     * the ADR-0051 `ui-form-reset` protocol dispatch (composed, bubbling, no detail — the target IS the
+     * resetting control) so an observing `ui-field` re-suppresses its visible error. Covers BOTH reset paths:
+     * native `form.reset()` (the platform walks its FACE members' `formResetCallback`s) and a form-less
+     * provider's direct call to this same public platform callback.
+     */
+    formResetCallback(): void;
+    /** Platform fieldset/form-disabled change → the reactive `#formDisabled` signal behind `effectiveDisabled()`. */
+    formDisabledCallback(disabled: boolean): void;
+    /** Platform state restore (navigation/autofill) → the `formStateRestore(state)` hook. */
+    formStateRestoreCallback(state: File | string | FormData | null, _mode: 'restore' | 'autocomplete'): void;
+    /** Platform association change → the no-op `formAssociated(form)` hook (an extension point). */
+    formAssociatedCallback(form: HTMLFormElement | null): void;
+    /** Restore value ← defaultValue on form reset. Default no-op — the subclass owns `value` + its defaultValue. */
+    protected formReset(): void;
+    /** Restore value from a previously-submitted/autofilled form state. Default no-op — the subclass decodes `state`. */
+    protected formStateRestore(_state: File | string | FormData | null): void;
+    /** Called when the element associates with / disassociates from a form. Default no-op extension point. */
+    protected formAssociated(_form: HTMLFormElement | null): void;
+    /** The owning `<form>`, or null. */
+    get form(): HTMLFormElement | null;
+    /** The platform's live `ValidityState` (the IDL object; distinct from the `formValidity()` verdict hook). */
+    get validity(): ValidityState;
+    /** The platform validation message (the `setValidity` message; empty when valid). */
+    get validationMessage(): string;
+    /** Whether this control is a candidate for constraint validation. */
+    get willValidate(): boolean;
+    /** Run constraint validation, firing an `invalid` event when invalid. */
+    checkValidity(): boolean;
+    /** Like `checkValidity`, and additionally reports the problem to the user (focuses the anchor). */
+    reportValidity(): boolean;
+    /**
+     * Public — a `ui-field` calls this with its label/description/error part elements; `null` clears the
+     * association (control removed from its field, or the field itself torn down). Signal-backed (the
+     * `setCustomValidity` precedent, ADR-0029 §5) — deliberately NOT a prop: elements can't ride attributes,
+     * so this stays off the attributes-as-API descriptor surface. Safe on a disconnected control (a plain
+     * signal write); the base effect applies it on next connect.
+     */
+    setFieldLabelling(refs: FieldLabelling | null): void;
+    /** Protected reactive read — an override's forwarding effect (or a subclass's own label/message effects,
+     *  e.g. text-field's wire) re-runs on association/clear. */
+    protected get fieldLabelling(): FieldLabelling | null;
+    /**
+     * Protected forwarding hook (ADR-0051 cl.2), applied by the base scope-owned effect installed in
+     * `connectedCallback`. Default: internals ARIA element reflection, GUARDED on `internals.role != null` —
+     * every internals-role control (checkbox/switch/radio/slider/calendar) wires for FREE, while a role-less
+     * host deliberately no-ops (a half-attached name on a role-less AX node is silent lossiness that can fool
+     * a probe — a part-role control, e.g. text-field, MUST override instead). Contract for an override:
+     * idempotent; handle `null` (clear); guard a not-yet-created part.
+     */
+    protected applyFieldLabelling(refs: FieldLabelling | null): void;
+    /**
+     * Protected user-invalid gate, feeding `FormConnectDetail.userInvalid` (ADR-0050). Default `false`. A
+     * control composing `trackUserInvalid` overrides it with its tracker's gate (`() =>
+     * tracker.userInvalid()`), keeping ONE timing source — the field's error observation rides this read
+     * (jsdom cannot match `:state(user-invalid)`; the browser gate asserts the equivalence).
+     */
+    protected formUserInvalid(): boolean;
+}
+export {};