@bian-womp/spark-graph 0.1.0

package/lib/cjs/index.cjs

@@ -0,0 +1,1872 @@
+'use strict';
+
+class CategoryRegistry {
+    constructor() {
+        this.categories = new Map();
+    }
+    register(cat) {
+        this.categories.set(cat.id, cat);
+        return this;
+    }
+    get(id) {
+        return this.categories.get(id);
+    }
+    has(id) {
+        return this.categories.has(id);
+    }
+}
+class Registry {
+    constructor() {
+        this.types = new Map();
+        this.nodes = new Map();
+        this.categories = new CategoryRegistry();
+        this.serializers = new Map();
+        this.coercions = new Map();
+        this.asyncCoercions = new Map();
+        this.enums = new Map();
+    }
+    registerType(desc) {
+        this.types.set(desc.id, desc);
+        return this;
+    }
+    registerNode(desc) {
+        this.nodes.set(desc.id, desc);
+        return this;
+    }
+    registerSerializer(typeId, s) {
+        this.serializers.set(typeId, s);
+        return this;
+    }
+    // Register a type coercion from one type id to another
+    registerCoercion(fromTypeId, toTypeId, convert) {
+        this.coercions.set(`${fromTypeId}->${toTypeId}`, convert);
+        return this;
+    }
+    // Register an async type coercion from one type id to another
+    registerAsyncCoercion(fromTypeId, toTypeId, convertAsync) {
+        this.asyncCoercions.set(`${fromTypeId}->${toTypeId}`, convertAsync);
+        return this;
+    }
+    canCoerce(fromTypeId, toTypeId) {
+        if (!fromTypeId || !toTypeId)
+            return false;
+        if (fromTypeId === toTypeId)
+            return true;
+        const key = `${fromTypeId}->${toTypeId}`;
+        return this.coercions.has(key) || this.asyncCoercions.has(key);
+    }
+    getCoercion(fromTypeId, toTypeId) {
+        if (fromTypeId === toTypeId)
+            return (v) => v;
+        return this.coercions.get(`${fromTypeId}->${toTypeId}`);
+    }
+    getAsyncCoercion(fromTypeId, toTypeId) {
+        if (fromTypeId === toTypeId)
+            return undefined;
+        return this.asyncCoercions.get(`${fromTypeId}->${toTypeId}`);
+    }
+    // Enum support
+    registerEnum(enumTypeId, options, labelType, valueType) {
+        const valueToLabel = new Map();
+        const labelToValue = new Map();
+        for (const { value, label } of options) {
+            valueToLabel.set(value, label);
+            labelToValue.set(label.toLowerCase(), value);
+        }
+        this.enums.set(enumTypeId, {
+            options,
+            valueToLabel,
+            labelToValue,
+        });
+        // Register type descriptor and serializer for enum (stored as number)
+        this.registerType({
+            id: enumTypeId,
+            validate: (v) => typeof v === "number" && valueToLabel.has(Number(v)),
+        });
+        this.registerSerializer(enumTypeId, {
+            serialize: (v) => v,
+            deserialize: (d) => Number(d),
+        });
+        // Coercions: string -> enum (by label), float -> enum (by numeric value), enum -> string (label)
+        this.registerCoercion(labelType, enumTypeId, (value) => {
+            const s = String(value ?? "")
+                .trim()
+                .toLowerCase();
+            const rec = this.enums.get(enumTypeId);
+            if (!rec)
+                return value;
+            if (rec.labelToValue.has(s))
+                return rec.labelToValue.get(s);
+            const asNum = Number(s);
+            if (Number.isFinite(asNum) && rec.valueToLabel.has(asNum))
+                return asNum;
+            return Array.from(rec.valueToLabel.keys())[0] ?? 0;
+        });
+        this.registerCoercion(valueType, enumTypeId, (value) => {
+            const n = Number(value);
+            const rec = this.enums.get(enumTypeId);
+            if (!rec)
+                return value;
+            return rec.valueToLabel.has(n)
+                ? n
+                : Array.from(rec.valueToLabel.keys())[0] ?? 0;
+        });
+        this.registerCoercion(enumTypeId, labelType, (value) => {
+            const n = Number(value);
+            const rec = this.enums.get(enumTypeId);
+            if (!rec)
+                return String(value);
+            return rec.valueToLabel.get(n) ?? String(n);
+        });
+        return this;
+    }
+    getEnumOptions(enumTypeId) {
+        return this.enums.get(enumTypeId)?.options ?? [];
+    }
+    getEnumLabel(enumTypeId, value) {
+        return this.enums.get(enumTypeId)?.valueToLabel.get(value);
+    }
+    getEnumValue(enumTypeId, label) {
+        return this.enums.get(enumTypeId)?.labelToValue.get(label.toLowerCase());
+    }
+}
+
+class GraphRuntime {
+    constructor() {
+        this.nodes = new Map();
+        this.edges = [];
+        this.listeners = new Map();
+        this.environment = {};
+        this.paused = false;
+    }
+    static create(def, registry, opts) {
+        const gr = new GraphRuntime();
+        gr.environment = opts?.environment ?? {};
+        // Instantiate nodes
+        for (const n of def.nodes) {
+            const desc = registry.nodes.get(n.typeId);
+            if (!desc)
+                throw new Error(`Unknown node type: ${n.typeId}`);
+            const cat = registry.categories.get(desc.categoryId);
+            if (!cat)
+                throw new Error(`Unknown category: ${desc.categoryId}`);
+            if (cat.validateImpl)
+                cat.validateImpl(desc.impl);
+            const runtime = cat.createRuntime({
+                nodeId: n.nodeId,
+                impl: desc.impl,
+            });
+            const rn = {
+                typeId: n.typeId,
+                nodeId: n.nodeId,
+                lifecycle: desc.lifecycle,
+                inputs: {},
+                outputs: {},
+                state: {},
+                runtime,
+                params: n.params,
+                policy: {
+                    ...cat.policy,
+                    ...(n.params && n.params.policy ? n.params.policy : {}),
+                },
+                activeControllers: new Set(),
+                queue: [],
+                stats: {
+                    runs: 0,
+                    active: 0,
+                    queued: 0,
+                    progress: 0,
+                },
+            };
+            gr.nodes.set(n.nodeId, rn);
+        }
+        // Instantiate edges
+        gr.edges = def.edges.map((e) => {
+            // infer type from source output if missing
+            const srcNode = def.nodes.find((n) => n.nodeId === e.source.nodeId);
+            const dstNode = def.nodes.find((n) => n.nodeId === e.target.nodeId);
+            let effectiveTypeId = e.typeId;
+            let srcDeclared;
+            let dstDeclared;
+            if (srcNode) {
+                const srcDesc = registry.nodes.get(srcNode.typeId);
+                if (srcDesc) {
+                    srcDeclared = srcDesc.outputs[e.source.handle];
+                }
+            }
+            if (!effectiveTypeId)
+                effectiveTypeId = srcDeclared;
+            if (dstNode) {
+                const dstDesc = registry.nodes.get(dstNode.typeId);
+                if (dstDesc) {
+                    dstDeclared = dstDesc.inputs[e.target.handle];
+                }
+            }
+            // Attach convert if source/target differ but coercible
+            let convert = undefined;
+            let convertAsync = undefined;
+            if (srcDeclared && dstDeclared && srcDeclared !== dstDeclared) {
+                const fn = registry.getCoercion(srcDeclared, dstDeclared);
+                if (fn)
+                    convert = convert ?? fn;
+                const afn = registry.getAsyncCoercion(srcDeclared, dstDeclared);
+                if (afn)
+                    convertAsync = convertAsync ?? afn;
+            }
+            return {
+                id: e.id,
+                source: { ...e.source },
+                target: { ...e.target },
+                typeId: effectiveTypeId ?? "untyped",
+                convert,
+                convertAsync,
+                stats: { runs: 0, inFlight: false, progress: 0 },
+            };
+        });
+        return gr;
+    }
+    on(event, handler) {
+        if (!this.listeners.has(event))
+            this.listeners.set(event, new Set());
+        const set = this.listeners.get(event);
+        set.add(handler);
+        return () => set.delete(handler);
+    }
+    emit(event, payload) {
+        const set = this.listeners.get(event);
+        if (set)
+            for (const h of Array.from(set))
+                h(payload);
+    }
+    setInput(nodeId, handle, value) {
+        const node = this.nodes.get(nodeId);
+        if (!node)
+            throw new Error(`Node not found: ${nodeId}`);
+        // If this input has an inbound edge, prefer propagated runtime value over manual input
+        const hasInbound = this.edges.some((e) => e.target.nodeId === nodeId && e.target.handle === handle);
+        if (hasInbound)
+            return; // respect linked value
+        node.inputs[handle] = value;
+        // Emit value event for input updates
+        this.emit("value", { nodeId, handle, value, io: "input" });
+        if (!this.paused)
+            this.scheduleInputsChanged(nodeId);
+    }
+    getOutput(nodeId, output) {
+        const node = this.nodes.get(nodeId);
+        return node?.outputs[output];
+    }
+    scheduleInputsChanged(nodeId) {
+        const node = this.nodes.get(nodeId);
+        if (!node)
+            return;
+        if (this.paused)
+            return;
+        const now = Date.now();
+        const policy = node.policy ?? {};
+        if (policy.debounceMs &&
+            node.lastScheduledAt &&
+            now - node.lastScheduledAt < policy.debounceMs) {
+            // debounce: replace latest queued
+            node.queue.splice(0, node.queue.length);
+            const rid = `${nodeId}:${now}`;
+            node.queue.push({ runId: rid, inputs: { ...node.inputs } });
+            return;
+        }
+        node.lastScheduledAt = now;
+        const rid = `${nodeId}:${now}:${Math.random().toString(36).slice(2, 8)}`;
+        node.latestRunId = rid;
+        const startRun = (runId, capturedInputs, onDone) => {
+            const controller = new AbortController();
+            node.stats.runs += 1;
+            node.stats.active += 1;
+            node.stats.lastStartAt = now;
+            node.stats.progress = 0;
+            node.activeControllers.add(controller);
+            const mode = policy.asyncConcurrency ?? "switch";
+            if (mode === "switch") {
+                for (const c of Array.from(node.activeControllers)) {
+                    if (c !== controller)
+                        c.abort("switch");
+                }
+            }
+            let timeoutId;
+            if (policy.timeoutMs && policy.timeoutMs > 0) {
+                timeoutId = setTimeout(() => controller.abort("timeout"), policy.timeoutMs);
+            }
+            const ctx = {
+                state: node.state,
+                setState: (next) => Object.assign(node.state, next),
+                emit: (handle, value) => {
+                    const m = policy.asyncConcurrency ?? "switch";
+                    if (m !== "merge" && runId !== node.latestRunId)
+                        return;
+                    this.propagate(nodeId, handle, value);
+                },
+                invalidateDownstream: () => this.invalidateDownstream(nodeId),
+                getInput: (handle) => capturedInputs[handle],
+                environment: this.environment,
+                runId: runId,
+                abortSignal: controller.signal,
+                createAbortController: () => new AbortController(),
+                reportProgress: (p) => {
+                    node.stats.progress = Math.max(0, Math.min(1, Number(p) || 0));
+                    this.emit("stats", {
+                        kind: "node-progress",
+                        nodeId,
+                        runId,
+                        progress: node.stats.progress,
+                    });
+                },
+            };
+            const exec = async (attempt) => {
+                try {
+                    await node.runtime.onInputsChanged?.(capturedInputs, ctx);
+                }
+                catch (err) {
+                    // Suppress errors caused by expected cancellations (switch)
+                    if (controller.signal.aborted) {
+                        const reason = controller.signal.reason;
+                        if (reason === "switch") {
+                            return; // ignore switched runs
+                        }
+                    }
+                    const retry = policy.retry;
+                    if (retry && attempt < (retry.attempts ?? 0)) {
+                        const delay = retry.backoffMs ? retry.backoffMs(attempt) : 0;
+                        await new Promise((r) => setTimeout(r, delay));
+                        return exec(attempt + 1);
+                    }
+                    this.emit("error", { nodeId, runId, err });
+                }
+                finally {
+                    if (timeoutId)
+                        clearTimeout(timeoutId);
+                    node.activeControllers.delete(controller);
+                    node.stats.active = Math.max(0, node.activeControllers.size);
+                    node.stats.lastEndAt = Date.now();
+                    node.stats.lastDurationMs =
+                        node.stats.lastStartAt && node.stats.lastEndAt
+                            ? node.stats.lastEndAt - node.stats.lastStartAt
+                            : undefined;
+                    this.emit("stats", {
+                        kind: "node-done",
+                        nodeId,
+                        runId,
+                        durationMs: node.stats.lastDurationMs,
+                    });
+                    if (onDone)
+                        onDone();
+                }
+            };
+            // fire node-start event
+            this.emit("stats", { kind: "node-start", nodeId, runId });
+            void exec(0);
+        };
+        const mode = policy.asyncConcurrency ?? "switch";
+        if (mode === "drop" && node.activeControllers.size > 0)
+            return;
+        if (mode === "queue") {
+            const maxQ = policy.maxQueue ?? 8;
+            node.queue.push({ runId: rid, inputs: { ...node.inputs } });
+            if (node.queue.length > maxQ)
+                node.queue.shift();
+            const processNext = () => {
+                if (node.activeControllers.size > 0)
+                    return;
+                const next = node.queue.shift();
+                if (!next)
+                    return;
+                node.latestRunId = next.runId;
+                startRun(next.runId, next.inputs, () => {
+                    // After finishing, schedule next
+                    setTimeout(processNext, 0);
+                });
+            };
+            processNext();
+            return;
+        }
+        // switch or merge
+        startRun(rid, { ...node.inputs });
+    }
+    invalidateDownstream(nodeId) {
+        // Notifies dependents; for now we propagate current outputs
+        for (const e of this.edges.filter((e) => e.source.nodeId === nodeId)) {
+            const value = this.getOutput(nodeId, e.source.handle);
+            if (value !== undefined)
+                this.propagate(nodeId, e.source.handle, value);
+        }
+    }
+    propagate(srcNodeId, srcHandle, value) {
+        // set source output
+        const srcNode = this.nodes.get(srcNodeId);
+        srcNode.outputs[srcHandle] = value;
+        this.emit("value", {
+            nodeId: srcNodeId,
+            handle: srcHandle,
+            value,
+            io: "output",
+        });
+        // fan-out along all edges from this output
+        const outEdges = this.edges.filter((e) => e.source.nodeId === srcNodeId && e.source.handle === srcHandle);
+        for (const e of outEdges) {
+            let nextVal = value;
+            const applyToTarget = (v) => {
+                const dstNode = this.nodes.get(e.target.nodeId);
+                if (!dstNode)
+                    return;
+                dstNode.inputs[e.target.handle] = v;
+                // Emit value event for input updates
+                this.emit("value", {
+                    nodeId: e.target.nodeId,
+                    handle: e.target.handle,
+                    value: v,
+                    io: "input",
+                });
+                if (!this.paused)
+                    this.scheduleInputsChanged(e.target.nodeId);
+            };
+            if (e.convertAsync) {
+                // emit edge-start before launching async conversion
+                this.emit("stats", {
+                    kind: "edge-start",
+                    edgeId: e.id,
+                    source: { nodeId: e.source.nodeId, handle: e.source.handle },
+                    target: { nodeId: e.target.nodeId, handle: e.target.handle },
+                });
+                const controller = new AbortController();
+                const startAt = Date.now();
+                e.stats.runs += 1;
+                e.stats.inFlight = true;
+                e.stats.progress = 0;
+                const sig = controller.signal;
+                // Fire async conversion
+                void e
+                    .convertAsync(nextVal, sig)
+                    .then((v) => {
+                    e.stats.inFlight = false;
+                    e.stats.lastEndAt = Date.now();
+                    e.stats.lastDurationMs = e.stats.lastEndAt - startAt;
+                    this.emit("stats", {
+                        kind: "edge-done",
+                        edgeId: e.id,
+                        source: { nodeId: e.source.nodeId, handle: e.source.handle },
+                        target: { nodeId: e.target.nodeId, handle: e.target.handle },
+                        durationMs: e.stats.lastDurationMs,
+                    });
+                    applyToTarget(v);
+                })
+                    .catch((err) => {
+                    if (sig.aborted)
+                        return;
+                    e.stats.inFlight = false;
+                    e.stats.lastError = err;
+                    this.emit("error", {
+                        kind: "edge-convert",
+                        edgeId: e.id,
+                        source: { nodeId: e.source.nodeId, handle: e.source.handle },
+                        target: { nodeId: e.target.nodeId, handle: e.target.handle },
+                        err,
+                    });
+                });
+            }
+            else {
+                if (e.convert)
+                    nextVal = e.convert(nextVal);
+                applyToTarget(nextVal);
+            }
+        }
+    }
+    launch() {
+        // call onActivated for nodes that implement it
+        for (const node of this.nodes.values()) {
+            const ctrl = new AbortController();
+            const ctx = {
+                state: node.state,
+                setState: (next) => Object.assign(node.state, next),
+                emit: (handle, value) => this.propagate(node.nodeId, handle, value),
+                invalidateDownstream: () => this.invalidateDownstream(node.nodeId),
+                getInput: (handle) => node.inputs[handle],
+                environment: this.environment,
+                runId: `${node.nodeId}:activation`,
+                abortSignal: ctrl.signal,
+                createAbortController: () => new AbortController(),
+                reportProgress: (p) => {
+                    node.stats.progress = Math.max(0, Math.min(1, Number(p) || 0));
+                },
+            };
+            node.lifecycle?.init?.(node.params ?? {}, {
+                state: node.state,
+                setState: (next) => Object.assign(node.state, next),
+            });
+            node.runtime.onActivated?.(ctx);
+        }
+    }
+    triggerExternal(nodeId, event) {
+        const node = this.nodes.get(nodeId);
+        if (!node)
+            return;
+        const ctrl = new AbortController();
+        const ctx = {
+            state: node.state,
+            setState: (next) => Object.assign(node.state, next),
+            emit: (handle, value) => this.propagate(nodeId, handle, value),
+            invalidateDownstream: () => this.invalidateDownstream(nodeId),
+            getInput: (handle) => node.inputs[handle],
+            environment: this.environment,
+            runId: `${nodeId}:external`,
+            abortSignal: ctrl.signal,
+            createAbortController: () => new AbortController(),
+            reportProgress: (p) => {
+                node.stats.progress = Math.max(0, Math.min(1, Number(p) || 0));
+            },
+        };
+        node.runtime.onExternalEvent?.(event, ctx);
+    }
+    dispose() {
+        for (const node of this.nodes.values()) {
+            node.runtime.onDeactivated?.();
+            node.runtime.dispose?.();
+            node.lifecycle?.dispose?.({
+                state: node.state,
+                setState: (next) => Object.assign(node.state, next),
+            });
+        }
+        this.nodes.clear();
+        this.edges = [];
+        this.listeners.clear();
+    }
+    // Unsafe helpers for serializer: read-only accessors and hydration
+    __unsafe_getNodeData(nodeId) {
+        const node = this.nodes.get(nodeId);
+        if (!node)
+            return undefined;
+        return {
+            inputs: { ...node.inputs },
+            outputs: { ...node.outputs },
+            state: node.state,
+            params: node.params,
+            stats: { ...node.stats },
+        };
+    }
+    __unsafe_getEnvironment() {
+        return { ...this.environment };
+    }
+    setEnvironment(env) {
+        this.environment = { ...env };
+    }
+    __unsafe_setEnvironment(env) {
+        this.setEnvironment(env);
+    }
+    __unsafe_hydrateNode(nodeId, data, opts) {
+        const node = this.nodes.get(nodeId);
+        if (!node)
+            return;
+        if (opts?.replace) {
+            node.inputs = {};
+            node.outputs = {};
+            node.state = {};
+        }
+        if (data.inputs)
+            Object.assign(node.inputs, data.inputs);
+        if (data.outputs)
+            Object.assign(node.outputs, data.outputs);
+        if (data.state !== undefined)
+            node.state = data.state;
+        if (data.params)
+            node.params = data.params;
+    }
+    async whenIdle() {
+        const isIdle = () => {
+            for (const n of this.nodes.values()) {
+                if (n.activeControllers.size > 0)
+                    return false;
+                if (n.queue.length > 0)
+                    return false;
+            }
+            return true;
+        };
+        if (isIdle())
+            return;
+        await new Promise((resolve) => {
+            const check = () => {
+                if (isIdle())
+                    resolve();
+                else
+                    setTimeout(check, 10);
+            };
+            setTimeout(check, 10);
+        });
+    }
+    pause() {
+        this.paused = true;
+    }
+    resume() {
+        this.paused = false;
+    }
+    __unsafe_invalidateDownstream(nodeId) {
+        this.invalidateDownstream(nodeId);
+    }
+    __unsafe_reemitNodeOutputs(nodeId) {
+        const node = this.nodes.get(nodeId);
+        if (!node)
+            return;
+        for (const [handle, value] of Object.entries(node.outputs)) {
+            this.propagate(nodeId, handle, value);
+        }
+    }
+    __unsafe_scheduleInputsChanged(nodeId) {
+        this.scheduleInputsChanged(nodeId);
+    }
+    // Incrementally update nodes/edges to match new definition without full rebuild
+    update(def, registry) {
+        // Handle node additions and removals
+        const desiredIds = new Set(def.nodes.map((n) => n.nodeId));
+        const currentIds = new Set(this.nodes.keys());
+        // Remove nodes not present
+        for (const nodeId of Array.from(currentIds)) {
+            if (!desiredIds.has(nodeId)) {
+                const node = this.nodes.get(nodeId);
+                node.runtime.onDeactivated?.();
+                node.runtime.dispose?.();
+                node.lifecycle?.dispose?.({
+                    state: node.state,
+                    setState: (next) => Object.assign(node.state, next),
+                });
+                this.nodes.delete(nodeId);
+            }
+        }
+        // Add or update existing nodes
+        for (const n of def.nodes) {
+            const existing = this.nodes.get(n.nodeId);
+            if (!existing) {
+                // create new runtime node
+                const desc = registry.nodes.get(n.typeId);
+                if (!desc)
+                    throw new Error(`Unknown node type: ${n.typeId}`);
+                const cat = registry.categories.get(desc.categoryId);
+                if (!cat)
+                    throw new Error(`Unknown category: ${desc.categoryId}`);
+                if (cat.validateImpl)
+                    cat.validateImpl(desc.impl);
+                const runtime = cat.createRuntime({
+                    nodeId: n.nodeId,
+                    impl: desc.impl,
+                });
+                const rn = {
+                    typeId: n.typeId,
+                    nodeId: n.nodeId,
+                    lifecycle: desc.lifecycle,
+                    inputs: {},
+                    outputs: {},
+                    state: {},
+                    runtime,
+                    params: n.params,
+                    policy: {
+                        ...cat.policy,
+                        ...(n.params && n.params.policy ? n.params.policy : {}),
+                    },
+                    activeControllers: new Set(),
+                    queue: [],
+                    stats: {
+                        runs: 0,
+                        active: 0,
+                        queued: 0,
+                        progress: 0,
+                    },
+                };
+                this.nodes.set(n.nodeId, rn);
+                // Activate new node
+                const ctrl = new AbortController();
+                const ctx = {
+                    state: rn.state,
+                    setState: (next) => Object.assign(rn.state, next),
+                    emit: (handle, value) => this.propagate(rn.nodeId, handle, value),
+                    invalidateDownstream: () => this.invalidateDownstream(rn.nodeId),
+                    getInput: (handle) => rn.inputs[handle],
+                    environment: this.environment,
+                    runId: `${rn.nodeId}:activation`,
+                    abortSignal: ctrl.signal,
+                    createAbortController: () => new AbortController(),
+                };
+                rn.lifecycle?.init?.(rn.params ?? {}, {
+                    state: rn.state,
+                    setState: (next) => Object.assign(rn.state, next),
+                });
+                rn.runtime.onActivated?.(ctx);
+            }
+            else {
+                // update params/policy
+                existing.params = n.params;
+                if (!existing.stats) {
+                    existing.stats = {
+                        runs: 0,
+                        active: 0,
+                        queued: 0,
+                        progress: 0,
+                    };
+                }
+            }
+        }
+        // Capture previous inbound map before rebuilding edges
+        const prevInbound = new Map();
+        for (const e of this.edges) {
+            const set = prevInbound.get(e.target.nodeId) ?? new Set();
+            set.add(e.target.handle);
+            prevInbound.set(e.target.nodeId, set);
+        }
+        // Rebuild edges mapping with coercions
+        this.edges = def.edges.map((e) => {
+            const srcNode = def.nodes.find((nn) => nn.nodeId === e.source.nodeId);
+            const dstNode = def.nodes.find((nn) => nn.nodeId === e.target.nodeId);
+            let effectiveTypeId = e.typeId;
+            let srcDeclared;
+            let dstDeclared;
+            if (srcNode) {
+                const srcDesc = registry.nodes.get(srcNode.typeId);
+                if (srcDesc) {
+                    srcDeclared = srcDesc.outputs[e.source.handle];
+                }
+            }
+            if (!effectiveTypeId)
+                effectiveTypeId = srcDeclared;
+            if (dstNode) {
+                const dstDesc = registry.nodes.get(dstNode.typeId);
+                if (dstDesc) {
+                    dstDeclared = dstDesc.inputs[e.target.handle];
+                }
+            }
+            let convert = undefined;
+            let convertAsync = undefined;
+            if (srcDeclared && dstDeclared && srcDeclared !== dstDeclared) {
+                const fn = registry.getCoercion(srcDeclared, dstDeclared);
+                if (fn)
+                    convert = convert ?? fn;
+                const afn = registry.getAsyncCoercion(srcDeclared, dstDeclared);
+                if (afn)
+                    convertAsync = convertAsync ?? afn;
+            }
+            return {
+                id: e.id,
+                source: { ...e.source },
+                target: { ...e.target },
+                typeId: effectiveTypeId ?? "untyped",
+                convert,
+                convertAsync,
+                stats: { runs: 0, inFlight: false, progress: 0 },
+            };
+        });
+        // Build new inbound map
+        const nextInbound = new Map();
+        for (const e of this.edges) {
+            const set = nextInbound.get(e.target.nodeId) ?? new Set();
+            set.add(e.target.handle);
+            nextInbound.set(e.target.nodeId, set);
+        }
+        // For inputs that lost inbound connections, clear and schedule recompute
+        for (const [nodeId, prevSet] of prevInbound) {
+            const currSet = nextInbound.get(nodeId) ?? new Set();
+            const node = this.nodes.get(nodeId);
+            if (!node)
+                continue;
+            let changed = false;
+            for (const handle of Array.from(prevSet)) {
+                if (!currSet.has(handle)) {
+                    if (handle in node.inputs) {
+                        delete node.inputs[handle];
+                        changed = true;
+                    }
+                }
+            }
+            if (changed)
+                this.scheduleInputsChanged(nodeId);
+        }
+        // Re-emit existing outputs to populate new edges
+        for (const nodeId of this.nodes.keys()) {
+            this.__unsafe_reemitNodeOutputs(nodeId);
+        }
+    }
+}
+
+class GraphBuilder {
+    constructor(registry) {
+        this.registry = registry;
+    }
+    validate(def) {
+        const issues = [];
+        const nodeIds = new Set();
+        const edgeIds = new Set();
+        // nodes exist, ids unique, and categories registered
+        for (const n of def.nodes) {
+            if (nodeIds.has(n.nodeId)) {
+                issues.push({
+                    level: "error",
+                    code: "NODE_ID_DUP",
+                    message: `Duplicate nodeId ${n.nodeId}`,
+                    data: { nodeId: n.nodeId },
+                });
+            }
+            else {
+                nodeIds.add(n.nodeId);
+            }
+            const nodeType = this.registry.nodes.get(n.typeId);
+            if (!nodeType) {
+                issues.push({
+                    level: "error",
+                    code: "NODE_TYPE_MISSING",
+                    message: `Unknown node type ${n.typeId}`,
+                    data: { typeId: n.typeId, nodeId: n.nodeId },
+                });
+                continue;
+            }
+            if (!this.registry.categories.has(nodeType.categoryId)) {
+                issues.push({
+                    level: "error",
+                    code: "CATEGORY_MISSING",
+                    message: `Unknown category ${nodeType.categoryId} for node type ${n.typeId}`,
+                });
+            }
+        }
+        // edges validation: nodes exist, handles exist, type exists
+        const inboundCounts = new Map();
+        for (const e of def.edges) {
+            if (edgeIds.has(e.id)) {
+                issues.push({
+                    level: "error",
+                    code: "EDGE_ID_DUP",
+                    message: `Duplicate edge id ${e.id}`,
+                    data: { edgeId: e.id },
+                });
+            }
+            else {
+                edgeIds.add(e.id);
+            }
+            const srcNode = def.nodes.find((nn) => nn.nodeId === e.source.nodeId);
+            const dstNode = def.nodes.find((nn) => nn.nodeId === e.target.nodeId);
+            if (!srcNode)
+                issues.push({
+                    level: "error",
+                    code: "EDGE_SOURCE_MISSING",
+                    message: `Edge ${e.id} source node missing`,
+                    data: { edgeId: e.id },
+                });
+            if (!dstNode)
+                issues.push({
+                    level: "error",
+                    code: "EDGE_TARGET_MISSING",
+                    message: `Edge ${e.id} target node missing`,
+                    data: { edgeId: e.id },
+                });
+            // infer edge type from source output if missing
+            let effectiveTypeId = e.typeId;
+            if (!effectiveTypeId && srcNode) {
+                const srcType = this.registry.nodes.get(srcNode.typeId);
+                if (srcType) {
+                    effectiveTypeId = srcType.outputs[e.source.handle];
+                }
+            }
+            const type = effectiveTypeId
+                ? this.registry.types.get(effectiveTypeId)
+                : undefined;
+            if (!type) {
+                issues.push({
+                    level: "error",
+                    code: "TYPE_MISSING",
+                    message: `Edge ${e.id} type missing or unknown`,
+                    data: { edgeId: e.id },
+                });
+            }
+            if (srcNode) {
+                const srcType = this.registry.nodes.get(srcNode.typeId);
+                if (srcType && !(e.source.handle in srcType.outputs)) {
+                    issues.push({
+                        level: "error",
+                        code: "OUTPUT_MISSING",
+                        message: `Edge ${e.id} source output ${e.source.handle} missing on ${srcNode.typeId}`,
+                        data: {
+                            edgeId: e.id,
+                            nodeId: srcNode.nodeId,
+                            output: e.source.handle,
+                        },
+                    });
+                }
+                if (srcType) {
+                    const declared = srcType.outputs[e.source.handle];
+                    if (declared &&
+                        effectiveTypeId &&
+                        declared !== effectiveTypeId &&
+                        !this.registry.canCoerce(declared, effectiveTypeId)) {
+                        issues.push({
+                            level: "error",
+                            code: "TYPE_MISMATCH_OUTPUT",
+                            message: `Edge ${e.id} type ${effectiveTypeId} mismatches source output ${srcNode.typeId}.${e.source.handle} (${declared}) and no coercion exists`,
+                            data: {
+                                edgeId: e.id,
+                                nodeId: srcNode.nodeId,
+                                output: e.source.handle,
+                                declared,
+                                effectiveTypeId,
+                            },
+                        });
+                    }
+                }
+            }
+            if (dstNode) {
+                const dstType = this.registry.nodes.get(dstNode.typeId);
+                if (dstType && !(e.target.handle in dstType.inputs)) {
+                    issues.push({
+                        level: "error",
+                        code: "INPUT_MISSING",
+                        message: `Edge ${e.id} target input ${e.target.handle} missing on ${dstNode.typeId}`,
+                        data: {
+                            edgeId: e.id,
+                            nodeId: dstNode.nodeId,
+                            input: e.target.handle,
+                        },
+                    });
+                }
+                if (dstType) {
+                    const declared = dstType.inputs[e.target.handle];
+                    if (declared &&
+                        effectiveTypeId &&
+                        declared !== effectiveTypeId &&
+                        !this.registry.canCoerce(effectiveTypeId, declared)) {
+                        issues.push({
+                            level: "error",
+                            code: "TYPE_MISMATCH_INPUT",
+                            message: `Edge ${e.id} type ${effectiveTypeId} mismatches target input ${dstNode.typeId}.${e.target.handle} (${declared}) and no coercion exists`,
+                            data: {
+                                edgeId: e.id,
+                                nodeId: dstNode.nodeId,
+                                input: e.target.handle,
+                                declared,
+                                effectiveTypeId,
+                            },
+                        });
+                    }
+                }
+            }
+            // Track multiple inbound edges targeting the same input handle
+            const inboundKey = `${e.target.nodeId}::${e.target.handle}`;
+            inboundCounts.set(inboundKey, (inboundCounts.get(inboundKey) ?? 0) + 1);
+        }
+        for (const [key, count] of inboundCounts) {
+            if (count > 1) {
+                issues.push({
+                    level: "warning",
+                    code: "MULTI_INBOUND",
+                    message: `Input ${key} has ${count} inbound edges (last-write wins).`,
+                    data: { nodeId: key.split("::")[0], input: key.split("::")[1] },
+                });
+            }
+        }
+        return { ok: issues.every((i) => i.level !== "error"), issues };
+    }
+    build(def, opts) {
+        return GraphRuntime.create(def, this.registry, opts);
+    }
+    wrapAsNode(def, exposure, nodeTypeId, displayName) {
+        // Infer exposed handle types from inner graph using registry
+        const inputTypes = {};
+        const outputTypes = {};
+        for (const [outerIn, map] of Object.entries(exposure.inputs)) {
+            const innerNode = def.nodes.find((n) => n.nodeId === map.nodeId);
+            const innerDesc = innerNode
+                ? this.registry.nodes.get(innerNode.typeId)
+                : undefined;
+            const typeId = innerDesc ? innerDesc.inputs[map.handle] : undefined;
+            inputTypes[outerIn] = typeId ?? "untyped";
+        }
+        for (const [outerOut, map] of Object.entries(exposure.outputs)) {
+            const innerNode = def.nodes.find((n) => n.nodeId === map.nodeId);
+            const innerDesc = innerNode
+                ? this.registry.nodes.get(innerNode.typeId)
+                : undefined;
+            const typeId = innerDesc ? innerDesc.outputs[map.handle] : undefined;
+            outputTypes[outerOut] = typeId ?? "untyped";
+        }
+        return {
+            id: nodeTypeId,
+            displayName,
+            categoryId: "composite",
+            inputs: inputTypes,
+            outputs: outputTypes,
+            impl: { def, exposure },
+        };
+    }
+}
+
+class AbstractEngine {
+    constructor(graphRuntime) {
+        this.graphRuntime = graphRuntime;
+    }
+    launch() {
+        this.graphRuntime.launch();
+    }
+    setInput(nodeId, handle, value) {
+        this.graphRuntime.setInput(nodeId, handle, value);
+    }
+    triggerExternal(nodeId, event) {
+        this.graphRuntime.triggerExternal(nodeId, event);
+    }
+    on(event, handler) {
+        return this.graphRuntime.on(event, handler);
+    }
+    getOutput(nodeId, output) {
+        return this.graphRuntime.getOutput(nodeId, output);
+    }
+    whenIdle() {
+        return this.graphRuntime.whenIdle();
+    }
+    dispose() {
+        this.graphRuntime.dispose();
+    }
+}
+
+class PushEngine extends AbstractEngine {
+    constructor(graphRuntime) {
+        super(graphRuntime);
+    }
+}
+
+class LocalRunner {
+    constructor(registry) {
+        this.registry = registry;
+        this.builder = new GraphBuilder(registry);
+    }
+    async build(def, opts) {
+        const rt = this.builder.build(def, opts);
+        this.engine = new PushEngine(rt);
+    }
+    async update(def) {
+        // If engine exists and is a PushEngine backed by GraphRuntime, use runtime.update
+        // Otherwise rebuild.
+        const eng = this.engine;
+        if (eng && eng.graphRuntime) {
+            eng.graphRuntime.update(def, this.registry);
+            return;
+        }
+        await this.build(def);
+    }
+    getEngine() {
+        if (!this.engine)
+            throw new Error("Engine not built. Call build(def) first.");
+        return this.engine;
+    }
+}
+
+class BatchedEngine extends AbstractEngine {
+    constructor(graphRuntime, opts = {}) {
+        super(graphRuntime);
+        this.opts = opts;
+        this.dirtyNodes = new Set();
+    }
+    launch() {
+        this.graphRuntime.pause();
+        if (this.opts.flushIntervalMs && this.opts.flushIntervalMs > 0) {
+            this.timer = setInterval(() => this.flush(), this.opts.flushIntervalMs);
+        }
+    }
+    setInput(nodeId, handle, value) {
+        super.setInput(nodeId, handle, value);
+        this.dirtyNodes.add(nodeId);
+    }
+    triggerExternal(nodeId, event) {
+        super.triggerExternal(nodeId, event);
+        this.dirtyNodes.add(nodeId);
+    }
+    async flush() {
+        if (this.dirtyNodes.size === 0)
+            return;
+        // Resume, schedule dirty nodes, wait idle, then pause again
+        const nodes = Array.from(this.dirtyNodes);
+        this.dirtyNodes.clear();
+        this.graphRuntime.resume();
+        for (const n of nodes)
+            this.graphRuntime.__unsafe_scheduleInputsChanged(n);
+        await this.graphRuntime.whenIdle();
+        this.graphRuntime.pause();
+    }
+    dispose() {
+        if (this.timer)
+            clearInterval(this.timer);
+        super.dispose();
+    }
+}
+
+// PullEngine computes only when asked, otherwise holds inputs without scheduling
+class PullEngine extends AbstractEngine {
+    constructor(graphRuntime) {
+        super(graphRuntime);
+        this.graphRuntime.pause();
+    }
+    launch() { }
+    // Pull API
+    async computeNode(nodeId) {
+        this.graphRuntime.resume();
+        this.graphRuntime.__unsafe_scheduleInputsChanged(nodeId);
+        await this.graphRuntime.whenIdle();
+        this.graphRuntime.pause();
+    }
+}
+
+class HybridEngine extends AbstractEngine {
+    constructor(graphRuntime, opts = {}) {
+        super(graphRuntime);
+        this.opts = opts;
+        this.windowStart = 0;
+        this.countInWindow = 0;
+        this.batching = false;
+        this.dirtyNodes = new Set();
+        this.windowStart = Date.now();
+    }
+    updateWindow() {
+        const now = Date.now();
+        const windowMs = this.opts.windowMs ?? 250;
+        if (now - this.windowStart > windowMs) {
+            this.windowStart = now;
+            this.countInWindow = 0;
+            if (this.batching) {
+                this.graphRuntime.resume();
+                this.batching = false;
+                // schedule all dirty nodes accumulated during batching
+                const nodes = Array.from(this.dirtyNodes);
+                this.dirtyNodes.clear();
+                for (const n of nodes)
+                    this.graphRuntime.__unsafe_scheduleInputsChanged(n);
+                if (this.flushTimer) {
+                    clearTimeout(this.flushTimer);
+                    this.flushTimer = undefined;
+                }
+            }
+        }
+    }
+    launch() {
+        this.graphRuntime.resume();
+    }
+    setInput(nodeId, handle, value) {
+        this.updateWindow();
+        this.countInWindow += 1;
+        const threshold = this.opts.batchThreshold ?? 5;
+        if (!this.batching && this.countInWindow >= threshold) {
+            this.graphRuntime.pause();
+            this.batching = true;
+            // ensure flush even if no more inputs arrive
+            const windowMs = this.opts.windowMs ?? 250;
+            if (this.flushTimer)
+                clearTimeout(this.flushTimer);
+            this.flushTimer = setTimeout(() => {
+                if (!this.batching)
+                    return;
+                this.graphRuntime.resume();
+                this.batching = false;
+                const nodes = Array.from(this.dirtyNodes);
+                this.dirtyNodes.clear();
+                for (const n of nodes)
+                    this.graphRuntime.__unsafe_scheduleInputsChanged(n);
+                this.flushTimer = undefined;
+            }, windowMs);
+        }
+        super.setInput(nodeId, handle, value);
+        this.dirtyNodes.add(nodeId);
+        if (!this.batching)
+            this.graphRuntime.__unsafe_scheduleInputsChanged(nodeId);
+    }
+    triggerExternal(nodeId, event) {
+        super.triggerExternal(nodeId, event);
+        this.dirtyNodes.add(nodeId);
+    }
+    dispose() {
+        if (this.flushTimer) {
+            clearTimeout(this.flushTimer);
+            this.flushTimer = undefined;
+        }
+        super.dispose();
+    }
+}
+
+// StepEngine: expose explicit step() to process pending changes once
+class StepEngine extends AbstractEngine {
+    constructor(graphRuntime) {
+        super(graphRuntime);
+        this.dirtyNodes = new Set();
+        this.graphRuntime.pause();
+    }
+    launch() { }
+    setInput(nodeId, handle, value) {
+        super.setInput(nodeId, handle, value);
+        this.dirtyNodes.add(nodeId);
+    }
+    triggerExternal(nodeId, event) {
+        super.triggerExternal(nodeId, event);
+        this.dirtyNodes.add(nodeId);
+    }
+    async step() {
+        // resume first so scheduling isn't ignored due to pause
+        const nodes = Array.from(this.dirtyNodes);
+        this.dirtyNodes.clear();
+        this.graphRuntime.resume();
+        for (const n of nodes)
+            this.graphRuntime.__unsafe_scheduleInputsChanged(n);
+        await this.graphRuntime.whenIdle();
+        this.graphRuntime.pause();
+    }
+}
+
+const ComputeCategory = {
+    id: "compute",
+    displayName: "Compute",
+    createRuntime: ({ impl }) => ({
+        async onInputsChanged(inputs, ctx) {
+            const out = await impl(inputs, ctx);
+            if (out && typeof out === "object") {
+                for (const [h, v] of Object.entries(out))
+                    ctx.emit(h, v);
+            }
+        },
+    }),
+    policy: { mode: "push", asyncConcurrency: "switch" },
+};
+
+const CompositeCategory = (registry) => ({
+    id: "composite",
+    displayName: "Composite",
+    validateImpl: (impl) => {
+        if (!impl || !impl.def)
+            throw new Error("Composite impl requires def");
+    },
+    createRuntime: ({ impl }) => {
+        let inner;
+        let unsub;
+        return {
+            onActivated: () => {
+                inner = GraphRuntime.create(impl.def, registry);
+                // Wire inner outputs to outer emits
+                unsub = inner.on("value", (e) => {
+                    for (const [outHandle, map] of Object.entries(impl.exposure.outputs)) {
+                        if (e.nodeId === map.nodeId && e.handle === map.handle) ;
+                    }
+                });
+                inner.launch();
+            },
+            onInputsChanged: (inputs, ctx) => {
+                if (!inner)
+                    return;
+                // map outer input => inner node input
+                for (const [inHandle, map] of Object.entries(impl.exposure.inputs)) {
+                    if (inHandle in inputs)
+                        inner.setInput(map.nodeId, map.handle, inputs[inHandle]);
+                }
+                // pull inner exposed outputs and emit
+                for (const [outHandle, map] of Object.entries(impl.exposure.outputs)) {
+                    const v = inner.getOutput(map.nodeId, map.handle);
+                    if (v !== undefined)
+                        ctx.emit(outHandle, v);
+                }
+            },
+            onDeactivated: () => {
+                if (unsub)
+                    unsub();
+            },
+            dispose: () => {
+                if (unsub)
+                    unsub();
+                inner?.dispose();
+            },
+        };
+    },
+    policy: { mode: "hybrid" },
+});
+
+function setupBasicGraphRegistry() {
+    const registry = new Registry();
+    registry.categories.register(ComputeCategory);
+    const floatType = {
+        id: "float",
+        validate: (v) => typeof v === "number" && !Number.isNaN(v),
+    };
+    registry.registerType(floatType);
+    registry.registerSerializer("float", {
+        serialize: (v) => v,
+        deserialize: (d) => Number(d),
+    });
+    const boolType = {
+        id: "bool",
+        validate: (v) => typeof v === "boolean",
+    };
+    const stringType = {
+        id: "string",
+        validate: (v) => typeof v === "string",
+    };
+    const vec3Type = {
+        id: "vec3",
+        validate: (v) => Array.isArray(v) &&
+            v.length === 3 &&
+            v.every((x) => typeof x === "number"),
+    };
+    const floatArrayType = {
+        id: "float[]",
+        validate: (v) => Array.isArray(v) && v.every((x) => typeof x === "number"),
+    };
+    const boolArrayType = {
+        id: "bool[]",
+        validate: (v) => Array.isArray(v) && v.every((x) => typeof x === "boolean"),
+    };
+    const vec3ArrayType = {
+        id: "vec3[]",
+        validate: (v) => Array.isArray(v) &&
+            v.every((x) => Array.isArray(x) &&
+                x.length === 3 &&
+                x.every((n) => typeof n === "number")),
+    };
+    [
+        boolType,
+        stringType,
+        vec3Type,
+        floatType,
+        floatArrayType,
+        boolArrayType,
+        vec3ArrayType,
+    ].forEach((t) => {
+        registry.registerType(t);
+        registry.registerSerializer(t.id, {
+            serialize: (v) => v,
+            deserialize: (d) => d,
+        });
+    });
+    // Helpers
+    const asArray = (v) => Array.isArray(v) ? v : [Number(v)];
+    // Register core coercions: float <-> float[]
+    registry.registerCoercion("float", "float[]", (v) => Array.isArray(v) ? v : [Number(v)]);
+    registry.registerCoercion("float[]", "float", (v) => Array.isArray(v) ? Number(v[0] ?? 0) : Number(v));
+    // float[] -> vec3[] : map x to [x,0,0]
+    registry.registerCoercion("float[]", "vec3[]", (v) => {
+        const arr = asArray(v);
+        return arr.map((x) => [Number(x) || 0, 0, 0]);
+    });
+    // Example async coercion: simulate expensive conversion float[] -> vec3[] by computing magnitudes
+    registry.registerCoercion("float[]", "vec3[]", (v) => {
+        // synchronous fallback; async version can be provided on edge via convertAsync
+        if (!Array.isArray(v))
+            return [];
+        return v.map((t) => Math.hypot(Number(t?.[0] ?? 0), Number(t?.[1] ?? 0), Number(t?.[2] ?? 0)));
+    });
+    // Async coercion variant for vec3[] -> float[] (chunked + abortable)
+    registry.registerAsyncCoercion("vec3[]", "float[]", async (value, signal) => {
+        const arr = Array.isArray(value)
+            ? value
+            : [];
+        const out = new Array(arr.length);
+        for (let i = 0; i < arr.length; i++) {
+            if (signal.aborted)
+                throw new DOMException("Aborted", "AbortError");
+            const v = arr[i] ?? [0, 0, 0];
+            await new Promise((r) => setTimeout(r, 1000));
+            out[i] = Math.hypot(Number(v[0] ?? 0), Number(v[1] ?? 0), Number(v[2] ?? 0));
+        }
+        return out;
+    });
+    const broadcast = (a, b) => {
+        const aa = asArray(a);
+        const bb = asArray(b);
+        if (aa.length === bb.length)
+            return [aa, bb];
+        if (aa.length === 1)
+            return [new Array(bb.length).fill(aa[0]), bb];
+        if (bb.length === 1)
+            return [aa, new Array(aa.length).fill(bb[0])];
+        const len = Math.max(aa.length, bb.length);
+        return [new Array(len).fill(aa[0] ?? 0), new Array(len).fill(bb[0] ?? 0)];
+    };
+    const clamp = (x, min, max) => Math.min(max, Math.max(min, x));
+    const lerp = (a, b, t) => a + (b - a) * t;
+    const lcg = (seed) => {
+        let s = seed >>> 0 || 1;
+        return () => (s = (s * 1664525 + 1013904223) >>> 0) / 0xffffffff;
+    };
+    // Number
+    registry.registerNode({
+        id: "number",
+        categoryId: "compute",
+        inputs: { Value: "float" },
+        outputs: { Result: "float" },
+        impl: (ins) => ({ Result: Number(ins.Value) }),
+    });
+    // Integer
+    registry.registerNode({
+        id: "integer",
+        categoryId: "compute",
+        inputs: { Value: "float" },
+        outputs: { Result: "float" },
+        impl: (ins) => ({
+            Result: Math.trunc(Number(ins.Value)),
+        }),
+    });
+    // Number to String
+    registry.registerNode({
+        id: "numberToString",
+        categoryId: "compute",
+        inputs: { Value: "float" },
+        outputs: { Text: "string" },
+        impl: (ins) => ({ Text: String(ins.Value) }),
+    });
+    // Enums: Math Operation
+    registry.registerEnum("enum:math.operation", [
+        { value: 0, label: "Add" },
+        { value: 1, label: "Subtract" },
+        { value: 2, label: "Multiply" },
+        { value: 3, label: "Divide" },
+        { value: 4, label: "Min" },
+        { value: 5, label: "Max" },
+        { value: 6, label: "Modulo" },
+        { value: 7, label: "Power" },
+    ], "string", "float");
+    // Enums: Compare Operation
+    registry.registerEnum("enum:compare.operation", [
+        { value: 0, label: "LessThan" },
+        { value: 1, label: "LessThanOrEqual" },
+        { value: 2, label: "GreaterThan" },
+        { value: 3, label: "GreaterThanOrEqual" },
+        { value: 4, label: "Equal" },
+        { value: 5, label: "NotEqual" },
+    ], "string", "float");
+    // Clamp
+    registry.registerNode({
+        id: "clamp",
+        categoryId: "compute",
+        inputs: { Value: "float[]", Min: "float", Max: "float" },
+        outputs: { Value: "float[]" },
+        impl: (ins) => {
+            const vals = asArray(ins.Value);
+            const min = Number(ins.Min ?? 0);
+            const max = Number(ins.Max ?? 1);
+            return { Value: vals.map((v) => clamp(Number(v), min, max)) };
+        },
+    });
+    // Interpolate (lerp)
+    registry.registerNode({
+        id: "interpolate",
+        categoryId: "compute",
+        inputs: { ValueA: "float[]", ValueB: "float[]", Factor: "float" },
+        outputs: { Value: "float[]" },
+        impl: (ins) => {
+            const [a, b] = broadcast(ins.ValueA, ins.ValueB);
+            const t = Number(ins.Factor ?? 0);
+            const len = Math.max(a.length, b.length);
+            const out = new Array(len)
+                .fill(0)
+                .map((_, i) => lerp(Number(a[i] ?? 0), Number(b[i] ?? 0), t));
+            return { Value: out };
+        },
+    });
+    // Map Range (linear)
+    registry.registerNode({
+        id: "mapRange",
+        categoryId: "compute",
+        inputs: {
+            Mode: "string",
+            Clamp: "bool",
+            Value: "float[]",
+            FromMin: "float",
+            FromMax: "float",
+            ToMin: "float",
+            ToMax: "float",
+        },
+        outputs: { Value: "float[]" },
+        impl: (ins) => {
+            const vals = asArray(ins.Value);
+            const fromMin = Number(ins.FromMin ?? 0);
+            const fromMax = Number(ins.FromMax ?? 1);
+            const toMin = Number(ins.ToMin ?? 0);
+            const toMax = Number(ins.ToMax ?? 1);
+            const doClamp = Boolean(ins.Clamp);
+            const out = vals.map((v) => {
+                const t = (Number(v) - fromMin) / (fromMax - fromMin || 1);
+                const r = toMin + t * (toMax - toMin);
+                return doClamp
+                    ? clamp(r, Math.min(toMin, toMax), Math.max(toMin, toMax))
+                    : r;
+            });
+            return { Value: out };
+        },
+    });
+    // Math (subset) - scalar version for simple examples
+    registry.registerNode({
+        id: "math",
+        categoryId: "compute",
+        inputs: { Operation: "enum:math.operation", A: "float[]", B: "float[]" },
+        outputs: { Result: "float[]" },
+        impl: (ins) => {
+            // Gracefully handle missing inputs by treating them as zeros
+            const a = ins.A === undefined ? [] : asArray(ins.A);
+            const b = ins.B === undefined ? [] : asArray(ins.B);
+            const len = Math.max(a.length, b.length);
+            const op = Number(ins.Operation ?? 0) | 0;
+            const ops = [
+                (x, y) => x + y,
+                (x, y) => x - y,
+                (x, y) => x * y,
+                (x, y) => x / (y || 1),
+                (x, y) => Math.min(x, y),
+                (x, y) => Math.max(x, y),
+                (x, y) => (y ? x % y : 0),
+                (x, y) => Math.pow(x, y),
+            ];
+            const fn = ops[op] ?? ops[0];
+            const out = new Array(len).fill(0).map((_, i) => {
+                const ax = a.length === 1 && len > 1 ? a[0] : a[i] ?? 0;
+                const bx = b.length === 1 && len > 1 ? b[0] : b[i] ?? 0;
+                return fn(Number(ax), Number(bx));
+            });
+            return { Result: out };
+        },
+    });
+    // Compare
+    registry.registerNode({
+        id: "compare",
+        categoryId: "compute",
+        inputs: { Operation: "enum:compare.operation", A: "float[]", B: "float[]" },
+        outputs: { Result: "bool[]" },
+        impl: (ins) => {
+            const [a, b] = broadcast(ins.A, ins.B);
+            const op = Number(ins.Operation ?? 4) | 0; // default Equal
+            const ops = [
+                (x, y) => x < y,
+                (x, y) => x <= y,
+                (x, y) => x > y,
+                (x, y) => x >= y,
+                (x, y) => x === y,
+                (x, y) => x !== y,
+            ];
+            const fn = ops[op] ?? ops[4];
+            return { Result: a.map((x, i) => fn(Number(x), Number(b[i] ?? 0))) };
+        },
+    });
+    // Combine XYZ
+    registry.registerNode({
+        id: "combineXYZ",
+        categoryId: "compute",
+        inputs: { X: "float[]", Y: "float[]", Z: "float[]" },
+        outputs: { XYZ: "vec3[]" },
+        impl: (ins) => {
+            const [x, y] = broadcast(ins.X, ins.Y);
+            const [xx, z] = broadcast(x, ins.Z);
+            const len = Math.max(xx.length, z.length);
+            const out = new Array(len)
+                .fill(0)
+                .map((_, i) => [Number(xx[i] ?? 0), Number(y[i] ?? 0), Number(z[i] ?? 0)]);
+            return { XYZ: out };
+        },
+    });
+    // Separate XYZ
+    registry.registerNode({
+        id: "separateXYZ",
+        categoryId: "compute",
+        inputs: { XYZ: "vec3[]" },
+        outputs: { X: "float[]", Y: "float[]", Z: "float[]" },
+        impl: (ins) => {
+            const arr = ins.XYZ ?? [];
+            const X = arr.map((v) => Number(v?.[0] ?? 0));
+            const Y = arr.map((v) => Number(v?.[1] ?? 0));
+            const Z = arr.map((v) => Number(v?.[2] ?? 0));
+            return { X, Y, Z };
+        },
+    });
+    // Indices
+    registry.registerNode({
+        id: "indices",
+        categoryId: "compute",
+        inputs: { Domain: "float" },
+        outputs: { Indices: "float[]" },
+        impl: (ins) => {
+            const n = Math.trunc(ins.Domain);
+            return { Indices: Array.from({ length: n }, (_, i) => i) };
+        },
+    });
+    // Random Numbers
+    registry.registerNode({
+        id: "randomNumbers",
+        categoryId: "compute",
+        inputs: { Domain: "float", Min: "float", Max: "float", Seed: "float" },
+        outputs: { Values: "float[]" },
+        impl: (ins) => {
+            const len = Math.trunc(ins.Domain);
+            const min = Number(ins.Min ?? 0);
+            const max = Number(ins.Max ?? 1);
+            const rng = lcg(Number(ins.Seed ?? 1));
+            const out = Array.from({ length: len }, () => min + rng() * (max - min));
+            return { Values: out };
+        },
+    });
+    // Random Vectors
+    registry.registerNode({
+        id: "randomVectors",
+        categoryId: "compute",
+        inputs: { Domain: "float", Min: "vec3", Max: "vec3", Seed: "float" },
+        outputs: { Values: "vec3[]" },
+        impl: (ins) => {
+            const len = Math.trunc(ins.Domain);
+            const min = ins.Min ?? [0, 0, 0];
+            const max = ins.Max ?? [1, 1, 1];
+            const rng = lcg(Number(ins.Seed ?? 1));
+            const out = Array.from({ length: len }, () => [
+                min[0] + rng() * (max[0] - min[0]),
+                min[1] + rng() * (max[1] - min[1]),
+                min[2] + rng() * (max[2] - min[2]),
+            ]);
+            return { Values: out };
+        },
+    });
+    return registry;
+}
+function makeBasicGraphDefinition() {
+    return {
+        nodes: [
+            { nodeId: "n1", typeId: "math" },
+            { nodeId: "n2", typeId: "math" },
+        ],
+        edges: [
+            {
+                id: "e1",
+                source: { nodeId: "n1", handle: "Result" },
+                target: { nodeId: "n2", handle: "A" },
+            },
+        ],
+    };
+}
+function registerDelayNode(registry) {
+    registry.registerNode({
+        id: "delay",
+        categoryId: "compute",
+        inputs: { x: "float", ms: "float" },
+        outputs: { out: "float" },
+        impl: async (ins, ctx) => {
+            const ms = Number(ins.ms ?? 200);
+            const xRaw = ins.x;
+            if (xRaw === undefined || xRaw === null || Number.isNaN(Number(xRaw))) {
+                return; // wait until x is present to avoid NaN emissions
+            }
+            await new Promise((resolve, reject) => {
+                const id = setTimeout(resolve, ms);
+                const onAbort = () => {
+                    clearTimeout(id);
+                    reject(new DOMException("Aborted", "AbortError"));
+                };
+                if (ctx.abortSignal.aborted)
+                    return onAbort();
+                ctx.abortSignal.addEventListener("abort", onAbort, { once: true });
+            });
+            return { out: Number(xRaw) };
+        },
+    });
+}
+function sleepWithAbort(ms, signal) {
+    return new Promise((resolve, reject) => {
+        const id = setTimeout(() => {
+            cleanup();
+            resolve();
+        }, ms);
+        const onAbort = () => {
+            clearTimeout(id);
+            cleanup();
+            reject(new DOMException("Aborted", "AbortError"));
+        };
+        const cleanup = () => {
+            signal.removeEventListener("abort", onAbort);
+        };
+        if (signal.aborted)
+            return onAbort();
+        signal.addEventListener("abort", onAbort);
+    });
+}
+function registerProgressNodes(registry) {
+    registry.registerNode({
+        id: "progressWorker",
+        categoryId: "compute",
+        inputs: { Steps: "float", DelayMs: "float", ShouldError: "bool" },
+        outputs: { Done: "string" },
+        impl: async (ins, ctx) => {
+            const steps = Math.max(1, Math.trunc(Number(ins.Steps ?? 10)));
+            const delayMs = Math.max(0, Math.trunc(Number(ins.DelayMs ?? 50)));
+            const shouldError = Boolean(ins.ShouldError);
+            for (let i = 0; i < steps; i++) {
+                ctx.reportProgress?.(i / steps);
+                await sleepWithAbort(delayMs, ctx.abortSignal);
+                if (shouldError && i >= Math.floor(steps * 0.7)) {
+                    ctx.reportProgress?.(i / steps);
+                    throw new Error("progressWorker: simulated failure at 70% progress");
+                }
+            }
+            ctx.reportProgress?.(1);
+            return { Done: `Completed ${steps} steps` };
+        },
+    });
+}
+
+function createSimpleGraphDef() {
+    return makeBasicGraphDefinition();
+}
+function createSimpleGraphRegistry() {
+    return setupBasicGraphRegistry();
+}
+
+function createAsyncGraphDef() {
+    const def = {
+        nodes: [
+            {
+                nodeId: "n1",
+                typeId: "math",
+            },
+            {
+                nodeId: "n2",
+                typeId: "delay",
+                params: { policy: { asyncConcurrency: "queue", maxQueue: 4 } },
+            },
+            {
+                nodeId: "n3",
+                typeId: "separateXYZ",
+            },
+            {
+                nodeId: "n4",
+                typeId: "combineXYZ",
+            },
+        ],
+        edges: [
+            {
+                id: "e1",
+                source: { nodeId: "n1", handle: "Result" },
+                target: { nodeId: "n2", handle: "x" },
+            },
+            // Demonstrate async edge conversion: vec3[] -> float[] using coercion
+            {
+                id: "e2",
+                source: { nodeId: "n4", handle: "XYZ" },
+                target: { nodeId: "n1", handle: "A" },
+                typeId: "vec3[]",
+                // convertAsync,
+            },
+            {
+                id: "e3",
+                source: { nodeId: "n3", handle: "X" },
+                target: { nodeId: "n4", handle: "X" },
+            },
+            {
+                id: "e4",
+                source: { nodeId: "n3", handle: "Y" },
+                target: { nodeId: "n4", handle: "Y" },
+            },
+            {
+                id: "e5",
+                source: { nodeId: "n3", handle: "Z" },
+                target: { nodeId: "n4", handle: "Z" },
+            },
+        ],
+    };
+    return def;
+}
+function createAsyncGraphRegistry() {
+    const registry = setupBasicGraphRegistry();
+    registerDelayNode(registry);
+    return registry;
+}
+
+function createProgressGraphDef() {
+    const def = {
+        nodes: [
+            { nodeId: "steps", typeId: "number" },
+            { nodeId: "delay", typeId: "number" },
+            { nodeId: "work", typeId: "progressWorker" },
+        ],
+        edges: [
+            {
+                id: "e1",
+                source: { nodeId: "steps", handle: "Result" },
+                target: { nodeId: "work", handle: "Steps" },
+            },
+            {
+                id: "e2",
+                source: { nodeId: "delay", handle: "Result" },
+                target: { nodeId: "work", handle: "DelayMs" },
+            },
+            // not wiring ShouldError to show manual input driven error later
+        ],
+    };
+    return def;
+}
+function createProgressGraphRegistry() {
+    const registry = setupBasicGraphRegistry();
+    registerProgressNodes(registry);
+    return registry;
+}
+
+function createValidationGraphDef() {
+    // Intentionally build a graph with validation issues:
+    // - Unknown edge type (wire number to boolean input without coercion)
+    // - Missing target input handle
+    // - Multi inbound to same input
+    const def = {
+        nodes: [
+            { nodeId: "nA", typeId: "number" },
+            { nodeId: "nB", typeId: "number" },
+            { nodeId: "nC", typeId: "math" },
+            { nodeId: "s1", typeId: "numberToString" },
+            { nodeId: "cmp", typeId: "compare" },
+            // Global validation issue: unknown node type (no nodeId/edgeId in data)
+            { nodeId: "bad", typeId: "unknownType" },
+        ],
+        edges: [
+            // Valid: nA.Result -> nC.A (number)
+            {
+                id: "e1",
+                source: { nodeId: "nA", handle: "Result" },
+                target: { nodeId: "nC", handle: "A" },
+            },
+            // Invalid input name (INPUT_MISSING)
+            {
+                id: "e2",
+                source: { nodeId: "nB", handle: "Result" },
+                target: { nodeId: "nC", handle: "NonExistent" },
+            },
+            // Multi inbound to same input (warning): another edge to A
+            {
+                id: "e3",
+                source: { nodeId: "nB", handle: "Result" },
+                target: { nodeId: "nC", handle: "A" },
+            },
+            // Type mismatch to highlight coercion/validation (string -> float[] should error)
+            {
+                id: "e4",
+                source: { nodeId: "s1", handle: "Text" },
+                target: { nodeId: "cmp", handle: "A" },
+            },
+        ],
+    };
+    return def;
+}
+function createValidationGraphRegistry() {
+    const registry = setupBasicGraphRegistry();
+    return registry;
+}
+
+exports.BatchedEngine = BatchedEngine;
+exports.CompositeCategory = CompositeCategory;
+exports.ComputeCategory = ComputeCategory;
+exports.GraphBuilder = GraphBuilder;
+exports.GraphRuntime = GraphRuntime;
+exports.HybridEngine = HybridEngine;
+exports.LocalRunner = LocalRunner;
+exports.PullEngine = PullEngine;
+exports.PushEngine = PushEngine;
+exports.Registry = Registry;
+exports.StepEngine = StepEngine;
+exports.createAsyncGraphDef = createAsyncGraphDef;
+exports.createAsyncGraphRegistry = createAsyncGraphRegistry;
+exports.createProgressGraphDef = createProgressGraphDef;
+exports.createProgressGraphRegistry = createProgressGraphRegistry;
+exports.createSimpleGraphDef = createSimpleGraphDef;
+exports.createSimpleGraphRegistry = createSimpleGraphRegistry;
+exports.createValidationGraphDef = createValidationGraphDef;
+exports.createValidationGraphRegistry = createValidationGraphRegistry;
+exports.registerDelayNode = registerDelayNode;
+exports.registerProgressNodes = registerProgressNodes;
+//# sourceMappingURL=index.cjs.map