html-overlay-node 0.1.0

package/src/core/Hooks.test.js

@@ -0,0 +1,108 @@
+import { describe, it, expect } from "vitest";
+import { createHooks } from "./Hooks.js";
+
+describe("Hooks", () => {
+  describe("createHooks", () => {
+    it("should create a hooks system with specified events", () => {
+      const hooks = createHooks(["test:event", "another:event"]);
+      expect(hooks).toBeDefined();
+      expect(typeof hooks.on).toBe("function");
+      expect(typeof hooks.off).toBe("function");
+      expect(typeof hooks.emit).toBe("function");
+    });
+  });
+
+  describe("on", () => {
+    it("should register an event listener", () => {
+      const hooks = createHooks(["test:event"]);
+      let called = false;
+      hooks.on("test:event", () => {
+        called = true;
+      });
+      hooks.emit("test:event");
+      expect(called).toBe(true);
+    });
+
+    it("should register multiple listeners for same event", () => {
+      const hooks = createHooks(["test:event"]);
+      let count = 0;
+      hooks.on("test:event", () => count++);
+      hooks.on("test:event", () => count++);
+      hooks.emit("test:event");
+      expect(count).toBe(2);
+    });
+
+    it("should pass data to listeners", () => {
+      const hooks = createHooks(["test:event"]);
+      let receivedData = null;
+      hooks.on("test:event", (data) => {
+        receivedData = data;
+      });
+      hooks.emit("test:event", { value: 42 });
+      expect(receivedData).toEqual({ value: 42 });
+    });
+  });
+
+  describe("off", () => {
+    it("should unregister a specific listener", () => {
+      const hooks = createHooks(["test:event"]);
+      let count = 0;
+      const listener = () => count++;
+
+      hooks.on("test:event", listener);
+      hooks.emit("test:event");
+      expect(count).toBe(1);
+
+      hooks.off("test:event", listener);
+      hooks.emit("test:event");
+      expect(count).toBe(1); // Still 1, not 2
+    });
+
+    it("should not affect other listeners", () => {
+      const hooks = createHooks(["test:event"]);
+      let count1 = 0;
+      let count2 = 0;
+      const listener1 = () => count1++;
+      const listener2 = () => count2++;
+
+      hooks.on("test:event", listener1);
+      hooks.on("test:event", listener2);
+
+      hooks.off("test:event", listener1);
+      hooks.emit("test:event");
+
+      expect(count1).toBe(0);
+      expect(count2).toBe(1);
+    });
+  });
+
+  describe("emit", () => {
+    it("should call all registered listeners", () => {
+      const hooks = createHooks(["test:event"]);
+      const calls = [];
+      hooks.on("test:event", () => calls.push(1));
+      hooks.on("test:event", () => calls.push(2));
+      hooks.on("test:event", () => calls.push(3));
+
+      hooks.emit("test:event");
+      expect(calls).toEqual([1, 2, 3]);
+    });
+
+    it("should not throw when emitting event with no listeners", () => {
+      const hooks = createHooks(["test:event"]);
+      expect(() => {
+        hooks.emit("test:event");
+      }).not.toThrow();
+    });
+
+    it("should pass multiple arguments to listeners", () => {
+      const hooks = createHooks(["test:event"]);
+      let receivedArgs = null;
+      hooks.on("test:event", (...args) => {
+        receivedArgs = args;
+      });
+      hooks.emit("test:event", "arg1", "arg2", 123);
+      expect(receivedArgs).toEqual(["arg1", "arg2", 123]);
+    });
+  });
+});

package/src/core/Node.js

