@atolljs/devtools 0.1.7 → 0.1.8

package/app/panels/inspect-island.js

@@ -0,0 +1,351 @@
+// Island inspector tabs (rendered into #inspExtra): Elements (the island's
+// real DOM via `island.tree`, hover-to-highlight in the page via
+// `island.highlight`), Props (island:props history with diffs) and Events
+// (island:event log with payload previews).
+//
+// Render contract: the inspector hook fires many times a second. The tab
+// DOM is built once per inspected key; afterwards only counts/gates are
+// touched, and lists re-render when their data changed. The tree is only
+// rebuilt when a fetch lands, keeping expanded/selected state.
+
+const CSS = `
+.ii { margin: 10px 0 4px; }
+.ii-tabs { display:flex; gap:4px; margin-bottom:8px; }
+.ii-tabs button { background:none; border:1px solid #21262d; color:#8b949e; border-radius:6px; padding:3px 10px; cursor:pointer; font:inherit; font-size:11px; }
+.ii-tabs button.on { color:#c9d1d9; border-color:#58a6ff; background:#161b22; }
+.ii-tabs .n { color:#8b949e; margin-left:4px; }
+.ii-pane { display:none; } .ii-pane.on { display:block; }
+.ii-bar { display:flex; gap:8px; align-items:center; margin-bottom:6px; font-size:11px; flex-wrap:wrap; }
+.ii-bar input[type=text] { background:#0d1117; color:#c9d1d9; border:1px solid #30363d; border-radius:4px; padding:2px 6px; font:inherit; }
+.ii-msg { color:#d29922; font-size:11px; }
+.ii-split { display:grid; grid-template-columns: minmax(0,3fr) minmax(0,2fr); gap:10px; }
+.ii-tree, .ii-detail, .ii-list { border:1px solid #21262d; border-radius:8px; background:#010409; max-height:380px; overflow:auto; padding:4px 6px; font-size:11px; }
+.ii-node > .ii-row { white-space:nowrap; cursor:default; padding:0 4px; border-radius:3px; }
+.ii-node > .ii-row:hover { background:#161b22; }
+.ii-node > .ii-row.sel { background:#1f6feb33; }
+.ii-node > .ii-kids { padding-left:14px; }
+.ii-node.closed > .ii-kids { display:none; }
+.ii-caret { display:inline-block; width:12px; color:#8b949e; cursor:pointer; user-select:none; }
+.ii-tag { color:#7ee787; } .ii-an { color:#79c0ff; } .ii-av { color:#a5d6ff; } .ii-tx { color:#c9d1d9; }
+.ii-more { color:#8b949e; font-style:italic; padding-left:16px; }
+.ii-entry { border-bottom:1px dashed #21262d; padding:4px 0; }
+.ii-entry pre { margin:2px 0 0; white-space:pre-wrap; word-break:break-all; }
+.ii-t { color:#484f58; margin-right:6px; }
+.ii-add { color:#3fb950; } .ii-del { color:#f85149; } .ii-chg { color:#d29922; }
+`;
+
+const MAX_PROPS = 100;
+const MAX_EVENTS = 500;
+
+const injectCss = () => {
+  if (document.getElementById('ii-css')) return;
+  const s = document.createElement('style');
+  s.id = 'ii-css';
+  s.textContent = CSS;
+  document.head.appendChild(s);
+};
+
+const clock = (t) => {
+  const d = new Date(t);
+  const p = (n, w = 2) => String(n).padStart(w, '0');
+  return `${p(d.getHours())}:${p(d.getMinutes())}:${p(d.getSeconds())}.${p(d.getMilliseconds(), 3)}`;
+};
+
+const tryJson = (s) => {
+  try { return { ok: true, v: JSON.parse(s) }; } catch { return { ok: false }; }
+};
+
+/** Top-level key diff between two props previews ('' when unparseable). */
+const diffProps = (prev, next, esc) => {
+  if (prev === undefined) return '<span class="muted">initial</span>';
+  const a = tryJson(prev), b = tryJson(next);
+  if (!a.ok || !b.ok || typeof a.v !== 'object' || typeof b.v !== 'object' || !a.v || !b.v) {
+    return prev === next ? '<span class="muted">unchanged</span>' : '<span class="ii-chg">changed (preview truncated)</span>';
+  }
+  const out = [];
+  for (const k of Object.keys(b.v)) {
+    if (!(k in a.v)) out.push(`<span class="ii-add">+ ${esc(k)}: ${esc(JSON.stringify(b.v[k]))}</span>`);
+    else if (JSON.stringify(a.v[k]) !== JSON.stringify(b.v[k])) {
+      out.push(`<span class="ii-chg">~ ${esc(k)}: ${esc(JSON.stringify(a.v[k]))} → ${esc(JSON.stringify(b.v[k]))}</span>`);
+    }
+  }
+  for (const k of Object.keys(a.v)) if (!(k in b.v)) out.push(`<span class="ii-del">− ${esc(k)}</span>`);
+  return out.length ? out.join('<br>') : '<span class="muted">unchanged</span>';
+};
+
+export function setup(api) {
+  injectCss();
+  const { esc } = api;
+
+  /** islandKey → { props: [{t, preview}], events: [{t, name, payload}] } */
+  const hist = new Map();
+  const histOf = (k) => {
+    let h = hist.get(k);
+    if (!h) hist.set(k, (h = { props: [], events: [], seq: 0 }));
+    return h;
+  };
+
+  api.onEvent((s, e) => {
+    if (e.type === 'island:props') {
+      const h = histOf(api.key(s.id, e.instance));
+      h.props.push({ t: Date.now(), preview: e.props });
+      if (h.props.length > MAX_PROPS) h.props.shift();
+      h.seq++;
+    } else if (e.type === 'island:event') {
+      const h = histOf(api.key(s.id, e.instance));
+      h.events.push({ t: Date.now(), name: e.name, payload: e.payload });
+      if (h.events.length > MAX_EVENTS) h.events.shift();
+      h.seq++;
+    }
+  });
+  api.onReset(() => { hist.clear(); view = null; });
+  api.onReconcile((ids) => {
+    for (const k of [...hist.keys()]) if (!ids.has(api.sessOf(k))) hist.delete(k);
+  });
+
+  let tab = 'elements';
+  /** Per-inspected-key UI state; rebuilt when the key changes. */
+  let view = null;
+
+  const target = (islandKey) => {
+    const sid = api.sessOf(islandKey);
+    const instance = islandKey.slice(sid.length + 1);
+    // Nested islands' handles live in their worker: their DOM is replayed
+    // into the top-level island's container, so the tree comes from there.
+    const root = instance.split('~')[0];
+    return { sid, instance, root, nested: root !== instance };
+  };
+
+  const blocked = (sid) => {
+    if (api.livePaused) return 'Viewing a recording: live DOM is unavailable.';
+    if (api.state.sessions.get(sid)?.closed) return 'Session has ended: the island DOM is gone.';
+    if (!api.hasCommand(sid, 'island.tree')) {
+      return "The app doesn't expose 'island.tree' (devtools was off when the island mounted, or an older @atolljs/islands).";
+    }
+    return null;
+  };
+
+  /* ── Elements ──────────────────────────────────────────────────────────── */
+
+  const renderAttrs = (n) =>
+    n.attrs.map(([k, v]) => ` <span class="ii-an">${esc(k)}</span>=<span class="ii-av">"${esc(v.length > 60 ? `${v.slice(0, 60)}…` : v)}"</span>`).join('');
+
+  const nodeRow = (n) => {
+    if (n.tag === '#text') return `<span class="ii-tx">"${esc(n.text.length > 80 ? `${n.text.slice(0, 80)}…` : n.text)}"</span>`;
+    if (n.tag === '#shadow-root') return '<span class="muted">#shadow-root</span>';
+    return `<span class="ii-tag">&lt;${esc(n.tag)}</span>${renderAttrs(n)}<span class="ii-tag">&gt;</span>`;
+  };
+
+  const buildTree = (v, root) => {
+    const byId = new Map();
+    const build = (n, depth) => {
+      byId.set(n.id, n);
+      const el = document.createElement('div');
+      el.className = 'ii-node';
+      el.dataset.id = n.id;
+      const hasKids = n.children.length > 0 || n.more;
+      const open = v.expanded.has(n.id) || (!v.touched.has(n.id) && depth < 3);
+      if (hasKids && !open) el.classList.add('closed');
+      el.innerHTML =
+        `<div class="ii-row${v.selected === n.id ? ' sel' : ''}" data-id="${esc(n.id)}">` +
+        `<span class="ii-caret">${hasKids ? (open ? '▾' : '▸') : ''}</span>${nodeRow(n)}</div>`;
+      if (hasKids) {
+        const kids = document.createElement('div');
+        kids.className = 'ii-kids';
+        for (const c of n.children) kids.appendChild(build(c, depth + 1));
+        if (n.more) kids.insertAdjacentHTML('beforeend', `<div class="ii-more">… ${n.more} more (node cap)</div>`);
+        el.appendChild(kids);
+      }
+      return el;
+    };
+    v.byId = byId;
+    const scroll = v.els.tree.scrollTop;
+    v.els.tree.replaceChildren(build(root, 0));
+    v.els.tree.scrollTop = scroll;
+  };
+
+  const showDetail = (v) => {
+    const n = v.byId?.get(v.selected);
+    if (!n) { v.els.detail.innerHTML = '<span class="muted">click a node for its attributes</span>'; return; }
+    v.els.detail.innerHTML =
+      `<div><b>${esc(n.tag)}</b> <span class="muted">${esc(n.id)}</span></div>` +
+      (n.attrs.length
+        ? `<table class="tkv" style="margin-top:4px"><tbody>${n.attrs.map(([k, val]) => `<tr><td>${esc(k)}</td><td style="word-break:break-all">${esc(val)}</td></tr>`).join('')}</tbody></table>`
+        : '<div class="muted" style="margin-top:4px">no attributes</div>') +
+      (n.text !== undefined ? `<pre class="body" style="margin-top:6px">${esc(n.text)}</pre>` : '') +
+      `<div class="muted" style="margin-top:6px">${n.children.length} child node(s)${n.more ? ` + ${n.more} omitted` : ''}</div>`;
+  };
+
+  const fetchTree = (v) => {
+    const t = target(v.key);
+    if (blocked(t.sid) || v.loading) return;
+    v.loading = true;
+    v.els.status.textContent = 'loading…';
+    api.control(t.sid, 'island.tree', { instance: t.root, maxNodes: 4000 }, 5000)
+      .then((res) => {
+        if (view !== v) return;
+        buildTree(v, res.root);
+        showDetail(v);
+        v.loaded = true;
+        v.els.status.textContent = `${res.count} nodes${res.truncated ? ' (capped)' : ''} · ${clock(Date.now())}`;
+      })
+      .catch((err) => { if (view === v) v.els.status.textContent = `error: ${err.message}`; })
+      .finally(() => { v.loading = false; });
+  };
+
+  const highlight = (v, id) => {
+    if (v.hoverId === id) return;
+    v.hoverId = id;
+    const t = target(v.key);
+    if (blocked(t.sid)) return;
+    api.control(t.sid, 'island.highlight', { instance: t.root, id }, 2000).catch(() => {});
+  };
+
+  /* ── build per key ─────────────────────────────────────────────────────── */
+
+  const build = (extra, islandKey) => {
+    let box = extra.querySelector(':scope > .ii');
+    if (!box) {
+      box = document.createElement('div');
+      box.className = 'ii';
+      extra.appendChild(box);
+    }
+    box.innerHTML = `
+      <div class="ii-tabs">
+        <button data-tab="elements">Elements</button>
+        <button data-tab="props">Props<span class="n" data-n="props"></span></button>
+        <button data-tab="events">Events<span class="n" data-n="events"></span></button>
+      </div>
+      <div class="ii-pane" data-pane="elements">
+        <div class="ii-bar">
+          <button class="act" data-act="refresh">Refresh</button>
+          <label><input type="checkbox" data-act="auto"> auto-refresh (2s)</label>
+          <span class="muted" data-el="status"></span>
+        </div>
+        <div class="ii-msg" data-el="msg"></div>
+        <div class="ii-split">
+          <div class="ii-tree" data-el="tree"><span class="muted">no tree loaded</span></div>
+          <div class="ii-detail" data-el="detail"><span class="muted">click a node for its attributes</span></div>
+        </div>
+      </div>
+      <div class="ii-pane" data-pane="props"><div class="ii-list" data-el="props"></div></div>
+      <div class="ii-pane" data-pane="events">
+        <div class="ii-bar"><input type="text" data-el="filter" placeholder="filter by event name"></div>
+        <div class="ii-list" data-el="events"></div>
+      </div>`;
+    const q = (sel) => box.querySelector(sel);
+    const v = {
+      key: islandKey, box, expanded: new Set(), touched: new Set(), selected: null, byId: null,
+      hoverId: undefined, loaded: false, loading: false, tried: false, auto: false, lastAuto: 0,
+      propsSeq: -1, eventsSeq: -1, filter: '', gate: undefined,
+      els: {
+        tree: q('[data-el=tree]'), detail: q('[data-el=detail]'), status: q('[data-el=status]'),
+        msg: q('[data-el=msg]'), props: q('[data-el=props]'), events: q('[data-el=events]'),
+        filter: q('[data-el=filter]'), refresh: q('[data-act=refresh]'), auto: q('[data-act=auto]'),
+        nProps: q('[data-n=props]'), nEvents: q('[data-n=events]'),
+      },
+    };
+    const setTab = (name) => {
+      tab = name;
+      for (const b of box.querySelectorAll('.ii-tabs button')) b.classList.toggle('on', b.dataset.tab === name);
+      for (const p of box.querySelectorAll('.ii-pane')) p.classList.toggle('on', p.dataset.pane === name);
+    };
+    setTab(tab);
+    q('.ii-tabs').addEventListener('click', (ev) => {
+      const b = ev.target.closest('button[data-tab]');
+      if (b) setTab(b.dataset.tab);
+    });
+    v.els.refresh.onclick = () => fetchTree(v);
+    v.els.auto.onchange = () => { v.auto = v.els.auto.checked; };
+    v.els.filter.oninput = () => { v.filter = v.els.filter.value.trim().toLowerCase(); v.eventsSeq = -1; renderLists(v, true); };
+    v.els.tree.addEventListener('click', (ev) => {
+      const row = ev.target.closest('.ii-row');
+      if (!row) return;
+      const node = row.parentElement;
+      const id = row.dataset.id;
+      if (ev.target.classList.contains('ii-caret') && node.querySelector(':scope > .ii-kids')) {
+        const closed = node.classList.toggle('closed');
+        v.touched.add(id);
+        if (closed) v.expanded.delete(id); else v.expanded.add(id);
+        ev.target.textContent = closed ? '▸' : '▾';
+        return;
+      }
+      v.els.tree.querySelector('.ii-row.sel')?.classList.remove('sel');
+      row.classList.add('sel');
+      v.selected = id;
+      showDetail(v);
+    });
+    v.els.tree.addEventListener('mouseover', (ev) => {
+      const row = ev.target.closest('.ii-row');
+      if (row) highlight(v, row.dataset.id);
+    });
+    v.els.tree.addEventListener('mouseleave', () => highlight(v, null));
+    return v;
+  };
+
+  /* ── lists ─────────────────────────────────────────────────────────────── */
+
+  const renderLists = (v, force = false) => {
+    const h = hist.get(v.key) ?? { props: [], events: [] };
+    v.els.nProps.textContent = h.props.length ? String(h.props.length) : '';
+    v.els.nEvents.textContent = h.events.length ? String(h.events.length) : '';
+    if (force || v.propsSeq !== h.props.length + (h.props.at(-1)?.t ?? 0)) {
+      v.propsSeq = h.props.length + (h.props.at(-1)?.t ?? 0);
+      const rows = [];
+      for (let i = h.props.length - 1; i >= 0 && rows.length < 50; i--) {
+        const p = h.props[i];
+        const parsed = tryJson(p.preview);
+        rows.push(
+          `<div class="ii-entry"><span class="ii-t">${clock(p.t)}</span>${i === 0 && h.props.length < MAX_PROPS ? '<span class="pill">mount</span>' : ''}` +
+          `<div style="margin-top:2px">${diffProps(h.props[i - 1]?.preview, p.preview, esc)}</div>` +
+          `<details><summary class="muted">props</summary><pre>${esc(parsed.ok ? JSON.stringify(parsed.v, null, 2) : p.preview)}</pre></details></div>`,
+        );
+      }
+      v.els.props.innerHTML = rows.join('') || '<span class="muted">no island:props yet (emitted on mount and every updateProps while devtools is on)</span>';
+    }
+    const evSeq = h.events.length + (h.events.at(-1)?.t ?? 0);
+    if (force || v.eventsSeq !== evSeq) {
+      v.eventsSeq = evSeq;
+      const rows = [];
+      for (let i = h.events.length - 1; i >= 0 && rows.length < 200; i--) {
+        const e = h.events[i];
+        if (v.filter && !e.name.toLowerCase().includes(v.filter)) continue;
+        rows.push(
+          `<div class="ii-entry"><span class="ii-t">${clock(e.t)}</span><b>${esc(e.name)}</b>` +
+          (e.payload !== undefined ? `<pre>${esc(e.payload)}</pre>` : '') + '</div>',
+        );
+      }
+      v.els.events.innerHTML = rows.join('') || `<span class="muted">${h.events.length ? 'no events match the filter' : 'no emits yet'}</span>`;
+    }
+  };
+
+  /* ── hook ──────────────────────────────────────────────────────────────── */
+
+  api.onInspectIsland((islandKey, island, { extra }) => {
+    if (!view || view.key !== islandKey || !view.box.isConnected) {
+      if (view) highlight(view, null);
+      view = build(extra, islandKey);
+    }
+    const v = view;
+    const t = target(islandKey);
+    const reason = blocked(t.sid);
+    const msg = reason ?? (t.nested
+      ? `Nested island: its handle lives in the parent worker, so the tree below is the top-level island ${t.root}, which contains this island's replayed DOM.`
+      : '');
+    if (v.gate !== msg) {
+      v.gate = msg;
+      v.els.msg.textContent = msg;
+      v.els.refresh.disabled = reason !== null;
+      v.els.auto.disabled = reason !== null;
+    }
+    if (!reason && !v.tried) {
+      v.tried = true;
+      fetchTree(v);
+    }
+    if (!reason && v.auto && Date.now() - v.lastAuto > 2000) {
+      v.lastAuto = Date.now();
+      fetchTree(v);
+    }
+    renderLists(v);
+  });
+}

