@khanglvm/relay 0.2.0 → 0.4.0

package/src/server.js

@@ -1,6 +1,8 @@
 import http from 'node:http';
 import fs from 'node:fs';
 import path from 'node:path';
+import crypto from 'node:crypto';
+import { spawn } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
 import { loadBoard, saveBoard, saveRunning, removeRunning, loadPref, savePref } from './store.js';
 import { openUrl } from './open.js';
@@ -46,7 +48,7 @@ function vendorPresent(file) {
   }
 }
 
-function buildPage(record) {
+function buildPage(record, rev) {
   const html = fs.readFileSync(path.join(UI_DIR, 'index.html'), 'utf8');
   const css = readUi('style.css');
   const blocksCss = readUi('blocks.css');
@@ -69,6 +71,7 @@ function buildPage(record) {
   const vendor = {
     chart: specNeeds(spec, 'chart') && vendorPresent('chart.umd.js'),
     mermaid: specNeeds(spec, 'mermaid') && vendorPresent('mermaid.min.js'),
+    viz: specNeeds(spec, 'graphviz') && vendorPresent('viz-standalone.js'),
   };
   // Prefill from the LIVE draft at request time (drafts autosave in real time),
   // so a mid-fill page reload restores everything the user already entered.
@@ -78,9 +81,10 @@ function buildPage(record) {
         comment: record.draft.comment || '',
         notes: record.draft.notes || {},
         annotations: record.draft.annotations || [],
+        blockEdits: record.draft.blockEdits || {},
       }
     : null;
-  const boot = { boardId: record.id, spec: clientSpec, prefill, pref: loadPref(), vendor };
+  const boot = { boardId: record.id, spec: clientSpec, prefill, pref: loadPref(), vendor, rev };
   const json = JSON.stringify(boot).replace(/</g, '\\u003c');
   return html
     .split('__TITLE__').join(escapeHtml(spec.title))
@@ -93,8 +97,26 @@ function buildPage(record) {
     .split('__BOOT_JSON__').join(json);
 }
 
+// Validates + sanitizes one annotation's threaded replies. Keeps only
+// well-formed {author, text, createdAt} entries; caps at 50; coerces author.
+function sanitizeReplies(value) {
+  if (!Array.isArray(value)) return [];
+  const out = [];
+  for (const r of value) {
+    if (out.length >= 50) break;
+    if (r === null || typeof r !== 'object' || Array.isArray(r)) continue;
+    if (typeof r.text !== 'string' || r.text.length > 5000) continue;
+    const author = r.author === 'agent' ? 'agent' : 'user';
+    const createdAt = typeof r.createdAt === 'string' ? r.createdAt : new Date().toISOString();
+    out.push({ author, text: r.text, createdAt });
+  }
+  return out;
+}
+
 // Validates + sanitizes an incoming annotations array (from draft/submit).
 // Drops anything that isn't a well-formed annotation object; caps at 500.
+// Each annotation may carry an optional author ('user'|'agent', default
+// 'user') and a threaded replies array (validated + capped at 50).
 function sanitizeAnnotations(value) {
   if (!Array.isArray(value)) return [];
   const out = [];
@@ -103,7 +125,27 @@ function sanitizeAnnotations(value) {
     if (a === null || typeof a !== 'object' || Array.isArray(a)) continue;
     if (typeof a.text !== 'string' || a.text.length > 5000) continue;
     if (a.target === null || typeof a.target !== 'object' || Array.isArray(a.target)) continue;
-    out.push(a);
+    const clean = { ...a, author: a.author === 'agent' ? 'agent' : 'user' };
+    if (a.replies !== undefined) clean.replies = sanitizeReplies(a.replies);
+    out.push(clean);
+  }
+  return out;
+}
+
+// Validates + sanitizes an incoming blockEdits map (from draft/submit).
+// Keeps only string-keyed entries with string values <= 20000 chars; caps at
+// 50 entries; drops invalid entries. Returns {} when nothing valid is present.
+function sanitizeBlockEdits(value) {
+  if (value === null || typeof value !== 'object' || Array.isArray(value)) return {};
+  const out = {};
+  let n = 0;
+  for (const key of Object.keys(value)) {
+    if (n >= 50) break;
+    if (typeof key !== 'string') continue;
+    const v = value[key];
+    if (typeof v !== 'string' || v.length > 20000) continue;
+    out[key] = v;
+    n++;
   }
   return out;
 }
@@ -192,6 +234,47 @@ function readBody(req, limit = 5 * 1024 * 1024) {
   });
 }
 
+// Push-wake: run the agent's own local shell command after a board finishes.
+// The full result JSON is written to the command's stdin; RLY_BOARD_ID /
+// RLY_STATUS / RLY_URL are exported. Failures are swallowed (best effort) —
+// only a stderr note when not quiet. A 30s kill timer prevents a hung command
+// from keeping the process alive.
+function runOnResult(cmd, result, { quiet = false } = {}) {
+  if (typeof cmd !== 'string' || !cmd.trim()) return;
+  try {
+    const child = spawn('/bin/sh', ['-c', cmd], {
+      env: {
+        ...process.env,
+        RLY_BOARD_ID: result.boardId || '',
+        RLY_STATUS: result.status || '',
+        RLY_URL: result.url || '',
+      },
+      stdio: ['pipe', 'ignore', 'ignore'],
+    });
+    child.on('error', () => {
+      if (!quiet) process.stderr.write(`[relay] --on-result command failed to spawn\n`);
+    });
+    try {
+      child.stdin.write(JSON.stringify(result));
+      child.stdin.end();
+    } catch {
+      // best effort — stdin may already be gone
+    }
+    const killTimer = setTimeout(() => {
+      try {
+        child.kill('SIGKILL');
+      } catch {
+        // already gone
+      }
+    }, 30000);
+    killTimer.unref();
+    child.on('close', () => clearTimeout(killTimer));
+    child.unref();
+  } catch {
+    if (!quiet) process.stderr.write(`[relay] --on-result command failed to run\n`);
+  }
+}
+
 // Serves one board on 127.0.0.1 and resolves `done` when it finishes
 // (submitted / acknowledged / timeout / cancelled). The result is also
 // persisted into the board record so `rly wait` / `rly result` can read it
@@ -211,6 +294,7 @@ export async function runBoard({ id, port = 0, open = true, timeoutSec = 1800, q
         comment: record.result.comment || '',
         notes: record.result.notes || {},
         annotations: record.result.annotations || [],
+        blockEdits: record.result.blockEdits || {},
         updatedAt: new Date().toISOString(),
       };
     }
@@ -220,8 +304,14 @@ export async function runBoard({ id, port = 0, open = true, timeoutSec = 1800, q
   }
 
   const startedAt = Date.now();
+  // Mutation token: only `rly update` (which reads the running-file record)
+  // can authenticate to POST /api/update. Never embedded in the page/boot.
+  const token = crypto.randomBytes(16).toString('hex');
+  let rev = 1;
   let status = 'open';
   let finished = false;
+  // Latest client presence ping (null until the first ping arrives).
+  let presence = null;
   let resolveDone;
   const done = new Promise((r) => {
     resolveDone = r;
@@ -233,11 +323,48 @@ export async function runBoard({ id, port = 0, open = true, timeoutSec = 1800, q
     const theme = reqUrl.searchParams.get('theme') === 'dark' ? 'dark' : 'light';
     try {
       if (req.method === 'GET' && pathname === '/') {
-        sendHtml(res, buildPage(record));
+        sendHtml(res, buildPage(record, rev));
       } else if (req.method === 'GET' && pathname === '/api/board') {
-        sendJson(res, 200, { id: record.id, spec, draft: record.draft, result: record.result });
+        sendJson(res, 200, { id: record.id, spec: record.spec, draft: record.draft, result: record.result });
       } else if (req.method === 'GET' && pathname === '/api/status') {
-        sendJson(res, 200, { status });
+        sendJson(res, 200, { status, rev });
+      } else if (req.method === 'POST' && pathname === '/api/ping') {
+        const body = JSON.parse((await readBody(req)) || '{}');
+        // Validate body shape: visible/focused booleans, idleMs finite >= 0.
+        if (
+          typeof body.visible === 'boolean' &&
+          typeof body.focused === 'boolean' &&
+          Number.isFinite(body.idleMs) &&
+          body.idleMs >= 0
+        ) {
+          presence = { atMs: Date.now(), visible: body.visible, focused: body.focused, idleMs: body.idleMs };
+        }
+        sendJson(res, 200, { ok: true });
+      } else if (req.method === 'GET' && pathname === '/api/presence') {
+        if (!presence) {
+          sendJson(res, 200, { open: true, seen: false });
+        } else {
+          sendJson(res, 200, {
+            open: true,
+            seen: true,
+            visible: presence.visible,
+            focused: presence.focused,
+            secondsSinceActivity: Math.round((Date.now() - presence.atMs + presence.idleMs) / 1000),
+            secondsSincePing: Math.round((Date.now() - presence.atMs) / 1000),
+          });
+        }
+      } else if (req.method === 'POST' && pathname === '/api/update') {
+        if (req.headers['x-relay-token'] !== token) return sendJson(res, 403, { error: 'forbidden' });
+        const body = JSON.parse((await readBody(req)) || '{}');
+        const next = body.spec;
+        if (next === null || typeof next !== 'object' || Array.isArray(next) ||
+            !Array.isArray(next.questions) || !Array.isArray(next.blocks)) {
+          return sendJson(res, 400, { error: 'spec must be an object with questions[] and blocks[] arrays' });
+        }
+        record.spec = next;
+        rev++;
+        saveBoard(record);
+        sendJson(res, 200, { ok: true, rev });
       } else if (req.method === 'GET' && pathname === '/kit.js') {
         if (!sendFromDir(res, UI_DIR, 'kit.js', 'application/javascript; charset=utf-8')) {
           sendJs(res, ''); // kit.js authored concurrently — empty fallback keeps iframes working
@@ -249,16 +376,16 @@ export async function runBoard({ id, port = 0, open = true, timeoutSec = 1800, q
         }
       } else if (req.method === 'GET' && pathname.startsWith('/html/b/')) {
         const blockId = decodeURIComponent(pathname.slice('/html/b/'.length));
-        const block = findHtmlBlock(spec, blockId);
+        const block = findHtmlBlock(record.spec, blockId);
         if (!block) return sendJson(res, 404, { error: `no html block "${blockId}"` });
         sendHtml(res, wrapFragment(block.html || '', theme));
       } else if (req.method === 'GET' && pathname === '/html/board') {
         // Legacy alias → the board's first html block.
-        const block = firstBoardHtml(spec);
+        const block = firstBoardHtml(record.spec);
         sendHtml(res, wrapFragment((block && block.html) || '', theme));
       } else if (req.method === 'GET' && pathname.startsWith('/html/q/')) {
         const qid = decodeURIComponent(pathname.slice('/html/q/'.length));
-        const q = spec.questions.find((q) => q.id === qid);
+        const q = record.spec.questions.find((q) => q.id === qid);
         if (!q) return sendJson(res, 404, { error: `no question "${qid}"` });
         const block = firstQuestionHtml(q);
         sendHtml(res, wrapFragment((block && block.html) || '', theme));
@@ -273,6 +400,7 @@ export async function runBoard({ id, port = 0, open = true, timeoutSec = 1800, q
           comment: typeof body.comment === 'string' ? body.comment : '',
           notes: body.notes && typeof body.notes === 'object' ? body.notes : {},
           annotations: sanitizeAnnotations(body.annotations),
+          blockEdits: sanitizeBlockEdits(body.blockEdits),
           updatedAt: new Date().toISOString(),
         };
         saveBoard(record);
@@ -281,15 +409,16 @@ export async function runBoard({ id, port = 0, open = true, timeoutSec = 1800, q
         if (status !== 'open') return sendJson(res, 409, { error: 'board already finished' });
         const body = JSON.parse((await readBody(req)) || '{}');
         const answers = body.answers && typeof body.answers === 'object' ? body.answers : {};
-        const skipped = spec.questions.filter((q) => !(q.id in answers)).map((q) => q.id);
+        const skipped = record.spec.questions.filter((q) => !(q.id in answers)).map((q) => q.id);
         sendJson(res, 200, { ok: true });
         finish({
-          status: spec.questions.length ? 'submitted' : 'acknowledged',
+          status: record.spec.questions.length ? 'submitted' : 'acknowledged',
           answers,
           skipped,
           comment: typeof body.comment === 'string' ? body.comment : '',
           notes: body.notes && typeof body.notes === 'object' ? body.notes : {},
           annotations: sanitizeAnnotations(body.annotations),
+          blockEdits: sanitizeBlockEdits(body.blockEdits),
         });
       } else {
         sendJson(res, 404, { error: 'not found' });
@@ -311,6 +440,7 @@ export async function runBoard({ id, port = 0, open = true, timeoutSec = 1800, q
     port: actualPort,
     url,
     title: spec.title,
+    token,
     startedAt: new Date().toISOString(),
   });
 
@@ -324,6 +454,10 @@ export async function runBoard({ id, port = 0, open = true, timeoutSec = 1800, q
     if (finished) return;
     finished = true;
     status = partial.status;
+    // blockEdits: from this submit, else fall back to the autosaved draft
+    // (timeout/cancel). null when there are none.
+    const editsRaw = partial.blockEdits ?? (record.draft?.blockEdits || {});
+    const blockEdits = editsRaw && Object.keys(editsRaw).length ? editsRaw : null;
     const result = {
       status: partial.status,
       boardId: record.id,
@@ -334,6 +468,7 @@ export async function runBoard({ id, port = 0, open = true, timeoutSec = 1800, q
       comment: partial.comment ?? '',
       notes: partial.notes ?? null,
       annotations: partial.annotations ?? (record.draft?.annotations || []),
+      blockEdits,
       createdAt: record.createdAt,
       finishedAt: new Date().toISOString(),
       durationMs: Date.now() - startedAt,
@@ -345,6 +480,8 @@ export async function runBoard({ id, port = 0, open = true, timeoutSec = 1800, q
     }
     record.result = result;
     saveBoard(record);
+    // Push-wake: run the agent's local command for EVERY terminal status.
+    runOnResult(record.onResult, result, { quiet });
     removeRunning(record.id);
     if (timer) clearTimeout(timer);
     process.removeListener('SIGINT', onSignal);

package/src/spec.js

@@ -25,7 +25,7 @@ const HTML_HEIGHT = { min: 100, max: 2400, boardDefault: 400, questionDefault: 3
 
 // Block heights clamp to the same window; defaults vary per block type.
 const BLOCK_HEIGHT = { min: 100, max: 2400 };
-export const BLOCK_TYPES = ['markdown', 'mermaid', 'chart', 'table', 'code', 'html'];
+export const BLOCK_TYPES = ['markdown', 'mermaid', 'graphviz', 'plantuml', 'chart', 'table', 'code', 'html'];
 const CHART_KINDS = ['bar', 'line', 'pie', 'doughnut', 'radar', 'scatter'];
 
 const asStr = (v) => (typeof v === 'string' ? v : v == null ? '' : String(v));
@@ -89,6 +89,30 @@ function normalizeBlock(rawBlock, id, cwd, where) {
     const code = asStr(rawBlock.code);
     if (!code.trim()) throw new CliError(`${where}: mermaid block needs a non-empty "code" string.`);
     const block = { id, type: 'mermaid', code };
+    if (rawBlock.editable === true) block.editable = true;
+    if (hasHeight) block.height = clampInt(rawBlock.height, BLOCK_HEIGHT.min, BLOCK_HEIGHT.max, undefined);
+    return block;
+  }
+
+  if (type === 'graphviz') {
+    const dot = asStr(rawBlock.dot);
+    if (!dot.trim()) throw new CliError(`${where}: graphviz block needs a non-empty "dot" string.`);
+    const block = { id, type: 'graphviz', dot };
+    if (hasHeight) block.height = clampInt(rawBlock.height, BLOCK_HEIGHT.min, BLOCK_HEIGHT.max, undefined);
+    return block;
+  }
+
+  if (type === 'plantuml') {
+    const code = asStr(rawBlock.code);
+    if (!code.trim()) throw new CliError(`${where}: plantuml block needs a non-empty "code" string.`);
+    const block = { id, type: 'plantuml', code };
+    if (rawBlock.server !== undefined && rawBlock.server !== null && rawBlock.server !== '') {
+      const server = asStr(rawBlock.server).trim();
+      if (!/^https?:\/\/\S+$/i.test(server)) {
+        throw new CliError(`${where}: plantuml "server" must be an http(s) URL string.`);
+      }
+      block.server = server;
+    }
     if (hasHeight) block.height = clampInt(rawBlock.height, BLOCK_HEIGHT.min, BLOCK_HEIGHT.max, undefined);
     return block;
   }
@@ -343,7 +367,10 @@ const BLOCK_SCHEMA = {
     properties: {
       type: { type: 'string', enum: BLOCK_TYPES },
       md: { type: 'string', description: 'markdown: built-in mini renderer (no external library). Text selections are commentable.' },
-      code: { type: 'string', description: 'mermaid: diagram source (e.g. "graph TD; A-->B"); code: the source to display.' },
+      code: { type: 'string', description: 'mermaid: diagram source (e.g. "graph TD; A-->B"); plantuml: the @startuml…@enduml source; code: the source to display.' },
+      editable: { type: 'boolean', description: 'mermaid: when true, render an "Edit diagram" toggle so the user can edit the diagram source live. The edited source is returned in result.blockEdits[<blockId>].' },
+      dot: { type: 'string', description: 'graphviz: DOT source (e.g. "digraph { a -> b }"). Rendered offline via vendored Viz.js; nodes and edges are individually commentable.' },
+      server: { type: 'string', description: 'plantuml: PlantUML server base URL (http(s)). Defaults to https://www.plantuml.com/plantuml. Diagrams render via this server (needs network).' },
       lang: { type: 'string', description: 'code block: language hint for display.' },
       config: { type: 'object', description: 'chart: a full Chart.js config object.' },
       kind: { type: 'string', enum: CHART_KINDS, description: 'chart shorthand: chart kind (alternative to "config").' },
@@ -363,7 +390,7 @@ const BLOCK_SCHEMA = {
       sortable: { type: 'boolean', description: 'table: enable click-to-sort headers.' },
       html: { type: 'string', description: 'html: custom markup rendered in a sandboxed iframe.' },
       htmlFile: { type: 'string', description: 'html: path to an HTML file (alternative to "html").' },
-      height: { type: 'integer', minimum: BLOCK_HEIGHT.min, maximum: BLOCK_HEIGHT.max, description: 'Block height in px. Defaults: chart 320, html 360; markdown/table/code flow naturally; mermaid natural (max 1200, scrolls).' },
+      height: { type: 'integer', minimum: BLOCK_HEIGHT.min, maximum: BLOCK_HEIGHT.max, description: 'Block height in px. Defaults: chart 320, html 360; markdown/table/code flow naturally; mermaid/graphviz/plantuml natural (max 1200, scrolls).' },
     },
   },
 };
@@ -373,7 +400,7 @@ export const SPEC_SCHEMA = {
   title: 'relay board spec',
   type: 'object',
   description:
-    'A relay board. Renders an optional intro, board-level blocks, then questions (each with optional per-question blocks), then a submit button. The result JSON contains "answers", "comment", per-question "notes", and "annotations" (element-level comments the user attached to any block — see the annotation shape below).',
+    'A relay board. Renders an optional intro, board-level blocks, then questions (each with optional per-question blocks), then a submit button. The result JSON contains "answers", "comment", per-question "notes", "annotations" (element-level comments the user attached to any block — see the annotation shape below), and "blockEdits" (a map blockId→edited source for any editable mermaid block the user changed, null when none).',
   properties: {
     title: { type: 'string', description: 'Board title (default "Relay")' },
     intro: { type: 'string', description: 'Intro text shown under the title. Newlines preserved.' },
@@ -430,6 +457,12 @@ export const SPEC_SCHEMA = {
       description:
         'Returned in the result (not part of the input spec). Element-level comments the user attached to blocks. Each: {id, questionId|null, blockId|null, target:{kind:"chart-element"|"mermaid-node"|"table-cell"|"text"|"html-element", …}, text, createdAt}.',
     },
+    blockEdits: {
+      type: 'object',
+      readOnly: true,
+      description:
+        'Returned in the result (not part of the input spec). A map blockId→edited mermaid source for any editable mermaid block the user changed. null when the user made no edits. Read result.blockEdits[<blockId>] for the user\'s edited diagram source.',
+    },
   },
   anyOf: [{ required: ['questions'] }, { required: ['blocks'] }, { required: ['html'] }, { required: ['htmlFile'] }],
 };

package/src/ui/annotate.css

@@ -50,14 +50,64 @@
   margin-bottom: 8px;
   overflow-wrap: anywhere;
 }
-.ann-pop-existing { margin-bottom: 8px; }
+.ann-pop-existing { margin-bottom: 8px; max-height: min(50vh, 420px); overflow-y: auto; }
 .ann-pop-existing:empty { display: none; margin: 0; }
-.ann-pop-item {
-  display: flex; align-items: flex-start; gap: 8px;
-  padding: 6px 0;
+
+/* ---------- comment threads (popover) ---------- */
+.ann-thread {
+  padding: 7px 0;
   border-top: 1px solid var(--border);
 }
-.ann-pop-text { flex: 1; font-size: 0.88rem; white-space: pre-wrap; overflow-wrap: anywhere; }
+.ann-thread-head { display: flex; align-items: center; gap: 6px; }
+.ann-thread-head .ann-del { margin-left: auto; }
+.ann-pop-text { font-size: 0.88rem; white-space: pre-wrap; overflow-wrap: anywhere; }
+
+/* author chips: "you" muted, "agent" accent */
+.ann-chip {
+  flex: none;
+  display: inline-block;
+  background: var(--bg-sunken); color: var(--muted);
+  border-radius: 999px;
+  padding: 1px 7px;
+  font: 600 0.68rem/1.5 var(--sans);
+}
+.ann-chip-agent { background: var(--accent-soft); color: var(--accent); }
+.ann-time { color: var(--muted); font-size: 0.7rem; }
+
+/* replies, indented under their comment */
+.ann-replies {
+  margin-top: 5px;
+  padding-left: 10px;
+  border-left: 2px solid var(--border);
+}
+.ann-reply { padding: 3px 0; }
+.ann-reply-head { display: flex; align-items: center; gap: 6px; }
+.ann-reply-text { font-size: 0.84rem; white-space: pre-wrap; overflow-wrap: anywhere; }
+
+/* compact per-thread reply form */
+.ann-reply-form { display: flex; gap: 6px; margin-top: 6px; }
+.ann-reply-input {
+  flex: 1; min-width: 0;
+  background: var(--bg-sunken); color: var(--fg);
+  border: 1px solid var(--border); border-radius: 8px;
+  padding: 4px 8px;
+  font: 0.8rem/1.4 var(--sans);
+}
+.ann-reply-input:focus {
+  outline: none;
+  border-color: var(--accent);
+  box-shadow: 0 0 0 2px var(--accent-soft);
+}
+.ann-reply-btn {
+  flex: none;
+  background: transparent; color: var(--accent);
+  border: 1px solid var(--border); border-radius: 8px;
+  padding: 4px 10px;
+  font: 600 0.78rem var(--sans);
+  cursor: pointer;
+  transition: border-color 150ms var(--ease);
+}
+.ann-reply-btn:hover { border-color: var(--accent); }
 .ann-pop textarea.ann-ta {
   width: 100%; min-height: 64px;
   background: var(--bg-sunken); color: var(--fg);
@@ -131,6 +181,8 @@
 .ann-sum-main { flex: 1; min-width: 0; }
 .ann-sum-target { color: var(--muted); font-size: 0.78rem; overflow-wrap: anywhere; }
 .ann-sum-text { font-size: 0.92rem; white-space: pre-wrap; overflow-wrap: anywhere; }
+.ann-sum-meta { display: flex; align-items: center; gap: 6px; margin-top: 2px; }
+.ann-sum-replies { color: var(--muted); font-size: 0.75rem; }
 
 /* ---------- jump-to flash ---------- */
 .ann-flash { animation: ann-flash 1s var(--ease); }

package/src/ui/annotate.js

@@ -40,6 +40,10 @@
       }
       case 'mermaid-node':
         return 'Diagram · ' + truncate(t.text || t.nodeId || 'node', 50);
+      case 'graphviz-node':
+        return 'Graph · ' + truncate(t.text || t.nodeId || 'node', 50);
+      case 'image':
+        return truncate(t.label || 'Image', 50);
       case 'table-cell': {
         let s = `Table · row ${(Number(t.row) || 0) + 1} · ${t.col}`;
         if (t.value !== undefined && t.value !== null && t.value !== '') s += ` — “${truncate(t.value, 30)}”`;
@@ -58,6 +62,25 @@
   const sameTarget = (a, b) => JSON.stringify(a) === JSON.stringify(b);
   const sameBlock = (a, b) => (a ?? null) === (b ?? null);
 
+  // Author chip: "you" (muted) for user comments, "agent" (accent) for agent.
+  function chip(author) {
+    const agent = author === 'agent';
+    return el('span', { class: 'ann-chip' + (agent ? ' ann-chip-agent' : '') }, agent ? 'agent' : 'you');
+  }
+
+  // Short HH:MM timestamp (empty string when the date is unparsable).
+  function fmtTime(iso) {
+    const d = new Date(iso);
+    if (isNaN(d.getTime())) return '';
+    const p = (n) => String(n).padStart(2, '0');
+    return p(d.getHours()) + ':' + p(d.getMinutes());
+  }
+
+  function timeEl(iso) {
+    const t = fmtTime(iso);
+    return t ? el('span', { class: 'ann-time' }, t) : null;
+  }
+
   // ---------- state ----------
   let annotations = [];        // contract annotation objects
   let idCounter = 0;           // continues from max existing "aN"
@@ -177,6 +200,7 @@
   function refreshBadges() {
     for (const b of badges) b.remove();
     badges = [];
+    if (torndown) return;
     registered = registered.filter((r) => r.el.isConnected);
     for (const entry of registered) {
       const count = matching(entry.info).length;
@@ -221,7 +245,10 @@
     const pop = dom.pop;
     pop.replaceChildren(el('div', { class: 'ann-pop-label' }, humanize(info.target)));
 
-    // Existing comments on this exact target, each with a delete button.
+    // Existing comments on this exact target, rendered as threads: author
+    // chip + time + delete, the comment text, its replies indented below,
+    // and a compact reply input per thread. Deleting a comment deletes its
+    // whole thread.
     const existingWrap = el('div', { class: 'ann-pop-existing' });
     const renderExisting = () => {
       existingWrap.replaceChildren();
@@ -231,7 +258,37 @@
           removeAnnotation(a.id);
           renderExisting();
         });
-        existingWrap.append(el('div', { class: 'ann-pop-item' }, el('span', { class: 'ann-pop-text' }, a.text), del));
+        const thread = el('div', { class: 'ann-thread' },
+          el('div', { class: 'ann-thread-head' }, chip(a.author), timeEl(a.createdAt), del),
+          el('div', { class: 'ann-pop-text' }, a.text)
+        );
+        if (Array.isArray(a.replies) && a.replies.length) {
+          const list = el('div', { class: 'ann-replies' });
+          for (const r of a.replies) {
+            list.append(el('div', { class: 'ann-reply' },
+              el('div', { class: 'ann-reply-head' }, chip(r.author), timeEl(r.createdAt)),
+              el('div', { class: 'ann-reply-text' }, r.text)
+            ));
+          }
+          thread.append(list);
+        }
+        const input = el('input', { class: 'ann-reply-input', type: 'text', placeholder: 'Reply…', 'aria-label': 'Reply' });
+        const btn = el('button', { class: 'ann-reply-btn', type: 'button' }, 'Reply');
+        const submitReply = () => {
+          const text = input.value.trim();
+          if (!text) return;
+          addReply(a.id, text);
+          renderExisting();
+        };
+        btn.addEventListener('click', submitReply);
+        input.addEventListener('keydown', (e) => {
+          if (e.key === 'Enter' && !e.metaKey && !e.ctrlKey) {
+            e.preventDefault();
+            submitReply();
+          }
+        });
+        thread.append(el('div', { class: 'ann-reply-form' }, input, btn));
+        existingWrap.append(thread);
       }
     };
     renderExisting();
@@ -278,6 +335,23 @@
       target: info.target,
       text,
       createdAt: new Date().toISOString(),
+      author: 'user',
+      replies: [],
+    });
+    changed();
+  }
+
+  // Append a user reply to a top-level annotation's thread (cap 50, like the
+  // server). Empty text is ignored by callers.
+  function addReply(id, text) {
+    const a = annotations.find((x) => x.id === id);
+    if (!a) return;
+    if (!Array.isArray(a.replies)) a.replies = [];
+    if (a.replies.length >= 50) return;
+    a.replies.push({
+      author: 'user',
+      text: String(text).slice(0, 5000),
+      createdAt: new Date().toISOString(),
     });
     changed();
   }
@@ -367,10 +441,18 @@
         e.stopPropagation();
         removeAnnotation(a.id);
       });
+      // Thread meta: reply count, plus an "agent" chip when the latest entry
+      // in the thread (last reply, or the comment itself) is agent-authored.
+      const replyCount = Array.isArray(a.replies) ? a.replies.length : 0;
+      const latest = replyCount ? a.replies[replyCount - 1] : a;
+      const meta = [];
+      if (replyCount) meta.push(el('span', { class: 'ann-sum-replies' }, `${replyCount} ${replyCount === 1 ? 'reply' : 'replies'}`));
+      if (latest.author === 'agent') meta.push(chip('agent'));
       const row = el('div', { class: 'ann-sum-row' },
         el('div', { class: 'ann-sum-main' },
           el('div', { class: 'ann-sum-target' }, humanize(a.target)),
-          el('div', { class: 'ann-sum-text' }, a.text)
+          el('div', { class: 'ann-sum-text' }, a.text),
+          meta.length ? el('div', { class: 'ann-sum-meta' }, meta) : null
         ),
         del
       );
@@ -393,7 +475,22 @@
   // ---------- public API ----------
   function init(opts = {}) {
     ensureDom();
-    annotations = Array.isArray(opts.initial) ? opts.initial.map((a) => ({ ...a })) : [];
+    // Normalize threads: missing author -> 'user', missing replies -> [].
+    annotations = Array.isArray(opts.initial)
+      ? opts.initial.map((a) => ({
+          ...a,
+          author: a.author === 'agent' ? 'agent' : 'user',
+          replies: Array.isArray(a.replies)
+            ? a.replies
+                .filter((r) => r && typeof r === 'object' && typeof r.text === 'string')
+                .map((r) => ({
+                  author: r.author === 'agent' ? 'agent' : 'user',
+                  text: r.text,
+                  createdAt: typeof r.createdAt === 'string' ? r.createdAt : '',
+                }))
+            : [],
+        }))
+      : [];
     onChange = typeof opts.onChange === 'function' ? opts.onChange : null;
     idCounter = 0;
     for (const a of annotations) {
@@ -404,7 +501,32 @@
     renderSummaries();
   }
 
+  // Remove every floating element (pin, badges, popover, selection button)
+  // and stop reacting — called when the board reaches its submitted screen so
+  // nothing leaks over it (they live on <body> with elevated z-index).
+  let torndown = false;
+  function teardown() {
+    torndown = true;
+    try {
+      closePopover();
+    } catch {
+      // popover may not be open
+    }
+    hidePin();
+    hideSelBtn();
+    for (const b of badges) b.remove();
+    badges = [];
+    registered = [];
+    if (dom) {
+      dom.pin.remove();
+      dom.selBtn.remove();
+      dom.pop.remove();
+      dom = null;
+    }
+  }
+
   function register(targetEl, info) {
+    if (torndown) return;
     ensureDom();
     targetEl.classList.add('ann-target');
     const entry = { el: targetEl, info };
@@ -415,14 +537,17 @@
   }
 
   function enableTextSelection(rootEl, baseInfo) {
+    if (torndown) return;
     ensureDom();
     rootEl.addEventListener('mouseup', () => {
+      if (torndown) return;
       // defer: the selection settles after mouseup
       setTimeout(() => maybeShowSelBtn(rootEl, baseInfo), 0);
     });
   }
 
   function openExternal(info, anchorEl) {
+    if (torndown) return;
     openPopover(info, anchorEl);
   }
 
@@ -436,5 +561,5 @@
     renderSummaryInto(target);
   }
 
-  window.RelayAnnotate = { init, register, enableTextSelection, openExternal, list, renderSummary };
+  window.RelayAnnotate = { init, register, enableTextSelection, openExternal, list, renderSummary, teardown };
 })();