@@ -0,0 +1,70 @@
+import { randomUUID } from "../utils/utils.js";
+
+// src/core/Node.js
+
+/**
+ * Node represents a single node in the graph
+ */
+export class Node {
+  /**
+   * Create a new Node
+   * @param {Object} options - Node configuration
+   * @param {string} [options.id] - Unique identifier (auto-generated if not provided)
+   * @param {string} options.type - Node type identifier
+   * @param {string} [options.title] - Display title (defaults to type)
+   * @param {number} [options.x=0] - X position
+   * @param {number} [options.y=0] - Y position
+   * @param {number} [options.width=160] - Node width
+   * @param {number} [options.height=60] - Node height
+   */
+  constructor({ id, type, title, x = 0, y = 0, width = 160, height = 60 }) {
+    if (!type) {
+      throw new Error("Node type is required");
+    }
+    this.id = id ?? randomUUID();
+    this.type = type;
+    this.title = title ?? type;
+    this.pos = { x, y };
+    this.size = { width, height };
+    this.inputs = []; // {id,name,datatype,portType,dir}
+    this.outputs = []; // {id,name,datatype,portType,dir}
+    this.state = {}; // User state data
+
+    // Tree Structure
+    this.parent = null; // Parent Node (or null if root)
+    this.children = new Set(); // Set<Node>
+    this.computed = { x: 0, y: 0, w: 0, h: 0 }; // World Transform
+  }
+
+  /**
+   * Add an input port to this node
+   * @param {string} name - Port name
+   * @param {string} [datatype="any"] - Data type for the port
+   * @param {string} [portType="data"] - Port type: "exec" or "data"
+   * @returns {Object} The created port
+   */
+  addInput(name, datatype = "any", portType = "data") {
+    if (!name || typeof name !== "string") {
+      throw new Error("Input port name must be a non-empty string");
+    }
+    const port = { id: randomUUID(), name, datatype, portType, dir: "in" };
+    this.inputs.push(port);
+    return port;
+  }
+
+  /**
+   * Add an output port to this node
+   * @param {string} name - Port name
+   * @param {string} [datatype="any"] - Data type for the port
+   * @param {string} [portType="data"] - Port type: "exec" or "data"
+   * @returns {Object} The created port
+   */
+  addOutput(name, datatype = "any", portType = "data") {
+    if (!name || typeof name !== "string") {
+      throw new Error("Output port name must be a non-empty string");
+    }
+    const port = { id: randomUUID(), name, datatype, portType, dir: "out" };
+    this.outputs.push(port);
+    return port;
+  }
+}

package/src/core/Node.test.js

@@ -0,0 +1,113 @@
+import { describe, it, expect, beforeEach } from "vitest";
+import { Node } from "./Node.js";
+
+describe("Node", () => {
+  describe("constructor", () => {
+    it("should create a node with default values", () => {
+      const node = new Node({ type: "test/node" });
+      expect(node.type).toBe("test/node");
+      expect(node.title).toBe("test/node");
+      expect(node.pos).toEqual({ x: 0, y: 0 });
+      expect(node.size).toEqual({ width: 160, height: 60 });
+      expect(node.inputs).toEqual([]);
+      expect(node.outputs).toEqual([]);
+      expect(node.state).toEqual({});
+      expect(node.id).toBeDefined();
+    });
+
+    it("should create a node with custom values", () => {
+      const node = new Node({
+        id: "custom-id",
+        type: "test/node",
+        title: "Custom Title",
+        x: 100,
+        y: 200,
+        width: 300,
+        height: 400,
+      });
+      expect(node.id).toBe("custom-id");
+      expect(node.type).toBe("test/node");
+      expect(node.title).toBe("Custom Title");
+      expect(node.pos).toEqual({ x: 100, y: 200 });
+      expect(node.size).toEqual({ width: 300, height: 400 });
+    });
+
+    it("should throw error when type is missing", () => {
+      expect(() => {
+        new Node({});
+      }).toThrow(/type is required/);
+    });
+
+    it("should initialize tree structure", () => {
+      const node = new Node({ type: "test/node" });
+      expect(node.parent).toBe(null);
+      expect(node.children).toBeInstanceOf(Set);
+      expect(node.children.size).toBe(0);
+      expect(node.computed).toEqual({ x: 0, y: 0, w: 0, h: 0 });
+    });
+  });
+
+  describe("addInput", () => {
+    let node;
+
+    beforeEach(() => {
+      node = new Node({ type: "test/node" });
+    });
+
+    it("should add an input port", () => {
+      const port = node.addInput("test", "number");
+      expect(port.name).toBe("test");
+      expect(port.datatype).toBe("number");
+      expect(port.dir).toBe("in");
+      expect(port.id).toBeDefined();
+      expect(node.inputs).toContain(port);
+      expect(node.inputs.length).toBe(1);
+    });
+
+    it("should default datatype to 'any'", () => {
+      const port = node.addInput("test");
+      expect(port.datatype).toBe("any");
+    });
+
+    it("should throw error when name is missing", () => {
+      expect(() => {
+        node.addInput("");
+      }).toThrow(/must be a non-empty string/);
+    });
+
+    it("should throw error when name is not a string", () => {
+      expect(() => {
+        node.addInput(null);
+      }).toThrow(/must be a non-empty string/);
+    });
+  });
+
+  describe("addOutput", () => {
+    let node;
+
+    beforeEach(() => {
+      node = new Node({ type: "test/node" });
+    });
+
+    it("should add an output port", () => {
+      const port = node.addOutput("result", "string");
+      expect(port.name).toBe("result");
+      expect(port.datatype).toBe("string");
+      expect(port.dir).toBe("out");
+      expect(port.id).toBeDefined();
+      expect(node.outputs).toContain(port);
+      expect(node.outputs.length).toBe(1);
+    });
+
+    it("should default datatype to 'any'", () => {
+      const port = node.addOutput("result");
+      expect(port.datatype).toBe("any");
+    });
+
+    it("should throw error when name is missing", () => {
+      expect(() => {
+        node.addOutput("");
+      }).toThrow(/must be a non-empty string/);
+    });
+  });
+});

