@agent-ui-kit/components 0.0.3

package/dist/dom/props.js

@@ -0,0 +1,231 @@
+// props.ts — typed props-as-signals (plan §5).
+//
+// Two halves: (1) the COMPILE-TIME typing contract — `PropType`/`PropConfig`/`prop.*`/`ReactiveProps`
+// — that proves the headline TS bet (an `as const` enum prop declare-merges to its literal union,
+// never widened to `string`; goals.md G2 DoD1, proven in `props-typing.test.ts`); and (2) the RUNTIME
+// install, `finalize()`, which turns that contract into per-instance signal-backed prototype accessors
+// (goals.md G2 DoD2). `finalize` is the FIRST dom module code to touch the `../reactive` kernel —
+// the one allowed direction (dom → reactive). No decorators / enum / namespace (erasableSyntaxOnly).
+//
+// The runtime half also owns the attribute↔value REFLECTION BOUNDARY (goals.md G2 DoD2; rubric D3).
+// The string↔typed boundary lives at EXACTLY TWO functions: `coerceAttribute` (inbound, string→typed
+// via `PropType.from`) and `reflectOut` (outbound, typed→string via `PropType.to`). A per-instance
+// DIRECTIONAL LOCK guards each against the other so the platform's `attributeChangedCallback` echo
+// cannot loop: while a value→attribute reflect is in flight the inbound echo it triggers is suppressed,
+// and while an attribute→value coercion is in flight the setter does not reflect it back out.
+import { signal } from "../reactive/index.js";
+const stringType = {
+    from(attr) {
+        return attr ?? '';
+    },
+    to(value) {
+        return value;
+    },
+};
+const numberType = {
+    from(attr) {
+        return attr === null || attr === '' ? null : Number(attr);
+    },
+    to(value) {
+        return value === null ? null : String(value);
+    },
+};
+const booleanType = {
+    from(attr) {
+        return attr !== null; // presence semantics
+    },
+    to(value) {
+        return value ? '' : null;
+    },
+};
+/** A codec for a fixed string-literal set; `from` snaps an unknown attribute back to the first member. */
+export function enumType(values) {
+    return {
+        from(attr) {
+            return attr !== null && values.includes(attr) ? attr : values[0];
+        },
+        to(value) {
+            return value;
+        },
+    };
+}
+/** A codec for an arbitrary JSON-serializable value of type `T` (round-trips via JSON). */
+export function jsonType() {
+    return {
+        from(attr) {
+            return attr === null ? null : JSON.parse(attr);
+        },
+        to(value) {
+            return JSON.stringify(value);
+        },
+    };
+}
+/** The three fixed codecs (the parametric `enumType`/`jsonType` are factories above). */
+export const Types = {
+    string: stringType,
+    number: numberType,
+    boolean: booleanType,
+};
+export const prop = {
+    string(def = '') {
+        return { type: Types.string, default: def };
+    },
+    number(def = null) {
+        return { type: Types.number, default: def };
+    },
+    boolean(def = false) {
+        return { type: Types.boolean, default: def };
+    },
+    enum(values, def) {
+        return { type: enumType(values), default: def };
+    },
+    json(def) {
+        return { type: jsonType(), default: def };
+    },
+};
+const STORE = new WeakMap();
+const FINALIZED = new WeakSet();
+function signalFor(instance, name, config) {
+    let signals = STORE.get(instance);
+    if (!signals) {
+        signals = new Map();
+        STORE.set(instance, signals);
+    }
+    let sig = signals.get(name);
+    if (!sig) {
+        sig = signal(config.default); // lazy init to the declared default
+        signals.set(name, sig);
+    }
+    return sig;
+}
+const GUARD = new WeakMap();
+function guardOf(instance) {
+    let g = GUARD.get(instance);
+    if (!g) {
+        g = { outbound: new Set(), inbound: new Set() };
+        GUARD.set(instance, g);
+    }
+    return g;
+}
+function isCrossing(instance, dir, name) {
+    return GUARD.get(instance)?.[dir].has(name) ?? false;
+}
+/** Resolve a prop's attribute name: `attribute: false` ⇒ no attribute (property-only); else the override or the prop name. */
+function attrNameOf(config, name) {
+    return config.attribute === false ? null : (config.attribute ?? name);
+}
+/**
+ * Outbound seam (the second of the two boundary functions): cross a TYPED value → its attribute string
+ * via the prop's `PropType.to` codec, and write it to the host attribute exactly once. Holds the
+ * `outbound` directional lock across the write so the synchronous `attributeChangedCallback` echo the
+ * platform fires re-enters `coerceAttribute` LOCKED and is suppressed — the loop is broken at the gate,
+ * not after a redundant round-trip. A `null` from `to` (boolean-false / number-null / property-only)
+ * removes the attribute. Called only from the reflect setter, only when `config.reflect` is set.
+ */
+function reflectOut(instance, name, config, value) {
+    const attr = attrNameOf(config, name);
+    if (attr === null)
+        return; // property-only prop: nothing to reflect to
+    const host = instance; // a reflect prop's host is an Element; setAttribute is a DOM API, not an import
+    const guard = guardOf(instance);
+    guard.outbound.add(name);
+    try {
+        const serialized = config.type.to(value); // OUTBOUND boundary: typed → string
+        if (serialized === null)
+            host.removeAttribute(attr);
+        else
+            host.setAttribute(attr, serialized);
+    }
+    finally {
+        guard.outbound.delete(name);
+    }
+}
+/** Install signal-backed prototype accessors from `Ctor.props`. Idempotent (safe to call once per class). */
+export function finalize(ctor) {
+    if (FINALIZED.has(ctor))
+        return;
+    FINALIZED.add(ctor);
+    const props = ctor.props;
+    if (!props)
+        return;
+    for (const name of Object.keys(props)) {
+        const config = props[name];
+        Object.defineProperty(ctor.prototype, name, {
+            configurable: true,
+            enumerable: true,
+            get() {
+                return signalFor(this, name, config).value;
+            },
+            set(next) {
+                signalFor(this, name, config).value = next;
+                // Reflect value→attribute exactly once, unless this write IS an inbound coercion (the
+                // directional lock): an attribute→value crossing must not bounce straight back out.
+                if (config.reflect && !isCrossing(this, 'inbound', name)) {
+                    reflectOut(this, name, config, next);
+                }
+            },
+        });
+    }
+}
+/**
+ * Inbound seam (the first of the two boundary functions): cross an attribute STRING (or `null` for
+ * absence) into the typed prop signal via the prop's `PropType.from` codec, and return the coerced
+ * value. This is the primitive the element slice's `attributeChangedCallback` (e-attrs, later) composes
+ * on — p-install owns the per-instance store + the string→typed crossing; it does NOT own the platform
+ * callback. A no-op for an unknown prop name.
+ *
+ * Two directional-lock interactions (rubric D3): (1) if an outbound reflect for this prop is in flight,
+ * this call is that reflect's own platform echo — suppress it (return `undefined`) so it cannot loop.
+ * (2) Otherwise write through the installed accessor under the `inbound` lock, so the setter applies the
+ * value but does NOT reflect it straight back out. The write goes through the setter (not the raw signal)
+ * precisely so that symmetric guard is load-bearing: one write path, the lock decides whether it reflects.
+ */
+export function coerceAttribute(instance, ctor, name, attr) {
+    const config = ctor.props?.[name];
+    if (!config)
+        return undefined;
+    if (isCrossing(instance, 'outbound', name))
+        return undefined; // our own reflect's echo → suppress (no loop)
+    const value = config.type.from(attr); // INBOUND boundary: string → typed
+    const guard = guardOf(instance);
+    guard.inbound.add(name);
+    try {
+        ;
+        instance[name] = value; // through the accessor; the inbound lock stops a reflect-back
+    }
+    finally {
+        guard.inbound.delete(name);
+    }
+    return value;
+}
+// ── attribute↔prop NAME mapping (the e-attrs seam) ───────────────────────────
+//
+// The platform's `observedAttributes` / `attributeChangedCallback` speak ATTRIBUTE names; `coerceAttribute`
+// speaks PROP names. These two functions own the attribute↔prop NAME mapping (via the same `attrNameOf`
+// the reflect path uses), so the string↔typed boundary AND the name mapping stay single-sourced in
+// props.ts; element.ts (e-attrs) is a thin platform-callback adapter over them. Internal seam — used by
+// element.ts, NOT re-exported from the dom barrel.
+/** The attribute names to observe for a finalized ctor: each prop's attribute name, minus property-only props. */
+export function observedAttributesFor(ctor) {
+    const props = ctor.props;
+    if (!props)
+        return [];
+    const names = [];
+    for (const name of Object.keys(props)) {
+        const attr = attrNameOf(props[name], name);
+        if (attr !== null)
+            names.push(attr);
+    }
+    return names;
+}
+/** Reverse the mapping: the prop name owning a given attribute name (respecting `attribute` overrides), or `undefined`. */
+export function propForAttribute(ctor, attr) {
+    const props = ctor.props;
+    if (!props)
+        return undefined;
+    for (const name of Object.keys(props)) {
+        if (attrNameOf(props[name], name) === attr)
+            return name;
+    }
+    return undefined;
+}

