@3plate/graph-core 0.1.5 → 0.1.6

package/dist/index.cjs

@@ -30,6 +30,11 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
+  FileSource: () => FileSource,
+  FileSystemSource: () => FileSystemSource,
+  Ingest: () => Ingest,
+  Playground: () => Playground,
+  WebSocketSource: () => WebSocketSource,
   default: () => index_default,
   graph: () => graph
 });
@@ -3557,26 +3562,50 @@ var Updater = class _Updater {
     this.update.addNodes.push(node);
     return this;
   }
+  addNodes(...nodes) {
+    this.update.addNodes.push(...nodes);
+    return this;
+  }
   deleteNode(node) {
     this.update.removeNodes.push(node);
     return this;
   }
+  deleteNodes(...nodes) {
+    this.update.removeNodes.push(...nodes);
+    return this;
+  }
   updateNode(node) {
     this.update.updateNodes.push(node);
     return this;
   }
+  updateNodes(...nodes) {
+    this.update.updateNodes.push(...nodes);
+    return this;
+  }
   addEdge(edge) {
     this.update.addEdges.push(edge);
     return this;
   }
+  addEdges(...edges) {
+    this.update.addEdges.push(...edges);
+    return this;
+  }
   deleteEdge(edge) {
     this.update.removeEdges.push(edge);
     return this;
   }
+  deleteEdges(...edges) {
+    this.update.removeEdges.push(...edges);
+    return this;
+  }
   updateEdge(edge) {
     this.update.updateEdges.push(edge);
     return this;
   }
