yaml-flow 5.0.0 → 5.2.0

package/browser/live-cards.js

@@ -197,8 +197,12 @@ var LiveCard = (function () {
       getChatMessages: config.getChatMessages || null,
     };
 
-    const _cleanup = {};   // nodeId → { ac, timers, charts, unsubs }
-    const _subs = {};      // nodeId → Set<callback>
+    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 _todoState = {};  // stateKey → { currentState, pending } for todo dirty tracking
     const _renderers = {}; // kind → fn
     const _nodeEls = {};   // nodeId → { container, resultEl, uid }
     const _chatModal = {
@@ -949,7 +953,48 @@ var LiveCard = (function () {
       const schema = ed.fields || {};
       const props = schema.properties || {};
       const required = schema.required || [];
-      const values = writeTo ? (_resolveBind(node, writeTo) || {}) : (data && typeof data === 'object' ? data : {});
+
+      // --- 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);
+
+      if (!_formState[stateKey]) {
+        _formState[stateKey] = { currentState: incomingCopy, pending: Object.assign({}, incomingCopy) };
+      } 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
+      }
+
+      const st = _formState[stateKey];
+
+      function isDirty() {
+        return JSON.stringify(st.currentState) !== JSON.stringify(st.pending);
+      }
+
+      // Snapshot current input values into pending (called on each input event)
+      function capturePending(form) {
+        form.querySelectorAll('[data-key]').forEach(inp => {
+          const k = inp.dataset.key, 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 form = document.createElement('form');
       form.className = 'row g-2';
@@ -999,10 +1044,12 @@ var LiveCard = (function () {
 
         input.dataset.key = key;
         if (isReq) input.required = true;
-        if (values[key] != null) {
-          if (prop.type === 'boolean') input.checked = !!values[key];
-          else if (prop.format === 'date') input.value = String(values[key]).slice(0, 10);
-          else input.value = values[key];
+        // Populate from pending (not from server values directly)
+        const v = st.pending[key];
+        if (v != null) {
+          if (prop.type === 'boolean') input.checked = !!v;
+          else if (prop.format === 'date') input.value = String(v).slice(0, 10);
+          else input.value = v;
         }
         form.appendChild(col);
       });
@@ -1010,26 +1057,31 @@ var LiveCard = (function () {
       const btnCol = document.createElement('div');
       btnCol.className = 'col-12 mt-1';
       const btn = document.createElement('button');
-      btn.type = 'submit'; btn.className = 'btn btn-sm btn-primary'; btn.textContent = 'Submit';
+      btn.type = 'submit';
+      btn.className = 'btn btn-sm btn-primary' + (isDirty() ? '' : ' d-none');
+      btn.textContent = 'Submit';
       btnCol.appendChild(btn);
       form.appendChild(btnCol);
 
       el.innerHTML = '';
       el.appendChild(form);
 
+      // Real-time input → update pending + show Submit if now dirty
+      form.addEventListener('input', () => {
+        capturePending(form);
+        if (isDirty()) btn.classList.remove('d-none');
+      }, { signal });
+
       form.addEventListener('submit', e => {
         e.preventDefault();
         if (!form.checkValidity()) { form.classList.add('was-validated'); return; }
-        const vals = {};
-        form.querySelectorAll('[data-key]').forEach(inp => {
-          const k = inp.dataset.key, p = props[k];
-          if (p.type === 'boolean') vals[k] = inp.checked;
-          else if (p.type === 'number' || p.type === 'integer') vals[k] = inp.value ? parseFloat(inp.value) : 0;
-          else vals[k] = inp.value;
-        });
-        if (writeTo) _deepSet(node, writeTo, vals);
-        cfg.onPatchState(node.id, { fieldValues: vals });
-        notify(node.id, vals);
+        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);
+        btn.classList.add('d-none');
         btn.textContent = '✓ Saved';
         setTimeout(() => { btn.textContent = 'Submit'; }, 1500);
       }, { signal });
@@ -1042,14 +1094,29 @@ var LiveCard = (function () {
       const signal = cleanup.ac.signal;
       const ed = elemDef.data || {};
       const writeTo = ed.writeTo;
-      const content = typeof data === 'string' ? data : '';
+      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 || '');
+      if (!_notesState[stateKey]) {
+        _notesState[stateKey] = { currentState: incomingContent, pending: incomingContent };
+      } 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
+      }
+      const st = _notesState[stateKey];
 
       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(content)}</textarea>
+        <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>`;
 
       const textarea = el.querySelector('.lc-notes-textarea');
@@ -1069,10 +1136,12 @@ var LiveCard = (function () {
 
       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);
       }, { signal });
@@ -1080,19 +1149,210 @@ var LiveCard = (function () {
 
     // ---- todo ----
 
+    // ---- editable-table ----
+    // Renders an array bound via `data.bind` as an inline-editable table.
+    // Each row is editable in-place; changes are saved on blur (change event).
+    // `data.writeTo` persists changes back to card_data (same pattern as form).
+    // `data.columns` restricts which columns appear (and in what order).
+    // `data.schema.properties[col].type` ("number"/"integer") controls input type.
+    // `data.addRow` (default true) shows "+ Add row" button.
+    // `data.deleteRow` (default true) shows per-row delete button.
+    function _renderEditableTable(data, el, elemDef, node) {
+      const cleanup = _getCleanup(node.id);
+      const signal = cleanup.ac.signal;
+      const ed = elemDef.data || {};
+      const writeTo = ed.writeTo;
+      const schemaProps = (ed.schema && ed.schema.properties) || {};
+      const canAdd    = ed.addRow    !== false;
+      const canDelete = ed.deleteRow !== false;
+
+      // Derive columns from rows if not specified
+      function getCols(rows) {
+        if (ed.columns && ed.columns.length) return ed.columns;
+        const s = new Set();
+        rows.forEach(r => { if (r && typeof r === 'object') Object.keys(r).forEach(k => s.add(k)); });
+        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)
+        : [];
+      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)) };
+      } 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));
+        }
+        // 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);
+      }
+
+      function markDirty() {
+        const saveBtn = el.querySelector('.lc-et-save');
+        if (saveBtn) saveBtn.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));
+        build();
+      }
+
+      function build() {
+        const rows = st.pending;
+        const cols = getCols(rows);
+
+        if (!cols.length && !canAdd) {
+          el.innerHTML = `<p class="text-muted small">${_esc(ed.placeholder || 'No data')}</p>`;
+          return;
+        }
+
+        let h = '<div class="table-responsive"><table class="table table-sm table-bordered mb-0 lc-editable-table"><thead><tr>';
+        cols.forEach(c => { h += `<th class="small text-nowrap">${_esc(c)}</th>`; });
+        if (canDelete) h += '<th style="width:2rem"></th>';
+        h += '</tr></thead><tbody>';
+
+        rows.forEach((row, rowIdx) => {
+          h += `<tr>`;
+          cols.forEach(c => {
+            const v    = row[c];
+            const prop = schemaProps[c] || {};
+            const isNum = prop.type === 'number' || prop.type === 'integer' || (v != null && typeof v === 'number');
+            const displayVal = v != null ? String(v) : '';
+            h += `<td class="p-0">` +
+              `<input type="${isNum ? 'number' : 'text'}" ` +
+              `class="form-control form-control-sm border-0 rounded-0 lc-et-cell" ` +
+              `data-row="${rowIdx}" data-col="${_esc(c)}" value="${_esc(displayVal)}"` +
+              `${isNum ? ' step="any"' : ''}>` +
+              `</td>`;
+          });
+          if (canDelete) {
+            h += `<td class="text-center align-middle p-0">` +
+              `<button class="btn btn-sm btn-link text-danger p-0 lc-et-del" data-row="${rowIdx}" title="Remove row">✕</button>` +
+              `</td>`;
+          }
+          h += '</tr>';
+        });
+
+        if (!rows.length) {
+          const span = cols.length + (canDelete ? 1 : 0);
+          h += `<tr><td colspan="${span}" class="text-muted small text-center">${_esc(ed.placeholder || 'No rows')}</td></tr>`;
+        }
+
+        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-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
+        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;
+            if (isDirty()) markDirty();
+          }, { signal });
+        });
+
+        // Delete row — updates pending, rebuilds (Save button shown if dirty)
+        el.querySelectorAll('.lc-et-del').forEach(btn => {
+          btn.addEventListener('click', () => {
+            const rowIdx = parseInt(btn.dataset.row);
+            st.pending = st.pending.filter((_, i) => i !== rowIdx);
+            build();
+          }, { signal });
+        });
+
+        // Add row — appends blank row to pending, rebuilds (Save button shown if dirty)
+        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];
+            build();
+          }, { signal });
+        }
+
+        // Save button — persist pending to server via fieldValues (same as form submit)
+        const saveBtn = el.querySelector('.lc-et-save');
+        if (saveBtn) {
+          saveBtn.addEventListener('click', () => {
+            commitSave();
+            saveBtn.textContent = '✓ Saved';
+            setTimeout(() => { saveBtn.textContent = 'Save'; }, 1500);
+          }, { signal });
+        }
+      }
+
+      build();
+    }
+
+    // ---- todo ----
+
     function _renderTodo(data, el, elemDef, node) {
       const cleanup = _getCleanup(node.id);
       const signal = cleanup.ac.signal;
       const ed = elemDef.data || {};
       const writeTo = ed.writeTo;
-      const items = Array.isArray(data) ? data : [];
+
+      // --- Journal-style dirty tracking ---
+      // currentState = last confirmed server state; pending = local working copy
+      // On SSE re-render: if dirty (action in-flight), keep pending; if clean, sync from server
+      const stateKey = node.id + ':' + (writeTo || '');
+      const incomingItems = Array.isArray(data) ? data.map(r => Object.assign({}, r)) : [];
+
+      if (!_todoState[stateKey]) {
+        _todoState[stateKey] = { currentState: incomingItems, pending: incomingItems.map(r => Object.assign({}, r)) };
+      } else {
+        const s = _todoState[stateKey];
+        const wasDirty = JSON.stringify(s.currentState) !== JSON.stringify(s.pending);
+        s.currentState = incomingItems;
+        if (!wasDirty) s.pending = incomingItems.map(r => Object.assign({}, r));
+        // if dirty, pending stays so in-flight changes survive the SSE tick
+      }
+      const st = _todoState[stateKey];
 
       function save() {
-        if (writeTo) _deepSet(node, writeTo, items);
-        cfg.onPatchState(node.id, { items });
+        if (writeTo) _deepSet(node, writeTo, st.pending);
+        cfg.onPatchState(node.id, { fieldValues: st.pending });
+        notify(node.id, st.pending);
+        // mark clean after save so next SSE sync resumes normally
+        st.currentState = st.pending.map(r => Object.assign({}, r));
       }
 
       function build() {
+        const items = st.pending;
         let h = '<div class="lc-todo-list">';
         items.forEach((item, i) => {
           const chk = item.done ? ' checked' : '';
@@ -1108,14 +1368,25 @@ var LiveCard = (function () {
         el.innerHTML = h;
 
         el.querySelectorAll('input[data-idx]').forEach(cb => {
-          cb.addEventListener('change', () => { items[parseInt(cb.dataset.idx)].done = cb.checked; save(); build(); }, { signal });
+          cb.addEventListener('change', () => {
+            st.pending[parseInt(cb.dataset.idx)].done = cb.checked;
+            save(); build();
+          }, { signal });
         });
         el.querySelectorAll('[data-rm]').forEach(btn => {
-          btn.addEventListener('click', () => { items.splice(parseInt(btn.dataset.rm), 1); save(); build(); }, { signal });
+          btn.addEventListener('click', () => {
+            st.pending.splice(parseInt(btn.dataset.rm), 1);
+            save(); build();
+          }, { signal });
         });
         const addInput = el.querySelector('.input-group input');
         const addBtn = el.querySelector('.lc-todo-add');
-        const addItem = () => { const t = addInput.value.trim(); if (!t) return; items.push({ text: t, done: false }); save(); build(); };
+        const addItem = () => {
+          const t = addInput.value.trim();
+          if (!t) return;
+          st.pending.push({ text: t, done: false });
+          save(); build();
+        };
         addBtn.addEventListener('click', addItem, { signal });
         addInput.addEventListener('keydown', e => { if (e.key === 'Enter') { e.preventDefault(); addItem(); } }, { signal });
       }
@@ -1171,7 +1442,10 @@ var LiveCard = (function () {
     function _renderText(data, el, elemDef) {
       const ed = elemDef.data || {};
       const format = ed.format || 'default';
-      const style = ed.style || 'default';
+      const style = elemDef.style || ed.style || 'default';
+      const hideIfEmpty = ed.hideIfEmpty || elemDef.hideIfEmpty;
+
+      if (hideIfEmpty && (data == null || data === '')) { el.innerHTML = ''; return; }
 
       // Handle file-links format
       if (format === 'file-links') {
@@ -1195,7 +1469,10 @@ var LiveCard = (function () {
 
       // Default text rendering
       const tag = style === 'heading' ? 'h4' : 'div';
-      const cls = style === 'muted' ? 'text-muted small' : (style === 'heading' ? 'fw-bold' : 'small');
+      const cls = style === 'muted' ? 'text-muted small'
+        : style === 'muted-italic' ? 'text-muted small fst-italic'
+        : style === 'heading' ? 'fw-bold'
+        : 'small';
       el.innerHTML = `<${tag} class="${cls}">${_esc(data != null ? String(data) : '')}</${tag}>`;
     }
 
@@ -1527,8 +1804,9 @@ var LiveCard = (function () {
 
     // ---- Register built-in renderers ----
 
-    _renderers.table     = _renderTable;
-    _renderers.filter    = _renderFilter;
+    _renderers.table          = _renderTable;
+    _renderers['editable-table'] = _renderEditableTable;
+    _renderers.filter         = _renderFilter;
     _renderers.metric    = _renderMetric;
     _renderers.list      = _renderList;
     _renderers.chart     = _renderChart;
@@ -1558,6 +1836,26 @@ var LiveCard = (function () {
       const container = document.createElement('div');
       container.className = 'row g-2';
 
+      const _taskStatus = node.runtime_state && node.runtime_state.task_status;
+      if (_taskStatus && _taskStatus !== 'completed') {
+        const statusEl = document.createElement('div');
+        statusEl.className = 'col-12 d-flex align-items-center gap-2 mb-1';
+        var _statusIconHtml;
+        if (_taskStatus === 'running') {
+          _statusIconHtml = '<span class="spinner-border spinner-border-sm text-muted" style="width:.75rem;height:.75rem;flex-shrink:0"></span>';
+        } else if (_taskStatus === 'failed') {
+          _statusIconHtml = '<span style="font-size:.75rem;line-height:1;flex-shrink:0;color:#dc3545">&#x26A0;&#xFE0E;</span>'; // ⚠ (text variant)
+        } else if (_taskStatus === 'not-started') {
+          _statusIconHtml = '<span style="font-size:.75rem;line-height:1;flex-shrink:0" class="text-muted">&#x25CB;</span>'; // ○
+        } else if (_taskStatus === 'inactivated') {
+          _statusIconHtml = '<span style="font-size:.75rem;line-height:1;flex-shrink:0" class="text-muted">&#x2296;</span>'; // ⊖
+        } else {
+          _statusIconHtml = '<span style="font-size:.75rem;line-height:1;flex-shrink:0" class="text-muted">&#x2013;</span>'; // –
+        }
+        statusEl.innerHTML = _statusIconHtml + '<span class="text-muted" style="font-size:.75rem">' + _esc(_taskStatus) + '</span>';
+        container.appendChild(statusEl);
+      }
+
       view.elements.forEach(elemDef => {
         // Visibility gate
         if (elemDef.visible) {
@@ -1631,18 +1929,35 @@ var LiveCard = (function () {
       if (filesCount > 0) h += `<span class="ms-1 small" aria-label="${filesCount} files">${filesCount}</span>`;
       h += '</button>';
       // Chat icon button (speech bubble)
-      h += `<button class="btn btn-sm btn-outline-secondary" id="${uid}-chat-open" title="Chat">`;
+      h += `<button class="btn btn-sm btn-outline-secondary d-inline-flex align-items-center" id="${uid}-chat-open" title="Chat">`;
       h += '<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="M21 15a2 2 0 01-2 2H7l-4 4V5a2 2 0 012-2h14a2 2 0 012 2z"/></svg>';
       h += '</button>';
       // Refresh icon button
       if (showRefresh) {
-        h += `<button class="btn btn-sm btn-outline-secondary" id="${uid}-refresh" title="Refresh">`;
+        h += `<button class="btn btn-sm btn-outline-secondary d-inline-flex align-items-center" id="${uid}-refresh" title="Refresh">`;
         h += '<svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><polyline points="23 4 23 10 17 10"/><path d="M20.49 15a9 9 0 11-2.12-9.36L23 10"/></svg>';
         h += '</button>';
       }
       h += '</div>';
       h += '</div>';
 
+      // Inference status bar: completion criteria + task-completed tick
+      const inferenceData = node.card_data && node.card_data.llm_task_completion_inference;
+      const isTaskCompleted = !!(inferenceData && inferenceData.isTaskCompleted);
+      const whenIs = node.card && typeof node.card.when_is_task_completed === 'string' && node.card.when_is_task_completed.trim();
+      if (whenIs || isTaskCompleted) {
+        h += `<div class="d-flex align-items-start gap-2 mb-2 px-1 py-1 rounded lc-inference-bar" style="background:rgba(0,0,0,.03)">`;
+        if (isTaskCompleted) {
+          h += `<span class="lc-inference-icon" title="Task completed" style="color:#198754;font-size:.75rem;line-height:1.2;flex-shrink:0">&#x25CF;</span>`;
+        } else {
+          h += `<span class="lc-inference-icon" style="color:#aaa;font-size:.75rem;line-height:1.4;flex-shrink:0" title="Awaiting inference">&#x25CB;</span>`;
+        }
+        if (whenIs) {
+          h += `<span class="text-muted" style="font-size:.72rem;line-height:1.4;font-style:italic"><span style="opacity:.55;font-style:normal">done when:</span> ${_esc(whenIs)}</span>`;
+        }
+        h += `</div>`;
+      }
+
       // Elements area
       h += `<div class="lc-result" id="${uid}-result"></div>`;
 
@@ -1659,9 +1974,7 @@ var LiveCard = (function () {
       const resultEl = document.getElementById(uid + '-result');
       _nodeEls[node.id] = { container: containerEl, resultEl, uid };
 
-      if (node.card_data && node.card_data.status === 'loading') {
-        resultEl.innerHTML = '<div class="d-flex align-items-center gap-2"><span class="spinner-border spinner-border-sm text-muted"></span><span class="text-muted small">Loading…</span></div>';
-      } else if (node.card_data && node.card_data.status === 'error' && node.card_data.error) {
+      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); });
@@ -1758,9 +2071,20 @@ var LiveCard = (function () {
       const filesCountEl = document.getElementById(info.uid + '-files-count');
       if (filesCountEl && filesCountEl.parentNode) filesCountEl.parentNode.removeChild(filesCountEl);
 
-      if (node.card_data.status === 'loading') {
-        info.resultEl.innerHTML = '<div class="d-flex align-items-center gap-2"><span class="spinner-border spinner-border-sm text-muted"></span><span class="text-muted small">Loading…</span></div>';
-      } else if (node.card_data.status === 'error' && node.card_data.error) {
+      // Update inference status bar (tick / hourglass) if card_data changed
+      const infBar = info.container.querySelector('.lc-inference-bar');
+      if (infBar) {
+        const infData = node.card_data && node.card_data.llm_task_completion_inference;
+        const done = !!(infData && infData.isTaskCompleted);
+        const iconEl = infBar.querySelector('.lc-inference-icon');
+        if (iconEl) {
+          iconEl.title = done ? 'Task completed' : 'Awaiting inference';
+          iconEl.style.color = done ? '#198754' : '#aaa';
+          iconEl.innerHTML = done ? '&#x25CF;' : '&#x25CB;';
+        }
+      }
+
+      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); });

package/browser/live-cards.schema.json

@@ -100,9 +100,9 @@
     },
 
     "source_def": {
-      "description": "One source entry. The engine only cares about 'bindTo' (compute namespace key) and 'outputFile' (delivery signal). Every other property is yours — add whatever your task-executor needs: kind, url, headers, mailbox, channel, model, query, etc. The full object is passed verbatim as the --in JSON to the executor.",
+      "description": "One source entry. The engine requires 'bindTo' (compute namespace key) and 'outputFile' (delivery signal path). bindTo and outputFile must be unique across all sources in a card. Every other property is yours — add whatever your task-executor needs: kind, url, headers, mailbox, channel, model, query, etc. The full object is passed verbatim as the --in JSON to the executor.",
       "type": "object",
-      "required": ["bindTo"],
+      "required": ["bindTo", "outputFile"],
       "additionalProperties": true,
       "properties": {
         "bindTo":     { "type": "string",  "description": "Key under fetched_sources.* available in compute expressions" },
@@ -119,7 +119,7 @@
       "properties": {
         "id":        { "type": "string", "description": "Optional element ID for targeted updates" },
         "kind":      {
-          "enum": ["metric", "table", "chart", "form", "filter", "list",
+          "enum": ["metric", "table", "editable-table", "chart", "form", "filter", "list",
                    "notes", "todo", "alert", "narrative", "badge", "text",
                    "markdown", "custom", "actions"]
         },
@@ -227,7 +227,7 @@
     "view":     { "$ref": "#/definitions/view" },
     "card_data": {
       "type": "object",
-      "description": "Authored card data supplied in the card definition",
+      "description": "Authored card data and runtime metadata. Includes uploaded-file metadata maintained by host handlers and inference evaluation results.",
       "properties": {
         "files": {
           "type": "array",
@@ -255,6 +255,18 @@
             },
             "additionalProperties": false
           }
+        },
+        "llm_task_completion_inference": {
+          "type": "object",
+          "description": "Runtime state written by the inference adapter (advanced/undocumented). Prefer the standard sources → compute → provides pattern for LLM-based signals.",
+          "properties": {
+            "inferenceRequested": { "type": "string", "format": "date-time", "description": "Timestamp when the latest inference request was initiated" },
+            "inferenceCompletedAt": { "type": "string", "format": "date-time", "description": "Timestamp when the latest inference request completed" },
+            "isTaskCompleted": { "type": "boolean", "description": "Whether the task is considered complete by the adapter" },
+            "reasoning": { "type": "string", "description": "Explanation of completion decision" },
+            "evidence": { "type": "array", "description": "Supporting evidence from sources/compute" }
+          },
+          "additionalProperties": true
         }
       },
       "additionalProperties": true
@@ -268,6 +280,10 @@
       "type": "array",
       "description": "Ordered array of compute steps. Each reads card_data.*/requires.*/fetched_sources.*/computed_values.* and writes to ephemeral computed_values[bindTo].",
       "items": { "$ref": "#/definitions/compute_step" }
+    },
+    "when_is_task_completed": {
+      "type": "string",
+      "description": "Advanced/undocumented: invokes a registered inference adapter instead of the default source-delivery completion gate. Prefer the standard pattern: use an LLM-backed source, compute a verdict token, and publish it via provides."
     }
   }
 }