package/dist/dom/repeat.d.ts

@@ -0,0 +1,10 @@
+import { type DirectiveResult } from './template.js';
+/**
+ * `repeat(items, keyFn, template)` — render a keyed list into a child hole, reusing DOM by key across data
+ * changes. `keyFn(item, index)` must return a value UNIQUE per item (a duplicate throws); `template(item,
+ * index)` renders each item (text, a `TemplateResult`, …). A reorder MOVES surviving items by identity
+ * (node identity preserved always; focus / selection preserved where native `moveBefore` is supported,
+ * identity-only fallback otherwise — ADR-0022), while append / remove-tail / a stable prefix cost zero
+ * moves. Prefer `repeat` over a positional array hole when items carry identity or interactive state.
+ */
+export declare function repeat<T>(items: Iterable<T>, keyFn: (item: T, index: number) => unknown, template: (item: T, index: number) => unknown): DirectiveResult;

package/dist/dom/repeat.js

@@ -0,0 +1,202 @@
+// repeat.ts — the `repeat` directive (plan §6; G3 slice 1, the keyed list reconcile).
+//
+// `repeat(items, keyFn, template)` is a DOM-owning child directive (returns `NO_COMMIT`): it drives one
+// sub-`ChildPart` per item and reconciles the keyed list itself, REUSING the part engine rather than any
+// kernel/binding primitive — list reconciliation is pure DOM + key bookkeeping, it owns no effect (so it
+// needs no scope_seam / `ctx`). The reconcile is a head/tail two-pointer trim plus a key→old-index map for
+// the disordered middle: a surviving key REUSES its sub-part (commit the new template value → the part's
+// `Object.is` skip), a moved key relocates its sub-part by IDENTITY via `moveBefore`, a new key creates a
+// sub-part, a removed key disposes one, and a duplicate key THROWS. Append / remove-tail / a stable prefix
+// perform ZERO moves of existing nodes (the head/tail fast paths never reach the move/map branches).
+//
+// Reorder guarantee — TWO-TIER (ADR-0022, the `moveBefore` seam): DOM node IDENTITY is preserved across a
+// reorder ALWAYS, on every engine (the same node objects move, never re-created — what the keyed reconcile
+// guarantees). ELEMENT STATE — focus / selection / transitions — additionally survives where the platform's
+// native `Node.prototype.moveBefore` is supported (an atomic move); on engines without it the seam falls back
+// to detach+reinsert: identity-only, focus NOT preserved (graceful degradation, no regression).
+//
+// SCOPE LIMIT (from the seam's `moveBefore`): a sub-part's move relocates its owned nodes + anchor —
+// complete for an item rendering text or a SINGLE template (the norm). An item whose template renders an
+// ARRAY or a nested directive keeps deeper content in sub-anchors `moveBefore` does not track; multi-node
+// item moves are out of this slice's scope.
+//
+// Imports only the directive seam from `./template.ts` (same dom layer) — inward-only layering; not
+// re-exported from this file (the dom barrel re-exports `repeat`).
+import { Directive, directive, NO_COMMIT } from "./template.js";
+/** Render a key for a clear duplicate-key error without throwing on a symbol / object key. */
+function describeKey(key) {
+    if (typeof key === 'string')
+        return JSON.stringify(key);
+    if (typeof key === 'symbol')
+        return key.toString();
+    return String(key);
+}
+/**
+ * The `repeat` directive instance. Holds the committed list as two aligned arrays — `#keys` (the committed
+ * keys, in DOM order) and `#parts` (their sub-parts) — and reconciles them against the new keys on each
+ * commit of the SAME hole (state threads across commits). Owns no effect; ignores `ctx`.
+ */
+class RepeatDirective extends Directive {
+    #keys = [];
+    #parts = [];
+    update(args) {
+        const items = args[0];
+        const keyFn = args[1];
+        const template = args[2];
+        // Pass 1 — materialize the new keys + values, throwing on a DUPLICATE key BEFORE any DOM mutation, so a
+        // bad input never leaves the list half-reconciled. Keys must be unique for the reconcile to be a bijection.
+        const newKeys = [];
+        const newValues = [];
+        const seen = new Set();
+        let index = 0;
+        for (const item of items) {
+            const key = keyFn(item, index);
+            if (seen.has(key)) {
+                throw new Error(`repeat: duplicate key ${describeKey(key)} — every item's key must be unique within one render.`);
+            }
+            seen.add(key);
+            newKeys.push(key);
+            newValues.push(template(item, index));
+            index++;
+        }
+        this.#reconcile(newKeys, newValues);
+        return NO_COMMIT; // repeat owns its DOM via the per-item sub-parts → the host part commits nothing
+    }
+    /** Tear down every sub-part (each removes its content + anchor). The seam isolates a throwing disposer. */
+    dispose() {
+        for (const part of this.#parts)
+            part.dispose();
+        this.#keys = [];
+        this.#parts = [];
+    }
+    /** A move reference: the START node of the part a relocation lands before, or the host hole's end anchor. */
+    #refNode(part) {
+        return part ? part.startNode : this.endNode;
+    }
+    /** Create a sub-part, commit its value, and position it before `before` (or leave it at the tail). */
+    #mount(value, before) {
+        const part = this.createPart(); // its anchor lands just before the host anchor → the tail
+        part.commit(value);
+        if (before)
+            part.moveBefore(before.startNode); // a middle insert moves the (new) node into place
+        return part;
+    }
+    /**
+     * The keyed reconcile (Levitin/`lit-html` style): a head/tail two-pointer trims the unchanged prefix and
+     * suffix in place (committing each surviving key's new value → the part's `Object.is` skip, ZERO moves),
+     * the two cross checks catch a head↔tail swap, and a key→old-index map resolves the disordered middle —
+     * reusing a surviving key's sub-part (moved by IDENTITY), creating one for a new key, disposing one for a
+     * removed key. Append / remove-tail / a stable prefix never leave the head/tail fast paths → zero moves.
+     */
+    #reconcile(newKeys, newValues) {
+        const oldKeys = this.#keys;
+        const old = this.#parts.slice(); // working copy; entries are nulled as consumed
+        const newParts = new Array(newKeys.length).fill(null);
+        let oldHead = 0;
+        let oldTail = old.length - 1;
+        let newHead = 0;
+        let newTail = newKeys.length - 1;
+        // The maps over the disordered windows, built lazily on the FIRST middle case and reused thereafter
+        // (the windows only shrink, so the first window is a superset of every later one).
+        let oldKeyToIndex = null;
+        let newKeySet = null;
+        while (oldHead <= oldTail && newHead <= newTail) {
+            if (old[oldHead] === null) {
+                oldHead++; // a part consumed out of order by the map branch — skip its hole
+            }
+            else if (old[oldTail] === null) {
+                oldTail--;
+            }
+            else if (oldKeys[oldHead] === newKeys[newHead]) {
+                // Heads match — update in place, no move.
+                old[oldHead].commit(newValues[newHead]);
+                newParts[newHead] = old[oldHead];
+                oldHead++;
+                newHead++;
+            }
+            else if (oldKeys[oldTail] === newKeys[newTail]) {
+                // Tails match — update in place, no move.
+                old[oldTail].commit(newValues[newTail]);
+                newParts[newTail] = old[oldTail];
+                oldTail--;
+                newTail--;
+            }
+            else if (oldKeys[oldHead] === newKeys[newTail]) {
+                // Old head became the new tail — move it before the already-placed part after the new tail.
+                const part = old[oldHead];
+                part.commit(newValues[newTail]);
+                part.moveBefore(this.#refNode(newParts[newTail + 1]));
+                newParts[newTail] = part;
+                oldHead++;
+                newTail--;
+            }
+            else if (oldKeys[oldTail] === newKeys[newHead]) {
+                // Old tail became the new head — move it before the current head part.
+                const part = old[oldTail];
+                part.commit(newValues[newHead]);
+                part.moveBefore(this.#refNode(old[oldHead]));
+                newParts[newHead] = part;
+                oldTail--;
+                newHead++;
+            }
+            else {
+                if (oldKeyToIndex === null) {
+                    oldKeyToIndex = new Map();
+                    for (let i = oldHead; i <= oldTail; i++)
+                        oldKeyToIndex.set(oldKeys[i], i);
+                    newKeySet = new Set(newKeys.slice(newHead, newTail + 1));
+                }
+                if (!newKeySet.has(oldKeys[oldHead])) {
+                    old[oldHead].dispose(); // the head key is gone → remove it
+                    oldHead++;
+                }
+                else if (!newKeySet.has(oldKeys[oldTail])) {
+                    old[oldTail].dispose();
+                    oldTail--;
+                }
+                else {
+                    // The new head's key survives somewhere in the old middle — reuse that sub-part (or create one
+                    // if it is genuinely new), moving it before the current head part.
+                    const wantKey = newKeys[newHead];
+                    const oldIndex = oldKeyToIndex.has(wantKey) ? oldKeyToIndex.get(wantKey) : -1;
+                    const reusable = oldIndex >= 0 ? old[oldIndex] : null;
+                    if (reusable === null) {
+                        newParts[newHead] = this.#mount(newValues[newHead], old[oldHead]);
+                    }
+                    else {
+                        reusable.commit(newValues[newHead]);
+                        reusable.moveBefore(this.#refNode(old[oldHead]));
+                        old[oldIndex] = null; // consumed — its old hole is now a skip
+                        newParts[newHead] = reusable;
+                    }
+                    newHead++;
+                }
+            }
+        }
+        // Any new keys left are appended/inserted before the part after the new tail (the tail run lands before
+        // the host anchor in ascending order; a middle run moves before its fixed successor).
+        while (newHead <= newTail) {
+            newParts[newHead] = this.#mount(newValues[newHead], newParts[newTail + 1] ?? null);
+            newHead++;
+        }
+        // Any old parts left are removed (their keys are gone).
+        while (oldHead <= oldTail) {
+            old[oldHead]?.dispose();
+            oldHead++;
+        }
+        this.#keys = newKeys;
+        this.#parts = newParts; // every slot was filled by the reconcile above
+    }
+}
+const repeatDirective = directive(RepeatDirective);
+/**
+ * `repeat(items, keyFn, template)` — render a keyed list into a child hole, reusing DOM by key across data
+ * changes. `keyFn(item, index)` must return a value UNIQUE per item (a duplicate throws); `template(item,
+ * index)` renders each item (text, a `TemplateResult`, …). A reorder MOVES surviving items by identity
+ * (node identity preserved always; focus / selection preserved where native `moveBefore` is supported,
+ * identity-only fallback otherwise — ADR-0022), while append / remove-tail / a stable prefix cost zero
+ * moves. Prefer `repeat` over a positional array hole when items carry identity or interactive state.
+ */
+export function repeat(items, keyFn, template) {
+    return repeatDirective(items, keyFn, template);
+}

package/dist/dom/template.d.ts

@@ -0,0 +1,161 @@
+/**
+ * The inert product of `html\`…\`` / `svg\`…\``: the call site's frozen `strings`, this render's dynamic
+ * `values`, and the parse MODE (`svg` fragments parse in the SVG namespace). No DOM work happens at the
+ * call site — preparation is lazy, at render.
+ */
+export declare class TemplateResult {
+    readonly strings: TemplateStringsArray;
+    readonly values: readonly unknown[];
+    readonly svg: boolean;
+    constructor(strings: TemplateStringsArray, values: readonly unknown[], svg?: boolean);
+}
+/** Tagged-template tag → an inert HTML `TemplateResult`. */
+export declare function html(strings: TemplateStringsArray, ...values: unknown[]): TemplateResult;
+/** Like `html`, but the fragment parses in the SVG NAMESPACE — `<circle>`/`<path>`/… become real SVGElements. */
+export declare function svg(strings: TemplateStringsArray, ...values: unknown[]): TemplateResult;
+/**
+ * Where one hole binds. A child position (the marker comment), or one of the attribute-position kinds
+ * routed by binding sigil: `attr` (string attribute), `bool` (`?name`), `prop` (`.name`, a DOM property),
+ * `event` (`@name`). `nodeIndex` is the host node's pre-order index; `name` is the SOURCE name (sigil
+ * stripped) — taken from the template strings, NOT the parsed DOM, so a `.prop`'s camelCase survives the
+ * HTML parser's attribute-name lowercasing.
+ */
+type PartInfo = {
+    kind: 'child';
+    nodeIndex: number;
+} | {
+    kind: 'attr';
+    nodeIndex: number;
+    name: string;
+} | {
+    kind: 'bool';
+    nodeIndex: number;
+    name: string;
+} | {
+    kind: 'prop';
+    nodeIndex: number;
+    name: string;
+} | {
+    kind: 'event';
+    nodeIndex: number;
+    name: string;
+};
+interface PreparedTemplate {
+    template: HTMLTemplateElement;
+    parts: PartInfo[];
+}
+/**
+ * Prepare a call site's `strings`: build the marker HTML, parse it into one `<template>`, and walk it
+ * once to build the parts manifest (cleaning attribute markers). Memoized by `strings` IDENTITY — a
+ * re-render of the same call site hits the cache and re-parses nothing. Exported for the cache probes
+ * (an internal seam; NOT re-exported from the dom barrel).
+ */
+export declare function prepare(strings: TemplateStringsArray, svg?: boolean): PreparedTemplate;
+declare const DIRECTIVE_BRAND: unique symbol;
+/**
+ * The render-side handle a directive uses to reach the host's CONNECTION SCOPE — the scope_seam. A host
+ * (`UIElement`) satisfies it structurally via its scope-owned `effect`. Threaded read-only into the render
+ * path so a per-hole directive effect (e.g. `watch`) is owned by the connection scope, NOT the transient
+ * render effect — which re-runs (scheduler flush) with no active owner, so a bare `effect()` created there
+ * would leak. `ctx.effect` re-establishes scope ownership explicitly on every render.
+ *
+ * Install-once invariant for an effect-owning directive: gate the install on a flag, but re-assert that flag
+ * at the TOP of the effect body — NOT once after `ctx.effect`. The kernel runs an effect's cleanup before
+ * EVERY re-run (not only on disposal), so a cleanup that clears the flag clears it on normal re-runs too;
+ * re-asserting in the body nets `true` on a re-run and `false` only on disposal, so a later host re-render
+ * won't double-install. (See `watch.ts`; the `scope_seam` probe in template-directives.test.ts pins it.)
+ */
+export interface RenderContext {
+    effect(fn: () => void | (() => void)): () => void;
+}
+/** A directive's `update` returns this when it manages its OWN DOM (via sub-parts) — the host part commits nothing. */
+export declare const NO_COMMIT: unique symbol;
+/**
+ * A directive instance: `update` runs on every commit of its hole (threading state across commits of the
+ * SAME hole), returning a value the host part commits through its normal child path OR `NO_COMMIT` when the
+ * directive drives its own DOM; `dispose` tears it down. The host `ChildPart` is handed to the constructor
+ * so a DOM-owning directive can drive sub-parts via the `protected` primitives below. Subclassed by the
+ * rider files (repeat.ts/watch.ts) — never instantiated by consumers; reached only through `directive()`.
+ */
+export declare abstract class Directive {
+    #private;
+    constructor(part: ChildPart);
+    /**
+     * Create a sub-`ChildPart` rendering into THIS directive's hole (its anchor sits just before the host
+     * hole's anchor). `watch` drives one inner part; `repeat` drives one per item. The returned part's
+     * `commit` / `dispose` / `moveBefore` / `startNode` are the directive's DOM primitives.
+     */
+    protected createPart(): ChildPart;
+    /** The host hole's end boundary — sub-part content orders BEFORE this node (a `repeat` reorder reference). */
+    protected get endNode(): ChildNode;
+    /** Recognize the directive on each commit of the hole; return a value to commit, or `NO_COMMIT`. */
+    abstract update(args: readonly unknown[], ctx?: RenderContext): unknown;
+    /** Tear down owned DOM/effects. Default no-op; the part isolates a throw so sibling teardown still runs. */
+    dispose(): void;
+}
+type DirectiveConstructor = new (part: ChildPart) => Directive;
+/** The inert product of a directive factory call — like `TemplateResult`, no DOM work at the call site. */
+export interface DirectiveResult {
+    readonly [DIRECTIVE_BRAND]: true;
+    readonly ctor: DirectiveConstructor;
+    readonly args: readonly unknown[];
+}
+/**
+ * Wrap a `Directive` subclass into a factory: `const repeat = directive(RepeatDirective)`. Calling the
+ * factory returns an inert branded `DirectiveResult` that a child hole routes to its (per-hole, state-
+ * threading) instance. Rider files import this from template.ts — the one extension point.
+ */
+export declare function directive(ctor: DirectiveConstructor): (...args: unknown[]) => DirectiveResult;
+interface Part {
+    commit(value: unknown, ctx?: RenderContext): void;
+}
+/** A child hole: commits a primitive (text, updated in place), a nested `TemplateResult`, an array, or a directive. */
+declare class ChildPart implements Part {
+    #private;
+    constructor(anchor: Comment);
+    commit(value: unknown, ctx?: RenderContext): void;
+    /** Remove this part's content + its directive AND its own anchor — for an array sub-part being dropped. */
+    dispose(): void;
+    /** Create a sub-part whose anchor sits just before THIS part's anchor — a directive's DOM primitive. */
+    createChild(): ChildPart;
+    /** This part's end boundary — a directive orders sub-part content before it. */
+    get endNode(): ChildNode;
+    /** The first DOM node of this part's range (its first owned node, else its anchor) — a reorder reference. */
+    get startNode(): ChildNode;
+    /**
+     * Relocate this part's owned nodes + anchor to just before `ref`. TWO-TIER guarantee (ADR-0022): NODE
+     * IDENTITY is preserved always, on every engine (the same node objects move, never re-created). ELEMENT
+     * STATE — focus, selection, transitions, `<iframe>`/media — survives ONLY on the native path, where the
+     * parent supports `Node.prototype.moveBefore` (an atomic move that never detaches the node from the
+     * document); on the `before()` fallback (native absent) the nodes are detached + re-inserted, so identity
+     * is kept but focus/state are NOT (graceful degradation — the reconcile stays correct, only the focus
+     * nicety is absent). Covers a part holding text or a single nested template (the `repeat` item norm); a
+     * part holding an array/nested directive keeps deeper content in sub-anchors `#nodes` does not track.
+     *
+     * Caller invariant (repeat): `ref` and the moving `#nodes`/`#anchor` always share the same connected
+     * parent (the directive's container) — native `moveBefore`'s happy path, so no `try/catch` is needed; a
+     * future caller that violated same-parent/connected would get a loud `HierarchyRequestError`, not a
+     * silent mis-move.
+     */
+    moveBefore(ref: ChildNode): void;
+}
+/**
+ * Commit `result` into `container`. The first render of a given `strings` at a container instantiates the
+ * prepared template; a re-render with the SAME `strings` reuses that instance and writes only the changed
+ * holes (per-part `Object.is`). A different `strings` replaces the container's content. The optional `ctx`
+ * (the host's scope-owned `effect`) threads to directives so a per-hole effect (`watch`) is scope-owned;
+ * 2-arg calls keep working (`ctx` undefined → directives that need it simply have none).
+ */
+export declare function render(result: TemplateResult, container: Node, ctx?: RenderContext): void;
+/**
+ * Mount a kernel directive IMPERATIVELY (ADR-0023): commit `result` into `container` and return a teardown
+ * that disposes the directive (+ its sub-parts), clears its content, and removes the mount anchor. Reuses
+ * the SAME `ChildPart` engine `render()` rides — no parallel commit path: an anchor comment is appended to
+ * `container` (the directive's content commits as the anchor's previous siblings → inside `container`,
+ * leaving any pre-existing content untouched), a `ChildPart` is bound to it, and `result` is committed
+ * through the normal directive route. `ctx` threads the connection scope, so a per-hole effect (the `watch`
+ * pattern) stays scope-owned exactly as under `render()`. The public host for imperative consumers (the a2ui
+ * renderer) that need a kernel directive — e.g. `repeat` — WITHOUT the private `html\`\`` template entry.
+ */
+export declare function mount(result: DirectiveResult, container: Node, ctx?: RenderContext): () => void;
+export {};