@giamme/forge 0.8.0 → 0.10.0

package/ui/forge_ui/static/convo.js

@@ -0,0 +1,295 @@
+/* forge-ui conversation: what one dwarf or reviewer said and did, read from its agent CLI's log (transcripts.py), shown
+   in the stage's place like a diff. Its messages, its thinking folded, each command with its exit and output, each edit
+   with its patch and a link to the diff, other tool calls, the final answer and the tokens; a search, the errors one key
+   apart, and while the agent runs a poll every few seconds that follows the end. Defines window.ForgeConvo.render(host, ctx).
+   All API values enter the DOM as text.
+   ctx = { run, spec: {task, exec}, brief (the Execution, when the run lists it), live (false in an export), fetchJSON(path),
+           rerender(), closeHref, diffHash(spec) → hash } */
+window.ForgeConvo = (() => {
+  'use strict';
+  const list = v => Array.isArray(v) ? v : [];
+  const POLL = 2500;                                         // ms between reads of a log being written
+  const FOLD = 14;                                           // lines of an output shown before it folds
+  const cache = new Map();                                   // url → {data, error, pending, at, timer}
+  const views = new Map();                                   // url → {query, show, follow, open: Set, err}
+  const enc = encodeURIComponent;
+  function el(tag, text, cls) {
+    const n = document.createElement(tag);
+    if (text !== undefined && text !== null) n.textContent = String(text);
+    if (cls) n.className = cls;
+    return n;
+  }
+  const icon = name => window.ForgeIcons ? window.ForgeIcons.icon(name) : el('span');
+  const chip = (text, st) => el('span', text, 'chip st-' + st);
+  const num = v => Number.isFinite(Number(v)) && v !== null ? Number(v).toLocaleString() : '—';
+  const ICON = { prompt: 'flag', message: 'chat', reasoning: 'thought', command: 'terminal', edit: 'pencil', tool: 'tool', result: 'check', error: 'cross', text: 'keyboard', gap: 'chevron-down' };
+  // which kinds each filter key shows
+  const SHOW = [['all', 'All', null], ['said', 'Said', ['prompt', 'message', 'reasoning', 'result', 'error']], ['ran', 'Ran', ['command', 'tool', 'error']],
+    ['changed', 'Changed', ['edit']]];
+  const urlFor = (run, spec) => `/api/runs/${enc(run.key)}/executions/${enc(spec.exec)}/transcript`;
+
+  function read(ctx, url, entry) {
+    entry.pending = true;
+    ctx.fetchJSON(url).then(d => { entry.data = d; entry.error = null; }, e => { entry.error = e; })
+      .finally(() => { entry.at = performance.now(); entry.pending = false; ctx.rerender(); });
+  }
+  function load(ctx, url) {
+    let entry = cache.get(url);
+    if (!entry) {
+      entry = { pending: false, data: null, error: null, at: 0, timer: null };
+      cache.set(url, entry);
+      for (const old of cache.keys()) if (cache.size > 12 && old !== url) cache.delete(old);   // the conversations opened last
+      read(ctx, url, entry);
+    }
+    // a finished log never changes; one still being written is read again when the view comes back to it, and a
+    // read that failed is tried again after a while
+    else if (ctx.live && !entry.pending && !entry.timer && performance.now() - entry.at > (entry.error ? 10 * POLL : POLL) &&
+             (entry.error || (entry.data && entry.data.state === 'running'))) read(ctx, url, entry);
+    return entry;
+  }
+
+  /* ---------- the frame: title, what was read, the tools; built once per conversation ---------- */
+  function frame(host, ctx, url, v) {
+    host.replaceChildren();
+    const f = { url, drawn: [], nodes: [] };
+    const top = el('div', undefined, 'diff-top convo-top');
+    f.title = el('h2'); f.chips = el('div', undefined, 'chips');
+    const close = el('a', undefined, 'diff-close button'); close.href = ctx.closeHref; close.append(icon('close'), document.createTextNode('Close'));
+    top.append(f.title, f.chips, close);
+    f.meta = el('p', undefined, 'diff-meta convo-meta muted');
+    const tools = el('div', undefined, 'convo-tools'); tools.setAttribute('role', 'toolbar'); tools.setAttribute('aria-label', 'Conversation');
+    const find = el('label', undefined, 'convo-find'); find.append(icon('search'));
+    f.search = el('input'); f.search.type = 'search'; f.search.placeholder = 'Search what it said and ran'; f.search.setAttribute('aria-label', 'Search the conversation');
+    f.search.value = v.query;
+    f.search.addEventListener('input', () => { v.query = f.search.value; filter(f, v); });
+    f.search.addEventListener('keydown', e => { if (e.key === 'Escape' && f.search.value) { e.stopPropagation(); f.search.value = ''; v.query = ''; filter(f, v); } });
+    find.append(f.search);
+    f.count = el('span', undefined, 'convo-count muted'); f.count.setAttribute('aria-live', 'polite');
+    f.show = el('div', undefined, 'seg'); f.show.setAttribute('role', 'group'); f.show.setAttribute('aria-label', 'Show');
+    for (const [key, label] of SHOW) {
+      const b = el('button', label); b.type = 'button'; b.dataset.show = key;
+      b.addEventListener('click', () => { v.show = key; filter(f, v); });
+      f.show.append(b);
+    }
+    f.errs = el('span', undefined, 'convo-errs');
+    f.err = el('button', 'Next error', 'convo-err'); f.err.type = 'button'; f.err.title = 'Next error (E)'; f.err.setAttribute('aria-keyshortcuts', 'E');
+    f.err.append(el('kbd', 'E'));
+    f.err.addEventListener('click', () => nextError(f, v));
+    f.follow = el('button', 'Follow', 'convo-follow latch'); f.follow.type = 'button'; f.follow.title = 'Keep the newest event in view while it runs';
+    f.follow.addEventListener('click', () => { v.follow = !v.follow; f.follow.setAttribute('aria-pressed', String(v.follow)); if (v.follow) end(f); });
+    tools.append(find, f.count, f.show, f.errs, f.err, f.follow);
+    f.status = el('div', undefined, 'convo-status');
+    f.list = el('ol', undefined, 'convo-list'); f.list.setAttribute('aria-label', 'Events');
+    host.append(top, f.meta, tools, f.status, f.list);
+    host.tabIndex = -1; host.setAttribute('aria-label', 'Conversation: / searches, E goes to the next error');
+    host.onkeydown = e => {
+      if (e.altKey || e.ctrlKey || e.metaKey || /^(INPUT|TEXTAREA|SELECT)$/.test(e.target.tagName)) return;
+      if (e.key === '/') { e.preventDefault(); f.search.focus(); f.search.select(); }
+      else if (e.key === 'e' || e.key === 'E') { e.preventDefault(); nextError(f, v); }
+    };
+    // a fold opened or closed stays so through a rebuild
+    f.list.addEventListener('toggle', e => { const d = e.target; if (d.dataset && d.dataset.fold) { if (d.open) v.open.add(d.dataset.fold); else v.open.delete(d.dataset.fold); } }, true);
+    return f;
+  }
+
+  function header(f, ctx, D) {
+    const spec = ctx.spec, run = ctx.run, b = ctx.brief || {};
+    const owner = D && D.owner || {}, role = (D && D.role) || b.role || String(spec.exec).split('-')[0];
+    const where = owner.kind === 'final_review' ? 'Final review' : spec.task === 'solo' || run.kind === 'solo' ? 'Solo run' :
+      owner.kind === 'shadow' ? `Task ${String(owner.id).split('/')[0]} · shadow` : spec.task ? `Task ${spec.task}` : 'Run';
+    const attempt = D && D.attempt != null ? D.attempt : b.attempt;
+    f.title.replaceChildren(el('span', 'Conversation · ', 'muted'), document.createTextNode(`${where} · ${role === 'qa' ? 'reviewer' : role}${attempt != null ? ' · attempt ' + attempt : ''}`));
+    const chips = [];
+    const s = (D && D.spec) || (b.model && b.model.spec);
+    if (s && window.ForgeIcons) chips.push(window.ForgeIcons.modelPlate(s));
+    // one lamp: running, else a review's verdict, else how it ended
+    const state = (D && D.state) || b.state;
+    if (state === 'running') chips.push(chip('running', 'running'));
+    else if (b.verdict) chips.push(chip('verdict ' + b.verdict, String(b.verdict).toLowerCase()));
+    else if (b.id && window.ForgeRunModel) { const st = window.ForgeRunModel.execStatus(b); chips.push(chip(st, String(st).toLowerCase())); }
+    f.chips.replaceChildren(...chips);
+    if (!D) { f.meta.replaceChildren(); return; }
+    // where it was read from, then the numbers in a describer window
+    const t = D.tokens, from = { log: 'read from its log', session: "read from claude's session file", none: 'no log' }[D.source] || '';
+    const n = list(D.events).filter(e => e.kind !== 'gap').length;
+    const desc = el('span', undefined, 'describer');
+    if (t) desc.append(el('span', `${num(t.input)} in`), ...(t.cached ? [el('span', `${num(t.cached)} cached`, 'dim')] : []), el('span', `${num(t.output)} out`));
+    if (D.cost != null) desc.append(el('span', '$' + Number(D.cost).toFixed(D.cost < 1 ? 3 : 2)));
+    desc.append(el('span', `${n} event${n === 1 ? '' : 's'}`));
+    if (D.session) desc.append(el('span', `session ${D.session}`, 'dim'));
+    f.meta.replaceChildren(el('span', [D.harness, from].filter(Boolean).join(' · ')), desc);
+  }
+
+  /* ---------- one event ---------- */
+  const lines = s => String(s || '').split('\n').length;
+  function out(parent, text, key, v, { title = 'Output', open = false, cls = '' } = {}) {
+    if (text == null || text === '') return;
+    const pre = el('pre', text, 'ev-pre ' + cls);
+    if (lines(text) <= FOLD && String(text).length < 1600) { parent.append(pre); return; }
+    const d = el('details', undefined, 'ev-fold'); d.dataset.fold = key;
+    d.open = open || v.open.has(key);
+    d.append(el('summary', `${title} · ${lines(text).toLocaleString()} lines`), pre); parent.append(d);
+  }
+  function patch(parent, text, key, v) {
+    const pre = el('pre', undefined, 'ev-pre ev-patch');
+    for (const line of String(text).split('\n')) pre.append(el('span', line, line[0] === '+' ? 'add' : line[0] === '-' ? 'del' : null));
+    if (lines(text) <= FOLD) { parent.append(pre); return; }
+    const d = el('details', undefined, 'ev-fold'); d.dataset.fold = key; d.open = v.open.has(key);
+    d.append(el('summary', `Patch · ${lines(text).toLocaleString()} lines`), pre); parent.append(d);
+  }
+  // a path in the worktree the agent ran in (or the run's repo) as the diff names it
+  function rel(D, path, run) {
+    for (const r of [D.repo, run && run.repo]) {
+      const root = String(r || '').replace(/\/+$/, '');
+      if (root && path.startsWith(root + '/')) return path.slice(root.length + 1);
+    }
+    return path;
+  }
+  function eventNode(ctx, D, ev, i, v, t0) {
+    const kind = ICON[ev.kind] ? ev.kind : 'text';
+    const li = el('li', undefined, `ev ev--${kind}${ev.error ? ' is-error' : ''}${ev.running ? ' is-running' : ''}`);
+    li.id = 'ev-' + i; li.tabIndex = -1; li.dataset.kind = kind;
+    const gut = el('div', undefined, 'ev-gut'); gut.setAttribute('aria-hidden', 'true'); gut.append(icon(ICON[kind]));
+    const body = el('div', undefined, 'ev-body');
+    const head = el('div', undefined, 'ev-head');
+    const when = Number.isFinite(ev.t) && Number.isFinite(t0) ? el('span', '+' + clock(ev.t - t0), 'ev-time') : null;
+    const key = i + ':';
+    if (kind === 'gap') { li.append(el('p', `… ${num(ev.count)} events left out: the log is too long to show whole …`, 'muted ev-gap')); return li; }
+    if (kind === 'prompt' || kind === 'reasoning') {
+      const d = el('details', undefined, 'ev-fold'); d.dataset.fold = key + 'x'; d.open = v.open.has(key + 'x');
+      const sum = el('summary'); sum.append(el('span', kind === 'prompt' ? 'The task as it got it' : 'Thinking', 'ev-label'), el('span', String(ev.text || '').split('\n').find(s => s.trim()) || '', 'ev-peek'));
+      if (when) sum.append(when);
+      d.append(sum, el('div', ev.text, 'ev-text' + (kind === 'reasoning' ? ' ev-thought' : '')));
+      body.append(d);
+    } else if (kind === 'message') {
+      head.append(el('span', D.role === 'qa' ? 'Reviewer' : 'Dwarf', 'ev-label')); if (when) head.append(when);
+      body.append(head, el('div', ev.text, 'ev-text'));
+    } else if (kind === 'command') {
+      const st = ev.running ? 'running' : ev.error ? 'fail' : ev.exit === 0 || ev.error === false ? 'pass' : ev.exit != null ? 'fail' : 'none';
+      const line = el('span', undefined, 'ev-cmdline'); line.append(el('i', undefined, 'lamp st-' + st), el('code', ev.command || '(no command)', 'ev-cmd'));
+      head.append(line);
+      if (ev.exit != null) head.append(el('span', 'exit ' + ev.exit, 'tag' + (ev.exit ? ' tag-bad' : '')));
+      else if (ev.running) head.append(el('span', 'running', 'tag'));
+      if (when) head.append(when);
+      body.append(head); out(body, ev.output, key + 'o', v, { open: !!ev.error });
+    } else if (kind === 'edit') {
+      head.append(el('span', 'Edited', 'ev-label'));
+      if (ev.tool && ev.tool.toLowerCase() !== 'edit') head.append(el('span', ev.tool, 'mono muted ev-toolname'));
+      for (const p of list(ev.files)) {
+        const r = rel(D, String(p), ctx.run);
+        if (ctx.diffHash && ctx.spec.task) { const a = el('a', r, 'mono ev-file'); a.href = ctx.diffHash({ kind: 'task', task: ctx.spec.task, source: ctx.spec.exec, file: r }); a.title = 'This file in the diff its review read'; head.append(a); }
+        else head.append(el('span', r, 'mono ev-file'));
+      }
+      if (list(ev.change).length) head.append(el('span', [...new Set(ev.change)].join(', '), 'tag'));
+      if (ev.error) head.append(el('span', 'failed', 'tag tag-bad'));
+      if (when) head.append(when);
+      body.append(head);
+      if (ev.patch) patch(body, ev.patch, key + 'p', v); else out(body, ev.input, key + 'i', v, { title: 'Input' });
+      out(body, ev.output, key + 'o', v, { open: !!ev.error });
+    } else if (kind === 'tool') {
+      head.append(el('span', 'Tool', 'ev-label'), el('span', ev.tool || '?', 'mono ev-toolname'));
+      if (ev.target) head.append(el('span', rel(D, String(ev.target), ctx.run), 'mono ev-file'));
+      if (ev.error) head.append(el('span', 'failed', 'tag tag-bad'));
+      if (when) head.append(when);
+      body.append(head); out(body, ev.input, key + 'i', v, { title: 'Input' }); out(body, ev.output, key + 'o', v, { open: !!ev.error });
+    } else if (kind === 'result') {
+      head.append(el('span', ev.error ? 'Ended with an error' : 'Final answer', 'ev-label'));
+      const t = ev.tokens; if (t) head.append(el('span', `${num(t.input)} in · ${num(t.output)} out`, 'muted ev-tokens'));
+      if (when) head.append(when);
+      body.append(head);
+      if (!ev.same) body.append(el('div', ev.text, 'ev-text'));
+    } else if (kind === 'error') {
+      head.append(el('span', 'Error', 'ev-label')); if (when) head.append(when);
+      body.append(head, el('div', ev.text, 'ev-text warn'));
+    } else {
+      head.append(el('span', ev.stream === 'stderr' ? 'stderr' : 'Log', 'ev-label')); if (when) head.append(when);
+      body.append(head); out(body, ev.text, key + 't', v, { title: 'Lines' });
+    }
+    li.append(gut, body);
+    li.dataset.find = [ev.text, ev.command, ev.output, ev.input, ev.patch, ev.tool, ev.target, list(ev.files).join(' ')].filter(Boolean).join('\n').toLowerCase();
+    return li;
+  }
+  function clock(s) { s = Math.max(0, Math.round(s)); const h = Math.floor(s / 3600), m = Math.floor(s / 60) % 60, x = s % 60; return (h ? h + ':' + String(m).padStart(2, '0') : m) + ':' + String(x).padStart(2, '0'); }
+
+  /* ---------- the list: rebuilt from the first event that changed, so a live log only appends ---------- */
+  function events(f, ctx, D, v) {
+    const evs = list(D.events), sigs = evs.map(e => JSON.stringify(e));
+    let i = 0;
+    while (i < f.drawn.length && i < sigs.length && f.drawn[i] === sigs[i]) i++;
+    const grew = sigs.length > f.drawn.length || i < f.drawn.length;
+    for (const n of f.nodes.splice(i)) n.remove();
+    const t0 = evs.map(e => e.t).find(Number.isFinite);
+    for (let k = i; k < evs.length; k++) { const n = eventNode(ctx, D, evs[k], k, v, t0); f.nodes.push(n); f.list.append(n); }
+    // a final answer that repeats the agent's last message marks that message instead
+    const r = evs.findIndex(e => e.kind === 'result' && e.same);
+    let m = r - 1; while (m >= 0 && evs[m].kind !== 'message') m--;
+    const said = m >= 0 && f.nodes[m];
+    if (said && !said.querySelector('.ev-final')) said.querySelector('.ev-head').append(el('span', 'final answer', 'tag ev-final'));
+    f.drawn = sigs;
+    return grew && i < sigs.length;
+  }
+  function filter(f, v) {
+    const q = v.query.trim().toLowerCase(), kinds = (SHOW.find(s => s[0] === v.show) || SHOW[0])[2];
+    let shown = 0;
+    for (const n of f.nodes) {
+      const kind = n.dataset.kind;
+      const on = (!kinds || kinds.includes(kind)) && (!q || (n.dataset.find || '').includes(q));
+      n.hidden = !on; if (on && kind !== 'gap') shown++;
+    }
+    for (const b of f.show.children) b.setAttribute('aria-pressed', String(b.dataset.show === v.show));
+    const total = f.nodes.filter(n => n.dataset.kind !== 'gap').length;
+    f.count.textContent = q || kinds ? `${shown} of ${total}` : '';
+    const errs = f.nodes.filter(n => n.classList.contains('is-error')).length;
+    f.errs.replaceChildren(errs ? chip(`${errs} error${errs === 1 ? '' : 's'}`, 'fail') : el('span', 'no errors', 'muted'));
+    f.err.hidden = !errs;
+  }
+  function nextError(f, v) {
+    const errs = f.nodes.filter(n => n.classList.contains('is-error'));
+    if (!errs.length) return;
+    v.err = (v.err == null ? -1 : v.err) + 1;
+    if (v.err >= errs.length) v.err = 0;
+    const n = errs[v.err];
+    if (n.hidden) { v.query = ''; v.show = 'all'; f.search.value = ''; filter(f, v); }
+    for (const d of n.querySelectorAll('details')) d.open = true;
+    n.scrollIntoView({ block: 'center' }); n.focus({ preventScroll: true });
+    n.classList.remove('flash'); void n.offsetWidth; n.classList.add('flash');
+  }
+  function end(f) { const last = f.nodes[f.nodes.length - 1]; if (last) last.scrollIntoView({ block: 'end' }); }
+
+  /* ---------- the view ---------- */
+  function render(host, ctx) {
+    const url = urlFor(ctx.run, ctx.spec), entry = load(ctx, url);
+    let v = views.get(url);
+    if (!v) { v = { query: '', show: 'all', follow: true, open: new Set(), err: null }; views.set(url, v); }
+    let f = host.convoFrame;
+    const fresh = !f || f.url !== url;
+    if (fresh) { f = frame(host, ctx, url, v); host.convoFrame = f; }
+    const D = entry.data;
+    header(f, ctx, D);
+    if (!D) {
+      f.status.replaceChildren(el('p', entry.error ? (entry.error.snapshot ? 'This conversation is not in this export: it was made without prompts and texts.' :
+        `Could not load this conversation (${entry.error.status === 404 ? 'not found' : entry.error.message}).`) : 'Reading the log…', entry.error ? 'warn' : 'muted'));
+      return;
+    }
+    const running = D.state === 'running' && ctx.live !== false;
+    f.follow.hidden = !running; f.follow.setAttribute('aria-pressed', String(v.follow));
+    const status = [];
+    const ws = list(D.warnings);
+    if (ws.length) status.push(el('p', ws[0], 'warn'));
+    if (ws.length > 1) { const d = el('details', undefined, 'diff-warnings'); d.append(el('summary', `${ws.length - 1} more warning${ws.length === 2 ? '' : 's'}`), el('pre', ws.slice(1).join('\n'))); status.push(d); }
+    if (D.format === 'text' && list(D.events).length) status.push(el('p', `${D.harness || 'This harness'} left plain text, not a stream of events: its log is shown as it is.`, 'muted'));
+    if (!list(D.events).length) status.push(el('p', running ? 'Nothing logged yet: the agent has just started.' : D.source === 'none' ? 'No log was kept for this execution.' : 'Its log holds no conversation.', 'muted convo-empty'));
+    f.status.replaceChildren(...status);
+    const grew = events(f, ctx, D, v);
+    filter(f, v);
+    if (running && v.follow && (grew || fresh)) requestAnimationFrame(() => end(f));
+    // a log still being written: read it again shortly, while this view shows it
+    if (running && !entry.timer) {
+      entry.timer = setTimeout(() => {
+        entry.timer = null;
+        if (host.convoFrame === f && host.isConnected && !host.hidden && !entry.pending) read(ctx, url, entry);
+      }, POLL);
+    }
+  }
+  return { render, urlFor, cache };
+})();