package/src/core/Registry.js

@@ -0,0 +1,71 @@
+// src/core/Registry.js
+
+/**
+ * Registry for managing node type definitions
+ */
+export class Registry {
+  constructor() {
+    this.types = new Map();
+  }
+
+  /**
+   * Register a new node type
+   * @param {string} type - Unique type identifier (e.g., "core/Note")
+   * @param {Object} def - Node definition
+   * @param {string} [def.title] - Display title
+   * @param {Object} [def.size] - Default size {w, h}
+   * @param {Array} [def.inputs] - Input port definitions
+   * @param {Array} [def.outputs] - Output port definitions
+   * @param {Function} [def.onCreate] - Called when node is created
+   * @param {Function} [def.onExecute] - Called each execution cycle
+   * @param {Function} [def.onDraw] - Custom drawing function
+   * @param {Object} [def.html] - HTML overlay configuration
+   * @throws {Error} If type is already registered or invalid
+   */
+  register(type, def) {
+    if (!type || typeof type !== 'string') {
+      throw new Error(`Invalid node type: type must be a non-empty string, got ${typeof type}`);
+    }
+    if (!def || typeof def !== 'object') {
+      throw new Error(`Invalid definition for type "${type}": definition must be an object`);
+    }
+    if (this.types.has(type)) {
+      throw new Error(`Node type "${type}" is already registered. Use unregister() first to replace it.`);
+    }
+    this.types.set(type, def);
+  }
+
+  /**
+   * Unregister a node type
+   * @param {string} type - Type identifier to unregister
+   * @throws {Error} If type doesn't exist
+   */
+  unregister(type) {
+    if (!this.types.has(type)) {
+      throw new Error(`Cannot unregister type "${type}": type is not registered`);
+    }
+    this.types.delete(type);
+  }
+
+  /**
+   * Remove all registered node types
+   */
+  removeAll() {
+    this.types.clear();
+  }
+
+  /**
+   * Get the definition for a registered node type
+   * @param {string} type - Type identifier
+   * @returns {Object} Node definition
+   * @throws {Error} If type is not registered
+   */
+  createInstance(type) {
+    const def = this.types.get(type);
+    if (!def) {
+      const available = Array.from(this.types.keys()).join(', ') || 'none';
+      throw new Error(`Unknown node type: "${type}". Available types: ${available}`);
+    }
+    return def;
+  }
+}

