yaml-flow 6.0.0 → 7.0.0

package/browser/live-cards.js

@@ -1,17 +1,19 @@
 // live-cards.js — LiveCards v3: Node-based Board/Canvas engine
 //
 // Schema: Each node has { id } required; all else optional.
-//   id, meta, card_data, requires, provides, source_defs, compute, view
-//   Nodes with view render as cards; nodes with source_defs but no view render as source pills in canvas.
-//   compute[] — ordered array of { bindTo, expr } JSONata steps → writes to node.computed_values (ephemeral)
-//   source_defs[] — open objects: only bindTo + outputFile matter to the engine; all other fields are
-//               passed verbatim to the board's task-executor (--in JSON). Users define their own
-//               shape (kind, url, mailbox, channel, model, ...) per executor.
-//   requires[] — upstream node IDs; engine subscribes automatically
+//   id, meta, card_data, requires, provides, view
+//   Nodes with view render as cards; nodes with no view but with source_defs declared on the
+//   underlying card definition render as source pills in canvas mode (source_defs are runtime-only;
+//   they are not interpreted here).
+//   requires[] — upstream provider tokens; engine subscribes automatically
 //   provides[] — [{ bindTo, src }] explicit downstream token bindings
+//   computed_values — derived values produced by the runtime; rendered as-is, never recomputed here
+//
+// Rendering contract: this module renders derived state only. View bind paths resolve to one of
+//   card_data | requires | computed_values | runtime_state. Raw fetched-source payloads stay in the
+//   runtime and never reach the Board.
 //
 // Uses Bootstrap 5 for layout/forms, optional Chart.js for charts.
-// Uses CardCompute (card-compute.js) for declarative compute expressions.
 //
 // API:
 //   const engine = LiveCard.init({ resolve, onPatch, onPatchState, onRefresh, onAction, getChatMessages, markdown, sanitize, chartLib });
@@ -24,8 +26,15 @@
 //   engine.appendChatMessage(nodeId, role, text)
 //   engine.registerRenderer(name, fn)
 //
