@bian-womp/spark-workbench 0.2.24 → 0.2.26

package/lib/cjs/index.cjs

@@ -572,6 +572,10 @@ class RemoteGraphRunner extends AbstractGraphRunner {
         super(registry, backend);
         this.valueCache = new Map();
         this.listenersBound = false;
+        this.registryFetched = false;
+        this.registryFetching = false;
+        this.MAX_REGISTRY_FETCH_ATTEMPTS = 3;
+        this.INITIAL_RETRY_DELAY_MS = 1000; // 1 second
         // Auto-handle registry-changed invalidations from remote
         // We listen on invalidate and if reason matches, we rehydrate registry and emit a registry event
         this.ensureRemoteRunner().then(async (runner) => {
@@ -806,39 +810,178 @@ class RemoteGraphRunner extends AbstractGraphRunner {
         super.dispose();
         this.runner = undefined;
         this.transport = undefined;
+        this.registryFetched = false; // Reset so registry is fetched again on reconnect
+        this.registryFetching = false; // Reset fetching state
         this.emit("transport", {
             state: "disconnected",
             kind: this.backend.kind,
         });
     }
+    /**
+     * Fetch full registry description from remote and register it locally.
+     * Called automatically on first connection with retry mechanism.
+     */
+    async fetchRegistry(runner, attempt = 1) {
+        if (this.registryFetching) {
+            // Already fetching, don't start another fetch
+            return;
+        }
+        this.registryFetching = true;
+        try {
+            const desc = await runner.describeRegistry();
+            // Register types
+            for (const t of desc.types) {
+                if (t.options) {
+                    this.registry.registerEnum({
+                        id: t.id,
+                        options: t.options,
+                        bakeTarget: t.bakeTarget,
+                    });
+                }
+                else {
+                    if (!this.registry.types.has(t.id)) {
+                        this.registry.registerType({
+                            id: t.id,
+                            displayName: t.displayName,
+                            validate: (_v) => true,
+                            bakeTarget: t.bakeTarget,
+                        });
+                    }
+                }
+            }
+            // Register categories
+            for (const c of desc.categories || []) {
+                if (!this.registry.categories.has(c.id)) {
+                    // Create placeholder category descriptor
+                    const category = {
+                        id: c.id,
+                        displayName: c.displayName,
+                        createRuntime: () => ({
+                            async onInputsChanged() { },
+                        }),
+                        policy: { asyncConcurrency: "switch" },
+                    };
+                    this.registry.categories.register(category);
+                }
+            }
+            // Register coercions
+            for (const c of desc.coercions) {
+                if (c.async) {
+                    this.registry.registerAsyncCoercion(c.from, c.to, async (v) => v, {
+                        nonTransitive: c.nonTransitive,
+                    });
+                }
+                else {
+                    this.registry.registerCoercion(c.from, c.to, (v) => v, {
+                        nonTransitive: c.nonTransitive,
+                    });
+                }
+            }
+            // Register nodes
+            for (const n of desc.nodes) {
+                if (!this.registry.nodes.has(n.id)) {
+                    this.registry.registerNode({
+                        id: n.id,
+                        categoryId: n.categoryId,
+                        displayName: n.displayName,
+                        inputs: n.inputs || {},
+                        outputs: n.outputs || {},
+                        impl: () => { },
+                    });
+                }
+            }
+            this.registryFetched = true;
+            this.registryFetching = false;
+            this.emit("registry", this.registry);
+        }
+        catch (err) {
+            this.registryFetching = false;
+            const error = err instanceof Error ? err : new Error(String(err));
+            // Retry with exponential backoff if attempts remaining
+            if (attempt < this.MAX_REGISTRY_FETCH_ATTEMPTS) {
+                const delayMs = this.INITIAL_RETRY_DELAY_MS * Math.pow(2, attempt - 1);
+                console.warn(`Failed to fetch registry (attempt ${attempt}/${this.MAX_REGISTRY_FETCH_ATTEMPTS}), retrying in ${delayMs}ms...`, error);
+                // Emit error event for UI feedback
+                this.emit("error", {
+                    kind: "registry",
+                    message: `Registry fetch failed (attempt ${attempt}/${this.MAX_REGISTRY_FETCH_ATTEMPTS}), retrying...`,
+                    err: error,
+                    attempt,
+                    maxAttempts: this.MAX_REGISTRY_FETCH_ATTEMPTS,
+                });
+                // Retry after delay
+                setTimeout(() => {
+                    this.fetchRegistry(runner, attempt + 1).catch(() => {
+                        // Final failure handled below
+                    });
+                }, delayMs);
+            }
+            else {
+                // Max attempts reached, emit final error
+                console.error(`Failed to fetch registry after ${this.MAX_REGISTRY_FETCH_ATTEMPTS} attempts:`, error);
+                this.emit("error", {
+                    kind: "registry",
+                    message: `Failed to fetch registry after ${this.MAX_REGISTRY_FETCH_ATTEMPTS} attempts. Please check your connection and try refreshing.`,
+                    err: error,
+                    attempt: this.MAX_REGISTRY_FETCH_ATTEMPTS,
+                    maxAttempts: this.MAX_REGISTRY_FETCH_ATTEMPTS,
+                });
+            }
+        }
+    }
     // Ensure remote transport/runner
     async ensureRemoteRunner() {
         if (this.runner)
             return this.runner;
         let transport;
         const kind = this.backend.kind;
+        const backend = this.backend;
+        const connectOptions = backend.connectOptions;
         this.emit("transport", { state: "connecting", kind });
-        if (this.backend.kind === "remote-http") {
+        if (backend.kind === "remote-http") {
             if (!sparkRemote.HttpPollingTransport)
                 throw new Error("HttpPollingTransport not available");
-            transport = new sparkRemote.HttpPollingTransport(this.backend.baseUrl);
-            await transport.connect();
+            transport = new sparkRemote.HttpPollingTransport(backend.baseUrl);
+            await transport.connect(connectOptions);
         }
-        else if (this.backend.kind === "remote-ws") {
+        else if (backend.kind === "remote-ws") {
             if (!sparkRemote.WebSocketTransport)
                 throw new Error("WebSocketTransport not available");
-            transport = new sparkRemote.WebSocketTransport(this.backend.url);
-            await transport.connect();
+            transport = new sparkRemote.WebSocketTransport(backend.url);
+            await transport.connect(connectOptions);
         }
         else {
             throw new Error("Remote backend not configured");
         }
+        // Subscribe to custom events if handler provided
+        if (backend.onCustomEvent) {
+            transport.subscribe((event) => {
+                // Filter out standard runtime events, pass others to custom handler
+                const msg = event.message;
+                if (msg && typeof msg === "object" && "type" in msg) {
+                    const type = msg.type;
+                    // Standard runtime events: stats, value, error, invalidate
+                    // Custom events are anything else (e.g., flow-opened, flow-latest)
+                    if (!["stats", "value", "error", "invalidate"].includes(type)) {
+                        backend.onCustomEvent?.(event);
+                    }
+                }
+            });
+        }
         const runner = new sparkRemote.RemoteRunner(transport);
         this.runner = runner;
         this.transport = transport;
         this.valueCache.clear();
         this.listenersBound = false;
         this.emit("transport", { state: "connected", kind });
+        // Auto-fetch registry on first connection (only once)
+        if (!this.registryFetched && !this.registryFetching) {
+            // Log loading state (UI can listen to transport status for loading indication)
+            console.info("Loading registry from remote...");
+            this.fetchRegistry(runner).catch(() => {
+                // Error handling is done inside fetchRegistry
+            });
+        }
         return runner;
     }
 }
@@ -2955,7 +3098,7 @@ const WorkbenchCanvas = React.forwardRef(({ showValues, toString, toElement, get
                 }, onConnect: onConnect, onEdgesChange: onEdgesChange, onEdgesDelete: onEdgesDelete, onNodesDelete: onNodesDelete, onNodesChange: onNodesChange, deleteKeyCode: ["Backspace", "Delete"], proOptions: { hideAttribution: true }, noDragClassName: "wb-nodrag", noWheelClassName: "wb-nowheel", noPanClassName: "wb-nopan", fitView: true, children: [jsxRuntime.jsx(react.Background, { id: "workbench-canvas-background", variant: react.BackgroundVariant.Dots, gap: 12, size: 1 }), jsxRuntime.jsx(react.MiniMap, {}), jsxRuntime.jsx(react.Controls, {}), jsxRuntime.jsx(DefaultContextMenu, { open: menuOpen, clientPos: menuPos, onAdd: addNodeAt, onClose: onCloseMenu }), !!nodeAtMenu && (jsxRuntime.jsx(NodeContextMenu, { open: nodeMenuOpen, clientPos: nodeMenuPos, nodeId: nodeAtMenu, onClose: onCloseNodeMenu }))] }) }) }));
 });
 