package/ui/forge_ui/static/datatable.js

@@ -0,0 +1,232 @@
+/* forge-ui data tables: sortable, reorderable columns that can be hidden, remembered per table.
+   A column is { id, label, title?, cls?, mono?, value(row) → number|string|null (sort key), cell(row) → Node|<td>|text,
+   sortable? (default true), hideable? (default true; the first column never hides), hidden? (starts hidden until shown) }.
+   Click a header to sort (ascending, descending, off); drag a header, or Alt+←/→ on it, to move it; the Columns menu shows
+   or hides columns and resets the table. Empty values always sort last.
+   window.ForgeTable = { render(parent, opts) → root, normPrefs, sortRows, compare, move } and module.exports for node tests.
+   opts = { id, label, columns, rows, prefs, savePrefs(prefs), rowClass(row)?, onRow(row, tr)?, scrollKey?, tools? (an element
+   that receives the Columns button instead of a toolbar row) }. */
+(function (root, factory) {
+  const api = factory();
+  if (typeof module === 'object' && module.exports) module.exports = api;
+  else root.ForgeTable = api;
+})(typeof self !== 'undefined' ? self : this, () => {
+  'use strict';
+  const list = v => Array.isArray(v) ? v : [];
+  const empty = v => v === null || v === undefined || v === '' || (typeof v === 'number' && !Number.isFinite(v));
+
+  /* ---------- pure: preferences, ordering, sorting ---------- */
+  // Saved preferences against today's columns: unknown ids dropped, new columns slotted in at their default place
+  // (and hidden when they start hidden).
+  function normPrefs(prefs, columns) {
+    prefs = prefs && typeof prefs === 'object' ? prefs : {};
+    const ids = list(columns).map(c => c.id), known = new Set(ids);
+    const saved = list(prefs.order).filter((id, i, a) => known.has(id) && a.indexOf(id) === i);
+    const order = saved.slice();
+    ids.forEach((id, i) => {
+      if (order.includes(id)) return;
+      // after the nearest column that precedes it by default and is already placed
+      let at = 0;
+      for (let j = i - 1; j >= 0; j--) { const k = order.indexOf(ids[j]); if (k >= 0) { at = k + 1; break; } }
+      order.splice(at, 0, id);
+    });
+    const hideable = new Set(list(columns).filter((c, i) => i > 0 && c.hideable !== false).map(c => c.id));
+    const fresh = list(columns).filter(c => c.hidden && !saved.includes(c.id)).map(c => c.id);
+    const hidden = list(prefs.hidden).concat(fresh).filter((id, i, a) => hideable.has(id) && a.indexOf(id) === i);
+    const col = list(columns).find(c => prefs.sort && c.id === prefs.sort.id && c.sortable !== false);
+    const sort = col && (prefs.sort.dir === 'asc' || prefs.sort.dir === 'desc') ? { id: col.id, dir: prefs.sort.dir } : null;
+    return { order, hidden, sort };
+  }
+  // Numbers by value, text in natural order ("task-2" before "task-10"), numbers before text, empty last.
+  function compare(a, b) {
+    const ea = empty(a), eb = empty(b);
+    if (ea || eb) return ea === eb ? 0 : ea ? 1 : -1;
+    const na = typeof a === 'number', nb = typeof b === 'number';
+    if (na && nb) return a - b;
+    if (na !== nb) return na ? -1 : 1;
+    return String(a).localeCompare(String(b), undefined, { numeric: true, sensitivity: 'base' });
+  }
+  // A stable sort by one column; empty values stay at the bottom whichever way it runs.
+  function sortRows(rows, column, dir) {
+    const items = list(rows).map((row, i) => ({ row, i, v: column && column.value ? column.value(row) : null }));
+    if (!column || (dir !== 'asc' && dir !== 'desc')) return items.map(x => x.row);
+    const sign = dir === 'desc' ? -1 : 1;
+    items.sort((x, y) => {
+      const ex = empty(x.v), ey = empty(y.v);
+      if (ex || ey) return ex === ey ? x.i - y.i : ex ? 1 : -1;
+      return sign * compare(x.v, y.v) || x.i - y.i;
+    });
+    return items.map(x => x.row);
+  }
+  // The order with `id` moved to index `to` (clamped).
+  function move(order, id, to) {
+    const out = list(order).filter(x => x !== id);
+    if (out.length === list(order).length) return list(order).slice();
+    out.splice(Math.max(0, Math.min(out.length, to)), 0, id);
+    return out;
+  }
+  const nextSort = (sort, id) => !sort || sort.id !== id ? { id, dir: 'asc' } : sort.dir === 'asc' ? { id, dir: 'desc' } : null;
+
+  /* ---------- DOM ---------- */
+  const menusOpen = new Set();                              // tables whose Columns menu was open, kept across re-renders
+  function el(tag, text, cls) {
+    const n = document.createElement(tag);
+    if (text !== undefined && text !== null) n.textContent = String(text);
+    if (cls) n.className = cls;
+    return n;
+  }
+  const icon = (name) => window.ForgeIcons ? window.ForgeIcons.icon(name) : document.createTextNode('');
+
+  function render(parent, opts) {
+    const columns = list(opts.columns), byId = new Map(columns.map(c => [c.id, c]));
+    let prefs = normPrefs(opts.prefs, columns);
+    const save = next => { prefs = next; if (opts.savePrefs) opts.savePrefs({ order: next.order, hidden: next.hidden, sort: next.sort }); redraw(); };
+    let current = null;
+
+    function menu() {
+      const btn = el('button', undefined, 'dt-columns-btn'); btn.type = 'button';
+      btn.append(icon('columns'), el('span', 'Columns'));
+      btn.title = 'Show, hide and reset this table\'s columns';
+      const pop = el('div', undefined, 'dt-menu popover'); pop.popover = 'auto'; pop.id = 'dt-menu-' + opts.id;
+      pop.setAttribute('aria-label', `Columns of ${opts.label || opts.id}`);
+      btn.popoverTargetElement = pop; btn.setAttribute('aria-haspopup', 'true');
+      const head = el('div', undefined, 'dt-menu-head'); head.append(el('span', 'Columns', 'plate'));
+      const reset = el('button', 'Reset', 'dt-reset'); reset.type = 'button';
+      reset.title = 'Default order, every column shown, no sort';
+      reset.addEventListener('click', () => save(normPrefs({}, columns)));
+      head.append(reset); pop.append(head);
+      const ul = el('ul', undefined, 'dt-menu-list');
+      prefs.order.forEach((id, i) => {
+        const c = byId.get(id), li = el('li'), lab = el('label'), box = el('input');
+        box.type = 'checkbox'; box.checked = !prefs.hidden.includes(id);
+        box.disabled = columns[0].id === id || c.hideable === false;
+        box.addEventListener('change', () => save({ ...prefs, hidden: box.checked ? prefs.hidden.filter(x => x !== id) : prefs.hidden.concat(id) }));
+        lab.append(box, el('span', c.label));
+        const up = el('button', undefined, 'dt-step'); up.type = 'button'; up.append(icon('chevron-up')); up.disabled = i === 0;
+        up.setAttribute('aria-label', `Move ${c.label} left`); up.addEventListener('click', () => save({ ...prefs, order: move(prefs.order, id, i - 1) }));
+        const down = el('button', undefined, 'dt-step'); down.type = 'button'; down.append(icon('chevron-down')); down.disabled = i === prefs.order.length - 1;
+        down.setAttribute('aria-label', `Move ${c.label} right`); down.addEventListener('click', () => save({ ...prefs, order: move(prefs.order, id, i + 1) }));
+        li.append(lab, up, down); ul.append(li);
+      });
+      pop.append(ul);
+      pop.addEventListener('toggle', e => {
+        if (e.newState === 'open') {
+          menusOpen.add(opts.id);
+          const r = btn.getBoundingClientRect(), w = pop.offsetWidth || 260;
+          pop.style.top = Math.round(r.bottom + 6) + 'px';
+          pop.style.left = Math.round(Math.max(8, Math.min(window.innerWidth - w - 8, r.right - w))) + 'px';
+        } else menusOpen.delete(opts.id);
+      });
+      return [btn, pop];
+    }
+
+    function header(shown) {
+      const thead = el('thead'), tr = el('tr');
+      shown.forEach((c, i) => {
+        const th = el('th', undefined, c.cls || ''); th.scope = 'col'; th.dataset.col = c.id;
+        if (c.title) th.title = c.title;
+        const sorted = prefs.sort && prefs.sort.id === c.id;
+        if (sorted) th.setAttribute('aria-sort', prefs.sort.dir === 'asc' ? 'ascending' : 'descending');
+        th.draggable = true;
+        const lead = c.sortable === false ? el('span', undefined, 'th-label') : el('button', undefined, 'th-btn');
+        if (c.sortable !== false) {
+          lead.type = 'button';
+          lead.addEventListener('click', () => save({ ...prefs, sort: nextSort(prefs.sort, c.id) }));
+        }
+        lead.append(el('span', c.label, 'th-text'));
+        if (c.sortable !== false) {
+          const mark = el('span', undefined, 'th-sort' + (sorted ? ' on' : ''));
+          mark.append(icon(sorted ? (prefs.sort.dir === 'asc' ? 'sort-asc' : 'sort-desc') : 'sort'));
+          lead.append(mark);
+        }
+        lead.addEventListener('keydown', e => {
+          if (!e.altKey || (e.key !== 'ArrowLeft' && e.key !== 'ArrowRight')) return;
+          e.preventDefault();
+          const at = prefs.order.indexOf(c.id), to = e.key === 'ArrowLeft' ? at - 1 : at + 1;
+          if (to < 0 || to >= prefs.order.length) return;
+          save({ ...prefs, order: move(prefs.order, c.id, to) });
+          current.querySelector(`th[data-col="${CSS.escape(c.id)}"] .th-btn, th[data-col="${CSS.escape(c.id)}"] .th-label`)?.focus();
+        });
+        th.addEventListener('dragstart', e => { e.dataTransfer.setData('text/plain', c.id); e.dataTransfer.effectAllowed = 'move'; th.classList.add('dragging'); });
+        th.addEventListener('dragend', () => { th.classList.remove('dragging'); for (const n of thead.querySelectorAll('.drop-before, .drop-after')) n.classList.remove('drop-before', 'drop-after'); });
+        th.addEventListener('dragover', e => {
+          e.preventDefault(); e.dataTransfer.dropEffect = 'move';
+          const r = th.getBoundingClientRect(), after = e.clientX > r.left + r.width / 2;
+          th.classList.toggle('drop-after', after); th.classList.toggle('drop-before', !after);
+        });
+        th.addEventListener('dragleave', () => th.classList.remove('drop-before', 'drop-after'));
+        th.addEventListener('drop', e => {
+          e.preventDefault();
+          const id = e.dataTransfer.getData('text/plain'); if (!byId.has(id) || id === c.id) return;
+          const r = th.getBoundingClientRect(), after = e.clientX > r.left + r.width / 2;
+          const rest = prefs.order.filter(x => x !== id), at = rest.indexOf(c.id) + (after ? 1 : 0);
+          save({ ...prefs, order: move(prefs.order, id, at) });
+        });
+        th.append(lead);
+        if (i === 0) th.classList.add('dt-first');
+        tr.append(th);
+      });
+      thead.append(tr);
+      return thead;
+    }
+
+    function build() {
+      const node = el('div', undefined, 'dt');
+      node.dataset.table = opts.id;
+      const shown = prefs.order.filter(id => !prefs.hidden.includes(id)).map(id => byId.get(id));
+      const [btn, pop] = menu();
+      if (opts.tools) opts.tools.replaceChildren(btn);
+      else { const bar = el('div', undefined, 'dt-bar'); if (prefs.sort || prefs.hidden.length) bar.append(status()); bar.append(btn); node.append(bar); }
+      node.append(pop);
+      const wrap = el('div', undefined, 'table-scroll');
+      if (opts.scrollKey) wrap.dataset.scroll = opts.scrollKey;
+      wrap.tabIndex = 0; wrap.setAttribute('role', 'region'); wrap.setAttribute('aria-label', opts.label || opts.id);
+      const table = el('table', undefined, opts.className || '');
+      if (opts.label) table.append(el('caption', opts.label, 'visually-hidden'));
+      table.append(header(shown));
+      const body = el('tbody');
+      const col = prefs.sort && byId.get(prefs.sort.id);
+      for (const row of sortRows(opts.rows, col, prefs.sort && prefs.sort.dir)) {
+        const tr = el('tr', undefined, opts.rowClass ? opts.rowClass(row) || '' : '');
+        for (const c of shown) {
+          let v = c.cell ? c.cell(row) : c.value ? c.value(row) : null;
+          let td;
+          if (v instanceof Node && v.nodeName === 'TD') td = v;
+          else {
+            td = el('td', undefined, [c.cls, c.mono ? 'mono' : ''].filter(Boolean).join(' '));
+            td.append(v instanceof Node ? v : document.createTextNode(empty(v) ? '—' : String(v)));
+          }
+          td.dataset.col = c.id;
+          tr.append(td);
+        }
+        if (opts.onRow) opts.onRow(row, tr);
+        body.append(tr);
+      }
+      table.append(body); wrap.append(table);
+      // a fade on each edge that has more table past it
+      const frame = el('div', undefined, 'dt-frame'); frame.append(wrap); node.append(frame);
+      const edges = () => { const end = wrap.scrollWidth - wrap.clientWidth; frame.classList.toggle('more-left', wrap.scrollLeft > 1); frame.classList.toggle('more-right', wrap.scrollLeft < end - 1); };
+      wrap.addEventListener('scroll', edges, { passive: true });
+      if (typeof ResizeObserver !== 'undefined') new ResizeObserver(edges).observe(wrap);
+      if (menusOpen.has(opts.id)) queueMicrotask(() => { if (pop.isConnected && pop.showPopover) try { pop.showPopover(); } catch (_) { /* already open */ } });
+      return node;
+    }
+    function status() {
+      const s = el('span', undefined, 'dt-status muted');
+      const bits = [];
+      if (prefs.sort) bits.push(`sorted by ${byId.get(prefs.sort.id).label}, ${prefs.sort.dir === 'asc' ? 'ascending' : 'descending'}`);
+      if (prefs.hidden.length) bits.push(`${prefs.hidden.length} hidden`);
+      s.textContent = bits.join(' · ');
+      return s;
+    }
+    function redraw() {
+      const next = build();
+      current.replaceWith(next); current = next;
+    }
+    current = build();
+    parent.append(current);
+    return current;
+  }
+
+  return { render, normPrefs, sortRows, compare, move, nextSort };
+});

