npm - yaml-flow - Versions diffs - 3.1.1 → 5.0.0 - Mend

yaml-flow 3.1.1 → 5.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (194) hide show

package/examples/example-board/demo-shell-browser.html ADDED Viewed

@@ -0,0 +1,806 @@
+<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1" />
+  <title>Example Board Demo (Browser Runtime)</title>
+  <link href="https://cdn.jsdelivr.net/npm/bootstrap@5.3.3/dist/css/bootstrap.min.css" rel="stylesheet" />
+  <script src="https://cdn.jsdelivr.net/npm/jsonata/jsonata.min.js"></script>
+  <script src="../../browser/card-compute.js" onerror="this.onerror=null;this.src='https://cdn.jsdelivr.net/npm/yaml-flow@latest/browser/card-compute.js';"></script>
+  <script src="../../browser/live-cards.js" onerror="this.onerror=null;this.src='https://cdn.jsdelivr.net/npm/yaml-flow@latest/browser/live-cards.js';"></script>
+  <script src="../../browser/board-livegraph-runtime.js" onerror="this.onerror=null;this.src='https://cdn.jsdelivr.net/npm/yaml-flow@latest/browser/board-livegraph-runtime.js';"></script>
+   <script src="./reusable-runtime-artifacts-adapter.js"></script>
+</head>
+<body class="bg-light">
+  <div class="container-fluid py-3">
+    <div class="d-flex flex-wrap align-items-center justify-content-between gap-2 mb-3">
+      <div>
+        <h1 class="h4 mb-0" id="boardTitle">Example Board (Browser Runtime)</h1>
+        <div class="small text-muted" id="boardDesc"></div>
+      </div>
+      <div class="d-flex align-items-center gap-2">
+        <a class="btn btn-sm btn-outline-secondary" href="demo-shell-with-server.html">Open Server Runtime Shell</a>
+        <button class="btn btn-sm btn-outline-primary" id="modeBoard">Board</button>
+        <button class="btn btn-sm btn-outline-primary" id="modeCanvas">Canvas</button>
+        <button class="btn btn-sm btn-outline-secondary" id="autoLayout">Auto Layout</button>
+        <button class="btn btn-sm btn-outline-dark" id="refreshAll">Refresh All</button>
+        <div class="form-check ms-2">
+          <input class="form-check-input" type="checkbox" id="devModeToggle" />
+          <label class="form-check-label" for="devModeToggle">Dev Mode</label>
+        </div>
+      </div>
+    </div>
+    <div class="alert alert-info small py-2 mb-3">
+      Browser runtime mode: sources are executed in-browser through an opaque task executor.
+      Card source definitions are treated as task-executor-owned metadata.
+    </div>
+    <div class="alert alert-secondary small py-2 mb-3">
+      Contract and decision notes live in <a href="./demo-shell.html#assumptions-and-tradeoffs">Assumptions and Tradeoffs</a>.
+    </div>
+    <details id="debugPanelDetails" class="card border-warning mb-3 d-none">
+      <summary class="card-header py-2 d-flex justify-content-between align-items-center" style="cursor: pointer;">
+        <strong class="small">Live Debug Panel</strong>
+        <span class="badge text-bg-warning">browser-runtime</span>
+      </summary>
+      <div class="card-body py-2">
+        <pre id="debugPanelBody" class="small mb-0" style="white-space: pre-wrap; max-height: 220px; overflow: auto;">Initializing debug panel...</pre>
+      </div>
+    </details>
+    <div id="boardRoot"></div>
+  </div>
+  <script>
+    (function () {
+      function failInit(message) {
+        const root = document.getElementById('boardRoot');
+        if (root) {
+          root.innerHTML = `<div class="alert alert-danger">${message}</div>`;
+        }
+        console.error(message);
+      }
+      // Get LocalStorageService from board-livegraph-runtime export
+      const LocalStorageService = (window.BoardLiveGraph && window.BoardLiveGraph.LocalStorageService);
+      if (!LocalStorageService) {
+        failInit('LocalStorageService not loaded. Run "npm run build:browser" first.');
+        return;
+      }
+      // ========================================================================
+      // Demo Setup
+      // ========================================================================
+      const CARD_FILES = [
+        'card-ex-source.json',
+        'card-ex-source-http.json',
+        'card-ex-filter.json',
+        'card-ex-metric.json',
+        'card-ex-list.json',
+        'card-ex-chart.json',
+        'card-ex-table.json',
+        'card-ex-status.json',
+        'card-ex-markdown.json',
+        'card-ex-narrative.json',
+        'card-ex-todo.json',
+        'card-ex-form.json',
+        'card-ex-filtered-by-preference.json',
+        'card-ex-actions.json',
+        'card-chain-region-totals.json',
+        'card-chain-top-region.json',
+        'card-chain-region-alert.json',
+      ];
+      const ORDER_SEED = [
+        { id: 'ORD-1001', product: 'Widget A', quantity: 3, amount: 12400, region: 'North' },
+        { id: 'ORD-1002', product: 'Widget B', quantity: 2, amount: 8700, region: 'South' },
+        { id: 'ORD-1003', product: 'Widget A', quantity: 4, amount: 15200, region: 'East' },
+        { id: 'ORD-1004', product: 'Widget C', quantity: 1, amount: 6300, region: 'West' },
+        { id: 'ORD-1005', product: 'Widget B', quantity: 2, amount: 9100, region: 'North' },
+        { id: 'ORD-1006', product: 'Widget C', quantity: 3, amount: 9800, region: 'South' },
+      ];
+      const PRICE_SEED = [
+        { product: 'Widget A', price: 4133.33, currency: 'USD' },
+        { product: 'Widget B', price: 4450.0, currency: 'USD' },
+        { product: 'Widget C', price: 3266.67, currency: 'USD' },
+      ];
+      const clone = (x) => JSON.parse(JSON.stringify(x));
+      const nowIso = () => new Date().toISOString();
+      const MOCK_FS_PREFIX = 'yf:demo-surface:cards:';
+      function safeJsonParse(raw, fallback) {
+        if (!raw) return fallback;
+        try {
+          return JSON.parse(raw);
+        } catch {
+          return fallback;
+        }
+      }
+      function mockFsKey(cardId, dirName) {
+        return `${MOCK_FS_PREFIX}${String(cardId)}:${String(dirName)}`;
+      }
+      function readMockDir(cardId, dirName) {
+        const key = mockFsKey(cardId, dirName);
+        const parsed = safeJsonParse(localStorage.getItem(key), []);
+        return Array.isArray(parsed) ? parsed : [];
+      }
+      function writeMockDir(cardId, dirName, items) {
+        localStorage.setItem(mockFsKey(cardId, dirName), JSON.stringify(Array.isArray(items) ? items : []));
+      }
+      function clearMockDir(cardId, dirName) {
+        localStorage.removeItem(mockFsKey(cardId, dirName));
+      }
+      function toFileMetadataOnly(entry) {
+        if (!entry || typeof entry !== 'object') return null;
+        return {
+          name: entry.name || null,
+          stored_name: entry.stored_name || null,
+          size: typeof entry.size === 'number' ? entry.size : null,
+          mime_type: entry.mime_type || null,
+          path: entry.path || null,
+          uploaded_at: entry.uploaded_at || null,
+        };
+      }
+      function normalizeDisplayFileName(name) {
+        const input = String(name || '').trim();
+        if (!input) return 'upload.bin';
+        const parts = input.split(/[/\\]/);
+        const base = parts[parts.length - 1] || 'upload.bin';
+        return base;
+      }
+      function normalizeStem(rawStem) {
+        const normalized = String(rawStem || '')
+          .toLowerCase()
+          .replace(/\s+/g, '_')
+          .replace(/[^a-z0-9_-]/g, '_')
+          .replace(/_+/g, '_')
+          .replace(/^_+|_+$/g, '');
+        return normalized || 'file';
+      }
+      function normalizeExt(rawExt) {
+        if (!rawExt || rawExt === '.') return '';
+        const extBody = String(rawExt).replace(/^\./, '').toLowerCase().replace(/[^a-z0-9]/g, '');
+        return extBody ? `.${extBody}` : '';
+      }
+      function parseLeadingSerial(fileName) {
+        const m = String(fileName || '').match(/^(\d+)[-_]/);
+        return m ? parseInt(m[1], 10) : 0;
+      }
+      function nextSerialFromNames(names) {
+        let maxSeen = 0;
+        for (const name of names) {
+          const serial = parseLeadingSerial(name);
+          if (Number.isFinite(serial) && serial > maxSeen) maxSeen = serial;
+        }
+        return maxSeen + 1;
+      }
+      function buildStoredFileName(cardId, fileName) {
+        const maxLen = 32;
+        const displayName = normalizeDisplayFileName(fileName);
+        const extRaw = displayName.includes('.') ? displayName.slice(displayName.lastIndexOf('.')) : '';
+        const ext = normalizeExt(extRaw);
+        const stemRaw = extRaw ? displayName.slice(0, -extRaw.length) : displayName;
+        const stemNorm = normalizeStem(stemRaw);
+        const existing = readPersistedFileMetadata(cardId);
+        const names = existing.map((f) => f && typeof f.stored_name === 'string' ? f.stored_name : '').filter(Boolean);
+        let serial = nextSerialFromNames(names);
+        while (true) {
+          const prefix = `${String(serial).padStart(3, '0')}-`;
+          let keepExt = ext;
+          let stemBudget = maxLen - prefix.length - keepExt.length;
+          if (stemBudget < 1) {
+            keepExt = '';
+            stemBudget = maxLen - prefix.length;
+          }
+          const stem = stemNorm.slice(0, Math.max(1, stemBudget));
+          let candidate = `${prefix}${stem}${keepExt}`;
+          if (candidate.length > maxLen) {
+            candidate = candidate.slice(0, maxLen).replace(/\.$/, '');
+          }
+          if (!names.includes(candidate)) return candidate;
+          serial += 1;
+        }
+      }
+      function nextChatPath(cardId, role) {
+        const chats = readMockDir(cardId, 'chats');
+        const names = chats
+          .map((entry) => {
+            if (!entry || typeof entry.path !== 'string') return '';
+            const parts = entry.path.split('/');
+            return parts[parts.length - 1] || '';
+          })
+          .filter(Boolean);
+        const serial = nextSerialFromNames(names);
+        const safeRole = String(role || 'system').toLowerCase().replace(/[^a-z0-9_-]/g, '_') || 'system';
+        return `${cardId}/chats/${String(serial).padStart(3, '0')}_${safeRole}.txt`;
+      }
+      function readPersistedFileMetadata(cardId) {
+        return readMockDir(cardId, 'files')
+          .map(toFileMetadataOnly)
+          .filter(Boolean);
+      }
+      function readPersistedChatMessages(cardId) {
+        return readMockDir(cardId, 'chats')
+          .map((entry) => {
+            if (!entry || typeof entry !== 'object') return null;
+            return {
+              role: typeof entry.role === 'string' ? entry.role : 'system',
+              text: typeof entry.text === 'string' ? entry.text : '',
+              files: Array.isArray(entry.files) ? entry.files.map(toFileMetadataOnly).filter(Boolean) : [],
+              at: typeof entry.at === 'string' ? entry.at : null,
+            };
+          })
+          .filter(Boolean);
+      }
+      async function fileToBase64(file) {
+        if (!file || typeof file.arrayBuffer !== 'function') return null;
+        const buffer = await file.arrayBuffer();
+        const bytes = new Uint8Array(buffer);
+        let binary = '';
+        const chunkSize = 0x8000;
+        for (let i = 0; i < bytes.length; i += chunkSize) {
+          const chunk = bytes.subarray(i, i + chunkSize);
+          binary += String.fromCharCode.apply(null, chunk);
+        }
+        return btoa(binary);
+      }
+      async function persistFileForCard(cardId, fileLike, now) {
+        if (!fileLike) return null;
+        if (typeof fileLike === 'object' && typeof fileLike.name === 'string' && typeof fileLike.arrayBuffer === 'function') {
+          const name = normalizeDisplayFileName(fileLike.name);
+          const storedName = buildStoredFileName(cardId, name);
+          const metadata = {
+            name,
+            stored_name: storedName,
+            size: typeof fileLike.size === 'number' ? fileLike.size : null,
+            mime_type: fileLike.type || 'application/octet-stream',
+            path: `${cardId}/files/${storedName}`,
+            uploaded_at: now,
+          };
+          const filesDir = readMockDir(cardId, 'files');
+          filesDir.push({
+            ...metadata,
+            content_base64: await fileToBase64(fileLike),
+          });
+          writeMockDir(cardId, 'files', filesDir);
+          return metadata;
+        }
+        if (typeof fileLike === 'object' && typeof fileLike.name === 'string') {
+          const displayName = normalizeDisplayFileName(fileLike.name);
+          const storedName = fileLike.stored_name || buildStoredFileName(cardId, displayName);
+          const metadata = {
+            name: displayName,
+            stored_name: storedName,
+            size: typeof fileLike.size === 'number' ? fileLike.size : null,
+            mime_type: fileLike.mime_type || 'application/octet-stream',
+            path: fileLike.path || `${cardId}/files/${storedName}`,
+            uploaded_at: fileLike.uploaded_at || now,
+          };
+          const filesDir = readMockDir(cardId, 'files');
+          const knownPaths = new Set(filesDir.map((entry) => entry && entry.path).filter(Boolean));
+          if (!knownPaths.has(metadata.path)) {
+            filesDir.push(metadata);
+            writeMockDir(cardId, 'files', filesDir);
+          }
+          return metadata;
+        }
+        if (typeof fileLike === 'string') {
+          const displayName = normalizeDisplayFileName(fileLike);
+          const storedName = buildStoredFileName(cardId, displayName);
+          const metadata = {
+            name: displayName,
+            stored_name: storedName,
+            size: null,
+            mime_type: 'application/octet-stream',
+            path: `${cardId}/files/${storedName}`,
+            uploaded_at: now,
+          };
+          const filesDir = readMockDir(cardId, 'files');
+          filesDir.push(metadata);
+          writeMockDir(cardId, 'files', filesDir);
+          return metadata;
+        }
+        return null;
+      }
+      function appendChatRecord(cardId, record) {
+        const chatsDir = readMockDir(cardId, 'chats');
+        const next = { ...(record || {}) };
+        if (!next.path) {
+          next.path = nextChatPath(cardId, next.role || 'system');
+        }
+        chatsDir.push(next);
+        writeMockDir(cardId, 'chats', chatsDir);
+      }
+      function renderDebugPanel(runtimeState, artifacts) {
+        const el = document.getElementById('debugPanelBody');
+        if (!el) return;
+        const tasks = runtimeState && runtimeState.state && runtimeState.state.tasks
+          ? runtimeState.state.tasks
+          : {};
+        const availableOutputs = runtimeState && runtimeState.state && Array.isArray(runtimeState.state.availableOutputs)
+          ? runtimeState.state.availableOutputs
+          : [];
+        const byStatus = {};
+        for (const task of Object.values(tasks)) {
+          const status = task && task.status ? task.status : 'unknown';
+          byStatus[status] = (byStatus[status] || 0) + 1;
+        }
+        const cardRuntimeById = artifacts && artifacts.cardRuntimeById ? artifacts.cardRuntimeById : {};
+        const metric = cardRuntimeById['card-ex-metric'] && cardRuntimeById['card-ex-metric'].computed_values
+          ? cardRuntimeById['card-ex-metric'].computed_values.totalRevenue
+          : undefined;
+        const topProducts = cardRuntimeById['card-ex-list'] && cardRuntimeById['card-ex-list'].computed_values
+          ? cardRuntimeById['card-ex-list'].computed_values.topProducts
+          : undefined;
+        const regionCounts = cardRuntimeById['card-ex-chart'] && cardRuntimeById['card-ex-chart'].computed_values
+          ? cardRuntimeById['card-ex-chart'].computed_values.regionCounts
+          : undefined;
+        const filteredOrders = cardRuntimeById['card-ex-table'] && cardRuntimeById['card-ex-table'].computed_values
+          ? cardRuntimeById['card-ex-table'].computed_values.filtered
+          : undefined;
+        const watched = {
+          orders: availableOutputs.includes('orders'),
+          prices: availableOutputs.includes('prices'),
+          selections: availableOutputs.includes('selections'),
+          formToken: availableOutputs.includes('card-ex-form'),
+        };
+        const lines = [
+          `updatedAt: ${new Date().toISOString()}`,
+          `statusCounts: ${JSON.stringify(byStatus)}`,
+          `availableOutputs(${availableOutputs.length}): ${availableOutputs.slice().sort().join(', ')}`,
+          `watchedTokens: ${JSON.stringify(watched)}`,
+          `card-ex-metric.totalRevenue: ${JSON.stringify(metric)}`,
+          `card-ex-list.topProducts.length: ${Array.isArray(topProducts) ? topProducts.length : 'n/a'}`,
+          `card-ex-chart.regionCounts.length: ${Array.isArray(regionCounts) ? regionCounts.length : 'n/a'}`,
+          `card-ex-table.filtered.length: ${Array.isArray(filteredOrders) ? filteredOrders.length : 'n/a'}`,
+        ];
+        el.textContent = lines.join('\n');
+      }
+      function hasCompatiblePersistedArtifacts(cardDefinitions, cardRuntimeById) {
+        if (!cardRuntimeById || typeof cardRuntimeById !== 'object') return false;
+        const cards = Array.isArray(cardDefinitions) ? cardDefinitions : [];
+        if (!cards.length) return false;
+        return cards.every((card) => {
+          const artifact = cardRuntimeById[card.id];
+          if (!artifact || typeof artifact !== 'object') return false;
+          if (card.sources && card.sources.length > 0) {
+            if (!(artifact.fetched_sources && typeof artifact.fetched_sources === 'object' && !Array.isArray(artifact.fetched_sources))) {
+              return false;
+            }
+          }
+          if (card.requires && card.requires.length > 0) {
+            if (!(artifact.requires && typeof artifact.requires === 'object' && !Array.isArray(artifact.requires))) {
+              return false;
+            }
+          }
+          return true;
+        });
+      }
+      function parseBoardMeta(yamlText) {
+        const nameMatch = yamlText.match(/^name:\s*(.+)$/m);
+        const descMatch = yamlText.match(/^desc:\s*(.+)$/m);
+        return {
+          name: nameMatch ? nameMatch[1].trim() : 'Example Board',
+          desc: descMatch ? descMatch[1].trim() : '',
+        };
+      }
+      async function loadBoardFromFiles() {
+        const [boardYaml, ...cards] = await Promise.all([
+          fetch('./board.yaml').then(r => r.text()),
+          ...CARD_FILES.map(name => fetch(`./cards/${name}`).then(r => r.json())),
+        ]);
+        const boardMeta = parseBoardMeta(boardYaml);
+        for (const c of cards) {
+          c.card_data = c.card_data || {};
+          const persistedFiles = readPersistedFileMetadata(c.id);
+          if (persistedFiles.length > 0) c.card_data.files = persistedFiles;
+          const persistedChats = readPersistedChatMessages(c.id);
+          if (persistedChats.length > 0) c.card_data.messages = persistedChats;
+          // Persist card definition to localStorage (mirrors server's tmp/cards/<id>.json)
+          LocalStorageService.writeCard(c.id, c);
+        }
+        return { board: boardMeta, cards };
+      }
+      function makeMockSourceServer() {
+        let orderRows = clone(ORDER_SEED);
+        let priceRows = clone(PRICE_SEED);
+        return {
+          fetchSource: async function (card, sourceDef) {
+            const mockKey = sourceDef && typeof sourceDef.mock === 'string' ? sourceDef.mock : '';
+            const script = String(sourceDef && sourceDef.script || sourceDef && sourceDef.cli || '').toLowerCase();
+            if (mockKey === 'orders') return clone(orderRows);
+            if (mockKey === 'prices') return clone(priceRows);
+            if (card.id === 'card-ex-source' || script.includes('fetch-orders')) return clone(orderRows);
+            if (card.id === 'card-ex-source-http' || script.includes('fetch-prices')) return clone(priceRows);
+            return null;
+          },
+          setDatasets: function (nextOrders, nextPrices) {
+            if (Array.isArray(nextOrders)) orderRows = clone(nextOrders);
+            if (Array.isArray(nextPrices)) priceRows = clone(nextPrices);
+          },
+        };
+      }
+      function replaceNodeInPlace(target, source) {
+        Object.keys(target).forEach(k => delete target[k]);
+        Object.assign(target, clone(source));
+      }
+      let board = null;
+      let runtime = null;
+      let runtimeUnsub = null;
+      let currentMode = 'board';
+      const nodesById = {};
+      function setDebugPanelVisibility(isDevModeOn) {
+        const details = document.getElementById('debugPanelDetails');
+        if (!details) return;
+        if (isDevModeOn) {
+          details.classList.remove('d-none');
+        } else {
+          details.open = false;
+          details.classList.add('d-none');
+        }
+      }
+      function toIsoTimeTag(iso) {
+        const d = new Date(iso);
+        const hh = String(d.getHours()).padStart(2, '0');
+        const mm = String(d.getMinutes()).padStart(2, '0');
+        const ss = String(d.getSeconds()).padStart(2, '0');
+        return `${hh}:${mm}:${ss}`;
+      }
+      function compactFiles(files) {
+        if (!Array.isArray(files)) return [];
+        return files
+          .map((f) => {
+            if (!f) return null;
+            if (typeof f === 'string') return { name: f };
+            if (typeof f === 'object' && typeof f.name === 'string') return { name: f.name, size: f.size || null };
+            return null;
+          })
+          .filter(Boolean);
+      }
+      async function handleActionInBrowserRuntime(id, actionType, payload) {
+        const node = nodesById[id];
+        if (!node) return;
+        const now = nowIso();
+        const cardData = node.card_data || {};
+        if (actionType === 'chat-send') {
+          const text = payload && typeof payload.text === 'string' ? payload.text.trim() : '';
+          const rawFiles = Array.isArray(payload && payload.files) ? payload.files : [];
+          if (!text && rawFiles.length === 0) return;
+          const fileMetas = [];
+          for (const fileLike of rawFiles) {
+            const persisted = await persistFileForCard(id, fileLike, now);
+            if (persisted) fileMetas.push(persisted);
+          }
+          appendChatRecord(id, {
+            at: now,
+            role: 'user',
+            text,
+            files: fileMetas,
+          });
+          fileMetas.forEach((fileMeta) => {
+            if (!fileMeta || !fileMeta.stored_name) return;
+            const display = fileMeta.name || 'file';
+            appendChatRecord(id, {
+              at: now,
+              role: 'system',
+              text: `File ${display} uploaded as ${fileMeta.stored_name}.`,
+              files: [],
+            });
+          });
+          // Keep chat render state in sync with local-storage-backed chat entries.
+          runtime.patchCardState(id, {
+            messages: readPersistedChatMessages(id),
+            lastInteractionAt: now,
+          });
+          return;
+        }
+        if (actionType === 'action') {
+          const buttonId = payload && typeof payload.buttonId === 'string' ? payload.buttonId : '';
+          if (!buttonId) return;
+          runtime.patchCardState(id, {
+            lastAction: { buttonId, at: now },
+            lastActionText: `${buttonId} @ ${toIsoTimeTag(now)}`,
+          });
+        }
+      }
+      function syncBoardNodes(nextNodes) {
+        const existingIds = new Set(board ? board.nodes.map(n => n.id) : []);
+        const nextById = Object.fromEntries(nextNodes.map(n => [n.id, n]));
+        if (board) {
+          for (const id of existingIds) {
+            if (!nextById[id]) board.remove(id);
+          }
+        }
+        for (const nextNode of nextNodes) {
+          const existing = nodesById[nextNode.id];
+          if (existing) replaceNodeInPlace(existing, nextNode);
+          else {
+            nodesById[nextNode.id] = clone(nextNode);
+            if (board) board.add(nodesById[nextNode.id]);
+          }
+        }
+        if (board) board.refresh();
+      }
+      async function bootstrap() {
+        const loaded = await loadBoardFromFiles();
+        const mockServer = makeMockSourceServer();
+        const createBoardLiveGraphRuntime = (window.BoardLiveGraph && window.BoardLiveGraph.createBoardLiveGraphRuntime);
+        if (!createBoardLiveGraphRuntime) {
+          throw new Error('BoardLiveGraph runtime not loaded. Run "npm run build:browser" first.');
+        }
+        document.getElementById('boardTitle').textContent = loaded.board.name + ' (Browser Runtime)';
+        document.getElementById('boardDesc').textContent = loaded.board.desc;
+        const cardDefinitions = loaded.cards;
+        const cardDefsById = Object.fromEntries(cardDefinitions.map(c => [c.id, c]));
+        const deepSet = (obj, path, value) => {
+          if (!path) return;
+          const parts = String(path).split('.');
+          let cur = obj;
+          for (let i = 0; i < parts.length - 1; i++) {
+            const k = parts[i];
+            if (!cur[k] || typeof cur[k] !== 'object') cur[k] = {};
+            cur = cur[k];
+          }
+          cur[parts[parts.length - 1]] = value;
+        };
+        runtime = createBoardLiveGraphRuntime(loaded.cards, {
+          taskExecutor: async function ({ card }) {
+            const out = {};
+            for (const sourceDef of (card.sources || [])) {
+              const payload = await mockServer.fetchSource(card, sourceDef);
+              if (payload !== null && payload !== undefined) out[sourceDef.bindTo] = payload;
+            }
+            return out;
+          },
+        });
+        // Restore previous runtime artifacts from localStorage (mirrors reading runtime-out/ from disk on server)
+        const cardRuntimeById = LocalStorageService.readAllComputedArtifacts(cardDefinitions.map(c => c.id));
+        let statusSnapshot = LocalStorageService.readStatusSnapshot();
+        // Build initial renderable nodes from artifacts (same pattern as server shell)
+        const initialArtifacts = statusSnapshot && Object.keys(cardRuntimeById).length > 0 && hasCompatiblePersistedArtifacts(cardDefinitions, cardRuntimeById)
+          ? { cardDefinitions, statusSnapshot, cardRuntimeById }
+          : buildBrowserArtifactsFromRuntime({
+              boardPath: 'browser',
+              cardDefinitions,
+              runtimeModels: runtime.getNodes(),
+              graphState: runtime.getState(),
+            });
+        const initialNodes = buildLiveCardModelsFromArtifacts(initialArtifacts);
+        for (const n of initialNodes) nodesById[n.id] = clone(n);
+        const engine = LiveCard.init({
+          resolve: (id) => nodesById[id],
+          onPatchState: (id, patch) => {
+            // Form submissions pass { fieldValues: {...} } from LiveCard form elements.
+            // Persist those values in localStorage card at the card's writeTo path.
+            if (patch && Object.keys(patch).length === 1 && patch.fieldValues) {
+              const cardDef = cardDefsById[id];
+              let writeTo = null;
+              if (cardDef && cardDef.view && Array.isArray(cardDef.view.elements)) {
+                for (const elem of cardDef.view.elements) {
+                  if (elem && elem.data && elem.data.writeTo) {
+                    writeTo = elem.data.writeTo;
+                    break;
+                  }
+                }
+              }
+              const statePatch = {};
+              if (typeof writeTo === 'string' && writeTo.startsWith('card_data.')) {
+                deepSet(statePatch, writeTo.slice('card_data.'.length), patch.fieldValues);
+              } else {
+                Object.assign(statePatch, patch.fieldValues);
+              }
+              // Apply patch to card definition in memory and in localStorage
+              const cardInMem = cardDefsById[id];
+              if (cardInMem) {
+                deepSet(cardInMem, 'card_data', { ...cardInMem.card_data, ...statePatch });
+                LocalStorageService.writeCard(id, cardInMem);
+              }
+              // Also patch the runtime (which may be used by compute)
+              runtime.patchCardState(id, statePatch);
+              return;
+            }
+            // Auto-commit: file-upload element reports staged files via _stagedFiles.
+            // Persist metadata immediately and update the rendered list — no commit button needed.
+            if (patch && Array.isArray(patch._stagedFiles) && patch._stagedFiles.length > 0) {
+              const now = nowIso();
+              const existing = readPersistedFileMetadata(id);
+              const seen = new Set(existing.map((f) => f && f.name ? f.name : String(f)));
+              for (const item of patch._stagedFiles) {
+                if (!item || typeof item.name !== 'string') continue;
+                if (seen.has(item.name)) continue;
+                existing.push(persistStagedFileMetadata(id, item));
+                seen.add(item.name);
+              }
+              writeStoredFiles(id, existing);
+              runtime.patchCardState(id, { files: existing, _stagedFiles: [] });
+              return;
+            }
+            runtime.patchCardState(id, patch || {});
+          },
+          onRefresh: (id) => runtime.retrigger(id),
+          onAction: (id, actionType, payload) => {
+            void handleActionInBrowserRuntime(id, actionType, payload || {});
+          },
+          getChatMessages: (id) => {
+            const items = readPersistedChatMessages(id);
+            return items.map((m) => ({
+              role: m && typeof m.role === 'string' ? m.role : 'system',
+              text: m && typeof m.text === 'string' ? m.text : '',
+              files: Array.isArray(m && m.files) ? m.files : [],
+            }));
+          },
+        });
+        board = LiveCard.Board(engine, document.getElementById('boardRoot'), {
+          nodes: Object.values(nodesById),
+          mode: currentMode,
+          canvas: { height: '72vh', overflow: 'auto' },
+        });
+        runtimeUnsub = runtime.subscribe(function () {
+          const runtimeState = runtime.getState();
+          // Build runtime artifacts (mirrors what CLI does after compute)
+          const artifacts = buildBrowserArtifactsFromRuntime({
+            boardPath: 'browser',
+            cardDefinitions,
+            runtimeModels: runtime.getNodes(),
+            graphState: runtimeState,
+          });
+          // Persist to localStorage (mirrors CLI writing to runtime-out/)
+          for (const [id, artifact] of Object.entries(artifacts.cardRuntimeById)) {
+            LocalStorageService.writeComputedArtifact(artifact);
+          }
+          LocalStorageService.writeStatusSnapshot(artifacts.statusSnapshot);
+          // Rebuild renderable nodes from persisted artifacts (same pattern as server shell)
+          syncBoardNodes(buildLiveCardModelsFromArtifacts(artifacts));
+          // Keep a compact runtime snapshot visible for debugging token flow issues.
+          renderDebugPanel(runtimeState, artifacts);
+        });
+        runtime.push({ type: 'inject-tokens', tokens: [], timestamp: nowIso() });
+        // Force a full recompute pass to recover from stale/incomplete localStorage artifacts.
+        runtime.retriggerAll();
+        window.demoLiveGraph = {
+          mode: 'browser',
+          runtime,
+          setDatasets: function (nextOrders, nextPrices) {
+            mockServer.setDatasets(nextOrders, nextPrices);
+            runtime.retriggerAll();
+          },
+          clearLocalStorage: function () {
+            LocalStorageService.clear();
+            Object.keys(localStorage).forEach((key) => {
+              if (String(key).startsWith(MOCK_FS_PREFIX)) localStorage.removeItem(key);
+            });
+            window.location.reload();
+          },
+        };
+        document.getElementById('modeBoard').addEventListener('click', function () {
+          currentMode = 'board';
+          if (board) board.setMode('board');
+        });
+        document.getElementById('modeCanvas').addEventListener('click', function () {
+          currentMode = 'canvas';
+          if (board) board.setMode('canvas');
+        });
+        document.getElementById('autoLayout').addEventListener('click', function () {
+          if (board) {
+            board.setMode('canvas');
+            currentMode = 'canvas';
+            board.autoLayout();
+          }
+        });
+        document.getElementById('refreshAll').addEventListener('click', function () {
+          if (runtime) runtime.retriggerAll();
+        });
+        document.getElementById('devModeToggle').addEventListener('change', function () {
+          if (board) board.setDevMode(this.checked);
+          setDebugPanelVisibility(this.checked);
+        });
+        // Keep debug UI out of the way unless Dev Mode is explicitly enabled.
+        setDebugPanelVisibility(document.getElementById('devModeToggle').checked);
+      }
+      bootstrap().catch(function (err) {
+        console.error(err);
+        document.getElementById('boardRoot').innerHTML =
+          `<div class="alert alert-danger">Failed to start browser runtime demo: ${String(err && err.message || err)}</div>`;
+      });
+      window.addEventListener('beforeunload', function () {
+        if (runtimeUnsub) runtimeUnsub();
+        if (runtime) runtime.dispose();
+      });
+    })();
+  </script>
+</body>
+</html>