yaml-flow 5.4.2 → 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 () {
@@ -98,6 +107,20 @@ var LiveCard = (function () {
       .lc-gandalf-caret:hover { opacity:1; }
       .lc-gandalf-card.lc-collapsed .lc-gandalf-caret { transform:rotate(-90deg); }
       .lc-gandalf-card.lc-collapsed .card-body { display:none !important; }
+      .lc-token-row { display:flex; flex-wrap:wrap; gap:0.35rem; padding:0.2rem 0.5rem; background:transparent; align-items:center; justify-content:center; min-height:0; }
+      .lc-token-row-requires { border-bottom:none; padding-bottom:0.1rem; }
+      .lc-token-row-provides { border-top:none; padding-top:0.1rem; }
+      .lc-token-gem { display:inline-block; width:10px; height:10px; border-radius:50%; cursor:default; transition:transform .15s, box-shadow .15s; position:relative; }
+      .lc-token-gem:hover { transform:scale(1.5); box-shadow:0 0 4px rgba(0,0,0,0.3); z-index:5; }
+      .lc-token-gem-requires { background:var(--bs-secondary,#6c757d); border:1.5px solid var(--bs-secondary,#6c757d); }
+      .lc-token-gem-requires.lc-token-available { background:var(--bs-success,#198754); border-color:var(--bs-success,#198754); }
+      .lc-token-gem-provides { background:var(--bs-secondary,#6c757d); border:1.5px solid var(--bs-secondary,#6c757d); }
+      .lc-token-gem-provides.lc-token-available { background:var(--bs-success,#198754); border-color:var(--bs-success,#198754); }
+      .lc-running { animation:lc-running-pulse 2s ease-in-out infinite; position:relative; }
+      .lc-running::before { content:''; position:absolute; inset:-2px; border-radius:inherit; background:linear-gradient(90deg,transparent,rgba(13,110,253,.45),rgba(102,16,242,.4),rgba(13,110,253,.45),transparent); background-size:300% 100%; animation:lc-running-shimmer 2s linear infinite; z-index:-1; pointer-events:none; }
+      @keyframes lc-running-pulse { 0%,100%{ box-shadow:0 0 4px rgba(13,110,253,.15); } 50%{ box-shadow:0 0 14px 3px rgba(13,110,253,.35); } }
+      @keyframes lc-running-shimmer { 0%{ background-position:100% 0; } 100%{ background-position:-100% 0; } }
+      .lc-running .card-header { border-bottom-color:rgba(13,110,253,.35); }
       @media (max-width:576px) {
         .lc-metric-value { font-size:1.5rem; }
         .lc-chart-wrap { min-height:150px; }
@@ -216,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 = {
@@ -261,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;
 
@@ -753,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;
@@ -781,7 +821,29 @@ var LiveCard = (function () {
       const requires = (node && node.card && Array.isArray(node.card.requires)) ? node.card.requires : [];
       if (!requires.length) return;
       const cleanup = _getCleanup(node.id);
-      cleanup.unsubs = requires.map(upId => subscribe(upId, () => {
+
+      // Resolve required tokens to upstream node IDs via provides declarations.
+      // Build a token→nodeId map from all nodes the engine knows about.
+      const tokenMap = {};
+      const allNodeIds = Object.keys(_subs).concat(Object.keys(_nodeEls));
+      allNodeIds.forEach(function(nid) {
+        const n = cfg.resolve(nid);
+        if (!n || !n.card) return;
+        var provides = (Array.isArray(n.card.provides) && n.card.provides.length)
+          ? n.card.provides.map(function(p) { return typeof p === 'string' ? p : (p.bindTo || p); })
+          : [n.id];
+        provides.forEach(function(tok) { tokenMap[tok] = n.id; });
+      });
+
+      // Subscribe to each upstream provider node (deduplicated)
+      const seen = {};
+      const upIds = [];
+      requires.forEach(function(token) {
+        var srcId = tokenMap[token] || token; // fallback: treat token as nodeId
+        if (!seen[srcId]) { seen[srcId] = true; upIds.push(srcId); }
+      });
+
+      cleanup.unsubs = upIds.map(upId => subscribe(upId, () => {
         const info = _nodeEls[node.id];
         if (!info || !info.resultEl) return;
         const updated = cfg.resolve(node.id);
@@ -1145,6 +1207,7 @@ var LiveCard = (function () {
         const nextValues = getEffectiveValues();
         cfg.onPatchState(node.id, { fieldValues: nextValues });
         btn.textContent = 'Saving...';
+        _showSavingOverlay(el);
       }, { signal });
 
       discardBtn.addEventListener('click', () => {
@@ -1223,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', () => {
@@ -1307,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() {
@@ -1925,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',
@@ -2144,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 ----
@@ -2239,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);
       }
     }
 
@@ -2318,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 };
@@ -2351,6 +2417,17 @@ var LiveCard = (function () {
     };
     const ac = new AbortController();
     const signal = ac.signal;
+    const _edges = [];        // LeaderLine instances for canvas edges
+
+    // Edge style config (from canvas opts)
+    const edgeOpts = co.edgeStyle || {};
+    const edgeCfg = {
+      color:     edgeOpts.color || 'rgba(108, 117, 125, 0.6)',
+      size:      edgeOpts.size || 2,
+      dash:      edgeOpts.dash !== false,
+      animation: edgeOpts.animation !== false,
+      endPlug:   edgeOpts.endPlug || 'arrow1',
+    };
 
     // DOM containers
     const root = document.createElement('div');
@@ -2362,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);
 
@@ -2384,10 +2459,16 @@ var LiveCard = (function () {
       const s = document.createElement('style');
       s.id = 'lc-board-css';
       s.textContent = `
-        .lc-canvas-card { position:absolute; min-width:${cvs.minWidth}px; max-width:${cvs.maxWidth}px; cursor:grab; user-select:none; z-index:1; }
+        .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 { max-height:${cvs.cardMaxH}px; overflow:auto; }
-        .lc-canvas-edges line { stroke:var(--bs-secondary,#6c757d); stroke-width:1.5; }
+        .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: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; }
       `;
@@ -2422,6 +2503,51 @@ var LiveCard = (function () {
       return (node && node.card && Array.isArray(node.card.requires)) ? node.card.requires : [];
     }
 
+    /**
+     * Returns tokens this node provides.
+     * Explicit: card.provides[].bindTo
+     * Implicit default: the node's own id (if no provides declared)
+     */
+    function _getProvides(node) {
+      if (!node || !node.card) return [node ? node.id : ''];
+      if (Array.isArray(node.card.provides) && node.card.provides.length > 0) {
+        return node.card.provides.map(function(p) { return (typeof p === 'string') ? p : (p.bindTo || p); });
+      }
+      // Default: node provides a token equal to its own id
+      return [node.id];
+    }
+
+    /**
+     * Build token → provider nodeId map from all nodes in the board.
+     * Called before drawing edges so we can resolve requires tokens → source nodes.
+     */
+    function _buildTokenMap() {
+      var map = {};
+      nodeList.forEach(function(node) {
+        _getProvides(node).forEach(function(token) {
+          map[token] = node.id;
+        });
+      });
+      return map;
+    }
+
+    /**
+     * Resolve required tokens to provider node IDs.
+     * Returns deduplicated array of source node IDs for a given consumer node.
+     */
+    function _resolveEdgeSources(node, tokenMap) {
+      var sources = [];
+      var seen = {};
+      _getRequires(node).forEach(function(token) {
+        var srcId = tokenMap[token];
+        if (srcId && !seen[srcId]) {
+          seen[srcId] = true;
+          sources.push(srcId);
+        }
+      });
+      return sources;
+    }
+
     function _showCardInspector(node) {
       const modal = document.createElement('div');
       modal.className = 'modal d-block';
@@ -2447,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');
@@ -2482,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>';
@@ -2511,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);
@@ -2562,8 +2621,9 @@ var LiveCard = (function () {
       const card = node && node.card ? node.card : {};
       const isSimulation = card.meta && card.meta.simulation === true;
       const isGandalfCard  = card.meta && card.meta._gandalfCard === true;
+      const isRunning     = node && node.runtime_state && node.runtime_state.task_status === 'running';
       const extraClass   = isSimulation ? ' lc-simulation-card' : (isGandalfCard ? ' lc-gandalf-card' : '');
-      wrap.className = 'card shadow-sm h-100' + extraClass;
+      wrap.className = 'card shadow-sm h-100' + extraClass + (isRunning ? ' lc-running' : '');
       const header = document.createElement('div');
       header.className = 'card-header d-flex align-items-center gap-2 py-2';
       const title = (card.meta && card.meta.title) || node.id;
@@ -2639,8 +2699,44 @@ var LiveCard = (function () {
       
       const body = document.createElement('div');
       body.className = 'card-body p-2';
+
+      // Token gem rows — requires gems above header, provides gems below body
+      const requiresTokens = (card.requires && Array.isArray(card.requires)) ? card.requires : [];
+      const providesTokens = (Array.isArray(card.provides) && card.provides.length)
+        ? card.provides.map(function(p) { return typeof p === 'string' ? p : (p.bindTo || p); })
+        : [node.id];
+
+      // Requires gems — top of card (above header)
+      if (requiresTokens.length) {
+        const reqRow = document.createElement('div');
+        reqRow.className = 'lc-token-row lc-token-row-requires';
+        requiresTokens.forEach(function(token) {
+          const gem = document.createElement('span');
+          gem.className = 'lc-token-gem lc-token-gem-requires';
+          gem.dataset.token = token;
+          gem.title = token;
+          reqRow.appendChild(gem);
+        });
+        wrap.appendChild(reqRow);
+      }
+
       wrap.appendChild(header);
       wrap.appendChild(body);
+
+      // Provides gems — bottom of card (below body)
+      if (providesTokens.length) {
+        const provRow = document.createElement('div');
+        provRow.className = 'lc-token-row lc-token-row-provides';
+        providesTokens.forEach(function(token) {
+          const gem = document.createElement('span');
+          gem.className = 'lc-token-gem lc-token-gem-provides';
+          gem.dataset.token = token;
+          gem.title = token;
+          provRow.appendChild(gem);
+        });
+        wrap.appendChild(provRow);
+      }
+
       return { wrap, header, body };
     }
 
@@ -2661,7 +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 = '';
@@ -2684,6 +2796,7 @@ var LiveCard = (function () {
         nodeMap[node.id] = { node, colEl: col, bodyEl: body };
         engine.render(node, body, { showChat });
       });
+      _updateTokenAvailability();
     }
 
     // ---- Canvas mode ----
@@ -2692,26 +2805,116 @@ var LiveCard = (function () {
       canvasInner.style.transform = `translate(${cvs.panX}px,${cvs.panY}px) scale(${cvs.zoom})`;
     }
 
+    /**
+     * Update token badge availability: a provides badge turns green when the
+     * node has data; a requires badge turns green when the upstream provider
+     * has data for that token.
+     */
+    function _updateTokenAvailability() {
+      var tokenMap = _buildTokenMap();
+      // 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 cv = node.computed_values;
+        var status = cd && cd.status;
+        var hasOutput = (cd && Object.keys(cd).length > 0) || (cv && Object.keys(cv).length > 0);
+        nodeHasData[node.id] = hasOutput || status === 'fresh' || status === 'completed';
+      });
+
+      // Update all gem elements in root container
+      var allGems = root.querySelectorAll('.lc-token-gem');
+      allGems.forEach(function(gem) {
+        var token = gem.dataset.token;
+        if (!token) return;
+        if (gem.classList.contains('lc-token-gem-provides')) {
+          // The provides gem: green if this node has data
+          var nodeEl = gem.closest('[data-node-id]');
+          var nId = nodeEl && nodeEl.dataset.nodeId;
+          gem.classList.toggle('lc-token-available', !!(nId && nodeHasData[nId]));
+        } else if (gem.classList.contains('lc-token-gem-requires')) {
+          // The requires gem: green if the upstream provider for this token has data
+          var srcId = tokenMap[token];
+          gem.classList.toggle('lc-token-available', !!(srcId && nodeHasData[srcId]));
+        }
+      });
+    }
+
+    function _destroyEdges() {
+      _edges.forEach(function(line) { try { line.remove(); } catch(e) { /* noop */ } });
+      _edges.length = 0;
+    }
+
+    function _repositionEdges() {
+      _edges.forEach(function(line) { try { line.position(); } catch(e) { /* noop */ } });
+    }
+
     function _drawEdges() {
-      svgEl.querySelectorAll('line').forEach(l => l.remove());
+      _destroyEdges();
+      svgEl.querySelectorAll('line,path').forEach(function(el) { el.remove(); });
       if (!cvs.edges) return;
 
-      nodeList.forEach(node => {
-        _getRequires(node).forEach(srcId => {
-          const srcInfo = nodeMap[srcId];
-          const tgtInfo = nodeMap[node.id];
-          if (!srcInfo || !tgtInfo) return;
-          const sEl = srcInfo.colEl;
-          const tEl = tgtInfo.colEl;
-          const sx = sEl.offsetLeft + sEl.offsetWidth;
-          const sy = sEl.offsetTop + sEl.offsetHeight / 2;
-          const tx = tEl.offsetLeft;
-          const ty = tEl.offsetTop + tEl.offsetHeight / 2;
-          const line = document.createElementNS('http://www.w3.org/2000/svg', 'line');
-          line.setAttribute('x1', sx); line.setAttribute('y1', sy);
-          line.setAttribute('x2', tx); line.setAttribute('y2', ty);
-          line.setAttribute('marker-end', 'url(#lc-arrow)');
-          svgEl.appendChild(line);
+      // Build token → provider nodeId map
+      var tokenMap = _buildTokenMap();
+
+      // 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;
+        _getRequires(node).forEach(function(token) {
+          var srcId = tokenMap[token];
+          if (!srcId) return;
+          var srcInfo = nodeMap[srcId];
+          if (!srcInfo || !srcInfo.colEl) return;
+          // Locate gems; fall back to card element if gem not found
+          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 sx, sy, tx, ty;
+          var innerRect = canvasInner.getBoundingClientRect();
+          if (srcGem) {
+            var srcRect = srcGem.getBoundingClientRect();
+            sx = (srcRect.left + srcRect.width / 2 - innerRect.left) / cvs.zoom;
+            sy = (srcRect.bottom - innerRect.top) / cvs.zoom;
+          } else {
+            var sEl = srcInfo.colEl;
+            sx = sEl.offsetLeft + sEl.offsetWidth / 2;
+            sy = sEl.offsetTop + sEl.offsetHeight;
+          }
+          if (tgtGem) {
+            var tgtRect = tgtGem.getBoundingClientRect();
+            tx = (tgtRect.left + tgtRect.width / 2 - innerRect.left) / cvs.zoom;
+            ty = (tgtRect.top - innerRect.top) / cvs.zoom;
+          } else {
+            var tEl = tgtInfo.colEl;
+            tx = tEl.offsetLeft + tEl.offsetWidth / 2;
+            ty = tEl.offsetTop;
+          }
+          // 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');
+          path.setAttribute('marker-end', 'url(#lc-arrow)');
+          path.classList.add('lc-edge-path');
+          svgEl.appendChild(path);
         });
       });
     }
@@ -2736,7 +2939,8 @@ var LiveCard = (function () {
         const dy = (e.clientY - startY) / cvs.zoom;
         el.style.left = (origX + dx) + 'px';
         el.style.top  = (origY + dy) + 'px';
-        _drawEdges();
+        if (_edges.length) _repositionEdges();
+        else _drawEdges();
       }, { signal });
 
       el.addEventListener('pointerup', () => {
@@ -2755,15 +2959,81 @@ var LiveCard = (function () {
           node.card.view.layout.canvas.y = y;
         }
         engine.notify(node.id);
-        _drawEdges();
+        _fitCanvasToContent();
+        if (_edges.length) _repositionEdges();
+        else _drawEdges();
+      }, { signal });
+    }
+
+    function _makeResizable(el, node) {
+      const handle = document.createElement('div');
+      handle.className = 'lc-resize-handle';
+      el.appendChild(handle);
+      el.style.overflow = 'visible';
+
+      let resizing = false, startX, startY, origW, origH;
+
+      handle.addEventListener('pointerdown', function(e) {
+        if (e.button !== 0) return;
+        e.stopPropagation();
+        e.preventDefault();
+        resizing = true;
+        el.classList.add('lc-resizing');
+        handle.setPointerCapture(e.pointerId);
+        startX = e.clientX;
+        startY = e.clientY;
+        origW = el.offsetWidth;
+        origH = el.offsetHeight;
+      }, { signal });
+
+      handle.addEventListener('pointermove', function(e) {
+        if (!resizing) return;
+        const dw = (e.clientX - startX) / cvs.zoom;
+        const dh = (e.clientY - startY) / cvs.zoom;
+        const newW = Math.max(cvs.minWidth, origW + dw);
+        const newH = Math.max(80, origH + dh);
+        el.style.width = newW + 'px';
+        el.style.height = newH + 'px';
+        if (_edges.length) _repositionEdges();
+        else _drawEdges();
+      }, { signal });
+
+      handle.addEventListener('pointerup', function() {
+        if (!resizing) return;
+        resizing = false;
+        el.classList.remove('lc-resizing');
+        const w = el.offsetWidth;
+        const h = el.offsetHeight;
+        // Snap to grid
+        const sw = cvs.snap > 1 ? Math.round(w / cvs.snap) * cvs.snap : w;
+        const sh = cvs.snap > 1 ? Math.round(h / cvs.snap) * cvs.snap : h;
+        el.style.width = sw + 'px';
+        el.style.height = sh + 'px';
+        // Persist dimensions
+        _positions[node.id] = Object.assign(_positions[node.id] || {}, { w: sw, h: sh });
+        if (node.card && node.card.view) {
+          if (!node.card.view.layout) node.card.view.layout = {};
+          if (!node.card.view.layout.canvas) node.card.view.layout.canvas = {};
+          node.card.view.layout.canvas.w = sw;
+          node.card.view.layout.canvas.h = sh;
+        }
+        engine.notify(node.id);
+        _fitCanvasToContent();
+        if (_edges.length) _repositionEdges();
+        else _drawEdges();
       }, { signal });
     }
 
     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').forEach(l => l.remove());
+      svgEl.querySelectorAll('line,path').forEach(function(el) { el.remove(); });
       _initPositions();
       _applyTransform();
 
@@ -2788,6 +3058,7 @@ var LiveCard = (function () {
           el.style.left = pos.x + 'px';
           el.style.top  = pos.y + 'px';
           if (pos.w) el.style.width = pos.w + 'px';
+          if (pos.h) el.style.height = pos.h + 'px';
 
           const { wrap, body } = _buildCardWrapper(node);
           while (wrap.firstChild) el.appendChild(wrap.firstChild);
@@ -2798,10 +3069,20 @@ var LiveCard = (function () {
           nodeMap[node.id] = { node, colEl: el, bodyEl: body };
           engine.render(node, body, { showChat: false });
           _makeDraggable(el, node);
+          _makeResizable(el, node);
         }
       });
 
-      _drawEdges();
+      _updateTokenAvailability();
+
+      // Fit canvas to content then draw edges
+      requestAnimationFrame(function() {
+        _fitCanvasToContent();
+        _drawEdges();
+      });
+
+      // Reposition LeaderLine edges on scroll
+      canvasEl.addEventListener('scroll', function() { _repositionEdges(); }, { signal, passive: true });
 
       // Pan: middle-click or Ctrl+drag on background
       let panning = false, panStartX, panStartY, panOrigX, panOrigY;
@@ -2819,6 +3100,7 @@ var LiveCard = (function () {
         cvs.panX = panOrigX + (e.clientX - panStartX);
         cvs.panY = panOrigY + (e.clientY - panStartY);
         _applyTransform();
+        _repositionEdges();
       }, { signal });
       canvasEl.addEventListener('pointerup', () => { panning = false; }, { signal });
 
@@ -2829,6 +3111,7 @@ var LiveCard = (function () {
         const delta = e.deltaY > 0 ? 0.9 : 1.1;
         cvs.zoom = Math.min(cvs.zoomMax, Math.max(cvs.zoomMin, cvs.zoom * delta));
         _applyTransform();
+        _repositionEdges();
       }, { signal, passive: false });
     }
 
@@ -2840,11 +3123,12 @@ var LiveCard = (function () {
     // ---- Auto-layout (topological L → R) ----
 
     function autoLayout() {
+      const tokenMap = _buildTokenMap();
       const incoming = {};
       const levels = {};
       nodeList.forEach(n => { incoming[n.id] = []; levels[n.id] = 0; });
       nodeList.forEach(n => {
-        _getRequires(n).forEach(srcId => {
+        _resolveEdgeSources(n, tokenMap).forEach(srcId => {
           if (incoming[n.id]) incoming[n.id].push(srcId);
         });
       });
@@ -2907,9 +3191,44 @@ 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();
       engine.destroyAll();
       nodeList.length = 0;
       Object.keys(nodeMap).forEach(k => delete nodeMap[k]);
@@ -2929,6 +3248,8 @@ var LiveCard = (function () {
     }
 
     function destroy() {
+      _destroyEdges();
+      document.body.style.overflow = '';
       ac.abort();
       engine.destroyAll();
       nodeList.length = 0;
@@ -2947,7 +3268,7 @@ var LiveCard = (function () {
       add,
       remove,
       reorder,
-      refresh,
+      updateNode,
       clear,
       setMode,
       setDevMode,
@@ -2960,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 };
 })();