yaml-flow 5.2.6 → 5.3.0

package/browser/live-cards.js

@@ -1,10 +1,10 @@
 // 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, sources, compute, view
-//   Nodes with view render as cards; nodes with sources but no view render as source pills in canvas.
+//   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)
-//   sources[] — open objects: only bindTo + outputFile matter to the engine; all other fields are
+//   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
@@ -89,6 +89,15 @@ var LiveCard = (function () {
       .lc-files-modal-backdrop .modal-dialog { max-height:90vh; }
       .lc-files-modal-backdrop .modal-content { display:flex; flex-direction:column; max-height:90vh; }
       .lc-files-modal-backdrop .modal-body { overflow-y:auto; flex:1; min-height:200px; padding:1rem; }
+      .lc-simulation-card { background:#fdf6ec; border-color:#e0c97f !important; }
+      .lc-simulation-card .card-header { background:#faecc8; border-bottom-color:#e0c97f; }
+      .lc-gandalf-card { background:#eef4ff; border-color:#6ea4e0 !important; }
+      .lc-gandalf-card .card-header { background:#d7e8fa; border-bottom-color:#6ea4e0; cursor:pointer; user-select:none; }
+      .lc-gandalf-card .card-header:hover { background:#c8dcf5; }
+      .lc-gandalf-caret { transition:transform .2s; display:inline-flex; align-items:center; margin-left:auto; opacity:.6; flex-shrink:0; cursor:pointer; padding:2px; }
+      .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; }
       @media (max-width:576px) {
         .lc-metric-value { font-size:1.5rem; }
         .lc-chart-wrap { min-height:150px; }
@@ -203,9 +212,9 @@ var LiveCard = (function () {
 
     const _cleanup = {};    // nodeId → { ac, timers, charts, unsubs }
     const _subs = {};       // nodeId → Set<callback>
-    const _etState = {};    // stateKey → { currentState, pending } for editable-table dirty tracking
-    const _formState = {};  // stateKey → { currentState, pending } for form dirty tracking
-    const _notesState = {}; // stateKey → { currentState, pending } for notes dirty tracking
+    const _etState = {};    // stateKey → { baseRows, journalRows|null }
+    const _formState = {};  // stateKey → { baseValues, journal }
+    const _notesState = {}; // stateKey → { baseContent, journal|null }
     const _todoState = {};  // stateKey → { currentState, pending } for todo dirty tracking
     const _renderers = {}; // kind → fn
     const _nodeEls = {};   // nodeId → { container, resultEl, uid }
@@ -999,45 +1008,50 @@ var LiveCard = (function () {
       const props = schema.properties || {};
       const required = schema.required || [];
 
-      // --- Journal-style dirty tracking (mirrors editable-table) ---
-      // currentState = what the server last sent (updated each SSE re-render)
-      // pending      = user's local field values accumulated on top of currentState
-      // dirty        = JSON.stringify(currentState) !== JSON.stringify(pending)
-      //
-      // On SSE re-render:
-      //   - currentState updated to new server values
-      //   - if NOT dirty: pending follows currentState (no unsaved edits)
-      //   - if dirty: pending untouched, form is rebuilt from pending (edits survive)
-      const stateKey = node.id + ':' + (writeTo || '');
-      const incomingValues = writeTo ? (_resolveBind(node, writeTo) || {}) : (data && typeof data === 'object' ? data : {});
-      const incomingCopy = Object.assign({}, incomingValues);
+      const stateKey = node.id + ':' + (ed.bind || writeTo || '');
+      const baseValues = (data && typeof data === 'object' && !Array.isArray(data)) ? Object.assign({}, data) : {};
 
       if (!_formState[stateKey]) {
-        _formState[stateKey] = { currentState: incomingCopy, pending: Object.assign({}, incomingCopy) };
+        _formState[stateKey] = { baseValues, journal: {} };
       } else {
-        const s = _formState[stateKey];
-        const wasDirty = JSON.stringify(s.currentState) !== JSON.stringify(s.pending);
-        s.currentState = incomingCopy;
-        if (!wasDirty) {
-          s.pending = Object.assign({}, incomingCopy);
-        }
-        // if dirty, pending stays so user's in-progress edits survive the SSE tick
+        _formState[stateKey].baseValues = baseValues;
+        Object.keys(_formState[stateKey].journal).forEach(key => {
+          if (_same(_formState[stateKey].journal[key], baseValues[key])) {
+            delete _formState[stateKey].journal[key];
+          }
+        });
       }
 
       const st = _formState[stateKey];
 
+      function _toInputValue(prop, inp) {
+        if (prop.type === 'boolean') return !!inp.checked;
+        if (prop.type === 'number' || prop.type === 'integer') return inp.value !== '' ? parseFloat(inp.value) : 0;
+        return inp.value;
+      }
+
+      function _same(a, b) {
+        return JSON.stringify(a) === JSON.stringify(b);
+      }
+
+      function getEffectiveValues() {
+        return Object.assign({}, st.baseValues, st.journal);
+      }
+
       function isDirty() {
-        return JSON.stringify(st.currentState) !== JSON.stringify(st.pending);
+        return Object.keys(st.journal).length > 0;
       }
 
-      // Snapshot current input values into pending (called on each input event)
-      function capturePending(form) {
+      // Capture user edits into a journal overlay (only changed keys).
+      function captureJournal(form) {
         form.querySelectorAll('[data-key]').forEach(inp => {
-          const k = inp.dataset.key, p = props[k];
+          const k = inp.dataset.key;
+          const p = props[k];
           if (!p) return;
-          if (p.type === 'boolean') st.pending[k] = inp.checked;
-          else if (p.type === 'number' || p.type === 'integer') st.pending[k] = inp.value !== '' ? parseFloat(inp.value) : 0;
-          else st.pending[k] = inp.value;
+          const nextVal = _toInputValue(p, inp);
+          const baseVal = st.baseValues[k];
+          if (_same(nextVal, baseVal)) delete st.journal[k];
+          else st.journal[k] = nextVal;
         });
       }
 
@@ -1089,8 +1103,8 @@ var LiveCard = (function () {
 
         input.dataset.key = key;
         if (isReq) input.required = true;
-        // Populate from pending (not from server values directly)
-        const v = st.pending[key];
+        // Populate from effective values (base bind overlaid by local journal).
+        const v = getEffectiveValues()[key];
         if (v != null) {
           if (prop.type === 'boolean') input.checked = !!v;
           else if (prop.format === 'date') input.value = String(v).slice(0, 10);
@@ -1101,34 +1115,51 @@ var LiveCard = (function () {
 
       const btnCol = document.createElement('div');
       btnCol.className = 'col-12 mt-1';
+      const discardBtn = document.createElement('button');
+      discardBtn.type = 'button';
+      discardBtn.className = 'btn btn-sm btn-outline-secondary me-2' + (isDirty() ? '' : ' d-none');
+      discardBtn.textContent = 'Discard';
       const btn = document.createElement('button');
       btn.type = 'submit';
       btn.className = 'btn btn-sm btn-primary' + (isDirty() ? '' : ' d-none');
-      btn.textContent = 'Submit';
+      btn.textContent = 'Save';
+      btnCol.appendChild(discardBtn);
       btnCol.appendChild(btn);
       form.appendChild(btnCol);
 
       el.innerHTML = '';
       el.appendChild(form);
 
-      // Real-time input → update pending + show Submit if now dirty
+      // Real-time input → update journal + toggle Save/Discard buttons
       form.addEventListener('input', () => {
-        capturePending(form);
-        if (isDirty()) btn.classList.remove('d-none');
+        captureJournal(form);
+        const dirty = isDirty();
+        btn.classList.toggle('d-none', !dirty);
+        discardBtn.classList.toggle('d-none', !dirty);
       }, { signal });
 
       form.addEventListener('submit', e => {
         e.preventDefault();
         if (!form.checkValidity()) { form.classList.add('was-validated'); return; }
-        capturePending(form);
-        if (writeTo) _deepSet(node, writeTo, st.pending);
-        cfg.onPatchState(node.id, { fieldValues: st.pending });
-        notify(node.id, st.pending);
-        // After save, currentState = pending (no longer dirty)
-        st.currentState = Object.assign({}, st.pending);
+        captureJournal(form);
+        const nextValues = getEffectiveValues();
+        cfg.onPatchState(node.id, { fieldValues: nextValues });
+        btn.textContent = 'Saving...';
+      }, { signal });
+
+      discardBtn.addEventListener('click', () => {
+        st.journal = {};
+        form.querySelectorAll('[data-key]').forEach(inp => {
+          const k = inp.dataset.key;
+          const p = props[k];
+          if (!p) return;
+          const v = st.baseValues[k];
+          if (p.type === 'boolean') inp.checked = !!v;
+          else if (p.format === 'date') inp.value = v != null ? String(v).slice(0, 10) : '';
+          else inp.value = v != null ? v : '';
+        });
+        discardBtn.classList.add('d-none');
         btn.classList.add('d-none');
-        btn.textContent = '✓ Saved';
-        setTimeout(() => { btn.textContent = 'Submit'; }, 1500);
       }, { signal });
     }
 
@@ -1141,54 +1172,63 @@ var LiveCard = (function () {
       const writeTo = ed.writeTo;
       const incomingContent = typeof data === 'string' ? data : '';
 
-      // --- Journal-style dirty tracking ---
-      // currentState = last server value; pending = textarea content
-      // On SSE re-render: if dirty, leave textarea alone; if clean, sync from server
-      const stateKey = node.id + ':' + (writeTo || '');
+      // Base + journal overlay model:
+      // effective = journal when present, else baseContent from bind.
+      const stateKey = node.id + ':' + ((ed.bind || writeTo) || '');
       if (!_notesState[stateKey]) {
-        _notesState[stateKey] = { currentState: incomingContent, pending: incomingContent };
+        _notesState[stateKey] = { baseContent: incomingContent, journal: null };
       } else {
-        const s = _notesState[stateKey];
-        const wasDirty = s.currentState !== s.pending;
-        s.currentState = incomingContent;
-        if (!wasDirty) s.pending = incomingContent;
-        // if dirty, pending stays so user's typing survives the SSE tick
+        _notesState[stateKey].baseContent = incomingContent;
+        if (_notesState[stateKey].journal === incomingContent) {
+          _notesState[stateKey].journal = null;
+        }
       }
       const st = _notesState[stateKey];
 
+      function isDirty() {
+        return st.journal != null;
+      }
+
+      function getEffectiveContent() {
+        return st.journal != null ? st.journal : st.baseContent;
+      }
+
+      function setJournal(nextValue) {
+        st.journal = nextValue === st.baseContent ? null : nextValue;
+      }
+
       el.innerHTML = `
-        <div class="btn-group btn-group-sm mb-2" role="group">
-          <button class="btn btn-outline-secondary active lc-n-edit" type="button">Edit</button>
-          <button class="btn btn-outline-secondary lc-n-preview" type="button">Preview</button>
-        </div>
-        <textarea class="form-control form-control-sm lc-notes-textarea" rows="8" placeholder="Write markdown...">${_esc(st.pending)}</textarea>
-        <div class="lc-notes-preview d-none border rounded p-2 small"></div>`;
+        <textarea class="form-control form-control-sm lc-notes-textarea" rows="8" placeholder="Write markdown...">${_esc(getEffectiveContent())}</textarea>
+        <div class="mt-2">
+          <button class="btn btn-sm btn-outline-secondary me-2 lc-n-discard${isDirty() ? '' : ' d-none'}" type="button">Discard</button>
+          <button class="btn btn-sm btn-primary lc-n-save${isDirty() ? '' : ' d-none'}" type="button">Save</button>
+        </div>`;
 
       const textarea = el.querySelector('.lc-notes-textarea');
-      const preview = el.querySelector('.lc-notes-preview');
-      const editBtn = el.querySelector('.lc-n-edit');
-      const previewBtn = el.querySelector('.lc-n-preview');
+      const discardBtn = el.querySelector('.lc-n-discard');
+      const saveBtn = el.querySelector('.lc-n-save');
 
-      editBtn.addEventListener('click', () => {
-        textarea.classList.remove('d-none'); preview.classList.add('d-none');
-        editBtn.classList.add('active'); previewBtn.classList.remove('active');
+      function syncDirtyButtons() {
+        const dirty = isDirty();
+        saveBtn.classList.toggle('d-none', !dirty);
+        discardBtn.classList.toggle('d-none', !dirty);
+      }
+
+      textarea.addEventListener('input', () => {
+        setJournal(textarea.value);
+        syncDirtyButtons();
       }, { signal });
-      previewBtn.addEventListener('click', () => {
-        preview.innerHTML = _renderMd(textarea.value);
-        textarea.classList.add('d-none'); preview.classList.remove('d-none');
-        previewBtn.classList.add('active'); editBtn.classList.remove('active');
+
+      saveBtn.addEventListener('click', () => {
+        const nextValue = textarea.value;
+        cfg.onPatchState(node.id, { notes: nextValue });
+        saveBtn.textContent = 'Saving...';
       }, { signal });
 
-      let timer;
-      textarea.addEventListener('input', () => {
-        st.pending = textarea.value; // track in journal
-        clearTimeout(timer);
-        timer = setTimeout(() => {
-          if (writeTo) _deepSet(node, writeTo, textarea.value);
-          cfg.onPatchState(node.id, { notes: textarea.value });
-          st.currentState = textarea.value; // saved — no longer dirty
-        }, 800);
-        cleanup.timers.push(timer);
+      discardBtn.addEventListener('click', () => {
+        st.journal = null;
+        textarea.value = st.baseContent || '';
+        syncDirtyButtons();
       }, { signal });
     }
 
@@ -1206,7 +1246,11 @@ var LiveCard = (function () {
       const cleanup = _getCleanup(node.id);
       const signal = cleanup.ac.signal;
       const ed = elemDef.data || {};
-      const writeTo = ed.writeTo;
+      // Standard convention:
+      // - bind = read source
+      // - writeTo = explicit write target for editable views
+      // If bind already points at card_data, default writeTo to bind.
+      const writeTo = ed.writeTo || ((typeof ed.bind === 'string' && ed.bind.startsWith('card_data.')) ? ed.bind : undefined);
       const schemaProps = (ed.schema && ed.schema.properties) || {};
       const canAdd    = ed.addRow    !== false;
       const canDelete = ed.deleteRow !== false;
@@ -1219,57 +1263,59 @@ var LiveCard = (function () {
         return [...s];
       }
 
-      // --- Journal-style dirty tracking ---
-      // currentState = what the server last sent (updated each SSE re-render)
-      // pending      = user's local accumulation of edits on top of currentState
-      // dirty        = JSON.stringify(currentState) !== JSON.stringify(pending)
-      //
-      // When SSE fires and re-renders this element:
-      //   - currentState is updated to the new server value
-      //   - if NOT dirty: pending follows currentState (no unsaved edits)
-      //   - if dirty: pending is left untouched (user's edits survive the SSE tick)
-      const stateKey = node.id + ':' + (ed.bind || ed.writeTo || '');
-      const incomingRows = Array.isArray(writeTo ? _resolveBind(node, writeTo) : data)
-        ? (writeTo ? _resolveBind(node, writeTo) : data)
-        : [];
+      // Base + journal overlay model:
+      // effectiveRows = journalRows if present, else baseRows(bind).
+      // Dirty is determined by journal presence (supports Save/Discard UX).
+      const stateKey = node.id + ':' + (ed.bind || writeTo || '');
+      const incomingRows = Array.isArray(data) ? data : [];
       const incomingCopy = incomingRows.map(r => Object.assign({}, r));
 
       if (!_etState[stateKey]) {
-        // First render — initialise both sides from server data
-        _etState[stateKey] = { currentState: incomingCopy, pending: incomingCopy.map(r => Object.assign({}, r)) };
+        _etState[stateKey] = { baseRows: incomingCopy, journalRows: null };
       } else {
-        const s = _etState[stateKey];
-        const wasDirty = JSON.stringify(s.currentState) !== JSON.stringify(s.pending);
-        s.currentState = incomingCopy;
-        if (!wasDirty) {
-          // No unsaved edits — sync pending to new server state
-          s.pending = incomingCopy.map(r => Object.assign({}, r));
+        _etState[stateKey].baseRows = incomingCopy;
+        if (_etState[stateKey].journalRows && JSON.stringify(_etState[stateKey].journalRows) === JSON.stringify(incomingCopy)) {
+          _etState[stateKey].journalRows = null;
         }
-        // If dirty, pending stays as-is so user's edits survive the SSE tick
       }
 
       const st = _etState[stateKey];
 
       function isDirty() {
-        return JSON.stringify(st.currentState) !== JSON.stringify(st.pending);
+        return Array.isArray(st.journalRows);
+      }
+
+      function getEffectiveRows() {
+        const rows = Array.isArray(st.journalRows) ? st.journalRows : st.baseRows;
+        return rows.map(r => Object.assign({}, r));
+      }
+
+      function updateJournal(nextRows) {
+        if (JSON.stringify(nextRows) === JSON.stringify(st.baseRows)) st.journalRows = null;
+        else st.journalRows = nextRows.map(r => Object.assign({}, r));
       }
 
       function markDirty() {
         const saveBtn = el.querySelector('.lc-et-save');
+        const discardBtn = el.querySelector('.lc-et-discard');
         if (saveBtn) saveBtn.classList.remove('d-none');
+        if (discardBtn) discardBtn.classList.remove('d-none');
       }
 
       function commitSave() {
-        if (writeTo) _deepSet(node, writeTo, st.pending);
-        cfg.onPatchState(node.id, { fieldValues: st.pending });
-        notify(node.id, st.pending);
-        // After save, currentState = pending (no longer dirty)
-        st.currentState = st.pending.map(r => Object.assign({}, r));
+        const rows = getEffectiveRows();
+        cfg.onPatchState(node.id, { fieldValues: rows });
+        const saveBtn = el.querySelector('.lc-et-save');
+        if (saveBtn) saveBtn.textContent = 'Saving...';
+      }
+
+      function commitDiscard() {
+        st.journalRows = null;
         build();
       }
 
       function build() {
-        const rows = st.pending;
+        const rows = getEffectiveRows();
         const cols = getCols(rows);
 
         if (!cols.length && !canAdd) {
@@ -1312,44 +1358,63 @@ var LiveCard = (function () {
         h += '</tbody></table></div>';
         let footer = '';
         if (canAdd) footer += '<button class="btn btn-sm btn-outline-secondary mt-1 me-1 lc-et-add">+ Add row</button>';
+        footer += `<button class="btn btn-sm btn-outline-secondary mt-1 me-1 lc-et-discard${isDirty() ? '' : ' d-none'}">Discard</button>`;
         footer += `<button class="btn btn-sm btn-primary mt-1 lc-et-save${isDirty() ? '' : ' d-none'}">Save</button>`;
         el.innerHTML = h + footer;
 
-        // Cell edit → update pending on blur, show Save if now dirty
+        // Cell edit → update journal overlay and toggle Save/Discard.
         el.querySelectorAll('.lc-et-cell').forEach(inp => {
           inp.addEventListener('change', () => {
             const rowIdx  = parseInt(inp.dataset.row);
             const colName = inp.dataset.col;
             const prop    = schemaProps[colName] || {};
             const isNum   = prop.type === 'number' || prop.type === 'integer' || inp.type === 'number';
-            if (!st.pending[rowIdx]) return;
-            st.pending[rowIdx] = Object.assign({}, st.pending[rowIdx]);
-            st.pending[rowIdx][colName] = isNum ? (inp.value !== '' ? parseFloat(inp.value) : 0) : inp.value;
+            const nextRows = getEffectiveRows();
+            if (!nextRows[rowIdx]) return;
+            nextRows[rowIdx] = Object.assign({}, nextRows[rowIdx]);
+            nextRows[rowIdx][colName] = isNum ? (inp.value !== '' ? parseFloat(inp.value) : 0) : inp.value;
+            updateJournal(nextRows);
             if (isDirty()) markDirty();
+            else {
+              const saveBtn = el.querySelector('.lc-et-save');
+              const discardBtn = el.querySelector('.lc-et-discard');
+              if (saveBtn) saveBtn.classList.add('d-none');
+              if (discardBtn) discardBtn.classList.add('d-none');
+            }
           }, { signal });
         });
 
-        // Delete row — updates pending, rebuilds (Save button shown if dirty)
+        // Delete row — updates journal and rebuilds.
         el.querySelectorAll('.lc-et-del').forEach(btn => {
           btn.addEventListener('click', () => {
             const rowIdx = parseInt(btn.dataset.row);
-            st.pending = st.pending.filter((_, i) => i !== rowIdx);
+            const nextRows = getEffectiveRows().filter((_, i) => i !== rowIdx);
+            updateJournal(nextRows);
             build();
           }, { signal });
         });
 
-        // Add row — appends blank row to pending, rebuilds (Save button shown if dirty)
+        // Add row — appends blank row to journal and rebuilds.
         const addBtn = el.querySelector('.lc-et-add');
         if (addBtn) {
           addBtn.addEventListener('click', () => {
             const newRow = {};
-            getCols(st.pending).forEach(c => { newRow[c] = ''; });
-            st.pending = [...st.pending, newRow];
+            const nextRows = getEffectiveRows();
+            getCols(nextRows).forEach(c => { newRow[c] = ''; });
+            nextRows.push(newRow);
+            updateJournal(nextRows);
             build();
           }, { signal });
         }
 
-        // Save button — persist pending to server via fieldValues (same as form submit)
+        // Save/Discard controls.
+        const discardBtn = el.querySelector('.lc-et-discard');
+        if (discardBtn) {
+          discardBtn.addEventListener('click', () => {
+            commitDiscard();
+          }, { signal });
+        }
+
         const saveBtn = el.querySelector('.lc-et-save');
         if (saveBtn) {
           saveBtn.addEventListener('click', () => {
@@ -1847,6 +1912,68 @@ var LiveCard = (function () {
       };
     }
 
+    // ---- ref ----
+    // Indirection element: resolves a bind path to get the view definition,
+    // then dispatches to the real renderer. The resolved value may be:
+    //   - a string  → treated directly as the element kind ("table", "chart", etc.)
+    //   - an object → { kind, label, data: { columns, chartType, chartOptions, writeTo } }
+    //                 merged with static elemDef (static fields win for protection)
+    //   - null/undefined → falls back to elemDef.data.fallbackKind or shape-inferred kind
+    //
+    // Allowed kinds from resolved value (whitelist, unknown → "table"):
+    //   table, editable-table, chart, metric, list, badge, text, narrative, markdown
+    //
+    // Usage:
+    //   { "kind": "ref",
+    //     "data": { "bind": "fetched_sources.rebalance.proposed_trades",
+    //               "viewBind": "card_data.display_mode",
+    //               "fallbackKind": "table" } }
+    //
+    // viewBind can point to any namespace: card_data, fetched_sources, requires, computed_values.
+    // 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',
+      'text','narrative','markdown','form','filter','todo','alert',
+    ]);
+    function _renderRef(data, el, elemDef, node) {
+      const ed = elemDef.data || {};
+
+      // Resolve the view hint
+      const viewRaw = ed.viewBind ? _resolveBind(node, ed.viewBind) : undefined;
+
+      let resolvedKind, resolvedExtra;
+      if (typeof viewRaw === 'string' && viewRaw) {
+        resolvedKind  = viewRaw;
+        resolvedExtra = {};
+      } else if (viewRaw && typeof viewRaw === 'object' && !Array.isArray(viewRaw)) {
+        resolvedKind  = typeof viewRaw.kind === 'string' ? viewRaw.kind : undefined;
+        resolvedExtra = viewRaw.data && typeof viewRaw.data === 'object' ? viewRaw.data : {};
+      }
+
+      // Validate kind against whitelist; fall back to shape inference
+      if (!resolvedKind || !_REF_KIND_WHITELIST.has(resolvedKind)) {
+        resolvedKind = ed.fallbackKind && _REF_KIND_WHITELIST.has(ed.fallbackKind)
+          ? ed.fallbackKind
+          : (Array.isArray(data) ? 'table' : typeof data === 'string' ? 'text' : 'narrative');
+      }
+
+      // Build effective elemDef: resolved hints first, static elemDef fields override (card author wins)
+      const mergedData = Object.assign({}, resolvedExtra, ed);
+      delete mergedData.viewBind;
+      delete mergedData.fallbackKind;
+
+      // If the resolved hint provided its own bind path, honour it (but static ed.bind still wins)
+      if (!mergedData.bind && resolvedExtra.bind) mergedData.bind = resolvedExtra.bind;
+
+      const effectiveElemDef = Object.assign({}, elemDef, { kind: resolvedKind }, { data: mergedData });
+
+      // Re-resolve data using effective bind (may have changed)
+      const effectiveData = mergedData.bind ? _resolveBind(node, mergedData.bind) : data;
+
+      const renderer = _renderers[resolvedKind] || _renderers.table;
+      renderer(effectiveData, el, effectiveElemDef, node);
+    }
+
     // ---- Register built-in renderers ----
 
     _renderers.table          = _renderTable;
@@ -1867,6 +1994,7 @@ var LiveCard = (function () {
     _renderers['file-upload'] = _renderFileUpload;
     _renderers['chat']        = _renderChatEl;
     _renderers.actions        = _renderActions;
+    _renderers.ref            = _renderRef;
 
     // ===========================================================================
     // _renderElements — render all view.elements for a card node
@@ -2006,12 +2134,6 @@ var LiveCard = (function () {
       // Elements area
       h += `<div class="lc-result" id="${uid}-result"></div>`;
 
-      // Notes section (feature toggle)
-      if (features.notes && opts.showNotes !== false) {
-        h += `<details class="mt-2"><summary class="small fw-medium">Notes</summary>`;
-        h += `<textarea class="form-control form-control-sm mt-1" id="${uid}-notes" rows="3" placeholder="Add notes...">${_esc((node.card_data && node.card_data._notes) || '')}</textarea></details>`;
-      }
-
       h += '</div>';
       containerEl.innerHTML = h;
 
@@ -2051,21 +2173,6 @@ var LiveCard = (function () {
         }, { signal });
       }
 
-      // ---- Wire notes ----
-      const notesEl = document.getElementById(uid + '-notes');
-      if (notesEl) {
-        let nTimer;
-        notesEl.addEventListener('input', () => {
-          clearTimeout(nTimer);
-          nTimer = setTimeout(() => {
-            if (!node.card_data) node.card_data = {};
-            node.card_data._notes = notesEl.value;
-            cfg.onPatch(node.id, { _notes: notesEl.value });
-          }, 800);
-          cleanup.timers.push(nTimer);
-        }, { signal });
-      }
-
       _autoSubscribe(node);
     }
 
@@ -2221,7 +2328,6 @@ var LiveCard = (function () {
     const nodeList = [];
     const nodeMap = {};        // id → { node, colEl, bodyEl }
     const _positions = {};     // id → { x, y, w, h } for canvas mode
-    const showNotes = opts.showNotes !== false;
     const showChat  = opts.showChat || false;
     const defaultCol = opts.defaultCol || 6;
 
@@ -2453,26 +2559,75 @@ var LiveCard = (function () {
 
     function _buildCardWrapper(node) {
       const wrap = document.createElement('div');
-      wrap.className = 'card shadow-sm h-100';
+      const card = node && node.card ? node.card : {};
+      const isSimulation = card.meta && card.meta.simulation === true;
+      const isGandalfCard  = card.meta && card.meta._gandalfCard === true;
+      const extraClass   = isSimulation ? ' lc-simulation-card' : (isGandalfCard ? ' lc-gandalf-card' : '');
+      wrap.className = 'card shadow-sm h-100' + extraClass;
       const header = document.createElement('div');
       header.className = 'card-header d-flex align-items-center gap-2 py-2';
-      const card = node && node.card ? node.card : {};
       const title = (card.meta && card.meta.title) || node.id;
       const tags = (card.meta && card.meta.tags) || [];
       let badgeHtml = '';
-      if ((card.sources && card.sources.length) && !card.view) {
-        var src = card.sources[0] || {};
+      if ((card.source_defs && card.source_defs.length) && !card.view) {
+        var src = card.source_defs[0] || {};
         badgeHtml = '<span class="badge bg-info text-dark ms-auto">' + _esc(src.kind || 'source') + '</span>';
       } else if (tags.length) {
         badgeHtml = tags.map(t => '<span class="badge bg-secondary ms-1">' + _esc(t) + '</span>').join('');
       }
       header.innerHTML = '<strong class="small">' + _esc(title) + '</strong>' + badgeHtml;
-      
+
+      // Gandalf cards: collapsible via caret — caret gets its own click listener,
+      // header is left alone for dragging in canvas mode.
+      if (isGandalfCard) {
+        const caret = document.createElement('span');
+        caret.className = 'lc-gandalf-caret';
+        caret.title = 'Collapse / expand';
+        caret.innerHTML = '<svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.5" stroke-linecap="round" stroke-linejoin="round"><polyline points="6 9 12 15 18 9"/></svg>';
+        header.appendChild(caret);
+
+        const storageKey = 'lc-gandalf-collapsed:' + (node.id || title);
+        if (sessionStorage.getItem(storageKey) === '1') {
+          wrap.classList.add('lc-collapsed');
+          header.dataset.gandalfCollapsed = '1';
+        }
+
+        caret.addEventListener('click', function(e) {
+          e.stopPropagation();
+          const cardEl = caret.closest('.lc-gandalf-card') || wrap;
+          cardEl.classList.toggle('lc-collapsed');
+          sessionStorage.setItem(storageKey, cardEl.classList.contains('lc-collapsed') ? '1' : '0');
+        });
+        caret.addEventListener('pointerdown', e => e.stopPropagation()); // prevent drag start
+      }
+      if (isSimulation) {
+        const simBtns = document.createElement('span');
+        simBtns.className = 'd-inline-flex align-items-center gap-1 ms-auto';
+
+        const pinBtn = document.createElement('button');
+        pinBtn.className = 'btn btn-sm btn-outline-success lc-sim-pin';
+        pinBtn.style.cssText = 'padding: 2px 6px;';
+        pinBtn.innerHTML = '<svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M12 17v5"/><path d="M9 2h6l-1 7h-4L9 2z"/><path d="M6 17h12l-2-4H8L6 17z"/></svg>';
+        pinBtn.title = 'Pin this simulation card';
+        pinBtn.dataset.nodeId = node.id;
+
+        const discardBtn = document.createElement('button');
+        discardBtn.className = 'btn btn-sm btn-outline-danger lc-sim-discard';
+        discardBtn.style.cssText = 'padding: 2px 6px;';
+        discardBtn.innerHTML = '<svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><line x1="18" y1="6" x2="6" y2="18"/><line x1="6" y1="6" x2="18" y2="18"/></svg>';
+        discardBtn.title = 'Discard this simulation card';
+        discardBtn.dataset.nodeId = node.id;
+
+        simBtns.appendChild(pinBtn);
+        simBtns.appendChild(discardBtn);
+        header.appendChild(simBtns);
+      }
+
       // Add dev mode code icon button if devMode is enabled
       if (devMode.current) {
         const codeBtn = document.createElement('button');
         codeBtn.className = 'btn btn-sm btn-outline-secondary';
-        codeBtn.style.cssText = 'padding: 2px 6px; margin-left: auto;';
+        codeBtn.style.cssText = 'padding: 2px 6px;' + (isSimulation ? '' : ' margin-left: auto;');
         codeBtn.innerHTML = '&lt;/&gt;';
         codeBtn.title = 'Inspect card data';
         codeBtn.addEventListener('click', function(e) {
@@ -2495,7 +2650,7 @@ var LiveCard = (function () {
       const status = (node.card_data && node.card_data.status) || 'fresh';
       const card = node && node.card ? node.card : {};
       const title = (card.meta && card.meta.title) || node.id;
-      const kind = (card.sources && card.sources[0] && card.sources[0].kind) || 'source';
+      const kind = (card.source_defs && card.source_defs[0] && card.source_defs[0].kind) || 'source';
       el.innerHTML = `<div class="lc-source-pill shadow-sm">
         ${_statusDot(status)}
         <span class="fw-medium">${_esc(title)}</span>
@@ -2527,7 +2682,7 @@ var LiveCard = (function () {
         col.appendChild(wrap);
         gridEl.appendChild(col);
         nodeMap[node.id] = { node, colEl: col, bodyEl: body };
-        engine.render(node, body, { showNotes, showChat });
+        engine.render(node, body, { showChat });
       });
     }
 
@@ -2615,7 +2770,7 @@ var LiveCard = (function () {
       nodeList.forEach(node => {
         const pos = _positions[node.id] || { x: 0, y: 0 };
 
-        if ((!node.card || !node.card.view) && (node.card && node.card.sources && node.card.sources.length)) {
+        if ((!node.card || !node.card.view) && (node.card && node.card.source_defs && node.card.source_defs.length)) {
           const el = _buildSourcePill(node);
           el.dataset.nodeId = node.id;
           el.style.left = pos.x + 'px';
@@ -2625,7 +2780,10 @@ var LiveCard = (function () {
           _makeDraggable(el, node);
         } else {
           const el = document.createElement('div');
-          el.className = 'lc-canvas-card card shadow-sm';
+          const isSimCanvas   = node.card && node.card.meta && node.card.meta.simulation === true;
+          const isGandalfCanvas = node.card && node.card.meta && node.card.meta._gandalfCard === true;
+          const canvasExtra   = isSimCanvas ? ' lc-simulation-card' : (isGandalfCanvas ? ' lc-gandalf-card' : '');
+          el.className = 'lc-canvas-card card shadow-sm' + canvasExtra;
           el.dataset.nodeId = node.id;
           el.style.left = pos.x + 'px';
           el.style.top  = pos.y + 'px';
@@ -2633,9 +2791,12 @@ var LiveCard = (function () {
 
           const { wrap, body } = _buildCardWrapper(node);
           while (wrap.firstChild) el.appendChild(wrap.firstChild);
+          // Re-apply collapsed state: in canvas mode el is the card container, not wrap
+          const movedHeader = el.querySelector('.card-header');
+          if (movedHeader && movedHeader.dataset.gandalfCollapsed === '1') el.classList.add('lc-collapsed');
           canvasInner.appendChild(el);
           nodeMap[node.id] = { node, colEl: el, bodyEl: body };
-          engine.render(node, body, { showNotes: false, showChat: false });
+          engine.render(node, body, { showChat: false });
           _makeDraggable(el, node);
         }
       });