package/app/panels/memory-values.js

@@ -0,0 +1,287 @@
+// Memory › Values: live shared-memory field values for one session, polled
+// over the control channel (`memory.read`, ~2Hz, only while this sub-tab is
+// visible), with snapshot/diff, dashboard-set watchpoints (`memory.watch`,
+// `memory.unwatch`, `memory.watches`) and the memory:watch-hit log.
+
+const CSS = `
+.mvv-bar { display:flex; gap:8px; align-items:center; flex-wrap:wrap; margin-bottom:8px; font-size:11px; }
+.mvv-bar select, .mvv-bar input { background:#0d1117; color:#c9d1d9; border:1px solid #30363d; border-radius:4px; padding:2px 6px; font:inherit; }
+.mvv-msg { color:#d29922; font-size:11px; min-height:1em; margin-bottom:6px; }
+#mvvTable td.v { max-width:520px; overflow:hidden; text-overflow:ellipsis; white-space:nowrap; }
+#mvvTable td.d { color:#8b949e; max-width:260px; overflow:hidden; text-overflow:ellipsis; white-space:nowrap; }
+#mvvTable td.d.chg { color:#d29922; }
+@keyframes mvvFlash { from { background:#1f6feb55; } to { background:transparent; } }
+#mvvTable td.flash { animation: mvvFlash .9s ease-out; }
+.mvv-hits { border:1px solid #21262d; border-radius:8px; max-height:220px; overflow-y:auto; padding:4px 8px; font-size:11px; }
+.mvv-hits div { border-bottom:1px dashed #21262d; padding:2px 0; white-space:nowrap; overflow:hidden; text-overflow:ellipsis; }
+.mvv-watch { display:flex; gap:6px; align-items:center; padding:2px 0; font-size:11px; }
+`;
+
+const POLL_MS = 500;
+const MAX_HITS = 200;
+
+const injectCss = () => {
+  if (document.getElementById('mvv-css')) return;
+  const s = document.createElement('style');
+  s.id = 'mvv-css';
+  s.textContent = CSS;
+  document.head.appendChild(s);
+};
+
+const clock = (t) => {
+  const d = new Date(t);
+  const p = (n, w = 2) => String(n).padStart(w, '0');
+  return `${p(d.getHours())}:${p(d.getMinutes())}:${p(d.getSeconds())}.${p(d.getMilliseconds(), 3)}`;
+};
+
+export function setup(api) {
+  injectCss();
+  const { esc } = api;
+
+  const div = api.addSubview('memory', {
+    id: 'mv-values',
+    label: 'Values',
+    order: 60,
+    html: `
+      <h2>Live values <span class="muted">— polled at ~2Hz while this tab is open; changed cells flash</span></h2>
+      <div class="mvv-bar">
+        <span class="muted" id="mvvSess"></span>
+        <button class="act" id="mvvSnap" title="Remember the current values; the diff column compares against them">Snapshot</button>
+        <button class="act" id="mvvClearSnap">Clear snapshot</button>
+        <span class="muted" id="mvvStatus"></span>
+      </div>
+      <div class="mvv-msg" id="mvvMsg"></div>
+      <table id="mvvTable"><thead><tr>
+        <th>field</th><th>contract</th><th>value</th><th>version</th><th>vs snapshot</th>
+      </tr></thead><tbody></tbody></table>
+      <div class="grid2" style="margin-top:14px">
+        <div>
+          <h2>Watchpoints <span class="muted">— fire memory:watch-hit on matching writes</span></h2>
+          <div class="mvv-bar">
+            <select id="mvvPath"><option value="">field…</option></select>
+            <input id="mvvRule" type="text" value="change" size="14" title="change | > n | < n | >= n | <= n | == v | != v">
+            <button class="act" id="mvvAdd">Add watch</button>
+          </div>
+          <div id="mvvWatches"><span class="muted">no watches</span></div>
+          <div class="muted" style="font-size:11px;margin-top:6px">Rules: change, &gt; n, &lt; n, &gt;= n, &lt;= n, == v, != v (v as JSON, e.g. == "down"). Worker writes are checked when the main thread observes the version bump, so bursts between observations coalesce to the latest value.</div>
+        </div>
+        <div>
+          <h2>Watch hits</h2>
+          <div class="mvv-hits" id="mvvHits"><span class="muted">no hits yet</span></div>
+        </div>
+      </div>`,
+  });
+  const $ = (id) => div.querySelector(`#${id}`);
+  const tbody = $('mvvTable').querySelector('tbody');
+
+  /** rowKey `${contract}|${path}` → { tr, cells, value, version } */
+  const rows = new Map();
+  let snapshot = null; // { sid, at, values: Map(rowKey → value) }
+  let sid = null;
+  let inFlight = false;
+  let lastReadAt = 0;
+  let watches = [];
+  const hits = [];
+  let hitsRendered = -1;
+  let pathsSig = '';
+
+  const visible = () => div.classList.contains('on') && div.closest('.view')?.classList.contains('on');
+
+  const blocked = (s) => {
+    if (api.livePaused) return 'Viewing a recording: live values are unavailable.';
+    if (!s) return api.liveSessions().length ? 'Several live sessions: select one in the sidebar.' : 'No live session.';
+    if (api.state.sessions.get(s)?.closed) return 'Session has ended.';
+    if (!api.hasCommand(s, 'memory.read')) {
+      return "The app doesn't expose 'memory.read' (no shared-memory contract bound with devtools on, or an older @atolljs/core).";
+    }
+    return null;
+  };
+
+  const flash = (td) => {
+    td.classList.remove('flash');
+    void td.offsetWidth; // restart the animation
+    td.classList.add('flash');
+  };
+
+  const diffCell = (rowKey, value) => {
+    if (!snapshot || snapshot.sid !== sid) return ['', false];
+    if (!snapshot.values.has(rowKey)) return ['new', true];
+    const was = snapshot.values.get(rowKey);
+    return was === value ? ['=', false] : [`was ${was}`, true];
+  };
+
+  const applyRead = (list) => {
+    const seen = new Set();
+    for (const r of list) {
+      const rk = `${r.contract}|${r.path}`;
+      seen.add(rk);
+      let row = rows.get(rk);
+      if (!row) {
+        const tr = document.createElement('tr');
+        tr.innerHTML = `<td>${esc(r.path)}</td><td class="muted">#${r.contract}</td><td class="v"></td><td></td><td class="d"></td>`;
+        const cells = tr.querySelectorAll('td');
+        row = { tr, cells, value: undefined, version: undefined };
+        rows.set(rk, row);
+        tbody.appendChild(tr);
+      }
+      if (row.value !== r.value) {
+        if (row.value !== undefined) flash(row.cells[2]);
+        row.cells[2].textContent = r.value;
+        row.cells[2].title = r.value;
+        row.value = r.value;
+      }
+      if (row.version !== r.version) {
+        row.cells[3].textContent = String(r.version);
+        row.version = r.version;
+      }
+      const [d, chg] = diffCell(rk, r.value);
+      if (row.cells[4].textContent !== d) {
+        row.cells[4].textContent = d;
+        row.cells[4].title = d;
+        row.cells[4].classList.toggle('chg', chg);
+      }
+    }
+    for (const [rk, row] of rows) {
+      if (!seen.has(rk)) { row.tr.remove(); rows.delete(rk); }
+    }
+    const paths = [...new Set(list.map((r) => r.path))].sort();
+    const sig = paths.join('\n');
+    if (sig !== pathsSig) {
+      pathsSig = sig;
+      const sel = $('mvvPath');
+      const cur = sel.value;
+      sel.innerHTML = '<option value="">field…</option>' + paths.map((p) => `<option>${esc(p)}</option>`).join('');
+      if (paths.includes(cur)) sel.value = cur;
+    }
+  };
+
+  const clearRows = () => {
+    rows.clear();
+    tbody.innerHTML = '';
+    pathsSig = '';
+  };
+
+  const renderWatches = () => {
+    const box = $('mvvWatches');
+    if (!watches.length) { box.innerHTML = '<span class="muted">no watches</span>'; return; }
+    box.innerHTML = watches.map((w) =>
+      `<div class="mvv-watch"><b>${esc(w.path)}</b> <span>${esc(w.rule)}</span> <span class="muted">${w.hits} hit(s)</span>` +
+      `<button class="act" data-unwatch="${esc(w.path)}">remove</button></div>`).join('');
+  };
+
+  const refreshWatches = () => {
+    if (blocked(sid)) return;
+    api.control(sid, 'memory.watches', {}, 3000).then((list) => { watches = list; renderWatches(); }).catch(() => {});
+  };
+
+  const poll = () => {
+    if (!visible()) return;
+    const next = api.selectedOrOnlyLive();
+    if (next !== sid) {
+      sid = next;
+      clearRows();
+      watches = [];
+      renderWatches();
+      refreshWatches();
+      hitsRendered = -1;
+    }
+    const reason = blocked(sid);
+    $('mvvMsg').textContent = reason ?? '';
+    $('mvvSess').textContent = sid ? `session ${api.state.sessions.get(sid)?.name ?? sid}` : '';
+    for (const b of [$('mvvSnap'), $('mvvAdd')]) b.disabled = reason !== null;
+    renderHits();
+    if (reason || inFlight) return;
+    inFlight = true;
+    const asked = sid;
+    api.control(sid, 'memory.read', {}, 3000)
+      .then((list) => {
+        if (asked !== sid) return;
+        applyRead(list);
+        lastReadAt = Date.now();
+        $('mvvStatus').textContent = `${list.length} field(s) · read ${clock(lastReadAt)}` +
+          (snapshot && snapshot.sid === sid ? ` · snapshot ${clock(snapshot.at)}` : '');
+      })
+      .catch((err) => { $('mvvStatus').textContent = `error: ${err.message}`; })
+      .finally(() => { inFlight = false; });
+  };
+  setInterval(poll, POLL_MS);
+
+  const takeSnapshot = () => {
+    if (!sid) return;
+    snapshot = { sid, at: Date.now(), values: new Map([...rows].map(([rk, r]) => [rk, r.value])) };
+    for (const [rk, r] of rows) {
+      const [d, chg] = diffCell(rk, r.value);
+      r.cells[4].textContent = d;
+      r.cells[4].classList.toggle('chg', chg);
+    }
+  };
+  const clearSnapshot = () => {
+    snapshot = null;
+    for (const r of rows.values()) { r.cells[4].textContent = ''; r.cells[4].classList.remove('chg'); }
+  };
+
+  $('mvvSnap').onclick = takeSnapshot;
+  $('mvvClearSnap').onclick = clearSnapshot;
+  $('mvvAdd').onclick = () => {
+    const path = $('mvvPath').value;
+    const rule = $('mvvRule').value.trim() || 'change';
+    if (!path || blocked(sid)) return;
+    api.control(sid, 'memory.watch', { path, rule }, 3000)
+      .then((list) => { watches = list; renderWatches(); $('mvvMsg').textContent = ''; })
+      .catch((err) => { $('mvvMsg').textContent = err.message; });
+  };
+  $('mvvWatches').addEventListener('click', (ev) => {
+    const b = ev.target.closest('button[data-unwatch]');
+    if (!b || blocked(sid)) return;
+    api.control(sid, 'memory.unwatch', { path: b.dataset.unwatch }, 3000)
+      .then((list) => { watches = list; renderWatches(); })
+      .catch((err) => { $('mvvMsg').textContent = err.message; });
+  });
+
+  /* ── watch-hit log ─────────────────────────────────────────────────────── */
+
+  api.onEvent((s, e) => {
+    if (e.type !== 'memory:watch-hit') return;
+    hits.unshift({ t: Date.now(), sid: s.id, path: e.path, version: e.version, value: e.value, rule: e.rule });
+    if (hits.length > MAX_HITS) hits.pop();
+    const w = watches.find((x) => x.path === e.path);
+    if (w && s.id === sid) { w.hits++; renderWatches(); }
+  });
+
+  function renderHits() {
+    if (hitsRendered === hits.length + (hits[0]?.t ?? 0)) return;
+    hitsRendered = hits.length + (hits[0]?.t ?? 0);
+    const mine = sid ? hits.filter((h) => h.sid === sid) : hits;
+    $('mvvHits').innerHTML = mine.slice(0, 100).map((h) =>
+      `<div><span class="logts">${clock(h.t)}</span> <b>${esc(h.path)}</b> ${esc(h.rule)} → ${esc(h.value)} <span class="muted">v${h.version}</span></div>`,
+    ).join('') || '<span class="muted">no hits yet</span>';
+  }
+  api.onRender(() => { if (visible()) renderHits(); });
+
+  api.onReset(() => {
+    clearRows();
+    snapshot = null;
+    hits.length = 0;
+    hitsRendered = -1;
+    watches = [];
+    sid = null;
+    renderWatches();
+  });
+
+  /* ── palette ───────────────────────────────────────────────────────────── */
+
+  const openValues = () => api.openSub('memory', 'mv-values');
+  api.addPaletteItem({ id: 'memory.values', title: 'Memory: open live values', group: 'Memory', run: openValues });
+  api.addPaletteItem({
+    id: 'memory.snapshot',
+    title: 'Memory: snapshot values',
+    group: 'Memory',
+    hint: 'diff column compares against it',
+    run: () => {
+      openValues();
+      // values land on the next poll when the tab was just opened
+      if (rows.size) takeSnapshot(); else setTimeout(takeSnapshot, POLL_MS * 2);
+    },
+  });
+  api.addPaletteItem({ id: 'memory.clearSnapshot', title: 'Memory: clear values snapshot', group: 'Memory', run: clearSnapshot });
+}