package/ui/forge_ui/static/diffview.js

@@ -1,12 +1,11 @@
 /* forge-ui diff viewer: a task's diff (current, previous, committed, or exactly what one reviewer read), a final
    review's combined diff or a Fractal node's candidate, with each review finding shown under the line it points
    at. Defines window.ForgeDiff.render(host, ctx). All API values enter the DOM as text.
-   ctx = { run, spec: {kind: 'task'|'final'|'fractal', task, source, file, name, node}, fetchJSON(path),
+   ctx = { run, spec: {kind: 'task'|'final'|'fractal', task, source, file, name, node, finding}, fetchJSON(path),
            rerender(), href(spec) → hash, closeHref }. */
 window.ForgeDiff = (() => {
   'use strict';
   const list = v => Array.isArray(v) ? v : [];
-  const SEV = { P0: 'fail', P1: 'conflict', P2: 'timeout', P3: 'unknown' };
   const RANK = { P0: 0, P1: 1, P2: 2, P3: 3 };
   const BUDGET = 4000;                                       // lines drawn before the rest of the files wait for a click
   const cache = new Map();                                   // url → {data, error, pending, fresh}
@@ -18,6 +17,7 @@ window.ForgeDiff = (() => {
     return n;
   }
   const chip = (text, st) => el('span', text, 'chip st-' + st);
+  const sevChip = (text, sev) => el('span', text, 'chip sev-chip sev-' + (/^P[0-3]$/.test(sev) ? sev : 'none'));
   const enc = encodeURIComponent;
   const TASK_FILES = new Set(['current', 'prev', 'committed', 'existing']);
   function urlFor(run, spec) {
@@ -47,8 +47,9 @@ window.ForgeDiff = (() => {
   /* ---------- one finding, as a row under its line or in a list ---------- */
   function findingBox(f, where) {
     const box = el('div', undefined, 'diff-finding sev-' + (f.severity || 'P3'));
+    if (f.id) box.dataset.finding = f.id;                    // a mark on the stage opens the diff at this finding
     const head = el('div', undefined, 'diff-finding-head');
-    head.append(chip(f.severity || '?', SEV[f.severity] || 'unknown'));
+    head.append(sevChip(f.severity || '?', f.severity));
     if (f.status) head.append(el('span', f.status.toLowerCase(), 'tag'));
     const r = f.review || {};
     head.append(el('span', `${r.kind || 'review'}${r.attempt != null ? ' · attempt ' + r.attempt : ''}${r.spec ? ' · ' + r.spec : ''}`, 'muted'));
@@ -66,7 +67,7 @@ window.ForgeDiff = (() => {
     const st = { modified: 'running', added: 'merged', deleted: 'fail', renamed: 'nochanges', copied: 'nochanges' }[f.status] || 'unknown';
     head.append(chip(f.status, st));
     const name = el('a', f.status === 'renamed' || f.status === 'copied' ? `${f.old} → ${f.new}` : pathOf(f), 'mono diff-path');
-    name.href = ctx.href({ ...ctx.spec, file: pathOf(f) });
+    name.href = ctx.href({ ...ctx.spec, finding: null, file: pathOf(f) });
     head.append(name, el('span', `+${f.additions} −${f.deletions}`, 'diff-stat'));
     if (f.binary) head.append(el('span', 'binary', 'tag'));
     if (f.truncated) head.append(el('span', 'cut short', 'tag'));
@@ -118,15 +119,20 @@ window.ForgeDiff = (() => {
   function render(host, ctx) {
     const run = ctx.run, spec = ctx.spec, url = urlFor(run, spec), entry = load(ctx, url);
     // a poll that brought nothing new leaves thousands of rows alone
-    const sig = [url, entry.at || 0, !!entry.error, spec.file, opened.size].join('|');
+    const sig = [url, entry.at || 0, !!entry.error, spec.file, spec.finding, opened.size].join('|');
     if (host.diffSig === sig) return;
     host.diffSig = sig;
+    // the finding the keyboard is on keeps it through the rebuild (a poll, a fold)
+    const had = document.activeElement && host.contains(document.activeElement) && document.activeElement.closest('[data-finding]');
+    const keep = had ? had.dataset.finding : null;
     host.replaceChildren();
     const D = entry.data;
     const top = el('div', undefined, 'diff-top');
     const what = spec.kind === 'final' ? 'Final review' : spec.kind === 'fractal' ? `${spec.task} · Fractal node ${spec.node}` : spec.task === 'solo' && run.kind === 'solo' ? 'Solo run' : `Task ${spec.task}`;
     const title = el('h2'); title.append(el('span', 'Diff · ', 'muted'), document.createTextNode(what)); top.append(title);
-    const close = el('a', 'Close ✕', 'diff-close'); close.href = ctx.closeHref; top.append(close);
+    const close = el('a', undefined, 'diff-close button'); close.href = ctx.closeHref;
+    if (window.ForgeIcons) close.append(window.ForgeIcons.icon('close'));
+    close.append(document.createTextNode('Close')); top.append(close);
     host.append(top);
     if (!D) {
       host.append(el('p', entry.error ? (entry.error.snapshot ? 'This diff is not in this export.' : `Could not load this diff (${entry.error.status === 404 ? 'not found' : entry.error.message}).`) : 'Loading the diff…', entry.error ? 'warn' : 'muted'));
@@ -140,7 +146,7 @@ window.ForgeDiff = (() => {
       const cur = spec.kind === 'final' ? spec.name : spec.kind === 'fractal' ? 'candidate' : spec.source || 'current';
       for (const s of sources) {
         const a = el('a', s.label || s.id, 'diff-source'); a.setAttribute('aria-current', String(s.id === cur));
-        a.href = spec.kind === 'final' ? ctx.href({ kind: 'final', name: s.id }) : ctx.href({ ...spec, source: s.id, file: null });
+        a.href = spec.kind === 'final' ? ctx.href({ kind: 'final', name: s.id }) : ctx.href({ ...spec, source: s.id, file: null, finding: null });
         if (s.verdict) a.append(document.createTextNode(' '), chip(s.verdict, String(s.verdict).toLowerCase()));
         a.title = `${s.bytes != null ? s.bytes + ' bytes' : ''}${s.kind ? ' · ' + s.kind : ''}`;
         bar.append(a);
@@ -166,13 +172,13 @@ window.ForgeDiff = (() => {
     const nav = el('nav', undefined, 'diff-files'); nav.setAttribute('aria-label', 'Files in this diff');
     const ul = el('ul');
     files.forEach((f, fi) => {
-      const li = el('li'), a = el('a', undefined, 'diff-file-link'); a.href = ctx.href({ ...spec, file: pathOf(f) }); a.dataset.fi = String(fi);
+      const li = el('li'), a = el('a', undefined, 'diff-file-link'); a.href = ctx.href({ ...spec, finding: null, file: pathOf(f) }); a.dataset.fi = String(fi);
       const p = pathOf(f), cut = p.lastIndexOf('/');
       a.append(el('span', cut >= 0 ? p.slice(0, cut + 1) : '', 'diff-dir'), el('span', cut >= 0 ? p.slice(cut + 1) : p, 'diff-base'));
       const stat = el('span', undefined, 'diff-stat'); stat.append(el('span', `+${f.additions}`, 'diff-add'), document.createTextNode(' '), el('span', `−${f.deletions}`, 'diff-del'));
       a.append(stat);
       const ps = byFile.get(fi) || [];
-      if (ps.length) { const w = worst(ps.map(x => x.f)); a.append(chip(`${ps.length}`, SEV[w] || 'unknown')); a.title = `${ps.length} finding${ps.length === 1 ? '' : 's'}, worst ${w}`; }
+      if (ps.length) { const w = worst(ps.map(x => x.f)); a.append(sevChip(`${ps.length}`, w)); a.title = `${ps.length} finding${ps.length === 1 ? '' : 's'}, worst ${w}`; }
       if (spec.file && spec.file === p) a.setAttribute('aria-current', 'true');
       li.append(a); ul.append(li);
     });
@@ -207,7 +213,20 @@ window.ForgeDiff = (() => {
         fileEls[i].scrollIntoView({ block: 'start' }); e.preventDefault();
       }
     };
-    if (spec.file) {
+    const flash = n => { n.classList.add('flash'); setTimeout(() => n.classList.remove('flash'), 1600); };
+    const back = keep && order.find(n => n.dataset.finding === keep);
+    if (back) back.focus({ preventScroll: true });
+    if (spec.finding) {
+      const target = order.find(n => n.dataset.finding === spec.finding);
+      if (target && host.dataset.scrolledTo !== url + '\n#' + spec.finding) {
+        host.dataset.scrolledTo = url + '\n#' + spec.finding; fIdx = order.indexOf(target);
+        requestAnimationFrame(() => {
+          const live = target.isConnected ? target : [...host.querySelectorAll('.diff-finding[id]')].find(n => n.dataset.finding === spec.finding);
+          if (!live) return;
+          live.scrollIntoView({ block: 'center' }); flash(live); live.focus({ preventScroll: true });
+        });
+      }
+    } else if (spec.file) {
       const target = fileEls.find(s => s.dataset.path === spec.file);
       if (target && host.dataset.scrolledTo !== url + '\n' + spec.file) { host.dataset.scrolledTo = url + '\n' + spec.file; requestAnimationFrame(() => target.scrollIntoView({ block: 'start' })); }
     }