package/src/core/Registry.test.js

@@ -0,0 +1,88 @@
+import { describe, it, expect, beforeEach } from "vitest";
+import { Registry } from "./Registry.js";
+
+describe("Registry", () => {
+  let registry;
+
+  beforeEach(() => {
+    registry = new Registry();
+  });
+
+  describe("register", () => {
+    it("should register a new node type", () => {
+      const def = { title: "Test Node", size: { w: 100, h: 50 } };
+      registry.register("test/node", def);
+      expect(registry.types.has("test/node")).toBe(true);
+      expect(registry.types.get("test/node")).toBe(def);
+    });
+
+    it("should throw error when registering duplicate type", () => {
+      const def = { title: "Test" };
+      registry.register("test/node", def);
+      expect(() => {
+        registry.register("test/node", def);
+      }).toThrow(/already registered/);
+    });
+
+    it("should throw error when type is not a string", () => {
+      expect(() => {
+        registry.register(null, {});
+      }).toThrow(/must be a non-empty string/);
+    });
+
+    it("should throw error when definition is not an object", () => {
+      expect(() => {
+        registry.register("test/node", null);
+      }).toThrow(/must be an object/);
+    });
+  });
+
+  describe("unregister", () => {
+    it("should unregister an existing type", () => {
+      const def = { title: "Test" };
+      registry.register("test/node", def);
+      registry.unregister("test/node");
+      expect(registry.types.has("test/node")).toBe(false);
+    });
+
+    it("should throw error when unregistering non-existent type", () => {
+      expect(() => {
+        registry.unregister("non/existent");
+      }).toThrow(/is not registered/);
+    });
+  });
+
+  describe("removeAll", () => {
+    it("should remove all registered types", () => {
+      registry.register("test/a", { title: "A" });
+      registry.register("test/b", { title: "B" });
+      expect(registry.types.size).toBe(2);
+
+      registry.removeAll();
+      expect(registry.types.size).toBe(0);
+    });
+  });
+
+  describe("createInstance", () => {
+    it("should return the definition for a registered type", () => {
+      const def = { title: "Test" };
+      registry.register("test/node", def);
+      const instance = registry.createInstance("test/node");
+      expect(instance).toBe(def);
+    });
+
+    it("should throw error for unknown type with available types listed", () => {
+      registry.register("test/a", { title: "A" });
+      registry.register("test/b", { title: "B" });
+      expect(() => {
+        registry.createInstance("unknown");
+      }).toThrow(/Available types: test\/a, test\/b/);
+    });
+
+    it("should show 'none' when no types are available", () => {
+      expect(() => {
+        registry.createInstance("unknown");
+      }).toThrow(/Available types: none/);
+    });
+  });
+});

package/src/core/Runner.js

