modulearn 0.1.0__py3-none-any.whl

modulearn/static/graph.js

@@ -0,0 +1,1003 @@
+/* ModuLearn — the visual ('Unreal Blueprints') front end for training runs.
+ *
+ * Flow:
+ *   1. Fetch the node catalog from GET /api/nodes (built from the host app's
+ *      modulearn.Registry) and register one graph-engine node type per entry,
+ *      translating each catalog Param into an editable node widget.
+ *   2. The user drops nodes from the left palette and wires them on the canvas.
+ *   3. On every edit we serialize the canvas to the compact graph JSON that
+ *      modulearn/compiler.py expects and POST it to /api/graph/compile — a dry run
+ *      that returns either the resolved config or the list of wiring errors, shown
+ *      live in the corner panel.
+ *   4. "Train" POSTs the same graph to /api/graph/start, which compiles + launches.
+ *
+ * The catalog is authoritative: this file contains no hardcoded node list, so the
+ * palette can never drift from the Python it compiles to.
+ */
+(function () {
+  "use strict";
+
+  const graph = new LGraph();
+  const canvas = new LGraphCanvas("#graphcanvas", graph);
+  let CATALOG = null;                 // {port_types, categories, nodes:[spec,...]}
+  const SPEC_BY_TYPE = {};            // node type id -> catalog spec (for serialize)
+  const _meas = document.createElement("canvas").getContext("2d");  // offscreen text metrics
+  const history = []; // array of serialize() snapshots (JSON strings)
+  let histIdx = -1; // index of the currently-shown snapshot
+  let restoring = false; // true while reuild() replays a snapshot
+  let histTimer = null;
+
+  function captureHistory(){
+    if (restoring) return;
+    clearTimeout(histTimer);
+    histTimer = setTimeout(() => { // coalesce rapid edits (slider drags)
+      const snap = JSON.stringify(serialize());
+      if (snap === history[histIdx]) return; // no structural change
+      history.splice(histIdx + 1); // drop the redo tail
+      history.push(snap);
+      if (history.length > 100) history.shift();
+      histIdx = history.length - 1;
+      updateUndoButtons();
+    }, 350);
+  }
+
+  function applySnapshot(snap){
+    restoring = true;              // suppress capture from rebuild's node events
+    graph.clear();
+    rebuild(JSON.parse(snap));
+    restoring = false;
+    validate();                    // revalidate WITHOUT recapturing (scheduleValidate would)
+    persist();
+    updateUndoButtons();
+  }
+  function undo() {
+    if (histIdx > 0){
+      histIdx--;
+      applySnapshot(history[histIdx]);
+    }
+  }
+  function redo(){
+    if (histIdx < history.length - 1){
+      histIdx++;
+      applySnapshot(history[histIdx]);
+    }
+  }
+  function updateUndoButtons(){
+    const u = document.getElementById("undoBtn"), r = document.getElementById("redoBtn");
+    if (u) u.disabled = histIdx <= 0;
+    if (r) r.disabled = histIdx >= history.length - 1;
+  }
+
+  // ---- canvas sizing ---------------------------------------------------------
+  function resize() {
+    const c = document.getElementById("graphcanvas");
+    c.width = c.parentElement.clientWidth;
+    c.height = c.parentElement.clientHeight;
+    canvas.resize();
+  }
+  window.addEventListener("resize", resize);
+
+  // ---- animation engine ------------------------------------------------------
+  // The engine only repaints when "dirty"; we drive a rAF loop that forces a redraw
+  // while there's motion to show (nodes present or a run active), and paint all the
+  // ambient effects in canvas.onDrawForeground (graph space, after nodes).
+  const reduceMotion = window.matchMedia("(prefers-reduced-motion: reduce)").matches;
+  const PORT_COLORS = { dataset: "#5aa9e6", model: "#c8663c", loss: "#c98bdb",
+                        scalar: "#6fb98f", run: "#d8a24a" };
+  // Port types may be a family ("model") or a subtype ("scalar/lr"); color by base.
+  function linkColor(type) {
+    return PORT_COLORS[type] || PORT_COLORS[(type || "").split("/")[0]] || "#8b98a9";
+  }
+  const _pa = new Float32Array(2), _pb = new Float32Array(2);
+
+  function trainNode() { return graph._nodes.find((n) => n.type === "train.train"); }
+
+  // ---- helpers shared by the panel + navigation ------------------------------
+  function escapeHtml(s) {
+    return String(s).replace(/[&<>"']/g, (c) => (
+      { "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" }[c]));
+  }
+
+  // Compiler errors name the offending node(s) by their serialized id (e.g.
+  // "type mismatch on wire 3.model -> 5.dataset"). Find which live node ids a
+  // given message references so its line can deep-link back to the canvas.
+  function idsInError(err) {
+    const ids = [];
+    for (const n of graph._nodes) {
+      const id = String(n.id);
+      if (new RegExp("(?:^|[^0-9])" + id + "(?:[^0-9]|$)").test(err)) ids.push(id);
+    }
+    return ids;
+  }
+
+  // Select a node and pan the view so it sits centre-canvas.
+  function focusNode(id) {
+    const n = graph.getNodeById(+id);
+    if (!n) return;
+    canvas.selectNode(n);
+    canvas.centerOnNode(n);
+    canvas.setDirty(true, true);
+  }
+
+  // Frame every node in view (or reset to 1:1 when the canvas is empty).
+  function zoomToFit() {
+    const ds = canvas.ds, nodes = graph._nodes;
+    if (!nodes.length) { ds.scale = 1; ds.offset[0] = 0; ds.offset[1] = 0;
+      canvas.setDirty(true, true); return; }
+    let minx = Infinity, miny = Infinity, maxx = -Infinity, maxy = -Infinity;
+    for (const n of nodes) {
+      minx = Math.min(minx, n.pos[0]);
+      miny = Math.min(miny, n.pos[1] - LiteGraph.NODE_TITLE_HEIGHT);
+      maxx = Math.max(maxx, n.pos[0] + n.size[0]);
+      maxy = Math.max(maxy, n.pos[1] + n.size[1]);
+    }
+    const pad = 60, cw = canvas.canvas.width, ch = canvas.canvas.height;
+    const scale = Math.max(0.15, Math.min(cw / (maxx - minx + pad * 2),
+                                          ch / (maxy - miny + pad * 2), 1.6));
+    ds.scale = scale;                                   // screen = (graph + offset)*scale
+    ds.offset[0] = cw / (2 * scale) - (minx + maxx) / 2;
+    ds.offset[1] = ch / (2 * scale) - (miny + maxy) / 2;
+    canvas.setDirty(true, true);
+  }
+
+  // ---- Train button state: invalid | ready | running ------------------------
+  let graphValid = false;
+  function setTrainState(s) {
+    const b = document.getElementById("trainBtn");
+    if (!b) return;
+    b.classList.toggle("running", s === "running");
+    b.disabled = s === "invalid" || s === "running";
+    b.lastChild.textContent = s === "running" ? " Training…" : " Train";
+    b.title = s === "invalid" ? "Wire a valid graph to enable launch"
+            : s === "running" ? "A run is in progress" : "Compile and launch this graph";
+  }
+
+  function bezier(p0, p1, p2, p3, t) {
+    const u = 1 - t, uu = u * u, tt = t * t, uuu = uu * u, ttt = tt * t;
+    return [uuu * p0[0] + 3 * uu * t * p1[0] + 3 * u * tt * p2[0] + ttt * p3[0],
+            uuu * p0[1] + 3 * uu * t * p1[1] + 3 * u * tt * p2[1] + ttt * p3[1]];
+  }
+
+  // Dots traveling along each wire in flow direction; faster on wires feeding a
+  // currently-running Train node.
+  function drawFlowingWires(ctx, now) {
+    const tn = trainNode(), running = tn && tn._running;
+    for (const id in graph.links) {
+      const l = graph.links[id];
+      if (!l) continue;
+      const src = graph.getNodeById(l.origin_id), dst = graph.getNodeById(l.target_id);
+      if (!src || !dst) continue;
+      src.getConnectionPos(false, l.origin_slot, _pa);
+      dst.getConnectionPos(true, l.target_slot, _pb);
+      const a = [_pa[0], _pa[1]], b = [_pb[0], _pb[1]];
+      const dist = Math.hypot(b[0] - a[0], b[1] - a[1]);
+      const c1 = [a[0] + dist * 0.25, a[1]], c2 = [b[0] - dist * 0.25, b[1]];
+      const hot = running && dst === tn;
+      const color = linkColor(l.type);
+      const speed = hot ? 0.00085 : 0.00032, gap = 0.3;
+      const phase = ((now * speed) % gap + gap) % gap;
+      for (let t = phase; t < 1; t += gap) {
+        const p = bezier(a, c1, c2, b, t);
+        ctx.beginPath();
+        ctx.arc(p[0], p[1], hot ? 3.4 : 2.4, 0, Math.PI * 2);
+        ctx.fillStyle = color;
+        ctx.globalAlpha = hot ? 0.95 : 0.8;
+        ctx.fill();
+      }
+    }
+    ctx.globalAlpha = 1;
+  }
+
+  // A brief expanding ring when a node is dropped from the palette.
+  function drawSpawnRings(ctx, now) {
+    for (const n of graph._nodes) {
+      if (!n._spawn) continue;
+      const age = now - n._spawn, life = 450;
+      if (age > life) { n._spawn = 0; continue; }
+      const k = age / life;
+      const cx = n.pos[0] + n.size[0] / 2, cy = n.pos[1] + n.size[1] / 2;
+      ctx.beginPath();
+      ctx.arc(cx, cy, 12 + k * Math.max(n.size[0], n.size[1]) * 0.7, 0, Math.PI * 2);
+      ctx.strokeStyle = "rgba(200,102,60," + (1 - k) * 0.5 + ")";
+      ctx.lineWidth = 2; ctx.stroke();
+    }
+  }
+
+  // Glow ports of the hovered node, and — while dragging a wire — pulse every
+  // input port whose type matches the output being dragged.
+  function drawPortCues(ctx, now) {
+    const pulse = 0.5 + 0.5 * Math.sin(now * 0.006);
+    const ring = (x, y, r, color, alpha) => {
+      ctx.beginPath(); ctx.arc(x, y, r, 0, Math.PI * 2);
+      ctx.strokeStyle = color; ctx.globalAlpha = alpha; ctx.lineWidth = 2; ctx.stroke();
+      ctx.globalAlpha = 1;
+    };
+    const over = canvas.node_over;
+    if (over) {
+      (over.outputs || []).forEach((o, i) => {
+        over.getConnectionPos(false, i, _pa);
+        ring(_pa[0], _pa[1], 6 + pulse * 2, linkColor(o.type), 0.5);
+      });
+    }
+    const co = canvas.connecting_output;
+    if (co) {
+      for (const n of graph._nodes) {
+        (n.inputs || []).forEach((inp, i) => {
+          if (inp.type !== co.type) return;
+          n.getConnectionPos(true, i, _pb);
+          ring(_pb[0], _pb[1], 6 + pulse * 4, linkColor(inp.type), 0.35 + pulse * 0.45);
+        });
+      }
+    }
+  }
+
+  // Train node liveness: a pulsing colored border (accent while running, green on
+  // done, red on error) and a bottom progress bar tracking epoch completion.
+  function drawTrainStatus(node, ctx) {
+    const w = node.size[0], h = node.size[1];
+    const color = node._phase === "error" ? "#f85149"
+                : node._phase === "done" ? "#3fb950" : "#c8663c";
+    const running = node._phase === "running";
+    const pulse = 0.5 + 0.5 * Math.sin(performance.now() * 0.005);
+    ctx.save();
+    ctx.strokeStyle = color;
+    ctx.globalAlpha = running ? 0.35 + pulse * 0.5 : 0.85;
+    ctx.lineWidth = 2;
+    if (ctx.roundRect) { ctx.beginPath(); ctx.roundRect(1, 1, w - 2, h - 2, 7); ctx.stroke(); }
+    else ctx.strokeRect(1, 1, w - 2, h - 2);
+    const p = Math.max(0, Math.min(1, node._progress || 0));
+    ctx.globalAlpha = 1;
+    ctx.fillStyle = "rgba(255,255,255,.08)";
+    ctx.fillRect(8, h - 9, w - 16, 4);
+    ctx.fillStyle = color;
+    ctx.fillRect(8, h - 9, (w - 16) * p, 4);
+    ctx.restore();
+  }
+
+  function ambientDraw(ctx) {
+    if (reduceMotion) return;
+    const now = performance.now();
+    drawFlowingWires(ctx, now);
+    drawSpawnRings(ctx, now);
+    drawPortCues(ctx, now);
+  }
+
+  function animLoop() {
+    // Repaint only when there is something to animate — idle canvas stays still.
+    if (!reduceMotion && (graph._nodes.length || pollTimer)) canvas.draw(true, true);
+    requestAnimationFrame(animLoop);
+  }
+
+  // ---- widget factory: one catalog Param -> one node widget ------------------
+  // Keeps node.properties[name] in sync so serialization can read a flat param map.
+  // int_list is stored/edited as "128,64" text and parsed to an array at serialize.
+  function addWidget(node, p) {
+    node.properties[p.name] = p.default;
+    // Update the param and re-validate. The engine invokes this with (value, ...),
+    // and there is no canvas-level widget hook, so validation must originate here.
+    const set = (v) => { node.properties[p.name] = v; scheduleValidate(); };
+
+    if (p.kind === "float" || p.kind === "int") {
+      const opts = { step: p.kind === "int" ? 1 : 0.1,
+                     precision: p.kind === "int" ? 0 : 5 };
+      if (p.min != null) opts.min = p.min;
+      if (p.max != null) opts.max = p.max;
+      node.addWidget("number", p.label, p.default, set, opts);
+    } else if (p.kind === "enum") {
+      node.addWidget("combo", p.label, p.default, set, { values: p.choices });
+    } else if (p.kind === "bool") {
+      node.addWidget("toggle", p.label, !!p.default, set);
+    } else if (p.kind === "int_list") {
+      const text = (p.default || []).join(",");
+      node.properties[p.name] = text;
+      node.addWidget("text", p.label, text, set);
+    } else {
+      node.addWidget("text", p.label, String(p.default ?? ""), set);
+    }
+  }
+
+  // Grow a node so its title, widget labels and descriptor lines all fit — the
+  // engine's computeSize() uses a fixed base width, so without this long strings
+  // render outside the node box. `spec` is passed explicitly because node.type is
+  // set by createNode before the constructor body runs but we keep it explicit.
+  function fitNode(node, spec) {
+    node.size = node.computeSize();
+    _meas.font = "14px Arial";
+    let w = _meas.measureText(node.title || "").width;
+    (node.widgets || []).forEach((wd) => {
+      w = Math.max(w, _meas.measureText(`${wd.name}: ${wd.value}`).width);
+    });
+    (node._descriptors || []).forEach((d) => {
+      w = Math.max(w, _meas.measureText(`${d.label}: ${d.value}`).width);
+    });
+    node.size[0] = Math.max(node.size[0], Math.ceil(w) + 46);
+    if (node._descriptors && node._descriptors.length) {
+      node.size[1] += node._descriptors.length * 15 + 4;   // room for the subtitle
+    }
+    const isTrain = (spec && spec.id === "train.train") || node.type === "train.train";
+    if (isTrain) {
+      node.size[1] += 18;   // a dedicated lane below the slots for the progress bar
+    }
+  }
+
+  // ---- register every catalog node as a graph-engine type --------------------
+  function registerNodes() {
+    for (const spec of CATALOG.nodes) {
+      SPEC_BY_TYPE[spec.id] = spec;
+      const Node = function () {
+        spec.inputs.forEach((pt) => this.addInput(pt.name, pt.type));
+        spec.outputs.forEach((pt) => this.addOutput(pt.name, pt.type));
+        this.properties = {};
+        this._descriptors = [];   // readonly values drawn as a compact subtitle
+        spec.params.forEach((p) => {
+          if (p.readonly) {
+            this.properties[p.name] = p.default;
+            this._descriptors.push({ label: p.label, value: p.default });
+          } else {
+            addWidget(this, p);
+          }
+        });
+        fitNode(this, spec);
+      };
+      Node.title = spec.title_short || spec.title;
+      Node.desc = spec.help;
+      // Draw readonly descriptors as small muted lines, plus the Train node's live
+      // status (glowing border + epoch progress bar) while a run is attached.
+      Node.prototype.onDrawForeground = function (ctx) {
+        if (this.flags.collapsed) return;
+        if (this._descriptors && this._descriptors.length) {
+          ctx.save();
+          ctx.font = "11px Arial";
+          ctx.fillStyle = "#8b98a9";
+          let y = this.size[1] - this._descriptors.length * 15 + 3;
+          for (const d of this._descriptors) {
+            ctx.fillText(`${d.label}: ${d.value}`, 12, y);
+            y += 15;
+          }
+          ctx.restore();
+        }
+        if (this.type === "train.train" && this._phase) drawTrainStatus(this, ctx);
+      };
+      LiteGraph.registerNodeType(spec.id, Node);
+    }
+  }
+
+  // ---- left palette: searchable dropdowns, grouped by category ----------------
+  // Each category is a collapsible block (a dropdown). Entries carry a lowercase
+  // haystack (title + id + help) for the filter. Visibility is a single pass over
+  // both the current query and each block's collapsed state.
+  let paletteBlocks = [];   // [{ block, items:[{el, hay}], collapsed }]
+  let paletteQueryStr = "";
+
+  function buildPalette() {
+    const list = document.getElementById("paletteList");
+    const empty = document.getElementById("paletteEmpty");
+    paletteBlocks = [];
+    const byCat = {};
+    CATALOG.nodes.forEach((n) => (byCat[n.category] ||= []).push(n));
+    CATALOG.categories.forEach((cat) => {
+      if (!byCat[cat]) return;
+      const block = document.createElement("div");
+      block.className = "catblock collapsed";       // dropdowns start closed
+      const h = document.createElement("div");
+      h.className = "cat";
+      h.innerHTML = `<span class="caret">▶</span><span>${cat}</span>` +
+        `<span class="catcount">${byCat[cat].length}</span>`;
+      const entry = { block, items: [], collapsed: true };
+      h.onclick = () => { entry.collapsed = !entry.collapsed; applyPalette(); };
+      block.appendChild(h);
+      byCat[cat].forEach((spec) => {
+        const item = document.createElement("div");
+        item.className = "item" + (spec.experimental ? " exp" : "");
+        item.title = spec.help;
+        item.innerHTML = `<span>${spec.title}</span>` +
+          (spec.experimental ? `<span class="tag">soon</span>` : "");
+        item.onclick = () => addNode(spec.id);
+        block.appendChild(item);
+        entry.items.push({ el: item, hay: `${spec.title} ${spec.id} ${spec.help || ""}`.toLowerCase() });
+      });
+      list.appendChild(block);
+      paletteBlocks.push(entry);
+    });
+    list.appendChild(empty);   // keep the empty-state message last
+    applyPalette();
+  }
+
+  // Single visibility pass. An item shows when it matches the query AND its block is
+  // open; an active search force-opens any block that has matches so results appear.
+  function applyPalette() {
+    const q = paletteQueryStr;
+    let total = 0;
+    for (const b of paletteBlocks) {
+      const open = !b.collapsed || !!q;
+      let shown = 0;
+      for (const { el, hay } of b.items) {
+        const match = !q || hay.includes(q);
+        el.style.display = (match && open) ? "" : "none";
+        if (match) shown++;
+      }
+      b.block.style.display = shown ? "" : "none";
+      b.block.classList.toggle("collapsed", b.collapsed && !q);
+      total += shown;
+    }
+    document.getElementById("paletteEmpty").style.display = total ? "none" : "block";
+  }
+
+  function filterPalette(q) { paletteQueryStr = (q || "").trim().toLowerCase(); applyPalette(); }
+
+  function firstVisibleItem() {
+    for (const { items } of paletteBlocks) {
+      for (const { el } of items) if (el.style.display !== "none") return el;
+    }
+    return null;
+  }
+
+  function focusPaletteSearch() {
+    const q = document.getElementById("paletteQuery");
+    q.focus(); q.select();
+  }
+
+  // Wire the search box + global hotkeys (⌘/Ctrl+K, or "/" when not already typing).
+  function initPaletteSearch() {
+    const q = document.getElementById("paletteQuery");
+    q.addEventListener("input", () => filterPalette(q.value));
+    q.addEventListener("keydown", (e) => {
+      if (e.key === "Escape") { q.value = ""; filterPalette(""); q.blur(); }
+      else if (e.key === "Enter") { const it = firstVisibleItem(); if (it) it.click(); }
+    });
+    window.addEventListener("keydown", (e) => {
+      const typing = /^(input|textarea|select)$/i.test(e.target.tagName || "");
+      if ((e.metaKey || e.ctrlKey) && e.key.toLowerCase() === "z") {
+        e.preventDefault();
+        e.shiftKey ? redo() : undo();
+      } else if ((e.metaKey || e.ctrlKey) && e.key.toLowerCase() === "k") {
+        e.preventDefault(); focusPaletteSearch();
+      } else if (e.key === "/" && !typing) {
+        e.preventDefault(); focusPaletteSearch();
+      }
+    });
+  }
+
+  // ---- palette: collapse toggle + drag-to-resize -----------------------------
+  // Width persists across reloads; on narrow screens the palette is an overlay
+  // drawer (see the CSS media query) and starts hidden.
+  const isNarrow = () => window.matchMedia("(max-width:720px)").matches;
+  function initPaletteResize() {
+    const app = document.getElementById("app");
+    const rez = document.getElementById("resizer");
+    const toggle = document.getElementById("paletteToggle");
+    const root = document.documentElement;
+
+    const savedW = parseInt(localStorage.getItem("palette.w"), 10);
+    if (savedW >= 160 && savedW <= 480) root.style.setProperty("--palette-w", savedW + "px");
+    if (isNarrow() || localStorage.getItem("palette.hidden") === "1")
+      app.classList.add("palette-hidden");
+
+    toggle.onclick = () => {
+      const hidden = app.classList.toggle("palette-hidden");
+      if (!isNarrow()) localStorage.setItem("palette.hidden", hidden ? "1" : "0");
+      resize();
+    };
+
+    let dragging = false;
+    rez.addEventListener("mousedown", (e) => {
+      dragging = true; e.preventDefault();
+      rez.classList.add("dragging"); document.body.style.cursor = "col-resize";
+    });
+    window.addEventListener("mousemove", (e) => {
+      if (!dragging) return;
+      root.style.setProperty("--palette-w", Math.max(160, Math.min(480, e.clientX)) + "px");
+      resize();
+    });
+    window.addEventListener("mouseup", () => {
+      if (!dragging) return;
+      dragging = false; rez.classList.remove("dragging"); document.body.style.cursor = "";
+      const w = parseInt(getComputedStyle(root).getPropertyValue("--palette-w"), 10);
+      if (w) localStorage.setItem("palette.w", w);
+    });
+  }
+
+  // ---- validation/training panel: drag by its title bar, resize by the grip ---
+  // Position + size persist across reloads. On first interaction we switch the
+  // panel from its bottom-right CSS anchor to explicit top/left px so both the
+  // drag and the native resize grip (bottom-right corner) behave predictably.
+  function initOutPanel() {
+    const out = document.getElementById("out");
+    const handle = document.getElementById("outTitle");
+    const KEY = "out.box";
+
+    const anchorTopLeft = () => {
+      const r = out.getBoundingClientRect();
+      out.style.left = r.left + "px"; out.style.top = r.top + "px";
+      out.style.right = "auto"; out.style.bottom = "auto";
+    };
+    const save = () => {
+      const r = out.getBoundingClientRect();
+      try {
+        localStorage.setItem(KEY, JSON.stringify({
+          left: Math.round(r.left), top: Math.round(r.top),
+          w: out.style.width ? Math.round(r.width) : null,
+          h: out.style.height ? Math.round(r.height) : null }));
+      } catch (e) { /* quota/private mode */ }
+    };
+    // Keep the panel (at least its title bar) on-screen after a drag or a
+    // window resize, so it can never be lost off the edge.
+    const clampIntoView = () => {
+      const r = out.getBoundingClientRect();
+      const left = Math.max(4, Math.min(r.left, window.innerWidth - r.width - 4));
+      const top = Math.max(48, Math.min(r.top, window.innerHeight - 40));
+      out.style.left = left + "px"; out.style.top = top + "px";
+    };
+
+    // Anchor immediately so the resize grip works from the first drag, keeping
+    // the panel visually where the CSS placed it.
+    anchorTopLeft();
+    try {
+      const s = JSON.parse(localStorage.getItem(KEY) || "null");
+      if (s) {
+        out.style.left = s.left + "px"; out.style.top = s.top + "px";
+        if (s.w) out.style.width = s.w + "px";
+        if (s.h) out.style.height = s.h + "px";
+        clampIntoView();
+      }
+    } catch (e) { /* ignore malformed geometry */ }
+
+    // Drag by the title bar.
+    let ox = 0, oy = 0, dragging = false;
+    handle.addEventListener("mousedown", (e) => {
+      dragging = true;
+      const r = out.getBoundingClientRect();
+      ox = e.clientX - r.left; oy = e.clientY - r.top;
+      e.preventDefault();
+    });
+    window.addEventListener("mousemove", (e) => {
+      if (!dragging) return;
+      out.style.left = (e.clientX - ox) + "px";
+      out.style.top = (e.clientY - oy) + "px";
+    });
+    window.addEventListener("mouseup", () => {
+      if (!dragging) return;
+      dragging = false; clampIntoView(); save();
+    });
+
+    // Detect a native resize (grip drag anywhere but the title bar) and persist it.
+    out.addEventListener("mousedown", (e) => {
+      if (handle.contains(e.target)) return;   // that's a move, handled above
+      const w0 = out.offsetWidth, h0 = out.offsetHeight;
+      const up = () => {
+        document.removeEventListener("mouseup", up);
+        if (out.offsetWidth !== w0 || out.offsetHeight !== h0) {
+          out.style.width = out.offsetWidth + "px";
+          out.style.height = out.offsetHeight + "px";
+          save();
+        }
+      };
+      document.addEventListener("mouseup", up);
+    });
+
+    window.addEventListener("resize", clampIntoView);
+  }
+
+  // Drop a node near the current view centre, then re-validate.
+  function addNode(typeId) {
+    const node = LiteGraph.createNode(typeId);
+    const [cx, cy] = canvas.convertOffsetToCanvas
+      ? canvas.convertOffsetToCanvas([canvas.canvas.width / 2, canvas.canvas.height / 2])
+      : [200, 200];
+    node.pos = [cx + (Math.random() * 60 - 30), cy + (Math.random() * 60 - 30)];
+    node._spawn = performance.now();     // triggers the drop-in ring
+    graph.add(node);
+    scheduleValidate();
+  }
+
+  // ---- serialize the canvas to app/graph.py's graph JSON ---------------------
+  function serialize() {
+    const nodes = graph._nodes.map((n) => ({
+      id: String(n.id),
+      type: n.type,
+      params: collectParams(n),
+      pos: [Math.round(n.pos[0]), Math.round(n.pos[1])],
+    }));
+    const links = [];
+    for (const id in graph.links) {
+      const l = graph.links[id];
+      if (!l) continue;
+      const src = graph.getNodeById(l.origin_id);
+      const dst = graph.getNodeById(l.target_id);
+      if (!src || !dst) continue;
+      links.push({
+        from: String(l.origin_id), from_port: src.outputs[l.origin_slot].name,
+        to: String(l.target_id), to_port: dst.inputs[l.target_slot].name,
+      });
+    }
+    return { nodes, links };
+  }
+
+  // A node's params as a flat map, parsing int_list text ("128,64") back to [128,64].
+  function collectParams(node) {
+    const spec = SPEC_BY_TYPE[node.type];
+    const out = {};
+    (spec.params || []).forEach((p) => {
+      let v = node.properties[p.name];
+      if (p.kind === "int_list") {
+        v = String(v).split(",").map((s) => parseInt(s.trim(), 10)).filter((x) => !isNaN(x));
+      }
+      out[p.name] = v;
+    });
+    return out;
+  }
+
+  // ---- canvas persistence ----------------------------------------------------
+  // The canvas lives only in memory, so navigating away would lose it. Mirror it
+  // to localStorage on every edit and restore it on boot.
+  const STORE_KEY = "blueprint.graph";
+  function persist() {
+    try { localStorage.setItem(STORE_KEY, JSON.stringify(serialize())); } catch (e) { /* quota/private mode */ }
+  }
+  function restore() {
+    try {
+      const raw = localStorage.getItem(STORE_KEY);
+      if (!raw) return false;
+      const g = JSON.parse(raw);
+      if (!g.nodes || !g.nodes.length) return false;
+      rebuild(g);
+      return true;
+    } catch (e) { return false; }
+  }
+
+  // export blueprint button
+  function exportBlueprint() {
+    const doc = {
+      format: "modulearn.blueprint", version: 1,
+      graph: serialize(),
+    };
+    const blob = new Blob([JSON.stringify(doc, null, 2)],
+      { type: "application/json" });
+    const a = document.createElement("a");
+    a.href = URL.createObjectURL(blob);
+    a.download = "modulearn-blueprint.json";
+    a.click();
+    URL.revokeObjectURL(a.href);
+  }
+
+  // Load a blueprint file back onto the canvas (inverse of exportBlueprint).
+  // Accepts either our {format, version, graph} envelope or a bare graph JSON.
+  // Node types this registry doesn't know are dropped and reported, never
+  // silently lost — the file may come from a differently-configured host.
+  function importBlueprint(file) {
+    const reader = new FileReader();
+    reader.onload = () => {
+      let doc;
+      try { doc = JSON.parse(reader.result); }
+      catch (e) { setPanel("err", "not valid JSON"); return; }
+      const g = doc.graph || doc;
+      if (!g || !Array.isArray(g.nodes)) { setPanel("err", "no nodes in file"); return; }
+      const unknown = [...new Set(g.nodes.filter((n) => !SPEC_BY_TYPE[n.type])
+                                         .map((n) => n.type))];
+      g.nodes = g.nodes.filter((n) => SPEC_BY_TYPE[n.type]);
+      graph.clear();
+      rebuild(g);
+      // Surface skipped nodes on the next validate() so the note isn't clobbered
+      // by the compile result that scheduleValidate() paints ~250ms later.
+      importWarning = unknown.length ? "skipped unknown nodes: " + unknown.join(", ") : "";
+      scheduleValidate();
+    };
+    reader.onerror = () => setPanel("err", "could not read file");
+    reader.readAsText(file);
+  }
+
+  // ---- live validation via the dry-run compile endpoint ----------------------
+  let validateTimer = null;
+  let importWarning = "";   // one-shot notice (e.g. skipped nodes) for next validate()
+  function scheduleValidate() {
+    stopPolling();           // any edit means we're no longer just watching a run
+    clearTrainStatus();      // and the finished-run glow no longer applies
+    persist();
+    captureHistory();        // snapshot this edit for undo/redo
+    clearTimeout(validateTimer);
+    validateTimer = setTimeout(validate, 250);
+  }
+
+  async function validate() {
+    // A pending import note rides along with this validation, then clears.
+    const banner = importWarning
+      ? `<span class="err">⚠ ${escapeHtml(importWarning)}</span><br>` : "";
+    importWarning = "";
+    const graphJson = serialize();
+    if (!graphJson.nodes.length) { graphValid = false; setTrainState("invalid");
+      setPanel("k", banner + "Empty graph."); return; }
+    try {
+      const r = await fetch("/api/graph/compile", {
+        method: "POST", headers: { "content-type": "application/json" },
+        body: JSON.stringify(graphJson),
+      });
+      const j = await r.json();
+      if (r.ok) {
+        graphValid = true; setTrainState("ready");
+        const cfg = j.config;
+        setPanel("ok", banner + "✓ valid — resolved RunConfig:<br>" +
+          Object.entries(cfg).map(([k, v]) =>
+            `<span class="k">${k}</span> ${escapeHtml(JSON.stringify(v))}`).join("<br>"));
+      } else {
+        graphValid = false; setTrainState("invalid");
+        const errs = (j.detail && j.detail.errors) || [j.detail || "unknown error"];
+        // Each line deep-links to its node when the message names one.
+        setPanel("err", banner + "✗ " + errs.map((e) => {
+          const ids = idsInError(e), safe = escapeHtml(e);
+          return ids.length
+            ? `<span class="errline" data-node="${ids[0]}">• ${safe}</span>`
+            : `• ${safe}`;
+        }).join("<br>"));
+      }
+    } catch (e) {
+      setPanel("err", "request failed: " + escapeHtml(e));
+    }
+  }
+
+  // Re-validate whenever the graph structure changes. These three are real LGraph
+  // callbacks fired by graph-engine.js; widget-value edits
+  // re-validate via each widget's set() callback above.
+  graph.onNodeConnectionChange = scheduleValidate;
+  graph.onNodeAdded = scheduleValidate;
+  graph.onNodeRemoved = scheduleValidate;
+
+  // ---- live run tracking -----------------------------------------------------
+  // After launching, poll the run's state into the panel so training is visible
+  // right here on the canvas — no trip to the classic dashboard needed.
+  let pollTimer = null;
+  function stopPolling() {
+    clearTimeout(pollTimer); pollTimer = null;
+    const dot = document.querySelector("#bar .dot");
+    if (dot) dot.classList.remove("live");
+  }
+
+  // Clear a finished run's glow from the Train node (called when the graph is edited).
+  function clearTrainStatus() {
+    const tn = trainNode();
+    if (tn) { tn._phase = null; tn._progress = 0; tn._running = false; }
+    const dot = document.querySelector("#bar .dot");
+    if (dot) dot.classList.remove("live");
+    hideChart();
+    document.getElementById("outTitle").textContent = "VALIDATION";
+  }
+
+  // Write the validation/status panel, cross-fading only when the state changes.
+  function setPanel(cls, html) {
+    const body = document.getElementById("outBody");
+    body.className = cls;                       // resets (drops any .flash)
+    if (!reduceMotion && body._lastClass !== cls) {
+      void body.offsetWidth; body.classList.add("flash");
+    }
+    body._lastClass = cls;
+    body.innerHTML = html;
+  }
+
+  function fmt(v, unit) { return v == null ? "—" : (+v).toFixed(3) + (unit || ""); }
+
+  // Live learning curve (train vs val loss) drawn from the run's per-epoch metrics.
+  // Redrawn each poll so you watch the model learn on the canvas itself. Keys match
+  // the metric rows the host writes via reporter.metric(epoch=, train=, val=).
+  const CHART_SERIES = [
+    { key: "val", color: "#c8663c", label: "val" },
+    { key: "train", color: "#5aa9e6", label: "train" },
+  ];
+  function drawChart(metrics) {
+    const cv = document.getElementById("chart");
+    const pts = (metrics || []).filter((m) => typeof m.epoch === "number");
+    if (pts.length < 2) { cv.style.display = "none"; return; }
+    cv.style.display = "block";
+    const dpr = window.devicePixelRatio || 1;
+    const W = cv.clientWidth || 330, H = 120;
+    cv.width = W * dpr; cv.height = H * dpr;
+    const ctx = cv.getContext("2d");
+    ctx.setTransform(dpr, 0, 0, dpr, 0, 0);
+    ctx.clearRect(0, 0, W, H);
+    const pad = { l: 34, r: 8, t: 8, b: 18 };
+
+    const ys = [];
+    CHART_SERIES.forEach((s) => pts.forEach((m) => {
+      const v = m[s.key]; if (typeof v === "number" && isFinite(v)) ys.push(v);
+    }));
+    if (!ys.length) { cv.style.display = "none"; return; }
+    let ymin = Math.min(...ys), ymax = Math.max(...ys);
+    if (ymin === ymax) ymax = ymin + 1;
+    const yr = ymax - ymin; ymin -= yr * 0.08; ymax += yr * 0.08;
+    const xmin = pts[0].epoch, xmax = pts[pts.length - 1].epoch;
+    const X = (e) => pad.l + (xmax === xmin ? 0 : (e - xmin) / (xmax - xmin)) * (W - pad.l - pad.r);
+    const Y = (v) => pad.t + (1 - (v - ymin) / (ymax - ymin)) * (H - pad.t - pad.b);
+
+    // faint horizontal grid + y-axis labels
+    ctx.font = "9px ui-monospace, monospace"; ctx.textBaseline = "middle";
+    for (let i = 0; i <= 2; i++) {
+      const v = ymin + (ymax - ymin) * i / 2, y = Y(v);
+      ctx.strokeStyle = "rgba(255,255,255,.07)"; ctx.lineWidth = 1;
+      ctx.beginPath(); ctx.moveTo(pad.l, y); ctx.lineTo(W - pad.r, y); ctx.stroke();
+      ctx.fillStyle = "#8b98a9"; ctx.fillText(v.toFixed(1), 2, y);
+    }
+    // series lines with an emphasized latest point
+    CHART_SERIES.forEach((s) => {
+      ctx.beginPath(); let started = false, last = null;
+      pts.forEach((m) => {
+        const v = m[s.key]; if (typeof v !== "number" || !isFinite(v)) return;
+        const x = X(m.epoch), y = Y(v);
+        started ? ctx.lineTo(x, y) : (ctx.moveTo(x, y), started = true);
+        last = m;
+      });
+      ctx.strokeStyle = s.color; ctx.lineWidth = 1.5; ctx.stroke();
+      if (last) {
+        ctx.beginPath(); ctx.arc(X(last.epoch), Y(last[s.key]), 2.6, 0, Math.PI * 2);
+        ctx.fillStyle = s.color; ctx.fill();
+      }
+    });
+    // legend + axis unit
+    ctx.textBaseline = "alphabetic";
+    let lx = pad.l;
+    CHART_SERIES.forEach((s) => {
+      ctx.fillStyle = s.color; ctx.fillRect(lx, H - 8, 9, 3);
+      ctx.fillStyle = "#8b98a9"; ctx.fillText(s.label, lx + 12, H - 5); lx += 46;
+    });
+    ctx.fillStyle = "#5f6b7a"; ctx.fillText("loss · epoch", W - 70, H - 5);
+  }
+
+  function hideChart() { document.getElementById("chart").style.display = "none"; }
+
+  async function pollRun(runId) {
+    let st, j;
+    try {
+      j = await (await fetch("/api/run/" + runId)).json();
+      st = j.state || {};
+    } catch (e) { stopPolling(); return; }
+    drawChart(j.metrics);
+    document.getElementById("outTitle").textContent = "TRAINING";
+
+    const phase = st.phase || "?";
+    const ep = st.epoch != null ? st.epoch + 1 : 0, eps = st.epochs || "?";
+    const prog = (typeof st.epochs === "number" && st.epochs > 0)
+      ? (st.epoch + 1) / st.epochs : 0;
+    const done = phase === "done", errored = phase === "error";
+
+    // Feed the animated Train node + header dot.
+    const tn = trainNode();
+    if (tn) { tn._phase = phase; tn._progress = prog; tn._running = phase === "running"; }
+    const dot = document.querySelector("#bar .dot");
+    if (dot) dot.classList.toggle("live", phase === "running");
+    setTrainState(phase === "running" ? "running" : (graphValid ? "ready" : "invalid"));
+
+    setPanel(errored ? "err" : (done ? "ok" : "k"),
+      `<b>${done ? "✓" : errored ? "✗" : "▶"} ${runId}</b> · ${phase}<br>` +
+      `<span class="k">epoch</span> ${ep}/${eps}` +
+      (phase === "running" ? `  <span class="k">(${Math.round(prog * 100)}%)</span>` : "") + `<br>` +
+      `<span class="k">best val</span> ${fmt(st.best_val)}<br>` +
+      `<span class="k">test score</span> ${fmt(st.test_score)}` +
+      (errored && st.error ? `<br><span class="err">${st.error}</span>` : ""));
+
+    if (done || errored) { stopPolling(); refreshRuns(); return; }
+    pollTimer = setTimeout(() => pollRun(runId), 1500);
+  }
+
+  // ---- toolbar actions -------------------------------------------------------
+  async function train() {
+    const r = await fetch("/api/graph/start", {
+      method: "POST", headers: { "content-type": "application/json" },
+      body: JSON.stringify(serialize()),
+    });
+    const j = await r.json();
+    if (r.ok) {
+      stopPolling();
+      pollRun(j.run_id);        // start streaming live status into the panel
+    } else {
+      const errs = (j.detail && j.detail.errors) || [j.detail];
+      setPanel("err", "✗ cannot launch:<br>" + errs.map((e) => `• ${e}`).join("<br>"));
+    }
+  }
+
+  async function refreshRuns() {
+    const sel = document.getElementById("runs");
+    try {
+      const j = await (await fetch("/api/runs")).json();
+      sel.innerHTML = `<option value="">— saved blueprints —</option>` +
+        j.runs.map((r) => `<option value="${r.run_id}">${r.run_id} (${r.phase})</option>`).join("");
+    } catch { /* dashboard offline is fine */ }
+  }
+
+  // Load a run's saved graph.json back onto the canvas (reopen / fork a run).
+  async function loadRun() {
+    const run = document.getElementById("runs").value;
+    if (!run) return;
+    const r = await fetch("/api/graph/" + run);
+    const body = document.getElementById("outBody");
+    if (!r.ok) { body.className = "err"; body.textContent = `no saved blueprint for ${run}`; return; }
+    const g = await r.json();
+    graph.clear();
+    rebuild(g);
+    scheduleValidate();
+  }
+
+  // Reconstruct engine nodes + links from our graph JSON (inverse of serialize).
+  function rebuild(g) {
+    const byId = {};
+    (g.nodes || []).forEach((gn, i) => {
+      const node = LiteGraph.createNode(gn.type);
+      if (!node) return;
+      node.pos = Array.isArray(gn.pos) ? [gn.pos[0], gn.pos[1]] : [80 + (i % 4) * 240, 80 + Math.floor(i / 4) * 170];
+      (SPEC_BY_TYPE[gn.type].params || []).forEach((p) => {
+        let v = (gn.params || {})[p.name];
+        if (p.kind === "int_list" && Array.isArray(v)) v = v.join(",");
+        if (v === undefined) return;
+        node.properties[p.name] = v;
+        // Match the widget by name (index no longer aligns: readonly params have none).
+        const w = (node.widgets || []).find((wd) => wd.name === p.label);
+        if (w) w.value = v;
+        const d = (node._descriptors || []).find((dd) => dd.label === p.label);
+        if (d) d.value = v;
+      });
+      fitNode(node, SPEC_BY_TYPE[gn.type]);
+      graph.add(node);
+      byId[gn.id] = node;
+    });
+    (g.links || []).forEach((l) => {
+      const src = byId[l.from], dst = byId[l.to];
+      if (!src || !dst) return;
+      const so = src.outputs.findIndex((p) => p.name === l.from_port);
+      const di = dst.inputs.findIndex((p) => p.name === l.to_port);
+      if (so >= 0 && di >= 0) src.connect(so, dst, di);
+    });
+  }
+
+  // ---- boot ------------------------------------------------------------------
+  async function boot() {
+    // Header branding comes from the host app (create_app title/subtitle).
+    try {
+      const meta = await (await fetch("/api/meta")).json();
+      if (meta.title) document.getElementById("brand").firstChild.textContent = meta.title + " ";
+      if (meta.subtitle) document.getElementById("brandSub").textContent = "· " + meta.subtitle;
+      if (meta.title) document.title = meta.title + " — visual training editor";
+    } catch { /* branding is optional */ }
+    CATALOG = await (await fetch("/api/nodes")).json();
+    // Color the wires themselves by port type — including each scalar/<field>
+    // subtype — so they match the flowing-pulse colors.
+    const linkColors = {};
+    CATALOG.nodes.forEach((n) => [...n.inputs, ...n.outputs].forEach(
+      (p) => { linkColors[p.type] = linkColor(p.type); }));
+    LGraphCanvas.link_type_colors = Object.assign(
+      {}, LGraphCanvas.link_type_colors, linkColors);
+    registerNodes();
+    buildPalette();
+    initPaletteSearch();
+    initPaletteResize();
+    setTrainState("invalid");            // nothing wired yet
+    resize();
+    initOutPanel();                      // draggable + resizable status panel
+    canvas.onDrawForeground = ambientDraw;   // flowing wires, spawn rings, port cues
+    graph.start();
+    animLoop();                              // ambient repaint loop
+    if (restore()) scheduleValidate();   // bring back the last canvas after a reload
+    captureHistory();                    // seed history entry 0 (empty or restored canvas)
+    updateUndoButtons();
+    refreshRuns();
+    document.getElementById("trainBtn").onclick = train;
+    document.getElementById("loadBtn").onclick = loadRun;
+    document.getElementById("clearBtn").onclick = () => { graph.clear(); scheduleValidate(); };
+    document.getElementById("fitBtn").onclick = zoomToFit;
+    document.getElementById("exportBtn").onclick = exportBlueprint;
+    document.getElementById("importBtn").onclick = () =>
+      document.getElementById("importFile").click();
+    document.getElementById("importFile").onchange = (e) => {
+      if (e.target.files[0]) importBlueprint(e.target.files[0]);
+      e.target.value = "";                       // allow re-importing the same file
+    };
+    // Delegate clicks on error lines to deep-link back to the offending node.
+    document.getElementById("outBody").addEventListener("click", (e) => {
+      const el = e.target.closest(".errline");
+      if (el && el.dataset.node) focusNode(el.dataset.node);
+    });
+    // Debug handle for automated/headless testing of the live editor.
+    window.__bp = { graph, canvas, serialize, addNode, validate, rebuild, train,
+                    pollRun, persist, restore, SPEC_BY_TYPE,
+                    zoomToFit, focusNode, setTrainState,
+                    exportBlueprint, importBlueprint,
+                    undo, redo, captureHistory, get histIdx() { return histIdx; },
+                    history };
+  }
+  boot();
+})();