+  updateEdges(...edges) {
+    this.update.updateEdges.push(...edges);
+    return this;
+  }
   static add(nodes, edges) {
     const updater = new _Updater();
     updater.update.addNodes = nodes;
@@ -3607,19 +3636,8 @@ var API = class {
   constructor(args) {
     this.root = args.root;
     this.options = applyDefaults(args.options);
-    let graph2 = new Graph({ options: this.options.graph });
-    this.state = { graph: graph2, update: null };
     this.events = args.events || {};
-    this.seq = [this.state];
-    this.index = 0;
-    this.nodeIds = /* @__PURE__ */ new Map();
-    this.edgeIds = /* @__PURE__ */ new Map();
-    this.nodeVersions = /* @__PURE__ */ new Map();
-    this.nodeOverrides = /* @__PURE__ */ new Map();
-    this.edgeOverrides = /* @__PURE__ */ new Map();
-    this.nodeFields = /* @__PURE__ */ new Map();
-    this.nextNodeId = 1;
-    this.nextEdgeId = 1;
+    this.reset();
     this.canvas = new Canvas(this, {
       ...this.options.canvas,
       dummyNodeSize: this.options.graph.dummyNodeSize,
@@ -3633,6 +3651,31 @@ var API = class {
       this.history = [];
     }
   }
+  reset() {
+    let graph2 = new Graph({ options: this.options.graph });
+    this.state = { graph: graph2, update: null };
+    this.seq = [this.state];
+    this.index = 0;
+    this.nodeIds = /* @__PURE__ */ new Map();
+    this.edgeIds = /* @__PURE__ */ new Map();
+    this.nodeVersions = /* @__PURE__ */ new Map();
+    this.nodeOverrides = /* @__PURE__ */ new Map();
+    this.edgeOverrides = /* @__PURE__ */ new Map();
+    this.nodeFields = /* @__PURE__ */ new Map();
+    this.nextNodeId = 1;
+    this.nextEdgeId = 1;
+  }
+  /** Initialize the API */
+  async init() {
+    const root = document.getElementById(this.root);
+    if (!root) throw new Error("root element not found");
+    root.appendChild(this.canvas.container);
+    await this.applyHistory();
+  }
+  async applyHistory() {
+    for (const update of this.history)
+      await this.applyUpdate(update);
+  }
   /** Current history index (0-based) */
   getHistoryIndex() {
     return this.index;
@@ -3645,17 +3688,25 @@ var API = class {
   setEditable(editable) {
     this.canvas.editMode.editable = editable;
   }
+  /** Replace entire history (clears prior) */
+  async replaceHistory(frames) {
+    this.reset();
+    this.history = frames;
+    await this.applyHistory();
+  }
+  /** Rebuild from snapshot (nodes/edges) */
+  async replaceSnapshot(nodes, edges, description) {
+    this.reset();
+    this.history = [{
+      addNodes: nodes,
+      addEdges: edges,
+      description
+    }];
+    await this.applyHistory();
+  }
   get graph() {
     return this.state.graph;
   }
-  /** Initialize the API */
-  async init() {
-    const root = document.getElementById(this.root);
-    if (!root) throw new Error("root element not found");
-    root.appendChild(this.canvas.container);
-    for (const update of this.history)
-      await this.applyUpdate(update);
-  }
   /** Navigate to a different state */
   nav(nav) {
     let newIndex;
@@ -4077,6 +4128,989 @@ var API = class {
   }
 };
 
+// src/api/ingest.ts
+var Ingest = class {
+  constructor(api) {
+    this.api = api;
+  }
+  /**
+   * Apply an incoming ingest message to the API.
+   * - snapshot: rebuild state from nodes/edges (clears prior history)
+   * - update: apply incremental update
+   * - history: initialize from a set of frames (clears prior history)
+   */
+  async apply(msg) {
+    switch (msg.type) {
+      case "snapshot": {
+        await this.api.replaceSnapshot(msg.nodes, msg.edges, msg.description);
+        break;
+      }
+      case "update": {
+        await this.api.update((u) => {
+          if (msg.addNodes) u.addNodes(...msg.addNodes);
+          if (msg.removeNodes) u.deleteNodes(...msg.removeNodes);
+          if (msg.updateNodes) u.updateNodes(...msg.updateNodes);
+          if (msg.addEdges) u.addEdges(...msg.addEdges);
+          if (msg.removeEdges) u.deleteEdges(...msg.removeEdges);
+          if (msg.updateEdges) u.updateEdges(...msg.updateEdges);
+          if (msg.description) u.describe(msg.description);
+        });
+        break;
+      }
+      case "history": {
+        await this.api.replaceHistory(msg.frames);
+        break;
+      }
+    }
+  }
+};
+
+// src/api/sources/WebSocketSource.ts
+var WebSocketSource = class {
+  url;
+  ws = null;
+  onMessage;
+  onStatus;
+  reconnectMs;
+  closedByUser = false;
+  connectStartTime = null;
+  totalTimeoutMs = 1e4;
+  totalTimeoutTimer = null;
+  constructor(url, onMessage, onStatus, reconnectMs = 1500) {
+    this.url = url;
+    this.onMessage = onMessage;
+    this.onStatus = onStatus;
+    this.reconnectMs = reconnectMs;
+  }
+  connect() {
+    this.closedByUser = false;
+    this.connectStartTime = Date.now();
+    this.startTotalTimeout();
+    this.open();
+  }
+  disconnect() {
+    this.closedByUser = true;
+    this.clearTotalTimeout();
+    if (this.ws) {
+      try {
+        this.ws.close();
+      } catch {
+      }
+      this.ws = null;
+    }
+    this.onStatus?.("closed");
+  }
+  startTotalTimeout() {
+    this.clearTotalTimeout();
+    this.totalTimeoutTimer = window.setTimeout(() => {
+      if (!this.closedByUser && this.ws?.readyState !== WebSocket.OPEN) {
+        this.closedByUser = true;
+        if (this.ws) {
+          try {
+            this.ws.close();
+          } catch {
+          }
+          this.ws = null;
+        }
+        this.clearTotalTimeout();
+        this.onStatus?.("error", new Error("Connection timeout after 10 seconds"));
+      }
+    }, this.totalTimeoutMs);
+  }
+  clearTotalTimeout() {
+    if (this.totalTimeoutTimer !== null) {
+      clearTimeout(this.totalTimeoutTimer);
+      this.totalTimeoutTimer = null;
+    }
+    this.connectStartTime = null;
+  }
+  open() {
+    if (this.connectStartTime && Date.now() - this.connectStartTime >= this.totalTimeoutMs) {
+      if (!this.closedByUser) {
+        this.closedByUser = true;
+        this.clearTotalTimeout();
+        this.onStatus?.("error", new Error("Connection timeout after 10 seconds"));
+      }
+      return;
+    }
+    this.onStatus?.(this.ws ? "reconnecting" : "connecting");
+    const ws = new WebSocket(this.url);
+    this.ws = ws;
+    ws.onopen = () => {
+      this.clearTotalTimeout();
+      this.onStatus?.("connected");
+    };
+    ws.onerror = (e) => {
+      this.onStatus?.("error", e);
+    };
+    ws.onclose = () => {
+      if (this.closedByUser) {
+        this.onStatus?.("closed");
+        return;
+      }
+      if (this.connectStartTime && Date.now() - this.connectStartTime >= this.totalTimeoutMs) {
+        this.closedByUser = true;
+        this.clearTotalTimeout();
+        this.onStatus?.("error", new Error("Connection timeout after 10 seconds"));
+        return;
+      }
+      this.onStatus?.("reconnecting");
+      setTimeout(() => this.open(), this.reconnectMs);
+    };
+    ws.onmessage = (ev) => {
+      const data = typeof ev.data === "string" ? ev.data : "";
+      const lines = data.split("\n").map((l) => l.trim()).filter(Boolean);
+      for (const line of lines) {
+        try {
+          const obj = JSON.parse(line);
+          this.onMessage(obj);
+        } catch {
+        }
+      }
+    };
+  }
+};
+
+// src/api/sources/FileSystemSource.ts
+var FileSystemSource = class {
+  handle = null;
+  onMessage;
+  onStatus;
+  timer = null;
+  lastSize = 0;
+  filename;
+  intervalMs;
+  constructor(onMessage, onStatus, filename = "graph.ndjson", intervalMs = 1e3) {
+    this.onMessage = onMessage;
+    this.onStatus = onStatus;
+    this.filename = filename;
+    this.intervalMs = intervalMs;
+  }
+  async openDirectory() {
+    try {
+      const dir = await window.showDirectoryPicker?.();
+      if (!dir) throw new Error("File System Access not supported or cancelled");
+      const handle = await dir.getFileHandle(this.filename, { create: false });
+      this.handle = handle;
+      this.onStatus?.("opened", { file: this.filename });
+      this.lastSize = 0;
+      this.startPolling();
+    } catch (e) {
+      this.onStatus?.("error", e);
+    }
+  }
+  close() {
+    if (this.timer) {
+      window.clearInterval(this.timer);
+      this.timer = null;
+    }
+    this.handle = null;
+    this.onStatus?.("closed");
+  }
+  startPolling() {
+    if (this.timer) window.clearInterval(this.timer);
+    this.timer = window.setInterval(() => this.readNewLines(), this.intervalMs);
+  }
+  async readNewLines() {
+    try {
+      if (!this.handle) return;
+      this.onStatus?.("reading");
+      const file = await this.handle.getFile();
+      if (file.size === this.lastSize) return;
+      const slice = await file.slice(this.lastSize).text();
+      this.lastSize = file.size;
+      const lines = slice.split("\n").map((l) => l.trim()).filter(Boolean);
+      for (const line of lines) {
+        try {
+          const obj = JSON.parse(line);
+          this.onMessage(obj);
+        } catch {
+        }
+      }
+    } catch (e) {
+      this.onStatus?.("error", e);
+    }
+  }
+};
+
+// src/api/sources/FileSource.ts
+var FileSource = class {
+  url;
+  onMessage;
+  onStatus;
+  timer = null;
+  lastETag = null;
+  lastContent = "";
+  intervalMs = 1e3;
+  closed = false;
+  constructor(url, onMessage, onStatus, intervalMs = 1e3) {
+    this.url = url;
+    this.onMessage = onMessage;
+    this.onStatus = onStatus;
+    this.intervalMs = intervalMs;
+  }
+  async connect() {
+    this.closed = false;
+    this.lastETag = null;
+    this.lastContent = "";
+    this.onStatus?.("opened");
+    this.startPolling();
+  }
+  close() {
+    this.closed = true;
+    if (this.timer) {
+      window.clearInterval(this.timer);
+      this.timer = null;
+    }
+    this.onStatus?.("closed");
+  }
+  startPolling() {
+    if (this.timer) window.clearInterval(this.timer);
+    this.timer = window.setInterval(() => this.poll(), this.intervalMs);
+    this.poll();
+  }
+  async poll() {
+    if (this.closed) return;
+    try {
+      this.onStatus?.("reading");
+      const headers = {};
+      if (this.lastETag) {
+        headers["If-None-Match"] = this.lastETag;
+      }
+      const response = await fetch(this.url, { headers });
+      if (response.status === 304) {
+        return;
+      }
+      if (!response.ok) {
+        throw new Error(`HTTP ${response.status}: ${response.statusText}`);
+      }
+      const etag = response.headers.get("ETag");
+      if (etag) {
+        this.lastETag = etag;
+      }
+      const content = await response.text();
+      if (content === this.lastContent) {
+        return;
+      }
+      const lines = content.split("\n").map((l) => l.trim()).filter(Boolean);
+      const lastContentLines = this.lastContent.split("\n").map((l) => l.trim()).filter(Boolean);
+      const newLines = lines.slice(lastContentLines.length);
+      for (const line of newLines) {
+        try {
+          const obj = JSON.parse(line);
+          this.onMessage(obj);
+        } catch {
+        }
+      }
+      this.lastContent = content;
+    } catch (e) {
+      this.onStatus?.("error", e);
+    }
+  }
+};
+
+// src/playground/playground.ts
+var import_styles2 = __toESM(require("./styles.css?raw"), 1);
+var Playground = class {
+  options;
+  rootElement;
+  currentExample;
+  currentGraph = null;
+  ingest = null;
+  isEditable = false;
+  wsSource = null;
+  fsSource = null;
+  fileSource = null;
+  wsStatus = "disconnected";
+  fsStatus = "disconnected";
+  fileStatus = "disconnected";
+  activeSourceType = null;
+  wsUrl = "ws://localhost:8787";
+  sourceModal = null;
+  helpOverlay = null;
+  exampleList;
+  graphContainerId;
+  constructor(options) {
+    this.options = options;
+    this.exampleList = Object.keys(options.examples);
+    this.currentExample = options.defaultExample || this.exampleList[0];
+    this.graphContainerId = `playground-graph-${Math.random().toString(36).substr(2, 9)}`;
+    if (typeof options.root === "string") {
+      const el = document.getElementById(options.root);
+      if (!el) throw new Error(`Element with id "${options.root}" not found`);
+      this.rootElement = el;
+    } else {
+      this.rootElement = options.root;
+    }
+  }
+  async init() {
+    this.injectStyles();
+    this.createDOM();
+    this.setupEventListeners();
+    await this.renderGraph();
+    this.updateSourceIcon();
+    this.connectExampleSource();
+    const rebuildBtn = this.rootElement.querySelector("#rebuild");
+    if (rebuildBtn) rebuildBtn.disabled = !this.isEditable;
+  }
+  injectStyles() {
+    if (!document.getElementById("g3p-playground-styles")) {
+      const styleEl = document.createElement("style");
+      styleEl.id = "g3p-playground-styles";
+      styleEl.textContent = import_styles2.default;
+      document.head.appendChild(styleEl);
+    }
+  }
+  createDOM() {
+    const exampleList = this.exampleList.map((key, i) => {
+      const example = this.options.examples[key];
+      const isActive = i === 0 || key === this.currentExample;
+      return `
+        <button class="example-btn ${isActive ? "active" : ""}" data-example="${key}">
+          ${example.name}
+        </button>
+      `;
+    }).join("");
+    this.rootElement.innerHTML = `
+      <main class="playground">
+        <div class="sidebar">
+          <h2>Examples</h2>
+          <div class="example-list">
+            ${exampleList}
+          </div>
+
+          <h2>Options</h2>
+          <div class="options">
+            <div class="option-group">
+              <label>Orientation</label>
+              <select id="orientation">
+                <option value="TB">Top to Bottom</option>
+                <option value="BT">Bottom to Top</option>
+                <option value="LR">Left to Right</option>
+                <option value="RL">Right to Left</option>
+              </select>
+            </div>
+
+            <div class="option-group">
+              <label>Port Style</label>
+              <select id="portStyle">
+                <option value="outside">Outside</option>
+                <option value="inside">Inside</option>
+              </select>
+            </div>
+
+            <div class="option-group">
+              <label>
+                <input type="checkbox" id="portLabelRotate" />
+                Rotate Port Labels
+              </label>
+            </div>
+
+            <div class="option-group">
+              <label>Theme</label>
+              <select id="colorMode">
+                <option value="system">System</option>
+                <option value="light">Light</option>
+                <option value="dark">Dark</option>
+              </select>
+            </div>
+          </div>
+        </div>
+
+        <div class="graph-area">
+          <div class="graph-toolbar">
+            <div class="nav-controls">
+              <button class="nav-btn" id="nav-first" title="First (Home)">\u23EE</button>
+              <button class="nav-btn" id="nav-prev" title="Previous (\u2190)">\u25C0</button>
+              <span id="history-label" style="min-width: 4rem; text-align: center; display: inline-flex; align-items: center; justify-content: center; height: 2.25rem;">\u2014 / \u2014</span>
+              <button class="nav-btn" id="nav-next" title="Next (\u2192)">\u25B6</button>
+              <button class="nav-btn" id="nav-last" title="Last (End)">\u23ED</button>
+            </div>
+            <div class="connect-controls" style="display:flex; gap:.5rem; align-items:center;">
+              <button class="nav-btn source-icon-btn" id="source-icon" title="Data Source Connection">\u{1F4E1}</button>
+            </div>
+            <button class="nav-btn" id="help-btn" title="How to edit">\u2753</button>
+            <button class="nav-btn" id="edit-toggle" title="Toggle edit mode">\u270E Edit</button>
+            <button class="nav-btn" id="rebuild" title="Rebuild graph from scratch">\u{1F504} Rebuild</button>
+          </div>
+          <div class="graph-container" id="${this.graphContainerId}"></div>
+        </div>
+      </main>
+    `;
+  }
+  setupEventListeners() {
+    this.rootElement.querySelectorAll(".example-btn").forEach((btn) => {
+      btn.addEventListener("click", () => {
+        this.rootElement.querySelectorAll(".example-btn").forEach((b) => b.classList.remove("active"));
+        btn.classList.add("active");
+        this.currentExample = btn.getAttribute("data-example") || this.exampleList[0];
+        this.renderGraph();
+        this.connectExampleSource();
+      });
+    });
+    this.rootElement.querySelectorAll(".options select, .options input").forEach((el) => {
+      el.addEventListener("change", () => this.renderGraph());
+    });
+    this.rootElement.querySelector("#nav-first")?.addEventListener("click", () => {
+      this.currentGraph?.nav("first");
+      this.updateHistoryLabel();
+    });
+    this.rootElement.querySelector("#nav-prev")?.addEventListener("click", () => {
+      this.currentGraph?.nav("prev");
+      this.updateHistoryLabel();
+    });
+    this.rootElement.querySelector("#nav-next")?.addEventListener("click", () => {
+      this.currentGraph?.nav("next");
+      this.updateHistoryLabel();
+    });
+    this.rootElement.querySelector("#nav-last")?.addEventListener("click", () => {
+      this.currentGraph?.nav("last");
+      this.updateHistoryLabel();
+    });
+    this.rootElement.querySelector("#rebuild")?.addEventListener("click", () => {
+      this.currentGraph?.rebuild();
+    });
+    this.rootElement.querySelector("#edit-toggle")?.addEventListener("click", () => {
+      this.isEditable = !this.isEditable;
+      const btn = this.rootElement.querySelector("#edit-toggle");
+      if (btn) btn.textContent = this.isEditable ? "\u2713 Done" : "\u270E Edit";
+      const rebuildBtn = this.rootElement.querySelector("#rebuild");
+      if (rebuildBtn) rebuildBtn.disabled = !this.isEditable;
+      try {
+        this.currentGraph?.setEditable?.(this.isEditable);
+      } catch {
+      }
+    });
+    this.rootElement.querySelector("#help-btn")?.addEventListener("click", () => this.openHelp());
+    const sourceIconBtn = this.rootElement.querySelector("#source-icon");
+    if (sourceIconBtn) {
+      sourceIconBtn.addEventListener("click", (e) => {
+        e.preventDefault();
+        e.stopPropagation();
+        this.openSourceModal();
+      });
+    }
+    document.addEventListener("keydown", (e) => {
+      if (!this.currentGraph) return;
+      if (e.target instanceof HTMLInputElement || e.target instanceof HTMLSelectElement) return;
+      switch (e.key) {
+        case "Home":
+          this.currentGraph.nav("first");
+          this.updateHistoryLabel();
+          break;
+        case "End":
+          this.currentGraph.nav("last");
+          this.updateHistoryLabel();
+          break;
+        case "ArrowLeft":
+          this.currentGraph.nav("prev");
+          this.updateHistoryLabel();
+          break;
+        case "ArrowRight":
+          this.currentGraph.nav("next");
+          this.updateHistoryLabel();
+          break;
+      }
+    });
+  }
+  getResolvedColorMode() {
+    const mode = this.rootElement.querySelector("#colorMode")?.value;
+    if (mode === "system") {
+      return window.matchMedia("(prefers-color-scheme: dark)").matches ? "dark" : "light";
+    }
+    return mode;
+  }
+  getOptions(exampleOptions) {
+    const orientation = this.rootElement.querySelector("#orientation")?.value;
+    return {
+      graph: { orientation },
+      canvas: {
+        width: "100%",
+        height: "100%",
+        colorMode: this.getResolvedColorMode(),
+        editable: this.isEditable,
+        ...exampleOptions?.canvas
+      }
+    };
+  }
+  async renderGraph() {
+    const container = this.rootElement.querySelector(`#${this.graphContainerId}`);
+    if (!container) return;
+    container.innerHTML = "";
+    const example = this.options.examples[this.currentExample];
+    const options = this.getOptions(example.options);
+    try {
+      this.currentGraph = await graph({
+        root: this.graphContainerId,
+        nodes: example.nodes,
+        edges: example.edges,
+        options,
+        events: {
+          historyChange: () => this.updateHistoryLabel()
+        }
+      });
+      this.ingest = new Ingest(this.currentGraph);
+      this.updateHistoryLabel();
+    } catch (e) {
+      console.error("Failed to render graph:", e);
+      container.innerHTML = '<p style="padding: 2rem; color: #ef4444;">Failed to load graph</p>';
+    }
+  }
+  updateHistoryLabel() {
+    const label = this.rootElement.querySelector("#history-label");
+    if (!label || !this.currentGraph) return;
+    try {
+      const idx = this.currentGraph.getHistoryIndex?.() ?? 0;
+      const len = this.currentGraph.getHistoryLength?.() ?? 1;
+      label.textContent = `${idx + 1} / ${len}`;
+    } catch {
+      label.textContent = "\u2014 / \u2014";
+    }
+  }
+  connectExampleSource() {
+    const example = this.options.examples[this.currentExample];
+    if (!example.source) {
+      this.disconnectAllSources();
+      return;
+    }
+    this.disconnectAllSources();
+    if (example.source.type === "websocket") {
+      this.wsUrl = example.source.url;
+      this.wsSource = new WebSocketSource(example.source.url, this.handleIngestMessage.bind(this), this.updateWsStatus);
+      this.wsSource.connect();
+    } else if (example.source.type === "file") {
+      this.fileSource = new FileSource(example.source.path, this.handleIngestMessage.bind(this), this.updateFileStatus);
+      this.fileSource.connect();
+    }
+  }
+  disconnectAllSources() {
+    this.wsSource?.disconnect();
+    this.fsSource?.close();
+    this.fileSource?.close();
+    this.wsSource = null;
+    this.fsSource = null;
+    this.fileSource = null;
+    this.activeSourceType = null;
+    this.wsStatus = "disconnected";
+    this.fsStatus = "disconnected";
+    this.fileStatus = "disconnected";
+    this.updateSourceIcon();
+  }
+  openHelp() {
+    if (!this.helpOverlay) {
+      this.helpOverlay = document.createElement("div");
+      this.helpOverlay.className = "modal-overlay";
+      this.helpOverlay.innerHTML = `
+        <div class="modal" role="dialog" aria-modal="true" aria-labelledby="help-title">
+          <div class="modal-header">
+            <h3 id="help-title">Editing the Graph</h3>
+            <button class="modal-close" title="Close" aria-label="Close">\xD7</button>
+          </div>
+          <div class="modal-body">
+            <p>Here's how to edit the graph:</p>
+            <ul>
+              <li><strong>Enable editing</strong>: Click "Edit"</li>
+              <li><strong>Add a node</strong>: Double\u2011click an empty area</li>
+              <li><strong>Edit a node</strong>: Double\u2011click a node</li>
+              <li><strong>Edit an edge</strong>: Double\u2011click an edge</li>
+              <li><strong>Create an edge</strong>: Click and drag from a node (or its port) onto another node; press Esc to cancel</li>
+              <li><strong>Pan</strong>: Drag on canvas or edges; <strong>Zoom</strong>: Mouse wheel or controls</li>
+              <li><strong>Rebuild</strong>: Use "Rebuild" to re-layout from scratch (enabled in edit mode)</li>
+            </ul>
+            <p>When you're done, click "Done" to lock the canvas.</p>
+          </div>
+        </div>
+      `;
+      document.body.appendChild(this.helpOverlay);
+      this.helpOverlay.addEventListener("click", (e) => {
+        const target = e.target;
+        if (target.classList.contains("modal-overlay") || target.classList.contains("modal-close")) {
+          this.closeHelp();
+        }
+      });
+    }
+    this.helpOverlay.style.display = "flex";
+  }
+  closeHelp() {
+    if (this.helpOverlay) this.helpOverlay.style.display = "none";
+  }
+  handleIngestMessage = async (msg) => {
+    if (!this.ingest) return;
+    await this.ingest.apply(msg);
+  };
+  updateSourceIcon() {
+    const iconBtn = this.rootElement.querySelector("#source-icon");
+    if (!iconBtn) return;
+    iconBtn.classList.remove("active", "connecting", "error");
+    const isConnected = this.activeSourceType === "ws" && this.wsStatus === "connected" || this.activeSourceType === "folder" && this.fsStatus === "connected" || this.activeSourceType === "file" && this.fileStatus === "connected";
+    const isConnecting = this.activeSourceType === "ws" && this.wsStatus === "connecting" || this.activeSourceType === "folder" && this.fsStatus === "opening" || this.activeSourceType === "file" && this.fileStatus === "connecting";
+    const hasError = this.activeSourceType === "ws" && this.wsStatus === "error" || this.activeSourceType === "folder" && this.fsStatus === "error" || this.activeSourceType === "file" && this.fileStatus === "error";
+    let icon = "\u{1F4E1}";
+    if (this.activeSourceType === "folder") {
+      icon = "\u{1F4C1}";
+    } else if (this.activeSourceType === "file") {
+      icon = "\u{1F4C4}";
+    }
+    if (isConnected) {
+      iconBtn.classList.add("active");
+      iconBtn.textContent = icon;
+    } else if (isConnecting) {
+      iconBtn.classList.add("connecting");
+      iconBtn.textContent = icon;
+    } else if (hasError) {
+      iconBtn.classList.add("error");
+      iconBtn.textContent = icon;
+    } else {
+      iconBtn.textContent = "\u{1F4E1}";
+    }
+  }
+  updateWsStatus = (status, detail) => {
+    if (status === "connecting" || status === "reconnecting") {
+      this.wsStatus = "connecting";
+      this.activeSourceType = "ws";
+    } else if (status === "connected") {
+      this.wsStatus = "connected";
+      this.activeSourceType = "ws";
+      if (this.fsSource && this.fsStatus === "connected") {
+        this.fsSource.close();
+      }
+      if (this.fileSource && this.fileStatus === "connected") {
+        this.fileSource.close();
+      }
+    } else if (status === "error") {
+      this.wsStatus = "error";
+    } else {
+      this.wsStatus = "disconnected";
+      if (this.activeSourceType === "ws") {
+        this.activeSourceType = null;
+      }
+    }
+    this.updateSourceIcon();
+    this.updateSourceModal();
+  };
+  updateFsStatus = (status, detail) => {
+    if (status === "opened") {
+      this.fsStatus = "opening";
+      this.activeSourceType = "folder";
+      if (this.wsSource && this.wsStatus === "connected") {
+        this.wsSource.disconnect();
+      }
+    } else if (status === "reading") {
+      this.fsStatus = "connected";
+      this.activeSourceType = "folder";
+    } else if (status === "error") {
+      this.fsStatus = "error";
+    } else if (status === "closed") {
+      this.fsStatus = "disconnected";
+      if (this.activeSourceType === "folder") {
+        this.activeSourceType = null;
+      }
+    } else {
+      this.fsStatus = "disconnected";
+    }
+    this.updateSourceIcon();
+    this.updateSourceModal();
+  };
+  updateFileStatus = (status, detail) => {
+    if (status === "opened") {
+      this.fileStatus = "connecting";
+      this.activeSourceType = "file";
+      if (this.wsSource && this.wsStatus === "connected") {
+        this.wsSource.disconnect();
+      }
+      if (this.fsSource && this.fsStatus === "connected") {
+        this.fsSource.close();
+      }
+    } else if (status === "reading") {
+      this.fileStatus = "connected";
+      this.activeSourceType = "file";
+    } else if (status === "error") {
+      this.fileStatus = "error";
+    } else if (status === "closed") {
+      this.fileStatus = "disconnected";
+      if (this.activeSourceType === "file") {
+        this.activeSourceType = null;
+      }
+    } else {
+      this.fileStatus = "disconnected";
+    }
+    this.updateSourceIcon();
+    this.updateSourceModal();
+  };
+  createSourceModal() {
+    if (this.sourceModal) return this.sourceModal;
+    this.sourceModal = document.createElement("div");
+    this.sourceModal.className = "modal-overlay";
+    this.sourceModal.style.display = "none";
+    this.sourceModal.innerHTML = `
+      <div class="modal" role="dialog" aria-modal="true" aria-labelledby="source-modal-title">
+        <div class="modal-header">
+          <h3 id="source-modal-title">Data Source Connection</h3>
+          <button class="modal-close" title="Close" aria-label="Close">\xD7</button>
+        </div>
+        <div class="modal-body">
+          <div class="source-type-selector">
+            <button class="source-type-option" data-source="ws">\u{1F4E1} WebSocket</button>
+            <button class="source-type-option" data-source="folder">\u{1F4C1} Folder</button>
+          </div>
+
+          <div class="source-controls" data-source="ws">
+            <div class="form-group">
+              <label for="source-modal-url">WebSocket URL</label>
+              <input type="text" id="source-modal-url" value="${this.wsUrl}" />
+            </div>
+            <div class="button-group">
+              <button id="source-modal-connect-ws" class="primary">Connect</button>
+              <button id="source-modal-disconnect-ws">Disconnect</button>
+              <button id="source-modal-change-ws">Change Connection</button>
+            </div>
+          </div>
+
+          <div class="source-controls" data-source="folder">
+            <div class="form-group">
+              <label>File System Source</label>
+              <p style="font-size: 0.875rem; color: var(--color-text-muted); margin-top: 0.25rem;">
+                Select a directory containing a graph.ndjson file to watch for changes.
+              </p>
+            </div>
+            <div class="button-group">
+              <button id="source-modal-connect-folder" class="primary">Open Folder</button>
+              <button id="source-modal-disconnect-folder">Disconnect</button>
+            </div>
+          </div>
+
+          <div id="source-modal-status"></div>
+        </div>
+      </div>
+    `;
+    document.body.appendChild(this.sourceModal);
+    this.sourceModal.addEventListener("click", (e) => {
+      const target = e.target;
+      if (target.classList.contains("modal-overlay") || target.classList.contains("modal-close")) {
+        this.closeSourceModal();
+      }
+    });
+    this.sourceModal.querySelectorAll(".source-type-option").forEach((btn) => {
+      btn.addEventListener("click", () => {
+        const sourceType = btn.getAttribute("data-source");
+        if (sourceType) {
+          this.selectSourceType(sourceType);
+        }
+      });
+    });
+    document.getElementById("source-modal-connect-ws")?.addEventListener("click", () => this.handleConnect());
+    document.getElementById("source-modal-disconnect-ws")?.addEventListener("click", () => this.handleDisconnect());
+    document.getElementById("source-modal-change-ws")?.addEventListener("click", () => this.handleChangeConnection());
+    document.getElementById("source-modal-connect-folder")?.addEventListener("click", () => this.handleOpenFolder());
+    document.getElementById("source-modal-disconnect-folder")?.addEventListener("click", () => this.handleCloseFolder());
+    document.getElementById("source-modal-url")?.addEventListener("keydown", (e) => {
+      if (e.key === "Enter" && this.wsStatus !== "connected") {
+        this.handleConnect();
+      }
+    });
+    return this.sourceModal;
+  }
+  selectSourceType(type, skipUpdate = false) {
+    if (!this.sourceModal) return;
+    this.sourceModal.querySelectorAll(".source-type-option").forEach((btn) => {
+      if (btn.getAttribute("data-source") === type) {
+        btn.classList.add("active");
+      } else {
+        btn.classList.remove("active");
+      }
+    });
+    this.sourceModal.querySelectorAll(".source-controls").forEach((controls) => {
+      if (controls.getAttribute("data-source") === type) {
+        controls.classList.add("active");
+      } else {
+        controls.classList.remove("active");
+      }
+    });
+    if (!skipUpdate) {
+      this.updateSourceModalContent();
+    }
+  }
+  updateSourceModalContent() {
+    if (!this.sourceModal) return;
+    const urlInput = document.getElementById("source-modal-url");
+    const connectWsBtn = document.getElementById("source-modal-connect-ws");
+    const disconnectWsBtn = document.getElementById("source-modal-disconnect-ws");
+    const changeWsBtn = document.getElementById("source-modal-change-ws");
+    if (urlInput && connectWsBtn && disconnectWsBtn && changeWsBtn) {
+      const isWsConnected = this.wsStatus === "connected";
+      const isWsConnecting = this.wsStatus === "connecting";
+      connectWsBtn.disabled = isWsConnected || isWsConnecting;
+      disconnectWsBtn.disabled = !isWsConnected || isWsConnecting;
+      changeWsBtn.disabled = !isWsConnected || isWsConnecting;
+      urlInput.disabled = isWsConnecting;
+    }
+    const connectFolderBtn = document.getElementById("source-modal-connect-folder");
+    const disconnectFolderBtn = document.getElementById("source-modal-disconnect-folder");
+    if (connectFolderBtn && disconnectFolderBtn) {
+      const isFolderConnected = this.fsStatus === "connected";
+      const isFolderOpening = this.fsStatus === "opening";
+      connectFolderBtn.disabled = isFolderConnected || isFolderOpening;
+      disconnectFolderBtn.disabled = !isFolderConnected || isFolderOpening;
+    }
+    const statusDiv = document.getElementById("source-modal-status");
+    if (!statusDiv) return;
+    const currentUrl = urlInput?.value || this.wsUrl;
+    statusDiv.innerHTML = "";
+    if (this.activeSourceType === "ws") {
+      if (this.wsStatus === "connecting") {
+        statusDiv.innerHTML = `
+          <div class="status-message info">
+            <span class="loading-spinner"></span>
+            Connecting to ${currentUrl}...
+          </div>
+        `;
+      } else if (this.wsStatus === "connected") {
+        statusDiv.innerHTML = `
+          <div class="status-message success">
+            \u2713 Connected to ${currentUrl}
+          </div>
+        `;
+      } else if (this.wsStatus === "error") {
+        statusDiv.innerHTML = `
+          <div class="status-message error">
+            \u2717 Connection error. Please check the URL and try again.
+          </div>
+        `;
+      } else {
+        statusDiv.innerHTML = `
+          <div class="status-message info">
+            Not connected
+          </div>
+        `;
+      }
+    } else if (this.activeSourceType === "folder") {
+      if (this.fsStatus === "opening") {
+        statusDiv.innerHTML = `
+          <div class="status-message info">
+            <span class="loading-spinner"></span>
+            Opening folder...
+          </div>
+        `;
+      } else if (this.fsStatus === "connected") {
+        statusDiv.innerHTML = `
+          <div class="status-message success">
+            \u2713 Folder connected and watching for changes
+          </div>
+        `;
+      } else if (this.fsStatus === "error") {
+        statusDiv.innerHTML = `
+          <div class="status-message error">
+            \u2717 Error opening folder. Please try again.
+          </div>
+        `;
+      } else {
+        statusDiv.innerHTML = `
+          <div class="status-message info">
+            Not connected
+          </div>
+        `;
+      }
+    } else if (this.activeSourceType === "file") {
+      const example = this.options.examples[this.currentExample];
+      const filePath = example.source?.type === "file" ? example.source.path : "";
+      if (this.fileStatus === "connecting") {
+        statusDiv.innerHTML = `
+          <div class="status-message info">
+            <span class="loading-spinner"></span>
+            Connecting to ${filePath}...
+          </div>
+        `;
+      } else if (this.fileStatus === "connected") {
+        statusDiv.innerHTML = `
+          <div class="status-message success">
+            \u2713 Connected to ${filePath}
+          </div>
+        `;
+      } else if (this.fileStatus === "error") {
+        statusDiv.innerHTML = `
+          <div class="status-message error">
+            \u2717 Error loading file. Please check the path and try again.
+          </div>
+        `;
+      } else {
+        statusDiv.innerHTML = `
+          <div class="status-message info">
+            Not connected
+          </div>
+        `;
+      }
+    } else {
+      statusDiv.innerHTML = `
+        <div class="status-message info">
+          Select a source type to connect
+        </div>
+      `;
+    }
+  }
+  updateSourceModal() {
+    if (!this.sourceModal) return;
+    const activeType = (this.activeSourceType === "file" ? "ws" : this.activeSourceType) || "ws";
+    this.selectSourceType(activeType, true);
+    this.updateSourceModalContent();
+  }
+  openSourceModal() {
+    this.createSourceModal();
+    if (this.sourceModal) {
+      const urlInput = document.getElementById("source-modal-url");
+      if (urlInput) {
+        urlInput.value = this.wsUrl;
+      }
+      const activeType = (this.activeSourceType === "file" ? "ws" : this.activeSourceType) || "ws";
+      this.selectSourceType(activeType);
+      this.updateSourceModal();
+      this.sourceModal.style.display = "flex";
+    }
+  }
+  closeSourceModal() {
+    if (this.sourceModal) {
+      this.sourceModal.style.display = "none";
+    }
+  }
+  handleConnect() {
+    const urlInput = document.getElementById("source-modal-url");
+    if (!urlInput) return;
+    const url = urlInput.value.trim() || "ws://localhost:8787";
+    this.wsUrl = url;
+    if (this.wsSource) {
+      this.wsSource.disconnect();
+    }
+    this.wsSource = new WebSocketSource(url, this.handleIngestMessage.bind(this), this.updateWsStatus);
+    this.wsSource.connect();
+    this.updateSourceModal();
+  }
+  handleDisconnect() {
+    this.wsSource?.disconnect();
+    this.updateSourceModal();
+  }
+  handleChangeConnection() {
+    if (this.wsSource) {
+      this.wsSource.disconnect();
+    }
+    const urlInput = document.getElementById("source-modal-url");
+    if (urlInput) {
+      urlInput.focus();
+      urlInput.select();
+    }
+    this.updateSourceModal();
+  }
+  async handleOpenFolder() {
+    if (!this.fsSource) {
+      this.fsSource = new FileSystemSource(this.handleIngestMessage.bind(this), this.updateFsStatus);
+    }
+    this.updateSourceModal();
+    await this.fsSource.openDirectory();
+  }
+  handleCloseFolder() {
+    this.fsSource?.close();
+    this.updateSourceModal();
+  }
+};
+
 // src/index.ts
 async function graph(args = { root: "app" }) {
   const api = new API(args);
@@ -4086,5 +5120,10 @@ async function graph(args = { root: "app" }) {
 var index_default = graph;
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  FileSource,
+  FileSystemSource,
+  Ingest,
+  Playground,
+  WebSocketSource,
   graph
 });