-//   const board = LiveCard.Board(engine, el, { nodes, positions?, mode, canvas })
-//   board.setMode('board'|'canvas'), board.autoLayout(), board.add(node), board.remove(id)
+//   Reactive board (preferred): state in, view out. No destructive re-renders.
+//   const board = LiveCard.Board(engine, el, { initialState, getNodeIds, selectNode, mode?, canvas? });
+//   board.setState(nextState)          — diff vs prev; per-node updates only
+//   board.destroy()
+//
+//   Imperative core (advanced): direct node-list manipulation.
+//   const core = LiveCard.BoardCore(engine, el, { nodes, positions?, mode, canvas });
+//   core.add(node), core.remove(id), core.reorder(ids), core.updateNode(id, model)
+//   core.setMode('board'|'canvas'), core.setDevMode(flag), core.autoLayout(), core.clear(), core.destroy()
 
 // eslint-disable-next-line no-unused-vars
 var LiveCard = (function () {
@@ -230,6 +239,30 @@ var LiveCard = (function () {
     const _formState = {};  // stateKey → { baseValues, journal }
     const _notesState = {}; // stateKey → { baseContent, journal|null }
     const _todoState = {};  // stateKey → { currentState, pending } for todo dirty tracking
+
+    /**
+     * Overlay a "Saving…" spinner over `el` while a patch is in-flight.
+     * The overlay is removed automatically on the next SSE re-render because
+     * every editable renderer does `el.innerHTML = …` on refresh.
+     */
+    function _showSavingOverlay(el) {
+      // Ensure the container is a positioned ancestor so the overlay can fill it.
+      if (getComputedStyle(el).position === 'static') el.style.position = 'relative';
+      const overlay = document.createElement('div');
+      overlay.className = 'lc-saving-overlay';
+      overlay.setAttribute('aria-live', 'polite');
+      overlay.style.cssText = [
+        'position:absolute', 'inset:0',
+        'background:rgba(255,255,255,0.78)',
+        'display:flex', 'align-items:center', 'justify-content:center',
+        'gap:0.5rem', 'z-index:20', 'border-radius:inherit',
+        'pointer-events:all',   // blocks all clicks on underlying inputs
+      ].join(';');
+      overlay.innerHTML =
+        '<span class="spinner-border spinner-border-sm text-primary" role="status" aria-hidden="true"></span>' +
+        '<span class="text-primary fw-medium small">Saving…</span>';
+      el.appendChild(overlay);
+    }
     const _renderers = {}; // kind → fn
     const _nodeEls = {};   // nodeId → { container, resultEl, uid }
     const _chatModal = {
@@ -275,11 +308,6 @@ var LiveCard = (function () {
       return _cleanup[id];
     }
 
-    function _runCompute() {
-      // Runtime payload is authoritative; UI never recomputes derived values.
-      return Promise.resolve();
-    }
-
     function _ensureChatModal() {
       if (_chatModal.backdrop) return;
 
@@ -767,11 +795,9 @@ var LiveCard = (function () {
       const ns = {
         card: node && node.card ? node.card : {},
         card_data: node && node.card_data ? node.card_data : {},
-        fetched_sources: node && node.fetched_sources ? node.fetched_sources : {},
         requires: node && node.requires ? node.requires : {},
         computed_values: node && node.computed_values ? node.computed_values : {},
         runtime_state: node && node.runtime_state ? node.runtime_state : {},
-        data_objects: node && node.data_objects ? node.data_objects : {},
       };
 
       if (!Object.prototype.hasOwnProperty.call(ns, root)) return undefined;
@@ -1181,6 +1207,7 @@ var LiveCard = (function () {
         const nextValues = getEffectiveValues();
         cfg.onPatchState(node.id, { fieldValues: nextValues });
         btn.textContent = 'Saving...';
+        _showSavingOverlay(el);
       }, { signal });
 
       discardBtn.addEventListener('click', () => {
@@ -1259,6 +1286,7 @@ var LiveCard = (function () {
         const nextValue = textarea.value;
         cfg.onPatchState(node.id, { notes: nextValue });
         saveBtn.textContent = 'Saving...';
+        _showSavingOverlay(el);
       }, { signal });
 
       discardBtn.addEventListener('click', () => {
@@ -1343,6 +1371,7 @@ var LiveCard = (function () {
         cfg.onPatchState(node.id, { fieldValues: rows });
         const saveBtn = el.querySelector('.lc-et-save');
         if (saveBtn) saveBtn.textContent = 'Saving...';
+        _showSavingOverlay(el);
       }
 
       function commitDiscard() {
@@ -1961,11 +1990,11 @@ var LiveCard = (function () {
     //
     // Usage:
     //   { "kind": "ref",
-    //     "data": { "bind": "fetched_sources.rebalance.proposed_trades",
+    //     "data": { "bind": "computed_values.proposed_trades",
     //               "viewBind": "card_data.display_mode",
     //               "fallbackKind": "table" } }
     //
-    // viewBind can point to any namespace: card_data, fetched_sources, requires, computed_values.
+    // viewBind can point to any namespace: card_data, requires, computed_values, runtime_state.
     // If the resolved view object contains a "bind" sub-path, that overrides data.bind.
     const _REF_KIND_WHITELIST = new Set([
       'table','editable-table','chart','metric','list','badge',
@@ -2180,7 +2209,7 @@ var LiveCard = (function () {
       if (node.card_data && node.card_data.status === 'error' && node.card_data.error) {
         resultEl.innerHTML = `<div class="text-danger small fw-semibold">Refresh failed</div><pre class="text-muted small mt-1" style="white-space:pre-wrap">${_esc(node.card_data.error)}</pre>`;
       } else {
-        _runCompute(node).then(function () { _renderElements(node, resultEl); });
+        _renderElements(node, resultEl);
       }
 
       // ---- Wire refresh ----
@@ -2275,7 +2304,7 @@ var LiveCard = (function () {
       if (node.card_data.status === 'error' && node.card_data.error) {
         info.resultEl.innerHTML = `<div class="text-danger small fw-semibold">Refresh failed</div><pre class="text-muted small mt-1" style="white-space:pre-wrap">${_esc(node.card_data.error)}</pre>`;
       } else {
-        _runCompute(node).then(function () { _renderElements(node, info.resultEl); });
+        _renderElements(node, info.resultEl);
       }
     }
 
@@ -2354,10 +2383,11 @@ var LiveCard = (function () {
   }
 
   // ===========================================================================
-  // Board — grid (board) and DAG (canvas) modes
+  // BoardCore — imperative grid (board) and DAG (canvas) modes.
+  // Most callers should use Board (reactive wrapper) instead.
   // ===========================================================================
 
-  function Board(engine, containerEl, opts) {
+  function BoardCore(engine, containerEl, opts) {
     opts = opts || {};
     const mode = { current: opts.mode || 'board' };
     const devMode = { current: opts.devMode || false };
@@ -2409,20 +2439,18 @@ var LiveCard = (function () {
 
     const canvasEl = document.createElement('div');
     canvasEl.className = 'lc-canvas';
-    const canvasHeight = co.height || '600px';
-    const canvasOverflow = co.overflow || 'auto';
-    canvasEl.style.cssText = 'position:relative;overflow:' + canvasOverflow + ';width:100%;height:' + canvasHeight + ';';
+    canvasEl.style.cssText = 'position:relative;overflow:auto;width:100%;';
     const canvasInner = document.createElement('div');
     canvasInner.className = 'lc-canvas-inner';
-    canvasInner.style.cssText = 'position:absolute;top:0;left:0;transform-origin:0 0;';
+    canvasInner.style.cssText = 'position:relative;transform-origin:0 0;min-width:100%;min-height:100%;';
     canvasEl.appendChild(canvasInner);
 
     // SVG overlay for edges
     const svgEl = document.createElementNS('http://www.w3.org/2000/svg', 'svg');
     svgEl.setAttribute('class', 'lc-canvas-edges');
-    svgEl.style.cssText = 'position:absolute;top:0;left:0;width:100%;height:100%;pointer-events:none;overflow:visible;';
+    svgEl.style.cssText = 'position:absolute;top:0;left:0;width:100%;height:100%;pointer-events:none;overflow:hidden;z-index:0;';
     const defs = document.createElementNS('http://www.w3.org/2000/svg', 'defs');
-    defs.innerHTML = '<marker id="lc-arrow" viewBox="0 0 10 10" refX="10" refY="5" markerWidth="8" markerHeight="8" orient="auto-start-reverse"><path d="M 0 0 L 10 5 L 0 10 z" fill="var(--bs-secondary,#6c757d)"/></marker>';
+    defs.innerHTML = '<marker id="lc-arrow" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto-start-reverse"><path d="M 0 1 L 8 5 L 0 9 z" fill="rgba(108,117,125,0.55)"/></marker>';
     svgEl.appendChild(defs);
     canvasInner.appendChild(svgEl);
 
@@ -2433,13 +2461,13 @@ var LiveCard = (function () {
       s.textContent = `
         .lc-canvas-card { position:absolute; min-width:${cvs.minWidth}px; cursor:grab; user-select:none; z-index:1; }
         .lc-canvas-card.lc-dragging { cursor:grabbing; z-index:10; box-shadow:0 8px 24px rgba(0,0,0,0.18)!important; }
-        .lc-canvas-card .card-body { overflow:auto; }
+        .lc-canvas-card .card-body { overflow:hidden; }
         .lc-canvas-card.lc-resizing { cursor:nwse-resize; z-index:10; }
         .lc-resize-handle { position:absolute; bottom:0; right:0; width:14px; height:14px; cursor:nwse-resize; z-index:2; opacity:0.4; transition:opacity .15s; }
         .lc-resize-handle:hover { opacity:1; }
         .lc-resize-handle::after { content:''; position:absolute; bottom:3px; right:3px; width:8px; height:8px; border-right:2px solid var(--bs-secondary,#6c757d); border-bottom:2px solid var(--bs-secondary,#6c757d); }
-        .lc-canvas-edges path.lc-edge-path { stroke:var(--bs-secondary,#6c757d); stroke-width:1.5; stroke-dasharray:6 4; animation:lc-edge-flow 0.6s linear infinite; }
-        .lc-canvas-edges line { stroke:var(--bs-secondary,#6c757d); stroke-width:1.5; }
+        .lc-canvas-edges path.lc-edge-path { stroke:rgba(100,140,200,0.5); stroke-width:2; fill:none; stroke-linecap:round; }
+        .lc-canvas-edges line { stroke:rgba(100,140,200,0.4); stroke-width:2; }
         @keyframes lc-edge-flow { to { stroke-dashoffset:-10; } }
         .lc-source-node { position:absolute; cursor:grab; user-select:none; z-index:1; }
         .lc-source-node.lc-dragging { cursor:grabbing; z-index:10; }
@@ -2545,32 +2573,9 @@ var LiveCard = (function () {
 
       const cardSection = document.createElement('div');
       cardSection.className = 'mb-4';
-      cardSection.innerHTML = '<h6 class="fw-semibold mb-2">Card Object (Editable)</h6>';
-
-      const editableCardObject = JSON.parse(JSON.stringify((node && node.card) ? node.card : {}));
-
-      const editor = document.createElement('textarea');
-      editor.className = 'form-control form-control-sm font-monospace';
-      editor.rows = 16;
-      editor.style.whiteSpace = 'pre';
-      editor.value = JSON.stringify(editableCardObject, null, 2);
-
-      const editorHint = document.createElement('div');
-      editorHint.className = 'small text-muted mt-2';
-      editorHint.textContent = 'Edit JSON and click Submit to apply updates to this card.';
-
-      const editorError = document.createElement('div');
-      editorError.className = 'small text-danger mt-1 d-none';
-
-      const submitBtn = document.createElement('button');
-      submitBtn.type = 'button';
-      submitBtn.className = 'btn btn-primary btn-sm mb-2';
-      submitBtn.textContent = 'Submit';
-
-      cardSection.appendChild(submitBtn);
-      cardSection.appendChild(editor);
-      cardSection.appendChild(editorHint);
-      cardSection.appendChild(editorError);
+      cardSection.innerHTML = '<h6 class="fw-semibold mb-2">Card Definition (Read-only)</h6>';
+      const cardDef = (node && node.card) ? node.card : {};
+      cardSection.innerHTML += `<pre style="background: #f5f5f5; padding: 10px; border-radius: 4px; overflow-x: auto; font-size: 12px; white-space: pre-wrap; word-wrap: break-word;">${_esc(JSON.stringify(cardDef, null, 2))}</pre>`;
       body.appendChild(cardSection);
 
       const computedSection = document.createElement('div');
@@ -2580,13 +2585,6 @@ var LiveCard = (function () {
       computedSection.innerHTML += `<pre style="background: #f5f5f5; padding: 10px; border-radius: 4px; overflow-x: auto; font-size: 12px; white-space: pre-wrap; word-wrap: break-word;">${_esc(JSON.stringify(computedValues, null, 2))}</pre>`;
       body.appendChild(computedSection);
 
-      const sourcesSection = document.createElement('div');
-      sourcesSection.className = 'mb-4';
-      sourcesSection.innerHTML = '<h6 class="fw-semibold mb-2">Fetched Sources (Read-only)</h6>';
-      const sourcesData = node.fetched_sources || {};
-      sourcesSection.innerHTML += `<pre style="background: #f5f5f5; padding: 10px; border-radius: 4px; overflow-x: auto; font-size: 12px; white-space: pre-wrap; word-wrap: break-word;">${_esc(JSON.stringify(sourcesData, null, 2))}</pre>`;
-      body.appendChild(sourcesSection);
-
       const requiresSection = document.createElement('div');
       requiresSection.className = 'mb-4';
       requiresSection.innerHTML = '<h6 class="fw-semibold mb-2">Requires (Read-only)</h6>';
@@ -2609,43 +2607,6 @@ var LiveCard = (function () {
       closeBtn.textContent = 'Close';
       closeBtn.addEventListener('click', closeModal);
 
-      submitBtn.addEventListener('click', function () {
-        editorError.classList.add('d-none');
-        editorError.textContent = '';
-        try {
-          const parsed = JSON.parse(editor.value);
-          if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
-            throw new Error('Card Object must be a JSON object.');
-          }
-          if (parsed.id && parsed.id !== node.id) {
-            throw new Error('Changing card id is not supported in the inspector.');
-          }
-
-          const fixedId = node.id;
-          const preservedRuntime = {
-            card_data: node.card_data,
-            fetched_sources: node.fetched_sources,
-            requires: node.requires,
-            computed_values: node.computed_values,
-            runtime_state: node.runtime_state,
-            data_objects: node.data_objects,
-          };
-          node.card = parsed;
-          node.id = fixedId;
-          Object.assign(node, preservedRuntime);
-
-          engine.notify(node.id, { inspector: 'card-object-updated' });
-          _render();
-
-          submitBtn.textContent = '✓ Saved';
-          setTimeout(function () { submitBtn.textContent = 'Submit'; }, 1200);
-          closeModal();
-        } catch (err) {
-          editorError.textContent = 'Invalid JSON: ' + String((err && err.message) || err);
-          editorError.classList.remove('d-none');
-        }
-      });
-
       footer.appendChild(closeBtn);
       content.appendChild(header);
       content.appendChild(body);
@@ -2796,8 +2757,23 @@ var LiveCard = (function () {
 
     // ---- Board mode ----
 
+    // Compute canvas inner size from card positions + padding
+    function _fitCanvasToContent() {
+      var pad = 100;
+      var maxR = 0, maxB = 0;
+      canvasInner.querySelectorAll('.lc-canvas-card,.lc-source-node').forEach(function(el) {
+        var r = el.offsetLeft + el.offsetWidth;
+        var b = el.offsetTop + el.offsetHeight;
+        if (r > maxR) maxR = r;
+        if (b > maxB) maxB = b;
+      });
+      canvasInner.style.width = (maxR + pad) + 'px';
+      canvasInner.style.height = (maxB + pad) + 'px';
+    }
+
     function _renderBoard() {
       _destroyEdges();
+      document.body.style.overflow = '';
       root.innerHTML = '';
       root.appendChild(gridEl);
       gridEl.innerHTML = '';
@@ -2836,13 +2812,13 @@ var LiveCard = (function () {
      */
     function _updateTokenAvailability() {
       var tokenMap = _buildTokenMap();
-      // Determine which nodes "have data" (non-empty card_data or fetched_sources, or status=fresh/completed)
+      // A node "has data" when card_data or computed_values is non-empty, or status is fresh/completed.
       var nodeHasData = {};
       nodeList.forEach(function(node) {
         var cd = node.card_data || (node.card && node.card.card_data);
-        var fs = node.fetched_sources;
+        var cv = node.computed_values;
         var status = cd && cd.status;
-        var hasOutput = (cd && Object.keys(cd).length > 0) || (fs && Object.keys(fs).length > 0);
+        var hasOutput = (cd && Object.keys(cd).length > 0) || (cv && Object.keys(cv).length > 0);
         nodeHasData[node.id] = hasOutput || status === 'fresh' || status === 'completed';
       });
 
@@ -2881,41 +2857,7 @@ var LiveCard = (function () {
       // Build token → provider nodeId map
       var tokenMap = _buildTokenMap();
 
-      // For each consumer node, for each required token, draw edge from
-      // the provider's "provides" badge → the consumer's "requires" badge.
-      if (typeof LeaderLine !== 'undefined') {
-        nodeList.forEach(function(node) {
-          var tgtInfo = nodeMap[node.id];
-          if (!tgtInfo || !tgtInfo.colEl) return;
-          _getRequires(node).forEach(function(token) {
-            var srcId = tokenMap[token];
-            if (!srcId) return;
-            var srcInfo = nodeMap[srcId];
-            if (!srcInfo || !srcInfo.colEl) return;
-            // Find the specific gem elements for this token
-            var srcGem = srcInfo.colEl.querySelector('.lc-token-gem-provides[data-token="' + token + '"]');
-            var tgtGem = tgtInfo.colEl.querySelector('.lc-token-gem-requires[data-token="' + token + '"]');
-            var startEl = srcGem || srcInfo.colEl;
-            var endEl = tgtGem || tgtInfo.colEl;
-            try {
-              var lineOpts = {
-                color: edgeCfg.color,
-                size: edgeCfg.size,
-                endPlug: edgeCfg.endPlug,
-                startSocket: srcGem ? 'bottom' : 'right',
-                endSocket: tgtGem ? 'top' : 'left',
-              };
-              if (edgeCfg.dash) {
-                lineOpts.dash = edgeCfg.animation ? { animation: true } : true;
-              }
-              _edges.push(new LeaderLine(startEl, endEl, lineOpts));
-            } catch(e) { /* skip edge on error */ }
-          });
-        });
-        return;
-      }
-
-      // SVG fallback — connect badge-to-badge with curved paths
+      // SVG edges — rendered behind cards (z-index:0) for a clean look
       nodeList.forEach(function(node) {
         var tgtInfo = nodeMap[node.id];
         if (!tgtInfo || !tgtInfo.colEl) return;
@@ -2947,8 +2889,26 @@ var LiveCard = (function () {
             tx = tEl.offsetLeft + tEl.offsetWidth / 2;
             ty = tEl.offsetTop;
           }
-          var cpOffset = Math.min(Math.abs(ty - sy) * 0.5, 80);
-          var d = 'M ' + sx + ' ' + sy + ' C ' + sx + ' ' + (sy + cpOffset) + ', ' + tx + ' ' + (ty - cpOffset) + ', ' + tx + ' ' + ty;
+          // Route bezier curves around cards — offset control points outward
+          var dx = tx - sx;
+          var dy = ty - sy;
+          var dist = Math.sqrt(dx * dx + dy * dy);
+          var cpLen = Math.max(40, Math.min(dist * 0.4, 120));
+          // Determine if src is roughly above, below, left, or right of target
+          var absDx = Math.abs(dx);
+          var absDy = Math.abs(dy);
+          var cp1x, cp1y, cp2x, cp2y;
+          if (absDy > absDx * 0.4) {
+            // Mostly vertical — curve control points go straight down/up
+            cp1x = sx; cp1y = sy + cpLen;
+            cp2x = tx; cp2y = ty - cpLen;
+          } else {
+            // Mostly horizontal — swing control points outward to avoid overlapping cards
+            var sideSign = dx > 0 ? 1 : -1;
+            cp1x = sx + sideSign * cpLen; cp1y = sy + cpLen * 0.5;
+            cp2x = tx - sideSign * cpLen; cp2y = ty - cpLen * 0.5;
+          }
+          var d = 'M ' + sx + ' ' + sy + ' C ' + cp1x + ' ' + cp1y + ', ' + cp2x + ' ' + cp2y + ', ' + tx + ' ' + ty;
           var path = document.createElementNS('http://www.w3.org/2000/svg', 'path');
           path.setAttribute('d', d);
           path.setAttribute('fill', 'none');
@@ -2999,6 +2959,7 @@ var LiveCard = (function () {
           node.card.view.layout.canvas.y = y;
         }
         engine.notify(node.id);
+        _fitCanvasToContent();
         if (_edges.length) _repositionEdges();
         else _drawEdges();
       }, { signal });
@@ -3057,6 +3018,7 @@ var LiveCard = (function () {
           node.card.view.layout.canvas.h = sh;
         }
         engine.notify(node.id);
+        _fitCanvasToContent();
         if (_edges.length) _repositionEdges();
         else _drawEdges();
       }, { signal });
@@ -3064,8 +3026,12 @@ var LiveCard = (function () {
 
     function _renderCanvas() {
       _destroyEdges();
+      document.body.style.overflow = 'hidden';
       root.innerHTML = '';
       root.appendChild(canvasEl);
+      // Fill remaining viewport height
+      var top = canvasEl.getBoundingClientRect().top;
+      canvasEl.style.height = co.height || ('calc(100vh - ' + top + 'px)');
       canvasInner.querySelectorAll('.lc-canvas-card,.lc-source-node').forEach(el => el.remove());
       svgEl.querySelectorAll('line,path').forEach(function(el) { el.remove(); });
       _initPositions();
@@ -3109,12 +3075,11 @@ var LiveCard = (function () {
 
       _updateTokenAvailability();
 
-      // Draw edges — use rAF for LeaderLine so elements are laid out first
-      if (typeof LeaderLine !== 'undefined') {
-        requestAnimationFrame(function() { _drawEdges(); });
-      } else {
+      // Fit canvas to content then draw edges
+      requestAnimationFrame(function() {
+        _fitCanvasToContent();
         _drawEdges();
-      }
+      });
 
       // Reposition LeaderLine edges on scroll
       canvasEl.addEventListener('scroll', function() { _repositionEdges(); }, { signal, passive: true });
@@ -3226,7 +3191,41 @@ var LiveCard = (function () {
       _render();
     }
 
-    function refresh() { _render(); }
+    /**
+     * Per-node update: replace runtime fields on the existing node object in place
+     * and re-render only that node's body. Outer wrapper is rebuilt to pick up
+     * status/badges, but the surrounding column element is reused so layout is stable.
+     * Editable element state is preserved via journal overlays keyed by nodeId:bindPath.
+     */
+    function updateNode(id, model) {
+      const entry = nodeMap[id];
+      if (!entry) throw new Error('updateNode: unknown node id ' + id);
+      const node = entry.node;
+      if (model && typeof model === 'object') {
+        if (model.card !== undefined) node.card = model.card;
+        if (model.card_data !== undefined) node.card_data = model.card_data;
+        if (model.requires !== undefined) node.requires = model.requires;
+        if (model.computed_values !== undefined) node.computed_values = model.computed_values;
+        if (model.runtime_state !== undefined) node.runtime_state = model.runtime_state;
+      }
+      engine.destroy(id);
+      if (mode.current === 'board') {
+        const colEl = entry.colEl;
+        colEl.innerHTML = '';
+        const built = _buildCardWrapper(node);
+        colEl.appendChild(built.wrap);
+        nodeMap[id] = { node, colEl, bodyEl: built.body };
+        engine.render(node, built.body, { showChat });
+      } else {
+        const el = entry.colEl;
+        el.innerHTML = '';
+        const built = _buildCardWrapper(node);
+        while (built.wrap.firstChild) el.appendChild(built.wrap.firstChild);
+        nodeMap[id] = { node, colEl: el, bodyEl: built.body };
+        engine.render(node, built.body, { showChat: false });
+      }
+      _updateTokenAvailability();
+    }
 
     function clear() {
       _destroyEdges();
@@ -3250,6 +3249,7 @@ var LiveCard = (function () {
 
     function destroy() {
       _destroyEdges();
+      document.body.style.overflow = '';
       ac.abort();
       engine.destroyAll();
       nodeList.length = 0;
@@ -3268,7 +3268,7 @@ var LiveCard = (function () {
       add,
       remove,
       reorder,
-      refresh,
+      updateNode,
       clear,
       setMode,
       setDevMode,
@@ -3281,9 +3281,120 @@ var LiveCard = (function () {
     };
   }
 
+  // ===========================================================================
+  // Board — reactive host. State in, view out. No destructive re-renders.
+  // ===========================================================================
+
+  function Board(engine, containerEl, opts) {
+    opts = opts || {};
+    const initialState = opts.initialState;
+    const getNodeIds = opts.getNodeIds;
+    const selectNode = opts.selectNode;
+    if (typeof getNodeIds !== 'function' || typeof selectNode !== 'function') {
+      throw new Error('LiveCard.Board requires getNodeIds and selectNode functions');
+    }
+
+    let state = initialState;
+    const prevModelsById = {};
+    const prevFingerprintsById = {};
+
+    function _stableStringify(v) {
+      if (v == null || typeof v !== 'object') return JSON.stringify(v);
+      if (Array.isArray(v)) return '[' + v.map(_stableStringify).join(',') + ']';
+      const keys = Object.keys(v).sort();
+      return '{' + keys.map(k => JSON.stringify(k) + ':' + _stableStringify(v[k])).join(',') + '}';
+    }
+
+    function _modelFingerprint(model) {
+      if (!model || typeof model !== 'object') return 'null';
+      return _stableStringify({
+        card: model.card,
+        card_data: model.card_data,
+        requires: model.requires,
+        computed_values: model.computed_values,
+        runtime_state: model.runtime_state,
+      });
+    }
+
+    const initialIds = getNodeIds(state);
+    const initialNodes = initialIds.map(id => {
+      const m = selectNode(state, id);
+      prevModelsById[id] = m;
+      prevFingerprintsById[id] = _modelFingerprint(m);
+      return m;
+    });
+
+    const coreOpts = {};
+    Object.keys(opts).forEach(k => {
+      if (k === 'initialState' || k === 'getNodeIds' || k === 'selectNode' || k === 'nodes') return;
+      coreOpts[k] = opts[k];
+    });
+    coreOpts.nodes = initialNodes;
+
+    const core = BoardCore(engine, containerEl, coreOpts);
+
+    function _changed(prevFingerprint, nextFingerprint) {
+      return prevFingerprint !== nextFingerprint;
+    }
+
+    function setState(nextStateOrUpdater) {
+      const nextState = (typeof nextStateOrUpdater === 'function')
+        ? nextStateOrUpdater(state)
+        : nextStateOrUpdater;
+      if (nextState === undefined) return;
+
+      state = nextState;
+      const nextIds = getNodeIds(state);
+      const nextSet = new Set(nextIds);
+
+      // Removals
+      Object.keys(prevModelsById).forEach(id => {
+        if (!nextSet.has(id)) {
+          core.remove(id);
+          delete prevModelsById[id];
+          delete prevFingerprintsById[id];
+        }
+      });
+
+      // Additions and per-node updates
+      nextIds.forEach(id => {
+        const next = selectNode(state, id);
+        const prev = prevModelsById[id];
+        const nextFingerprint = _modelFingerprint(next);
+        const prevFingerprint = prevFingerprintsById[id];
+        if (!prev) {
+          core.add(next);
+        } else if (_changed(prevFingerprint, nextFingerprint)) {
+          core.updateNode(id, next);
+        }
+        prevModelsById[id] = next;
+        prevFingerprintsById[id] = nextFingerprint;
+      });
+
+      // Reorder if id sequence differs
+      const currentOrder = core.nodes.map(n => n.id);
+      const orderDiffers = nextIds.length !== currentOrder.length
+        || nextIds.some((id, i) => id !== currentOrder[i]);
+      if (orderDiffers) core.reorder(nextIds);
+    }
+
+    function destroy() {
+      Object.keys(prevModelsById).forEach(k => delete prevModelsById[k]);
+      Object.keys(prevFingerprintsById).forEach(k => delete prevFingerprintsById[k]);
+      core.destroy();
+    }
+
+    return {
+      setState,
+      destroy,
+      core,
+      get state() { return state; },
+    };
+  }
+
   // ===========================================================================
   // Module export
   // ===========================================================================
 
-  return { init, Board };
+  return { init, Board, BoardCore };
 })();

package/card-store.js

@@ -10,10 +10,7 @@ const distCli = path.join(__dirname, 'dist', 'cli', 'node', 'card-store-cli.js')
 const srcCli = path.join(__dirname, 'src', 'cli', 'node', 'card-store-cli.ts');
 const tsxCli = path.join(__dirname, 'node_modules', 'tsx', 'dist', 'cli.mjs');
 
-if (fs.existsSync(distCli)) {
-  const { cli } = await import(pathToFileUrl(distCli).href);
-  await cli(process.argv.slice(2));
-} else if (fs.existsSync(srcCli)) {
+if (fs.existsSync(srcCli)) {
   const result = spawnSync(process.execPath, [tsxCli, srcCli, ...process.argv.slice(2)], {
     stdio: 'inherit',
     shell: false,
@@ -26,6 +23,9 @@ if (fs.existsSync(distCli)) {
   }
 
   process.exit(result.status ?? 0);
+} else if (fs.existsSync(distCli)) {
+  const { cli } = await import(pathToFileUrl(distCli).href);
+  await cli(process.argv.slice(2));
 } else {
   console.error('[card-store] Could not find dist or src CLI entrypoint.');
   process.exit(1);