-function WorkbenchStudioCanvas({ setRegistry, autoScroll, onAutoScrollChange, example, onExampleChange, engine, onEngineChange, backendKind, onBackendKindChange, httpBaseUrl, onHttpBaseUrlChange, wsUrl, onWsUrlChange, debug, onDebugChange, showValues, onShowValuesChange, hideWorkbench, onHideWorkbenchChange, overrides, onInit, onChange, }) {
+function WorkbenchStudioCanvas({ setRegistry, autoScroll, onAutoScrollChange, example, onExampleChange, engine, onEngineChange, backendKind, onBackendKindChange, httpBaseUrl, onHttpBaseUrlChange, wsUrl, onWsUrlChange, debug, onDebugChange, showValues, onShowValuesChange, hideWorkbench, onHideWorkbenchChange, backendOptions, overrides, onInit, onChange, }) {
     const { wb, runner, registry, def, selectedNodeId, runAutoLayout } = useWorkbenchContext();
     const [transportStatus, setTransportStatus] = React.useState({
         state: "local",
@@ -3004,11 +3147,14 @@ function WorkbenchStudioCanvas({ setRegistry, autoScroll, onAutoScrollChange, ex
             return overrides.getExamples(defaultExamples);
         return defaultExamples;
     }, [overrides, defaultExamples]);
-    const [hydrated, setHydrated] = React.useState(false);
     const lastAutoLaunched = React.useRef(undefined);
     const autoLayoutRan = React.useRef(false);
     const canvasRef = React.useRef(null);
     const uploadInputRef = React.useRef(null);
+    const [registryReady, setRegistryReady] = React.useState(() => {
+        // For local backends, registry is always ready
+        return backendKind === "local";
+    });
     // Expose init callback with setInitialGraph helper
     const initCalled = React.useRef(false);
     React.useEffect(() => {
@@ -3067,7 +3213,7 @@ function WorkbenchStudioCanvas({ setRegistry, autoScroll, onAutoScrollChange, ex
         const { registry: r, def } = await ex.load();
         // Keep registry consistent with backend:
         // - For local backend, allow example to provide its own registry
-        // - For remote backend, NEVER overwrite the hydrated remote registry
+        // - For remote backend, registry is automatically managed by RemoteGraphRunner
         if (backendKind === "local") {
             if (r) {
                 setRegistry(r);
@@ -3180,79 +3326,8 @@ function WorkbenchStudioCanvas({ setRegistry, autoScroll, onAutoScrollChange, ex
     const triggerUpload = React.useCallback(() => {
         uploadInputRef.current?.click();
     }, []);
-    const hydrateFromBackend = React.useCallback(async (kind, base) => {
-        try {
-            const transport = kind === "remote-http"
-                ? new sparkRemote.HttpPollingTransport(base)
-                : new sparkRemote.WebSocketTransport(base);
-            await transport.connect();
-            const rr = new sparkRemote.RemoteRunner(transport);
-            const desc = await rr.describeRegistry();
-            const r = new sparkGraph.Registry();
-            // Types
-            for (const t of desc.types) {
-                if (t.options) {
-                    r.registerEnum({
-                        id: t.id,
-                        options: t.options,
-                        bakeTarget: t.bakeTarget,
-                    });
-                }
-                else {
-                    r.registerType({
-                        id: t.id,
-                        displayName: t.displayName,
-                        validate: (_v) => true,
-                        bakeTarget: t.bakeTarget,
-                    });
-                }
-            }
-            // Categories: create placeholders for display name
-            for (const c of desc.categories || []) {
-                // If you later expose real category descriptors, register them here
-                // For now, rely on ComputeCategory for behavior
-                const category = {
-                    id: c.id,
-                    displayName: c.displayName,
-                    createRuntime: () => ({
-                        async onInputsChanged() { },
-                    }),
-                    policy: { asyncConcurrency: "switch" },
-                };
-                r.categories.register(category);
-            }
-            // Coercions (client-side no-op to satisfy validation) if provided
-            for (const c of desc.coercions) {
-                if (c.async) {
-                    r.registerAsyncCoercion(c.from, c.to, async (v) => v, {
-                        nonTransitive: c.nonTransitive,
-                    });
-                }
-                else {
-                    r.registerCoercion(c.from, c.to, (v) => v, {
-                        nonTransitive: c.nonTransitive,
-                    });
-                }
-            }
-            // Nodes (use no-op impl for compute)
-            for (const n of desc.nodes) {
-                r.registerNode({
-                    id: n.id,
-                    categoryId: n.categoryId,
-                    displayName: n.displayName,
-                    inputs: n.inputs || {},
-                    outputs: n.outputs || {},
-                    impl: () => { },
-                });
-            }
-            setRegistry(r);
-            wb.setRegistry(r);
-            await transport.close();
-        }
-        catch (err) {
-            console.error("Failed to hydrate registry from backend:", err);
-        }
-    }, [setRegistry, wb]);
+    // Registry is now automatically fetched by RemoteGraphRunner on first connection
+    // No need for manual hydration
     // Ensure initial example is loaded (and sync when example prop changes)
     React.useEffect(() => {
         if (!example)
@@ -3263,6 +3338,21 @@ function WorkbenchStudioCanvas({ setRegistry, autoScroll, onAutoScrollChange, ex
         const off = runner.on("transport", (s) => setTransportStatus(s));
         return () => off();
     }, [runner]);
+    // Track registry readiness for remote backends
+    React.useEffect(() => {
+        // For local backends, registry is always ready
+        if (backendKind === "local") {
+            setRegistryReady(true);
+            return;
+        }
+        // Reset readiness when switching to remote backend
+        setRegistryReady(false);
+        // For remote backends, wait for registry event
+        const off = runner.on("registry", () => {
+            setRegistryReady(true);
+        });
+        return () => off();
+    }, [runner, backendKind]);
     React.useEffect(() => {
         if (!engine)
             return;
@@ -3284,25 +3374,13 @@ function WorkbenchStudioCanvas({ setRegistry, autoScroll, onAutoScrollChange, ex
             // ignore
         }
     }, [engine, runner, wb, backendKind]);
-    // When switching to remote backend, auto-hydrate registry from backend
-    React.useEffect(() => {
-        let hydrate;
-        if (backendKind === "remote-http" && httpBaseUrl) {
-            hydrate = hydrateFromBackend("remote-http", httpBaseUrl);
-        }
-        else if (backendKind === "remote-ws" && wsUrl) {
-            hydrate = hydrateFromBackend("remote-ws", wsUrl);
-        }
-        if (hydrate) {
-            hydrate.then(() => {
-                setHydrated(true);
-            });
-        }
-    }, [backendKind, httpBaseUrl, wsUrl, hydrateFromBackend, setHydrated]);
+    // Registry is automatically fetched by RemoteGraphRunner when it connects
+    // Run auto layout after registry is hydrated (for remote backends)
     React.useEffect(() => {
         if (autoLayoutRan.current)
             return;
-        if (backendKind !== "local" && !hydrated)
+        // Wait for registry to be ready for remote backends
+        if (backendKind !== "local" && !registryReady)
             return;
         const cur = wb.export();
         const positions = wb.getPositions();
@@ -3311,7 +3389,7 @@ function WorkbenchStudioCanvas({ setRegistry, autoScroll, onAutoScrollChange, ex
             autoLayoutRan.current = true;
             runAutoLayout();
         }
-    }, [wb, runAutoLayout, backendKind, hydrated]);
+    }, [wb, runAutoLayout, backendKind, registryReady, registry]);
     const baseSetInput = React.useCallback((handle, raw) => {
         if (!selectedNodeId)
             return;
@@ -3421,7 +3499,9 @@ function WorkbenchStudioCanvas({ setRegistry, autoScroll, onAutoScrollChange, ex
             value !== null &&
             "url" in value &&
             typeof value.url === "string") {
-            const title = ("title" in value && typeof value.title === "string") ? value.title : "";
+            const title = "title" in value && typeof value.title === "string"
+                ? value.title
+                : "";
             const url = String(value.url || "");
             // value.ts handles data URL formatting
             return title || url.slice(0, 32) + (url.length > 32 ? "…" : "");
@@ -3434,7 +3514,11 @@ function WorkbenchStudioCanvas({ setRegistry, autoScroll, onAutoScrollChange, ex
         const round4 = (n) => Math.round(Number(n) * 10000) / 10000;
         if (typeId === "base.vec3" && Array.isArray(value)) {
             const a = value;
-            return [round4(Number(a[0] ?? 0)), round4(Number(a[1] ?? 0)), round4(Number(a[2] ?? 0))].join(",");
+            return [
+                round4(Number(a[0] ?? 0)),
+                round4(Number(a[1] ?? 0)),
+                round4(Number(a[2] ?? 0)),
+            ].join(",");
         }
         const stringifyRounded = (v) => {
             try {
@@ -3519,21 +3603,38 @@ function WorkbenchStudioCanvas({ setRegistry, autoScroll, onAutoScrollChange, ex
                             }
                         }, children: "Download Snapshot" }), jsxRuntime.jsx("input", { ref: uploadInputRef, type: "file", accept: "application/json,.json", className: "hidden", onChange: onUploadPicked }), jsxRuntime.jsx("button", { className: "ml-2 border border-gray-300 rounded px-2 py-1.5", onClick: triggerUpload, children: "Upload Graph/Snapshot" }), jsxRuntime.jsxs("label", { className: "ml-2 flex items-center gap-1", children: [jsxRuntime.jsx("input", { type: "checkbox", checked: debug, onChange: (e) => onDebugChange(e.target.checked) }), jsxRuntime.jsx("span", { children: "Debug events" })] }), jsxRuntime.jsxs("label", { className: "ml-2 flex items-center gap-1", children: [jsxRuntime.jsx("input", { type: "checkbox", checked: showValues, onChange: (e) => onShowValuesChange(e.target.checked) }), jsxRuntime.jsx("span", { children: "Show values in nodes" })] })] }), jsxRuntime.jsxs("div", { className: "flex flex-1 min-h-0", children: [jsxRuntime.jsx("div", { className: "flex-1 min-w-0", children: jsxRuntime.jsx(WorkbenchCanvas, { ref: canvasRef, showValues: showValues, toString: toString, toElement: toElement, getDefaultNodeSize: overrides?.getDefaultNodeSize }) }), jsxRuntime.jsx(Inspector, { setInput: setInput, debug: debug, autoScroll: autoScroll, hideWorkbench: hideWorkbench, onAutoScrollChange: onAutoScrollChange, onHideWorkbenchChange: onHideWorkbenchChange, toString: toString, toElement: toElement, contextPanel: overrides?.contextPanel })] })] }));
 }
-function WorkbenchStudio({ engine, onEngineChange, example, onExampleChange, backendKind, onBackendKindChange, httpBaseUrl, onHttpBaseUrlChange, wsUrl, onWsUrlChange, debug, onDebugChange, showValues, onShowValuesChange, hideWorkbench, onHideWorkbenchChange, autoScroll, onAutoScrollChange, overrides, onInit, onChange, }) {
+function WorkbenchStudio({ engine, onEngineChange, example, onExampleChange, backendKind, onBackendKindChange, httpBaseUrl, onHttpBaseUrlChange, wsUrl, onWsUrlChange, debug, onDebugChange, showValues, onShowValuesChange, hideWorkbench, onHideWorkbenchChange, autoScroll, onAutoScrollChange, backendOptions, overrides, onInit, onChange, }) {
     const [registry, setRegistry] = React.useState(sparkGraph.createSimpleGraphRegistry());
     const [wb] = React.useState(() => new InMemoryWorkbench({ ui: new DefaultUIExtensionRegistry() }));
     const runner = React.useMemo(() => {
         if (backendKind === "remote-http") {
-            return new RemoteGraphRunner(registry, {
+            const backend = {
                 kind: "remote-http",
                 baseUrl: httpBaseUrl,
-            });
+                ...(backendOptions?.connectOptions && {
+                    connectOptions: backendOptions.connectOptions,
+                }),
+                ...(backendOptions?.onCustomEvent && {
+                    onCustomEvent: backendOptions.onCustomEvent,
+                }),
+            };
+            return new RemoteGraphRunner(registry, backend);
         }
         if (backendKind === "remote-ws") {
-            return new RemoteGraphRunner(registry, { kind: "remote-ws", url: wsUrl });
+            const backend = {
+                kind: "remote-ws",
+                url: wsUrl,
+                ...(backendOptions?.connectOptions && {
+                    connectOptions: backendOptions.connectOptions,
+                }),
+                ...(backendOptions?.onCustomEvent && {
+                    onCustomEvent: backendOptions.onCustomEvent,
+                }),
+            };
+            return new RemoteGraphRunner(registry, backend);
         }
         return new LocalGraphRunner(registry);
-    }, [registry, backendKind, httpBaseUrl, wsUrl]);
+    }, [registry, backendKind, httpBaseUrl, wsUrl, backendOptions]);
     // Allow external UI registration (e.g., node renderers) with access to wb
     React.useEffect(() => {
         const baseRegisterUI = (_wb) => { };
@@ -3544,7 +3645,7 @@ function WorkbenchStudio({ engine, onEngineChange, example, onExampleChange, bac
                 if (runner.isRunning())
                     runner.dispose();
                 onBackendKindChange(v);
-            }, httpBaseUrl: httpBaseUrl, onHttpBaseUrlChange: onHttpBaseUrlChange, wsUrl: wsUrl, onWsUrlChange: onWsUrlChange, debug: debug, onDebugChange: onDebugChange, showValues: showValues, onShowValuesChange: onShowValuesChange, hideWorkbench: hideWorkbench, onHideWorkbenchChange: onHideWorkbenchChange, overrides: overrides, onInit: onInit, onChange: onChange }) }));
+            }, httpBaseUrl: httpBaseUrl, onHttpBaseUrlChange: onHttpBaseUrlChange, wsUrl: wsUrl, onWsUrlChange: onWsUrlChange, debug: debug, onDebugChange: onDebugChange, showValues: showValues, onShowValuesChange: onShowValuesChange, hideWorkbench: hideWorkbench, onHideWorkbenchChange: onHideWorkbenchChange, backendOptions: backendOptions, overrides: overrides, onInit: onInit, onChange: onChange }) }));
 }
 
 exports.AbstractWorkbench = AbstractWorkbench;