@elaraai/east-ui 1.0.39 → 1.0.41

package/dist/src/collections/value-tree/index.js

@@ -0,0 +1,688 @@
+/**
+ * Copyright (c) 2025 Elara AI Pty Ltd
+ * Dual-licensed under AGPL-3.0 and commercial license. See LICENSE for details.
+ */
+/**
+ * ValueTree — the editable value-driven tree (#360).
+ *
+ * `ValueTree.Root(value, opts)` walks the STATIC East type of `value` at
+ * authoring time and materializes it into the fixed recursive
+ * {@link ValueTreeNodeType} IR — automatic tree formation from ANY East
+ * type, leaf-type-aware editing, and compound/collection editing
+ * (add/remove array rows and dict entries, variant tag switching,
+ * option toggling).
+ *
+ * Two edit surfaces, one contract:
+ *
+ * - **Value handlers** (the default): `onUpdate` receives the whole
+ *   value with the edit applied; `at: [ValueTree.at(Type, p => …, fn)]`
+ *   scopes receive just the rebuilt SUBTREE at their path. Every edit
+ *   dispatches to the deepest scope whose path prefixes the edit path
+ *   and bubbles up to `onUpdate` when no scope matches. The rebuild is
+ *   an authoring-time macro over the static type — hosts never
+ *   hand-apply paths.
+ * - **Path callbacks** (the escape hatch): `onEdit` / `onInsert` /
+ *   `onRemove` / `onTag` receive the raw typed path and payload for
+ *   hosts that own a finer-grained store. A raw callback overrides the
+ *   generated handler for its event.
+ *
+ * The host owns the data either way: write the new value and let the
+ * Reactive re-materialization refresh the tree (the same contract as
+ * every collection surface).
+ */
+import { ArrayType, East, Expr, FunctionType, NullType, RecursiveExpr, StringType, StructType, defaultValue, some, none, variant, } from "@elaraai/east";
+import { UIComponentType } from "../../component.js";
+import { ValueTreeStepType, ValueTreePathType, ValueTreeLeafType, ValueTreeNodeType, ValueTreeStyleType, ValueTreeRootType, } from "./types.js";
+export { ValueTreeStepType, ValueTreePathType, ValueTreeLeafType, ValueTreeNodeType, ValueTreeStyleType, ValueTreeRootType, } from "./types.js";
+import { materialize, applyEdit } from "./materialize.js";
+export { materialize, applyEdit, } from "./materialize.js";
+/** Beyond this many unrollings of a RecursiveType the subtree prints as
+ *  an `opaque` node (a lazy "expand further" is the #360 follow-up). */
+const MAX_RECURSION_DEPTH = 6;
+/** Total materializer expansions per tree — caps generated IR size for
+ *  wide recursive types, where a pure depth limit still explodes
+ *  (branching^depth). Exhausted subtrees print as `opaque`. */
+const MAX_MATERIALIZED_NODES = 4096;
+/** Expansion budget for each generated edit-application wrapper —
+ *  the rebuild macro mirrors the materializer's recursion, so it gets
+ *  the same cap; exhausted subtrees pass through unchanged (the
+ *  materializer shows them as read-only `opaque` anyway). */
+const MAX_REBUILD_NODES = 4096;
+/** Longest opaque summary before the printed value is clamped. */
+const MAX_OPAQUE_PRINT = 80n;
+/** The dict-entry element of a dict node. */
+const DictEntryType = StructType({ key: StringType, node: ValueTreeNodeType });
+/** The struct-field element of a struct node. */
+const StructFieldType = StructType({ name: StringType, node: ValueTreeNodeType });
+/** True when a Variant type is exactly the Option shape (`some` + `none`). */
+function isOptionType(t) {
+    if (t.type !== "Variant")
+        return false;
+    const tags = Object.keys(t.cases);
+    return tags.length === 2 && tags.includes("some") && tags.includes("none");
+}
+/** Clamps a printed value for opaque summaries (large collections would
+ *  otherwise dump their whole print into a single row). */
+const clampPrint = East.function([StringType], StringType, (_$, p) => p.length().greater(MAX_OPAQUE_PRINT).ifElse(() => p.substring(0n, MAX_OPAQUE_PRINT).concat("…"), () => p));
+/** Kind-aware opaque summary — "Set · 12 items" beats an unbounded print. */
+function opaqueSummary(t, v) {
+    switch (t.type) {
+        case "Set":
+            return East.str `Set · ${v.size()} items`;
+        case "Blob":
+            return East.str `Blob · ${v.size()} bytes`;
+        case "Vector":
+            return East.str `Vector · ${v.length()} values`;
+        case "Matrix": {
+            const m = v;
+            return East.str `Matrix · ${m.rows()}×${m.cols()}`;
+        }
+        case "Ref":
+            return East.str `Ref · ${clampPrint(East.print(v.get()))}`;
+        case "Function":
+        case "AsyncFunction":
+            return East.value("Function", StringType);
+        default:
+            return clampPrint(East.print(v));
+    }
+}
+/**
+ * Materialize `v` (typed `t`) into a {@link ValueTreeNodeType} expression.
+ * Recursion is over the STATIC type — the generated IR walks the value
+ * eagerly (the `mapRows` discipline: expressions expand once per type
+ * shape, user data flows through East collection ops).
+ */
+function nodeOf(t, v, depth, state) {
+    state.budget -= 1;
+    if (depth > MAX_RECURSION_DEPTH || state.budget <= 0) {
+        return East.value(variant("opaque", clampPrint(East.print(v))), ValueTreeNodeType);
+    }
+    switch (t.type) {
+        case "Null":
+            return East.value(variant("leaf", variant("null", null)), ValueTreeNodeType);
+        case "Boolean":
+            return East.value(variant("leaf", variant("boolean", v)), ValueTreeNodeType);
+        case "Integer":
+            return East.value(variant("leaf", variant("integer", v)), ValueTreeNodeType);
+        case "Float":
+            return East.value(variant("leaf", variant("float", v)), ValueTreeNodeType);
+        case "String":
+            return East.value(variant("leaf", variant("string", v)), ValueTreeNodeType);
+        case "DateTime":
+            return East.value(variant("leaf", variant("datetime", v)), ValueTreeNodeType);
+        case "Struct": {
+            const fields = t.fields;
+            const fieldNodes = Object.entries(fields).map(([name, ft]) => ({
+                name,
+                node: nodeOf(ft, v[name], depth, state),
+            }));
+            return East.value(variant("struct", {
+                fields: East.value(fieldNodes, ArrayType(StructFieldType)),
+            }), ValueTreeNodeType);
+        }
+        case "Array": {
+            const elem = t.value;
+            const fn = East.function([elem], ValueTreeNodeType, (_$, x) => nodeOf(elem, x, depth, state));
+            const items = v
+                .map((_$, x) => fn(x));
+            return East.value(variant("array", { items }), ValueTreeNodeType);
+        }
+        case "Dict": {
+            const { key, value } = t;
+            const editable = key.type === "String";
+            const fn = East.function([value, key], DictEntryType, (_$, x, k) => ({
+                key: editable
+                    ? k
+                    : East.print(k),
+                node: nodeOf(value, x, depth, state),
+            }));
+            const entries = v
+                .toArray((_$, x, k) => fn(x, k));
+            return East.value(variant("dict", { entries, editable }), ValueTreeNodeType);
+        }
+        case "Variant": {
+            const cases = t.cases;
+            const tags = Object.keys(cases);
+            if (isOptionType(t)) {
+                const someType = cases["some"];
+                return v.match({
+                    some: (_$, payload) => East.value(variant("option", {
+                        value: some(nodeOf(someType, payload, depth, state)),
+                    }), ValueTreeNodeType),
+                    none: () => East.value(variant("option", {
+                        value: none,
+                    }), ValueTreeNodeType),
+                });
+            }
+            const handlers = {};
+            for (const tag of tags) {
+                handlers[tag] = (_$, payload) => East.value(variant("variant", {
+                    tag,
+                    tags: East.value(tags, ArrayType(StringType)),
+                    value: nodeOf(cases[tag], payload, depth, state),
+                }), ValueTreeNodeType);
+            }
+            return v
+                .match(handlers);
+        }
+        case "Recursive":
+            // A recursive-typed expression only exposes unwrap()/wrap —
+            // unwrap to the inner node type before descending.
+            return nodeOf(t.node, v.unwrap(), depth + 1, state);
+        default:
+            // Sets, blobs, vectors, matrices, refs, functions — summarized.
+            return East.value(variant("opaque", opaqueSummary(t, v)), ValueTreeNodeType);
+    }
+}
+/** Leaf case tag of {@link ValueTreeLeafType} for a primitive type. */
+function leafTag(t) {
+    switch (t.type) {
+        case "String": return "string";
+        case "Integer": return "integer";
+        case "Float": return "float";
+        case "Boolean": return "boolean";
+        case "DateTime": return "datetime";
+        default: return undefined;
+    }
+}
+/** Zero value as an East expression, or undefined where no zero exists
+ *  (functions, matrices) — the corresponding insert/tag branch then
+ *  passes the value through unchanged. */
+function tryZeroExpr(t) {
+    try {
+        return East.value(zeroValue(t), t);
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Rebuild `v` (typed `t`) with `op` applied at `path` — the write-side
+ * mirror of {@link nodeOf}. Expands per static type shape; `si` is the
+ * number of path steps already consumed (static: one per nesting level),
+ * `depth` counts RecursiveType unrollings against the same cap as the
+ * materializer (edits cannot originate beyond what materialized).
+ *
+ * Op semantics at the addressed node:
+ * - `edit`: the path ends AT a primitive leaf — its typed payload replaces it.
+ * - `insert`: the path ends with `append` (array) or the NEW `key` (dict).
+ * - `remove`: the path ends with the element `index` / entry `key`.
+ * - `tag`: the path ends AT an option (tag "some"/"none") or variant node;
+ *   the payload becomes the target case's zero value.
+ */
+function rebuild(t, v, path, si, depth, state, op) {
+    state.budget -= 1;
+    if (depth > MAX_RECURSION_DEPTH || state.budget <= 0) {
+        return v;
+    }
+    const p = path;
+    const step = () => p.get(BigInt(si));
+    const atEnd = (n) => p.size().equals(BigInt(n));
+    switch (t.type) {
+        case "Null":
+            return v;
+        case "Boolean":
+        case "Integer":
+        case "Float":
+        case "String":
+        case "DateTime": {
+            if (op.kind !== "edit")
+                return v;
+            const tag = leafTag(t);
+            return op.leaf.unwrap(tag);
+        }
+        case "Struct": {
+            const fields = Object.entries(t.fields);
+            if (fields.length === 0)
+                return v;
+            const vs = v;
+            let chain = v;
+            for (const [name, ft] of [...fields].reverse()) {
+                const rebuiltFields = {};
+                for (const [n] of fields) {
+                    rebuiltFields[n] = n === name
+                        ? rebuild(ft, vs[n], path, si + 1, depth, state, op)
+                        : vs[n];
+                }
+                const prev = chain;
+                chain = step().hasTag("field")
+                    .and(() => step().unwrap("field").equals(name))
+                    .ifElse(() => East.value(rebuiltFields, t), () => prev);
+            }
+            return chain;
+        }
+        case "Array": {
+            const elem = t.value;
+            const av = v;
+            const descend = () => av.map((_$, x, i) => i.equals(step().unwrap("index"))
+                .ifElse(() => rebuild(elem, x, path, si + 1, depth, state, op), () => x));
+            if (op.kind === "insert") {
+                const zero = tryZeroExpr(elem);
+                if (zero === undefined)
+                    return descend();
+                return atEnd(si + 1)
+                    .and(() => step().hasTag("append"))
+                    .ifElse(() => av.concat(East.value([zero], ArrayType(elem))), descend);
+            }
+            if (op.kind === "remove") {
+                return atEnd(si + 1).ifElse(() => av.filter((_$, _x, i) => i.notEquals(step().unwrap("index"))), descend);
+            }
+            return descend();
+        }
+        case "Dict": {
+            const { key: kt, value: vt } = t;
+            if (kt.type !== "String")
+                return v;
+            const dv = v;
+            const descend = () => dv.map((_$, val, k) => k.equals(step().unwrap("key"))
+                .ifElse(() => rebuild(vt, val, path, si + 1, depth, state, op), () => val));
+            if (op.kind === "insert") {
+                const zero = tryZeroExpr(vt);
+                if (zero === undefined)
+                    return descend();
+                // Tail-return style (no `$.return`): these run inside the
+                // ASYNC generated wrappers, where a Return's control-flow
+                // exception would escape the sync call boundary.
+                const insertFn = East.function([t, StringType], t, ($, d, k) => {
+                    const next = $.let(d.copy());
+                    $(next
+                        .insertOrUpdate(k, zero));
+                    return next;
+                });
+                return atEnd(si + 1)
+                    .and(() => step().hasTag("key"))
+                    .ifElse(() => insertFn(v, step().unwrap("key")), descend);
+            }
+            if (op.kind === "remove") {
+                const removeFn = East.function([t, StringType], t, ($, d, k) => {
+                    const next = $.let(d.copy());
+                    $(next
+                        .tryDelete(k));
+                    return next;
+                });
+                return atEnd(si + 1)
+                    .and(() => step().hasTag("key"))
+                    .ifElse(() => removeFn(v, step().unwrap("key")), descend);
+            }
+            return descend();
+        }
+        case "Variant": {
+            const cases = t.cases;
+            const mv = v;
+            if (isOptionType(t)) {
+                const inner = cases["some"];
+                const descend = () => mv.match({
+                    some: (_$, payload) => East.value(some(rebuild(inner, payload, path, si + 1, depth, state, op)), t),
+                    none: () => East.value(none, t),
+                });
+                if (op.kind === "tag") {
+                    const zero = tryZeroExpr(inner);
+                    const toSome = zero !== undefined
+                        ? East.value(some(zero), t)
+                        : v;
+                    return atEnd(si).ifElse(() => op.tag.equals("some")
+                        .ifElse(() => toSome, () => East.value(none, t)), descend);
+                }
+                return descend();
+            }
+            const tags = Object.keys(cases);
+            const descend = () => {
+                const handlers = {};
+                for (const tag of tags) {
+                    handlers[tag] = (_$, payload) => East.value(variant(tag, rebuild(cases[tag], payload, path, si + 1, depth, state, op)), t);
+                }
+                return mv.match(handlers);
+            };
+            if (op.kind === "tag") {
+                let chain = v;
+                for (const tag of [...tags].reverse()) {
+                    const zero = tryZeroExpr(cases[tag]);
+                    if (zero === undefined)
+                        continue;
+                    const target = East.value(variant(tag, zero), t);
+                    const prev = chain;
+                    chain = op.tag.equals(tag)
+                        .ifElse(() => target, () => prev);
+                }
+                const tagChain = chain;
+                return atEnd(si).ifElse(() => tagChain, descend);
+            }
+            return descend();
+        }
+        case "Recursive": {
+            const inner = rebuild(t.node, v.unwrap(), path, si, depth + 1, state, op);
+            // Field/element sites require the exact wrapped type — re-wrap
+            // the rebuilt inner value (subtype transparency does not apply
+            // to heap slots).
+            return RecursiveExpr.wrap(inner, t, Expr.fromAst);
+        }
+        default:
+            // Sets, blobs, vectors, matrices, refs, functions — read-only.
+            return v;
+    }
+}
+/** Runtime probe: records navigation steps against the static type.
+ *  Members are lazy (getters / closures) so recursive types terminate. */
+function probeOf(t, steps) {
+    const probe = {};
+    Object.defineProperty(probe, "__vtSubtype", { value: t, enumerable: false });
+    Object.defineProperty(probe, "__vtSteps", { value: steps, enumerable: false });
+    let ct = t;
+    while (ct.type === "Recursive")
+        ct = ct.node;
+    if (ct.type === "Struct") {
+        for (const [name, ft] of Object.entries(ct.fields)) {
+            Object.defineProperty(probe, name, {
+                get: () => probeOf(ft, [...steps, { kind: "field", name }]),
+                enumerable: true,
+            });
+        }
+    }
+    else if (ct.type === "Array") {
+        const elem = ct.value;
+        probe["item"] = (index) => probeOf(elem, [...steps, { kind: "index", index: BigInt(index) }]);
+    }
+    else if (ct.type === "Dict") {
+        const { key, value } = ct;
+        if (key.type === "String") {
+            probe["entry"] = (k) => probeOf(value, [...steps, { kind: "key", key: k }]);
+        }
+    }
+    else if (isOptionType(ct)) {
+        const inner = ct.cases["some"];
+        probe["some"] = () => probeOf(inner, [...steps, { kind: "some" }]);
+    }
+    return probe;
+}
+/**
+ * Builds a scoped subtree handler for {@link ValueTree.Root}'s `at`
+ * option: navigate the root type with the typed probe, and receive the
+ * rebuilt SUBTREE at that path whenever an edit lands inside it.
+ *
+ * @typeParam T - The root value's East type
+ * @typeParam S - The subtree type at the accessor's path (inferred)
+ * @param root - The root value's East type (drives probe navigation)
+ * @param path - Accessor over the typed probe selecting the subtree
+ * @param onUpdate - Handler receiving the rebuilt subtree value
+ * @returns An opaque scope for the `at` option
+ *
+ * @example
+ * ```ts
+ * import { East, DictType, StringType, FloatType, NullType } from "@elaraai/east";
+ * import { ValueTree } from "@elaraai/east-ui";
+ *
+ * const RatesType = DictType(StringType, FloatType);
+ * const scope = ValueTree.at(RatesType, p => p.entry("base"),
+ *     East.function([FloatType], NullType, (_$, _next) => null));
+ * ```
+ */
+function scopeAt(root, path, onUpdate) {
+    const target = path(probeOf(root, []));
+    if (target?.__vtSteps === undefined) {
+        throw new Error("ValueTree.at: the path accessor must return a probe position (e.g. p => p.machines)");
+    }
+    return { steps: target.__vtSteps, subtype: target.__vtSubtype, handler: onUpdate };
+}
+/** Walks the static type along scope steps (RecursiveType transparent);
+ *  throws when a step does not fit the type — a scope built against a
+ *  different root type than the tree's value. */
+function navigateType(t, steps) {
+    let ct = t;
+    for (const st of steps) {
+        while (ct.type === "Recursive")
+            ct = ct.node;
+        if (st.kind === "field") {
+            const ft = ct.fields?.[st.name];
+            if (ct.type !== "Struct" || ft === undefined) {
+                throw new Error(`ValueTree.at: no struct field '${st.name}' at scope path`);
+            }
+            ct = ft;
+        }
+        else if (st.kind === "index") {
+            if (ct.type !== "Array")
+                throw new Error("ValueTree.at: 'item' step on a non-array at scope path");
+            ct = ct.value;
+        }
+        else if (st.kind === "key") {
+            if (ct.type !== "Dict")
+                throw new Error("ValueTree.at: 'entry' step on a non-dict at scope path");
+            ct = ct.value;
+        }
+        else {
+            if (!isOptionType(ct))
+                throw new Error("ValueTree.at: 'some' step on a non-option at scope path");
+            ct = ct.cases["some"];
+        }
+    }
+    return ct;
+}
+/** Navigates a value expression along scope steps (RecursiveType
+ *  unwrapped as consumed; the terminal value keeps its wrapper). */
+function navigateExpr(root, t, steps) {
+    let e = root;
+    let ct = t;
+    for (const st of steps) {
+        while (ct.type === "Recursive") {
+            e = e.unwrap();
+            ct = ct.node;
+        }
+        if (st.kind === "field") {
+            e = e[st.name];
+            ct = ct.fields[st.name];
+        }
+        else if (st.kind === "index") {
+            e = e.get(st.index);
+            ct = ct.value;
+        }
+        else if (st.kind === "key") {
+            e = e.get(st.key);
+            ct = ct.value;
+        }
+        else {
+            e = e.unwrap("some");
+            ct = ct.cases["some"];
+        }
+    }
+    return e;
+}
+/** Runtime prefix-match condition for a scope against an edit path.
+ *  `extra` is 1 for container ops (insert/remove: the affected element's
+ *  container must sit strictly below the scope root — removing the
+ *  scope's own subtree dispatches to its PARENT scope, whose value
+ *  still exists) and 0 for edit/tag. */
+function scopeMatch(path, scope, extra) {
+    const p = path;
+    let cond = p.size().greaterEqual(BigInt(scope.steps.length + extra));
+    scope.steps.forEach((st, i) => {
+        const stepAt = () => p.get(BigInt(i));
+        if (st.kind === "field") {
+            cond = cond.and(() => stepAt().hasTag("field")
+                .and(() => stepAt().unwrap("field").equals(st.name)));
+        }
+        else if (st.kind === "index") {
+            cond = cond.and(() => stepAt().hasTag("index")
+                .and(() => stepAt().unwrap("index").equals(st.index)));
+        }
+        else if (st.kind === "key") {
+            cond = cond.and(() => stepAt().hasTag("key")
+                .and(() => stepAt().unwrap("key").equals(st.key)));
+        }
+        else {
+            cond = cond.and(() => stepAt().hasTag("some"));
+        }
+    });
+    return cond;
+}
+/** Invokes a user handler expression (`FunctionType` value) with one arg. */
+function callHandler(handler, arg) {
+    const fn = East.value(handler);
+    return fn.call(arg);
+}
+// ============================================================================
+// Factory
+// ============================================================================
+/**
+ * Creates a ValueTree — the editable tree of any East value.
+ *
+ * @typeParam T - The value's East type (captured statically)
+ * @param value - The value to materialize (any East type)
+ * @param options - Value handlers, raw path callbacks + style
+ *   ({@link ValueTreeOptions})
+ * @returns An East expression of `UIComponentType`
+ *
+ * @example
+ * ```ts
+ * import { East, DictType, StringType, StructType, FloatType } from "@elaraai/east";
+ * import { ValueTree, UIComponentType } from "@elaraai/east-ui";
+ *
+ * const ConfigType = DictType(StringType, StructType({ rate: FloatType, label: StringType }));
+ * const view = East.function([ConfigType], UIComponentType, (_$, config) =>
+ *     ValueTree.Root(config),
+ * );
+ * ```
+ */
+function createValueTree(value, options) {
+    const v = East.value(value);
+    const t = Expr.type(v);
+    const root = nodeOf(t, v, 0, { budget: MAX_MATERIALIZED_NODES });
+    const scopes = options?.at ?? [];
+    for (const scope of scopes) {
+        // Fail at authoring time when a scope was built against a
+        // different root type than the tree's value.
+        navigateType(t, scope.steps);
+    }
+    const wantsGenerated = options?.onUpdate !== undefined || scopes.length > 0;
+    /** Deepest-first dispatch: scoped handlers, then `onUpdate`. */
+    const emitDispatch = ($, path, newRoot, extra) => {
+        const ordered = [...scopes].sort((a, b) => b.steps.length - a.steps.length);
+        const emit = ($b, remaining) => {
+            const scope = remaining[0];
+            if (scope === undefined) {
+                if (options?.onUpdate !== undefined) {
+                    $b(callHandler(options.onUpdate, newRoot));
+                }
+                return;
+            }
+            const subtree = navigateExpr(newRoot, t, scope.steps);
+            $b.if(scopeMatch(path, scope, extra), ($t) => {
+                $t(callHandler(scope.handler, subtree));
+            }).else(($e) => {
+                emit($e, remaining.slice(1));
+            });
+        };
+        emit($, ordered);
+    };
+    // Generated wrappers are ASYNC: user handlers routinely write State
+    // (an async platform effect), and sync handlers are subtypes.
+    const genOnEdit = () => East.asyncFunction([ValueTreePathType, ValueTreeLeafType], NullType, ($, p, leaf) => {
+        const next = $.let(rebuild(t, v, p, 0, 0, { budget: MAX_REBUILD_NODES }, { kind: "edit", leaf }));
+        emitDispatch($, p, next, 0);
+    });
+    const genOnInsert = () => East.asyncFunction([ValueTreePathType], NullType, ($, p) => {
+        const next = $.let(rebuild(t, v, p, 0, 0, { budget: MAX_REBUILD_NODES }, { kind: "insert" }));
+        emitDispatch($, p, next, 1);
+    });
+    const genOnRemove = () => East.asyncFunction([ValueTreePathType], NullType, ($, p) => {
+        const next = $.let(rebuild(t, v, p, 0, 0, { budget: MAX_REBUILD_NODES }, { kind: "remove" }));
+        emitDispatch($, p, next, 1);
+    });
+    const genOnTag = () => East.asyncFunction([ValueTreePathType, StringType], NullType, ($, p, tag) => {
+        const next = $.let(rebuild(t, v, p, 0, 0, { budget: MAX_REBUILD_NODES }, { kind: "tag", tag }));
+        emitDispatch($, p, next, 0);
+    });
+    const onEdit = options?.onEdit ?? (wantsGenerated ? genOnEdit() : undefined);
+    const onInsert = options?.onInsert ?? (wantsGenerated ? genOnInsert() : undefined);
+    const onRemove = options?.onRemove ?? (wantsGenerated ? genOnRemove() : undefined);
+    const onTag = options?.onTag ?? (wantsGenerated ? genOnTag() : undefined);
+    const style = options?.style;
+    // Sync raw callbacks widen into the async slots at runtime
+    // (FunctionType <: AsyncFunctionType) — the casts only quiet TS.
+    return East.value(variant("ValueTree", {
+        root,
+        onEdit: onEdit !== undefined ? some(onEdit) : none,
+        onInsert: onInsert !== undefined ? some(onInsert) : none,
+        onRemove: onRemove !== undefined ? some(onRemove) : none,
+        onTag: onTag !== undefined ? some(onTag) : none,
+        style: style !== undefined ? some(East.value({
+            height: style.height !== undefined ? some(style.height) : none,
+            maxHeight: style.maxHeight !== undefined ? some(style.maxHeight) : none,
+        }, ValueTreeStyleType)) : none,
+    }), UIComponentType);
+}
+/**
+ * A host-side zero value for any East data type — the default payload
+ * for inserted elements, toggled options and switched variant cases.
+ *
+ * @param t - The East type to zero
+ * @returns The TypeScript `ValueTypeOf` zero value
+ * @throws When the type has no default (functions; recursion below the
+ *   top level)
+ *
+ * @remarks
+ * Delegates to east's {@link defaultValue} (option variants default to
+ * `none` — their sorted first case), unrolling a top-level
+ * RecursiveType wrapper first.
+ */
+function zeroValue(t) {
+    let ct = t;
+    while (ct.type === "Recursive")
+        ct = ct.node;
+    return defaultValue(ct);
+}
+// ============================================================================
+// Namespace export
+// ============================================================================
+/**
+ * ValueTree component namespace.
+ *
+ * @remarks
+ * `ValueTree.Root(value, options)` materializes any East value into the
+ * editable tree; `ValueTree.at(Type, p => …, handler)` builds a scoped
+ * subtree handler for the `at` option; `ValueTree.zero(Type)` builds
+ * the host-side default element for raw `onInsert` handlers.
+ */
+export const ValueTree = {
+    /**
+     * Creates a ValueTree — the editable tree of any East value.
+     *
+     * @param value - The value to materialize (any East type)
+     * @param options - Value handlers, raw callbacks + style
+     *   ({@link ValueTreeOptions})
+     * @returns An East expression of `UIComponentType`
+     */
+    Root: createValueTree,
+    /**
+     * Builds a scoped subtree handler for the `at` option — the deepest
+     * scope whose path prefixes an edit's path receives the rebuilt
+     * subtree; unmatched edits bubble to `onUpdate`.
+     */
+    at: scopeAt,
+    /** Host-side zero value for any East type (for raw `onInsert` handlers). */
+    zero: zeroValue,
+    /**
+     * Host-side materializer — a DECODED value + its type into the node tree
+     * the renderer consumes (for callers holding a value, not an `Expr`; the
+     * East-side {@link ValueTree.Root} materializes an expression instead).
+     */
+    materialize,
+    /**
+     * Host-side edit application — apply one reported ValueTree edit (leaf /
+     * insert / remove / tag) to a decoded value, returning the new value.
+     */
+    applyEdit,
+    Types: {
+        /** The full ValueTree payload. */
+        Root: ValueTreeRootType,
+        /** The materialized node tree. */
+        Node: ValueTreeNodeType,
+        /** A node path. */
+        Path: ValueTreePathType,
+        /** One path step. */
+        Step: ValueTreeStepType,
+        /** A primitive leaf value / leaf edit. */
+        Leaf: ValueTreeLeafType,
+        /** Container style. */
+        Style: ValueTreeStyleType,
+    },
+};
+//# sourceMappingURL=index.js.map