html-overlay-node 0.1.9 → 0.1.11

package/src/core/Runner.js

@@ -7,14 +7,16 @@ export class Runner {
     this._raf = null;
     this._last = 0;
     this.cyclesPerFrame = Math.max(1, cyclesPerFrame | 0);
+    this.executionMode = "run"; // "run" or "step"
+    this.activePlan = null;
+    this.activeStepIndex = -1;
+    this.stepCache = new Map();
   }
 
-  // 외부에서 실행 중인지 확인
   isRunning() {
     return this.running;
   }
 
-  // 실행 도중에도 CPS 변경 가능
   setCyclesPerFrame(n) {
     this.cyclesPerFrame = Math.max(1, n | 0);
   }
@@ -47,71 +49,72 @@ export class Runner {
           }
         }
       }
-      // commit writes for this cycle
       this.graph.swapBuffers();
     }
   }
 
   /**
-   * Execute connected nodes once from a starting node
-   * Uses queue-based traversal to support branching exec flows
-   * @param {string} startNodeId - ID of the node to start from
-   * @param {number} dt - Delta time
+   * Execute connected nodes once from a starting node.
+   * Returns execEdgeOrder: exec edges in the order they were traversed.
    */
   runOnce(startNodeId, dt = 0) {
-    console.log("[Runner.runOnce] Starting exec flow from node:", startNodeId);
-
     const executedNodes = [];
     const allConnectedNodes = new Set();
-    const queue = [startNodeId];
-    const visited = new Set(); // Prevent infinite loops
+    const execEdgeOrder = []; // exec edge IDs in traversal order
+
+    // Local output cache: nodeId:portId → value
+    // Ensures outputs written by executeNode are immediately readable by subsequent nodes
+    const runCache = new Map();
+
+    // Queue items: { nodeId, fromEdgeId }
+    const queue = [{ nodeId: startNodeId, fromEdgeId: null }];
+    const visited = new Set();
 
-    // Queue-based traversal for branching execution
     while (queue.length > 0) {
-      const currentNodeId = queue.shift();
+      const { nodeId: currentNodeId, fromEdgeId } = queue.shift();
 
-      // Skip if already executed (prevents cycles)
       if (visited.has(currentNodeId)) continue;
       visited.add(currentNodeId);
 
+      // Record the exec edge that led to this node
+      if (fromEdgeId) execEdgeOrder.push(fromEdgeId);
+
       const node = this.graph.nodes.get(currentNodeId);
-      if (!node) {
-        console.warn(`[Runner.runOnce] Node not found: ${currentNodeId}`);
-        continue;
-      }
+      if (!node) continue;
 
       executedNodes.push(currentNodeId);
       allConnectedNodes.add(currentNodeId);
-      console.log(`[Runner.runOnce] Executing: ${node.title} (${node.type})`);
 
-      // Find and add data dependency nodes (nodes providing input data)
+      // Execute data dependency nodes first
       for (const input of node.inputs) {
         if (input.portType === "data") {
-          // Find edge feeding this data input
           for (const edge of this.graph.edges.values()) {
             if (edge.toNode === currentNodeId && edge.toPort === input.id) {
               const sourceNode = this.graph.nodes.get(edge.fromNode);
               if (sourceNode && !allConnectedNodes.has(edge.fromNode)) {
                 allConnectedNodes.add(edge.fromNode);
-                // Execute data source node before current node
-                this.executeNode(edge.fromNode, dt);
+                this._executeNodeWithCache(edge.fromNode, dt, runCache);
               }
             }
           }
         }
       }
 
-      // Execute current node
-      this.executeNode(currentNodeId, dt);
+      // Execute this node
+      this._executeNodeWithCache(currentNodeId, dt, runCache);
 
-      // Find all next nodes via exec outputs and add to queue
-      const nextNodes = this.findAllNextExecNodes(currentNodeId);
-      queue.push(...nextNodes);
+      // Find exec output edges and enqueue next nodes
+      const execOutputPorts = node.outputs.filter((p) => p.portType === "exec");
+      for (const execOutput of execOutputPorts) {
+        for (const edge of this.graph.edges.values()) {
+          if (edge.fromNode === currentNodeId && edge.fromPort === execOutput.id) {
+            queue.push({ nodeId: edge.toNode, fromEdgeId: edge.id });
+          }
+        }
+      }
     }
 
-    console.log("[Runner.runOnce] Executed nodes:", executedNodes.length);
-
-    // Find all edges involved (both exec and data)
+    // Collect all edges involved (both exec and data)
     const connectedEdges = new Set();
     for (const edge of this.graph.edges.values()) {
       if (allConnectedNodes.has(edge.fromNode) && allConnectedNodes.has(edge.toNode)) {
@@ -119,27 +122,163 @@ export class Runner {
       }
     }
 
-    console.log("[Runner.runOnce] Connected edges count:", connectedEdges.size);
-    return { connectedNodes: allConnectedNodes, connectedEdges };
+    return { connectedNodes: allConnectedNodes, connectedEdges, execEdgeOrder };
+  }
+
+  setExecutionMode(mode) {
+    this.executionMode = mode;
+    if (mode === "run") this.resetStepping();
+  }
+
+  resetStepping() {
+    this.activePlan = null;
+    this.activeStepIndex = -1;
+    this.stepCache.clear();
+    this.hooks?.emit?.("runner:step-updated", { activeNodeId: null });
+  }
+
+  buildPlan(startNodeId) {
+    const plan = [];
+    const allConnectedNodes = new Set();
+    const queue = [{ nodeId: startNodeId, fromEdgeId: null }];
+    const visited = new Set();
+
+    while (queue.length > 0) {
+      const { nodeId: currentNodeId, fromEdgeId } = queue.shift();
+      if (visited.has(currentNodeId)) continue;
+      visited.add(currentNodeId);
+      allConnectedNodes.add(currentNodeId);
+
+      const node = this.graph.nodes.get(currentNodeId);
+      if (!node) continue;
+
+      // Collect data dependency nodes (in order) for this exec node
+      const dataDeps = [];
+      for (const input of node.inputs) {
+        if (input.portType === "data") {
+          for (const edge of this.graph.edges.values()) {
+            if (edge.toNode === currentNodeId && edge.toPort === input.id) {
+              const srcId = edge.fromNode;
+              if (!allConnectedNodes.has(srcId)) {
+                allConnectedNodes.add(srcId);
+                dataDeps.push(srcId);
+              }
+            }
+          }
+        }
+      }
+
+      // Find ALL incoming edges (both exec and data) to highlight them in Step Mode
+      const incomingEdges = [];
+      for (const edge of this.graph.edges.values()) {
+        if (edge.toNode === currentNodeId) {
+          incomingEdges.push(edge.id);
+        }
+      }
+
+      plan.push({ nodeId: currentNodeId, fromEdgeId, incomingEdges, dataDeps });
+
+      // Enqueue next exec nodes
+      const execOutputs = node.outputs.filter((p) => p.portType === "exec");
+      for (const execOutput of execOutputs) {
+        for (const edge of this.graph.edges.values()) {
+          if (edge.fromNode === currentNodeId && edge.fromPort === execOutput.id) {
+            queue.push({ nodeId: edge.toNode, fromEdgeId: edge.id });
+          }
+        }
+      }
+    }
+
+    return plan;
+  }
+
+  startStepping(startNodeId) {
+    this.stepCache.clear();
+    this.activePlan = this.buildPlan(startNodeId);
+    this.activeStepIndex = 0;
+    const step = this.activePlan[0];
+    this.hooks?.emit?.("runner:step-updated", {
+      activeNodeId: step?.nodeId,
+      activeEdgeIds: step?.incomingEdges || [],
+    });
+    this.start(); // Start the loop to driving animations
+  }
+
+  executeNextStep() {
+    if (!this.activePlan || this.activeStepIndex < 0 || this.activeStepIndex >= this.activePlan.length) {
+      this.resetStepping();
+      return null;
+    }
+
+    const step = this.activePlan[this.activeStepIndex];
+
+    // Execute data deps
+    for (const depId of step.dataDeps) {
+      this._executeNodeWithCache(depId, 0, this.stepCache);
+    }
+
+    // Execute main node
+    this._executeNodeWithCache(step.nodeId, 0, this.stepCache);
+
+    this.activeStepIndex++;
+
+    if (this.activeStepIndex < this.activePlan.length) {
+      const nextStep = this.activePlan[this.activeStepIndex];
+      this.hooks?.emit?.("runner:step-updated", {
+        activeNodeId: nextStep.nodeId,
+        activeEdgeIds: nextStep.incomingEdges || [],
+      });
+    } else {
+      this.hooks?.emit?.("runner:step-updated", { activeNodeId: null });
+      this.resetStepping();
+    }
+
+    return step.nodeId;
+  }
+
+  /** Execute a node using a shared run-local output cache for reliable data passing. */
+  _executeNodeWithCache(nodeId, dt, runCache) {
+    const node = this.graph.nodes.get(nodeId);
+    if (!node) return;
+    const def = this.registry.types.get(node.type);
+    if (!def?.onExecute) return;
+
+    try {
+      def.onExecute(node, {
+        dt,
+        graph: this.graph,
+        getInput: (portName) => {
+          const p = node.inputs.find((i) => i.name === portName) || node.inputs[0];
+          if (!p) return undefined;
+          for (const edge of this.graph.edges.values()) {
+            if (edge.toNode === nodeId && edge.toPort === p.id) {
+              const key = `${edge.fromNode}:${edge.fromPort}`;
+              // Check run-local cache first, then fall back to graph buffer
+              return runCache.has(key) ? runCache.get(key) : this.graph._curBuf().get(key);
+            }
+          }
+          return undefined;
+        },
+        setOutput: (portName, value) => {
+          const p = node.outputs.find((o) => o.name === portName) || node.outputs[0];
+          if (p) {
+            runCache.set(`${node.id}:${p.id}`, value);
+          }
+        },
+      });
+    } catch (err) {
+      this.hooks?.emit?.("error", err);
+    }
   }
 
-  /**
-   * Find all nodes connected via exec outputs
-   * Supports multiple connections from a single exec output
-   * @param {string} nodeId - Current node ID
-   * @returns {string[]} Array of next node IDs
-   */
   findAllNextExecNodes(nodeId) {
     const node = this.graph.nodes.get(nodeId);
     if (!node) return [];
 
-    // Find all exec output ports
-    const execOutputs = node.outputs.filter(p => p.portType === "exec");
+    const execOutputs = node.outputs.filter((p) => p.portType === "exec");
     if (execOutputs.length === 0) return [];
 
     const nextNodes = [];
-
-    // Find all edges from exec outputs
     for (const execOutput of execOutputs) {
       for (const edge of this.graph.edges.values()) {
         if (edge.fromNode === nodeId && edge.fromPort === execOutput.id) {
@@ -147,15 +286,9 @@ export class Runner {
         }
       }
     }
-
     return nextNodes;
   }
 
-  /**
-   * Execute a single node
-   * @param {string} nodeId - Node ID to execute
-   * @param {number} dt - Delta time
-   */
   executeNode(nodeId, dt) {
     const node = this.graph.nodes.get(nodeId);
     if (!node) return;
@@ -174,7 +307,6 @@ export class Runner {
         setOutput: (portName, value) => {
           const p = node.outputs.find((o) => o.name === portName) || node.outputs[0];
           if (p) {
-            // Write directly to current buffer so other nodes can read it immediately
             const key = `${node.id}:${p.id}`;
             this.graph._curBuf().set(key, value);
           }
@@ -195,12 +327,14 @@ export class Runner {
       if (!this.running) return;
       const dtMs = this._last ? t - this._last : 0;
       this._last = t;
-      const dt = dtMs / 1000; // seconds
+      const dt = dtMs / 1000;
 
-      // 1) 스텝 실행
-      this.step(this.cyclesPerFrame, dt);
+      // Only execute nodes automatically in "run" mode.
+      // In "step" mode, we only want the loop to fire for animations (via tick event).
+      if (this.executionMode === "run") {
+        this.step(this.cyclesPerFrame, dt);
+      }
 
-      // 2) 프레임 훅 (렌더러/컨트롤러는 여기서 running, time, dt를 받아 표현 업데이트)
       this.hooks?.emit?.("runner:tick", {
         time: t,
         dt,

package/src/index.js

@@ -10,6 +10,7 @@ import { HtmlOverlay } from "./render/HtmlOverlay.js";
 import { RemoveNodeCmd, ChangeGroupColorCmd } from "./core/commands.js";
 import { Minimap } from "./minimap/Minimap.js";
 import { PropertyPanel } from "./ui/PropertyPanel.js";
+import { HelpOverlay } from "./ui/HelpOverlay.js";
 import { setupDefaultContextMenu as defaultContextMenuSetup } from "./defaults/contextMenu.js";
 
 
@@ -23,6 +24,8 @@ export function createGraphEditor(
     showMinimap = true,
     enablePropertyPanel = true,
     propertyPanelContainer = null,
+    enableHelp = true,
+    helpShortcuts = null,
     setupDefaultContextMenu = true,
     setupContextMenu = null,
     plugins = [],
@@ -171,6 +174,14 @@ export function createGraphEditor(
     });
   }
 
+  // Initialize Help Overlay if enabled
+  let helpOverlay = null;
+  if (enableHelp) {
+    helpOverlay = new HelpOverlay(container, {
+      shortcuts: helpShortcuts,
+    });
+  }
+
   const runner = new Runner({ graph, registry, hooks });
 
   // Attach runner and controller to graph for node access
@@ -179,42 +190,24 @@ export function createGraphEditor(
   graph.controller = controller;
 
   hooks.on("runner:tick", ({ time, dt }) => {
-    renderer.draw(graph, {
-      selection: controller.selection,
-      tempEdge: controller.connecting ? controller.renderTempEdge() : null, // 필요시 helper
-      running: true,
-      time,
-      dt,
-    });
-    htmlOverlay.draw(graph, controller.selection);
+    controller.render(time);
   });
   hooks.on("runner:start", () => {
-    // 첫 프레임 즉시 렌더
-    renderer.draw(graph, {
-      selection: controller.selection,
-      tempEdge: controller.connecting ? controller.renderTempEdge() : null,
-      running: true,
-      time: performance.now(),
-      dt: 0,
-    });
-    htmlOverlay.draw(graph, controller.selection);
+    controller.render(performance.now());
   });
   hooks.on("runner:stop", () => {
-    // 정지 프레임
-    renderer.draw(graph, {
-      selection: controller.selection,
-      tempEdge: controller.connecting ? controller.renderTempEdge() : null,
-      running: false,
-      time: performance.now(),
-      dt: 0,
-    });
-    htmlOverlay.draw(graph, controller.selection);
+    controller.render(performance.now());
   });
 
   hooks.on("node:updated", () => {
     controller.render();
   });
 
+  hooks.on("graph:deserialize", () => {
+    renderer.setTransform({ scale: 1, offsetX: 0, offsetY: 0 });
+    controller.render();
+  });
+
   // Note: Example nodes have been moved to src/nodes/
   // Users can import and register them selectively:
   // import { registerAllNodes } from "html-overlay-node/nodes";
@@ -278,6 +271,7 @@ export function createGraphEditor(
     },
     graph,
     renderer,
+    edgeRenderer, // Expose edge renderer for style changes
     controller, // Expose controller for snap-to-grid access
     runner, // Expose runner for trigger
     minimap, // Expose minimap
@@ -289,6 +283,14 @@ export function createGraphEditor(
     render: () => controller.render(),
     start: () => runner.start(),
     stop: () => runner.stop(),
+    setEdgeStyle: (style) => {
+      renderer.setEdgeStyle(style);
+      edgeRenderer.setEdgeStyle(style);
+    },
+    setExecutionMode: (mode) => {
+      runner.setExecutionMode(mode);
+      controller.render(); // Redraw to update overlays
+    },
     destroy: () => {
       runner.stop();
       ro.disconnect();
@@ -297,6 +299,7 @@ export function createGraphEditor(
       contextMenu.destroy();
       if (propertyPanel) propertyPanel.destroy();
       if (minimap) minimap.destroy();
+      if (helpOverlay) helpOverlay.destroy();
     },
   };
 

package/src/interact/Controller.js

@@ -25,6 +25,11 @@ export class Controller {
     this.gResizing = null;
     this.boxSelecting = null; // { startX, startY, currentX, currentY } - world coords
 
+    // Edge / node animation state
+    this.activeEdges = new Set();
+    this.activeEdgeTimes = new Map(); // edge.id → activation timestamp
+    this.activeNodes = new Set();     // node IDs currently executing
+
     // Feature flags
     this.snapToGrid = true; // Snap nodes to grid (toggle with G key)
     this.gridSize = 20; // Grid size for snapping
@@ -40,6 +45,18 @@ export class Controller {
     this._onDblClickEvt = this._onDblClick.bind(this);
 
     this._bindEvents();
+
+    // Listen for stepping updates from runner
+    this.hooks.on("runner:step-updated", ({ activeNodeId, activeEdgeIds = [] }) => {
+      this.activeNodes = activeNodeId ? new Set([activeNodeId]) : new Set();
+      this.activeEdges = new Set(activeEdgeIds);
+      this.activeEdgeTimes.clear(); // Clear previous times to ensure fresh animation
+      const now = performance.now();
+      for (const edgeId of activeEdgeIds) {
+        this.activeEdgeTimes.set(edgeId, now);
+      }
+      this.render();
+    });
   }
 
   destroy() {
@@ -401,7 +418,11 @@ export class Controller {
       const dy = w.y - this.resizing.startY;
 
       const minW = Controller.MIN_NODE_WIDTH;
-      const minH = Controller.MIN_NODE_HEIGHT;
+      // Minimum height must fit all port rows
+      const maxPorts = Math.max(n.inputs.length, n.outputs.length);
+      const minH = maxPorts > 0
+        ? Math.max(Controller.MIN_NODE_HEIGHT, 42 + maxPorts * 20)
+        : Controller.MIN_NODE_HEIGHT;
       n.size.width = Math.max(minW, this.resizing.startW + dx);
       n.size.height = Math.max(minH, this.resizing.startH + dy);
 
@@ -755,8 +776,10 @@ export class Controller {
     this.render();
   }
 
-  render() {
+  render(time = performance.now()) {
     const tEdge = this.renderTempEdge();
+    const runner = this.graph.runner;
+    const isStepMode = !!runner && runner.executionMode === "step";
 
     // 1. Draw background (grid, canvas-only nodes) on main canvas
     this.renderer.draw(this.graph, {
@@ -764,7 +787,10 @@ export class Controller {
       tempEdge: null, // Don't draw temp edge on background
       boxSelecting: this.boxSelecting,
       activeEdges: this.activeEdges || new Set(),
+      activeEdgeTimes: this.activeEdgeTimes,
       drawEdges: !this.edgeRenderer, // Only draw edges here if no separate edge renderer
+      time,
+      loopActiveEdges: isStepMode,
     });
 
     // 2. HTML Overlay layer (HTML nodes at z-index 10)
@@ -779,10 +805,13 @@ export class Controller {
       this.edgeRenderer._applyTransform();
 
       this.edgeRenderer.drawEdgesOnly(this.graph, {
-        activeEdges: this.activeEdges || new Set(),
-        running: false,
-        time: performance.now(),
-        tempEdge: tEdge, // Draw temp edge on edge layer
+        activeEdges: this.activeEdges,
+        activeEdgeTimes: this.activeEdgeTimes,
+        activeNodes: this.activeNodes,
+        selection: this.selection,
+        time,
+        tempEdge: tEdge,
+        loopActiveEdges: isStepMode,
       });
 
       this.edgeRenderer._resetTransform();