@@ -0,0 +1,211 @@
+export class Runner {
+  constructor({ graph, registry, hooks, cyclesPerFrame = 1 }) {
+    this.graph = graph;
+    this.registry = registry;
+    this.hooks = hooks;
+    this.running = false;
+    this._raf = null;
+    this._last = 0;
+    this.cyclesPerFrame = Math.max(1, cyclesPerFrame | 0);
+  }
+
+  // 외부에서 실행 중인지 확인
+  isRunning() {
+    return this.running;
+  }
+
+  // 실행 도중에도 CPS 변경 가능
+  setCyclesPerFrame(n) {
+    this.cyclesPerFrame = Math.max(1, n | 0);
+  }
+
+  step(cycles = 1, dt = 0) {
+    const nCycles = Math.max(1, cycles | 0);
+    for (let c = 0; c < nCycles; c++) {
+      for (const node of this.graph.nodes.values()) {
+        const def = this.registry.types.get(node.type);
+        if (def?.onExecute) {
+          try {
+            def.onExecute(node, {
+              dt,
+              graph: this.graph,
+              getInput: (portName) => {
+                const p =
+                  node.inputs.find((i) => i.name === portName) ||
+                  node.inputs[0];
+                return p ? this.graph.getInput(node.id, p.id) : undefined;
+              },
+              setOutput: (portName, value) => {
+                const p =
+                  node.outputs.find((o) => o.name === portName) ||
+                  node.outputs[0];
+                if (p) this.graph.setOutput(node.id, p.id, value);
+              },
+            });
+          } catch (err) {
+            this.hooks?.emit?.("error", err);
+          }
+        }
+      }
+      // commit writes for this cycle
+      this.graph.swapBuffers();
+    }
+  }
+
+  /**
+   * Execute connected nodes once from a starting node
+   * @param {string} startNodeId - ID of the node to start from
+   * @param {number} dt - Delta time
+   */
+  runOnce(startNodeId, dt = 0) {
+    console.log("[Runner.runOnce] Starting exec flow from node:", startNodeId);
+
+    const executedNodes = [];
+    const allConnectedNodes = new Set();
+    let currentNodeId = startNodeId;
+
+    // Follow exec flow
+    while (currentNodeId) {
+      const node = this.graph.nodes.get(currentNodeId);
+      if (!node) {
+        console.warn(`[Runner.runOnce] Node not found: ${currentNodeId}`);
+        break;
+      }
+
+      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)
+      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);
+              }
+            }
+          }
+        }
+      }
+
+      // Execute current node
+      this.executeNode(currentNodeId, dt);
+
+      // Find next node via exec output
+      currentNodeId = this.findNextExecNode(currentNodeId);
+    }
+
+    console.log("[Runner.runOnce] Executed nodes:", executedNodes.length);
+
+    // Find 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)) {
+        connectedEdges.add(edge.id);
+      }
+    }
+
+    console.log("[Runner.runOnce] Connected edges count:", connectedEdges.size);
+    return { connectedNodes: allConnectedNodes, connectedEdges };
+  }
+
+  /**
+   * Find the next node to execute by following exec output
+   * @param {string} nodeId - Current node ID
+   * @returns {string|null} Next node ID or null
+   */
+  findNextExecNode(nodeId) {
+    const node = this.graph.nodes.get(nodeId);
+    if (!node) return null;
+
+    // Find exec output port
+    const execOutput = node.outputs.find(p => p.portType === "exec");
+    if (!execOutput) return null;
+
+    // Find edge from exec output
+    for (const edge of this.graph.edges.values()) {
+      if (edge.fromNode === nodeId && edge.fromPort === execOutput.id) {
+        return edge.toNode;
+      }
+    }
+
+    return null;
+  }
+
+  /**
+   * 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;
+
+    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];
+          return p ? this.graph.getInput(node.id, p.id) : undefined;
+        },
+        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);
+          }
+        },
+      });
+    } catch (err) {
+      this.hooks?.emit?.("error", err);
+    }
+  }
+
+  start() {
+    if (this.running) return;
+    this.running = true;
+    this._last = 0;
+    this.hooks?.emit?.("runner:start");
+
+    const loop = (t) => {
+      if (!this.running) return;
+      const dtMs = this._last ? t - this._last : 0;
+      this._last = t;
+      const dt = dtMs / 1000; // seconds
+
+      // 1) 스텝 실행
+      this.step(this.cyclesPerFrame, dt);
+
+      // 2) 프레임 훅 (렌더러/컨트롤러는 여기서 running, time, dt를 받아 표현 업데이트)
+      this.hooks?.emit?.("runner:tick", {
+        time: t,
+        dt,
+        running: true,
+        cps: this.cyclesPerFrame,
+      });
+
+      this._raf = requestAnimationFrame(loop);
+    };
+
+    this._raf = requestAnimationFrame(loop);
+  }
+
+  stop() {
+    if (!this.running) return;
+    this.running = false;
+    if (this._raf) cancelAnimationFrame(this._raf);
+    this._raf = null;
+    this._last = 0;
+    this.hooks?.emit?.("runner:stop");
+  }
+}