@khanglvm/relay 0.14.2 → 0.16.0

package/src/spec.js

@@ -853,6 +853,7 @@ export function normalizeSpec(raw, { cwd = process.cwd() } = {}) {
     allowPartial: raw.allowPartial !== false,
     note: raw.note !== false,
     autoClose: raw.autoClose !== false,
+    responseRequired: raw.responseRequired !== false,
     questions: [],
     submitLabel: '',
   };
@@ -997,6 +998,9 @@ export function normalizeSpec(raw, { cwd = process.cwd() } = {}) {
   if (!spec.questions.length && !spec.blocks.length) {
     throw new CliError('Spec needs "questions" and/or "blocks"/"html" — nothing to show.');
   }
+  if (!spec.responseRequired && spec.questions.length) {
+    throw new CliError('responseRequired:false is display-only and cannot contain questions. Use responseRequired:true when answers are needed.');
+  }
   spec.submitLabel = asStr(raw.submitLabel).trim() || (spec.questions.length ? 'Submit' : 'Acknowledge');
   return spec;
 }
@@ -1126,6 +1130,7 @@ export const SPEC_SCHEMA = {
     allowPartial: { type: 'boolean', default: true, description: 'When true, users may submit with unanswered questions (returned in "skipped").' },
     note: { type: 'boolean', default: true, description: 'Show an optional free-text note box ("Anything else?") returned as "comment".' },
     autoClose: { type: 'boolean', default: true, description: 'Try to close the browser tab automatically after submit.' },
+    responseRequired: { type: 'boolean', default: true, description: 'Set false for a display-only board: no questions, note box, comments, or Submit/Acknowledge action are shown, and the presenting agent should continue immediately.' },
     submitLabel: { type: 'string', description: 'Submit button label. Defaults: "Submit", or "Acknowledge" when there are no questions.' },
     questions: {
       type: 'array',

package/src/store.js

@@ -1,6 +1,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import os from 'node:os';
+import crypto from 'node:crypto';
 
 // All state lives under one dir so multiple boards/instances never collide.
 // RLY_HOME override exists for tests and sandboxed agents.
@@ -21,6 +22,19 @@ export function newId() {
 
 const boardPath = (id) => path.join(BOARDS_DIR, `${id}.json`);
 const runningPath = (id) => path.join(RUNNING_DIR, `${id}.json`);
+export const artifactDirPath = (id) => path.join(BOARDS_DIR, `${id}.artifacts`);
+
+export function saveBoardArtifact(id, bytes, ext = 'png') {
+  ensureDirs();
+  if (!/^b-[a-z0-9]+$/i.test(String(id))) throw new Error('invalid board id');
+  const cleanExt = /^(?:png|jpe?g|webp)$/i.test(String(ext)) ? String(ext).toLowerCase() : 'png';
+  const dir = artifactDirPath(id);
+  fs.mkdirSync(dir, { recursive: true });
+  const file = `region-${Date.now().toString(36)}-${crypto.randomBytes(4).toString('hex')}.${cleanExt}`;
+  const target = path.join(dir, file);
+  fs.writeFileSync(target, bytes);
+  return target;
+}
 
 export function createBoard(spec) {
   ensureDirs();
@@ -72,6 +86,7 @@ export function deleteBoard(id) {
   try {
     fs.unlinkSync(boardPath(id));
     try { fs.unlinkSync(path.join(BOARDS_DIR, `${id}.result.json`)); } catch { /* no sidecar */ }
+    try { fs.rmSync(artifactDirPath(id), { recursive: true, force: true }); } catch { /* no artifacts */ }
     return true;
   } catch {
     return false;

package/src/ui/annotate.js

@@ -48,6 +48,11 @@
         return truncate(t.label || 'Image', 50);
       case 'image-point':
         return (t.label ? truncate(t.label, 30) + ' · ' : 'Image · ') + 'pin ' + Math.round((t.x || 0) * 100) + '%, ' + Math.round((t.y || 0) * 100) + '%';
+      case 'image-region': {
+        const source = t.side ? t.side.charAt(0).toUpperCase() + t.side.slice(1) + ' · ' : '';
+        const area = `${Math.round((t.w || 0) * 100)}×${Math.round((t.h || 0) * 100)}% area`;
+        return (t.label ? truncate(t.label, 30) + ' · ' : 'Image · ') + source + area;
+      }
       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)}”`;
@@ -109,8 +114,10 @@
   let pinTimer = null;
   let pinEntry = null;
   let popOpen = false;
-  let popScrollY = 0;
   let popSave = null;
+  let popAnchorEl = null;
+  let popPositionFrame = 0;
+  const commentDrafts = new Map();
   // Frozen by the host (e.g. relay's connection-lost block): suppress every way
   // to START a comment, so the user can't type feedback that won't be saved.
   let disabled = false;
@@ -341,16 +348,21 @@
     });
 
     // Capture-phase: also fires for nested scroll containers (mermaid pane…).
+    // Keep an open composer re-anchored instead of closing it: scrolling is a
+    // normal review action, and DOM-only draft text must never disappear merely
+    // because the user looked elsewhere on the board.
     window.addEventListener('scroll', (e) => {
       hidePin();
       hideSelBtn();
       if (!popOpen) return;
       if (dom.pop.contains(e.target)) return; // textarea scrolling inside
-      const isPage = e.target === document || e.target === document.documentElement || e.target === document.body;
-      if (!isPage || Math.abs(window.scrollY - popScrollY) > 80) closePopover();
+      schedulePositionPopover();
     }, true);
 
-    window.addEventListener('resize', scheduleBadgeRefresh);
+    window.addEventListener('resize', () => {
+      scheduleBadgeRefresh();
+      schedulePositionPopover();
+    });
   }
 
   // ---------- comments rail ----------
@@ -393,7 +405,7 @@
 
   // ---------- hover pin ----------
   function showPin(entry) {
-    if (disabled) return;
+    if (disabled || !permissions.add) return;
     clearTimeout(pinTimer);
     pinEntry = entry;
     const rect = entry.el.getBoundingClientRect();
@@ -491,10 +503,33 @@
   }
 
   // ---------- popover ----------
+  function positionPopover() {
+    popPositionFrame = 0;
+    if (!popOpen || !dom || !popAnchorEl || !popAnchorEl.isConnected) return;
+    const pop = dom.pop;
+    const rect = popAnchorEl.getBoundingClientRect();
+    const pw = pop.offsetWidth;
+    const ph = pop.offsetHeight;
+    const left = Math.max(8, Math.min(rect.left, window.innerWidth - pw - 8));
+    let top = rect.bottom + 8;
+    if (top + ph > window.innerHeight - 8 && rect.top - ph - 8 >= 8) top = rect.top - ph - 8;
+    top = Math.max(8, Math.min(top, window.innerHeight - ph - 8));
+    pop.style.left = left + 'px';
+    pop.style.top = top + 'px';
+  }
+
+  function schedulePositionPopover() {
+    if (!popOpen || popPositionFrame) return;
+    popPositionFrame = requestAnimationFrame(positionPopover);
+  }
+
   function closePopover() {
     if (!popOpen) return;
     popOpen = false;
     popSave = null;
+    popAnchorEl = null;
+    if (popPositionFrame) cancelAnimationFrame(popPositionFrame);
+    popPositionFrame = 0;
     dom.pop.style.display = 'none';
     dom.pop.replaceChildren();
   }
@@ -547,6 +582,12 @@
   function openPopover(info, anchorEl) {
     if (disabled) return;
     ensureDom();
+    const hasExisting = matching(info).length > 0;
+    const draftKey = sigOf(info.blockId, info.target);
+    // Read-only viewers can open existing threads from their badges, but a
+    // target with no feedback has nothing to show and must not expose an empty
+    // add-comment dialog.
+    if (!permissions.add && !hasExisting) return;
     closePopover();
     hidePin();
     const pop = dom.pop;
@@ -586,7 +627,10 @@
           ta.focus();
         });
         // agent replies aren't editable here — only the top-level user comment
-        const actions = el('div', { class: 'ann-thread-actions' }, a.author === 'user' ? edit : null, del);
+        const actions = el('div', { class: 'ann-thread-actions' },
+          permissions.edit && a.author === 'user' ? edit : null,
+          permissions.delete ? del : null
+        );
         const thread = el('div', { class: 'ann-thread' },
           el('div', { class: 'ann-thread-head' }, chip(a.author), timeEl(a.createdAt), actions),
           textEl
@@ -616,7 +660,7 @@
             submitReply();
           }
         });
-        thread.append(el('div', { class: 'ann-reply-form' }, input, btn));
+        if (permissions.reply) thread.append(el('div', { class: 'ann-reply-form' }, input, btn));
         existingWrap.append(thread);
       }
     };
@@ -624,35 +668,37 @@
     pop.append(existingWrap);
 
     const ta = el('textarea', { class: 'ann-ta', placeholder: 'Add a comment…', rows: '3' });
+    ta.value = commentDrafts.get(draftKey) || '';
+    ta.addEventListener('input', () => {
+      if (ta.value) commentDrafts.set(draftKey, ta.value);
+      else commentDrafts.delete(draftKey);
+    });
     const save = el('button', { class: 'ann-save', type: 'button' }, 'Save');
     const cancel = el('button', { class: 'ann-cancel', type: 'button' }, 'Cancel');
     popSave = () => {
       const text = ta.value.trim();
       if (text) addAnnotation(info, text);
+      commentDrafts.delete(draftKey);
       closePopover();
     };
     save.addEventListener('click', () => popSave && popSave());
-    cancel.addEventListener('click', closePopover);
-    pop.append(ta, el('div', { class: 'ann-pop-actions' }, save, cancel));
+    cancel.addEventListener('click', () => {
+      commentDrafts.delete(draftKey);
+      closePopover();
+    });
+    if (permissions.add) pop.append(ta, el('div', { class: 'ann-pop-actions' }, save, cancel));
 
-    // Position: prefer below the anchor, flip above when out of room,
-    // clamp to the viewport with an 8px margin. Fixed positioning, so we
-    // recompute on open and simply close on big scrolls.
+    // Position: prefer below the anchor, flip above when out of room, and clamp
+    // to the viewport. Scroll/resize re-run this through one animation frame so
+    // the composer tracks browser scrolling smoothly without losing its draft.
     pop.style.display = 'block';
     pop.style.visibility = 'hidden';
-    const rect = anchorEl.getBoundingClientRect();
-    const pw = pop.offsetWidth;
-    const ph = pop.offsetHeight;
-    const left = Math.max(8, Math.min(rect.left, window.innerWidth - pw - 8));
-    let top = rect.bottom + 8;
-    if (top + ph > window.innerHeight - 8 && rect.top - ph - 8 >= 8) top = rect.top - ph - 8;
-    top = Math.max(8, Math.min(top, window.innerHeight - ph - 8));
-    pop.style.left = left + 'px';
-    pop.style.top = top + 'px';
-    pop.style.visibility = '';
     popOpen = true;
-    popScrollY = window.scrollY;
-    ta.focus();
+    popAnchorEl = anchorEl;
+    positionPopover();
+    pop.style.visibility = '';
+    if (permissions.add) ta.focus();
+    else popClose.focus();
   }
 
   // ---------- mutations ----------
@@ -742,7 +788,7 @@
   }
 
   function maybeShowSelBtn(rootEl, baseInfo) {
-    if (disabled) return hideSelBtn();
+    if (disabled || !permissions.add) return hideSelBtn();
     const sel = window.getSelection();
     if (!sel || sel.isCollapsed || !sel.rangeCount) return hideSelBtn();
     if (!rootEl.contains(sel.anchorNode) || !rootEl.contains(sel.focusNode)) return hideSelBtn();
@@ -821,7 +867,7 @@
           el('div', { class: 'ann-sum-text' }, a.text),
           meta.length ? el('div', { class: 'ann-sum-meta' }, meta) : null
         ),
-        del
+        permissions.delete ? del : null
       );
       // Clicking a row jumps to (and flashes) the matching element: a
       // registered block element, or the inline highlight for a text comment.
@@ -912,6 +958,7 @@
     registered = [];
     textRoots.clear();
     highlightMap.clear();
+    commentDrafts.clear();
     if (dom) {
       dom.pin.remove();
       dom.selBtn.remove();

package/src/ui/app.js

@@ -3,6 +3,7 @@
 
   const boot = JSON.parse(document.getElementById('boot').textContent);
   const spec = boot.spec;
+  const responseRequired = spec.responseRequired !== false;
   const access = boot.access || {
     role: 'owner',
     canShare: true,
@@ -11,6 +12,8 @@
     canComment: true,
     canEditComments: true,
     canDeleteComments: true,
+    canEditBlocks: true,
+    canFinalize: true,
   };
   if (access.role) document.documentElement.dataset.accessRole = access.role;
   const QS = spec.questions || [];
@@ -23,8 +26,11 @@
   let seenDraftRev = typeof boot.draftRev === 'number' ? boot.draftRev : 0;
 
   function authHeaders(extra = {}) {
-    return access.token ? { ...extra, 'x-relay-share-token': access.token } : extra;
+    const headers = access.token ? { ...extra, 'x-relay-share-token': access.token } : { ...extra };
+    if (access.reviewSessionId) headers['x-relay-review-session'] = access.reviewSessionId;
+    return headers;
   }
+  const canPersistFeedback = responseRequired && Boolean(access.canEditAnswers || access.canComment || access.canEditBlocks);
 
   // ---------- helpers ----------
   function el(tag, attrs = {}, ...children) {
@@ -133,14 +139,17 @@
   applyFontScale();
 
   // ---------- localStorage draft mirror ----------
-  // Every autosave is ALSO written to localStorage, keyed by board id. This is
+  // Every autosave is ALSO written to localStorage, keyed by board id + access
+  // role/session. This keeps a reviewer side draft from leaking into a
+  // collaborator/read-only tab on the same LAN origin.
   // the durability layer the server file alone can't provide: if the connection
   // drops and the user keeps typing, the in-memory state is mirrored locally, so
   // even a tab reload / browser restart / a freshly opened tab on the same board
   // prefills the LATEST input instead of a blank board or a stale server save.
   // Guards (per design): newest-of-(local,server) wins; the mirror is discarded
   // if the board's spec rev changed (agent edited it); cleared on submit.
-  const LOCAL_DRAFT_KEY = 'relay-draft-' + (boot.boardId || 'unknown');
+  const LOCAL_DRAFT_KEY = 'relay-draft-' + (boot.boardId || 'unknown') + '-' +
+    (access.role || 'owner') + (access.reviewSessionId ? '-' + access.reviewSessionId : '');
   function writeLocalDraft(p, updatedAt) {
     try {
       localStorage.setItem(LOCAL_DRAFT_KEY, JSON.stringify({
@@ -352,7 +361,7 @@
   // to detect recovery from the Retry button / heartbeat.
   async function probeServer() {
     try {
-      const r = await fetch('/api/status', { cache: 'no-store' });
+      const r = await fetch('/api/status', { cache: 'no-store', headers: authHeaders() });
       return r.ok;
     } catch {
       return false;
@@ -407,6 +416,7 @@
     for (const node of app.querySelectorAll('input, textarea, button, select')) {
       node.disabled = false;
     }
+    applyAccessRestrictions();
     if (lostNote) lostNote.remove();
     // Re-arm the heartbeat (it stops itself when it confirms loss) and persist
     // everything typed during the outage. saveDraft() updates the save label.
@@ -454,7 +464,7 @@
   // probe → block. Any success resets it.
   let saveFailures = 0;
   function scheduleSave() {
-    if (submitted) return;
+    if (submitted || !canPersistFeedback) return;
     // Mirror to localStorage SYNCHRONOUSLY on every edit, before (and regardless
     // of) the network save. This is what survives a tab reload / crash / a new
     // tab during a connection outage — it must happen even while blocked.
@@ -465,6 +475,7 @@
     saveTimer = setTimeout(saveDraft, 450);
   }
   async function saveDraft() {
+    if (!canPersistFeedback) return;
     const seq = ++saveSeq;
     // Keep the local mirror current on every flush too (covers programmatic
     // saveDraft() calls that don't go through scheduleSave, e.g. recovery flush).
@@ -516,7 +527,7 @@
     if (submitted) return;
     fetch('/api/ping', {
       method: 'POST',
-      headers: { 'content-type': 'application/json' },
+      headers: authHeaders({ 'content-type': 'application/json' }),
       body: JSON.stringify({
         visible: !document.hidden,
         focused: document.hasFocus(),
@@ -531,7 +542,7 @@
   // RelayAnnotate owns the live annotation list; mirror it into state on every
   // change so payload()/autosave/submit carry it exactly like answers.
   const Annotate = typeof window.RelayAnnotate !== 'undefined' ? window.RelayAnnotate : null;
-  if (Annotate) {
+  if (Annotate && responseRequired) {
     Annotate.init({
       initial: state.annotations,
       permissions: {
@@ -548,6 +559,8 @@
         if (window.__relayBroadcastCounts) window.__relayBroadcastCounts();
       },
     });
+  } else if (Annotate && !responseRequired && typeof Annotate.teardown === 'function') {
+    Annotate.teardown();
   }
 
   // Editable-mermaid: record (or clear) the user's edit for a block, then
@@ -565,16 +578,34 @@
     onBlockEdit(d.blockId, d.value);
   });
 
+  async function saveRegionArtifact(artifact) {
+    const res = await fetch('/api/artifact', {
+      method: 'POST',
+      headers: authHeaders({ 'content-type': 'application/json' }),
+      body: JSON.stringify(artifact),
+    });
+    const body = await res.json().catch(() => null);
+    if (!res.ok || !body || !body.path) throw new Error(body && body.error ? body.error : 'could not save image crop');
+    return body;
+  }
+
   // ctx for RelayBlocks.render — theme()/htmlSrc per the shared contract, plus
   // the editable-mermaid plumbing (edits map + onBlockEdit callback).
   function blockCtx(questionId) {
     return {
       theme: effectiveTheme,
-      htmlSrc: (blockId) => '/html/b/' + encodeURIComponent(blockId) + '?theme=' + effectiveTheme(),
+      htmlSrc: (blockId) => {
+        const params = new URLSearchParams({ theme: effectiveTheme() });
+        if (access.token) params.set('token', access.token);
+        return '/html/b/' + encodeURIComponent(blockId) + '?' + params.toString();
+      },
       questionId: questionId == null ? null : questionId,
-      annotate: Annotate,
+      annotate: responseRequired ? Annotate : null,
+      canComment: responseRequired && access.canComment !== false,
+      saveArtifact: responseRequired && access.canComment !== false ? saveRegionArtifact : null,
       edits: state.blockEdits,
       onBlockEdit,
+      canEditBlocks: access.canEditBlocks !== false,
     };
   }
 
@@ -807,6 +838,7 @@
     const byVal = new Map(q.options.map((o) => [o.value, o]));
     let dragFrom = null;
     function move(from, to) {
+      if (!access.canEditAnswers) return;
       const arr = state.answers[q.id];
       if (!Array.isArray(arr) || to < 0 || to >= arr.length || from === to) return;
       const [x] = arr.splice(from, 1);
@@ -827,7 +859,7 @@
         down.disabled = i === order.length - 1;
         up.addEventListener('click', () => move(i, i - 1));
         down.addEventListener('click', () => move(i, i + 1));
-        const item = el('div', { class: 'rank-item', draggable: 'true' },
+        const item = el('div', { class: 'rank-item', draggable: access.canEditAnswers ? 'true' : 'false' },
           el('span', { class: 'rank-badge', 'aria-hidden': 'true' }, String(i + 1)),
           el('div', { class: 'rank-body' },
             el('div', { class: 'ol' }, o.label),
@@ -835,6 +867,7 @@
           el('div', { class: 'rank-ctrls' }, up, down)
         );
         item.addEventListener('dragstart', (e) => {
+          if (!access.canEditAnswers) { e.preventDefault(); return; }
           dragFrom = i; item.classList.add('dragging');
           try { e.dataTransfer.effectAllowed = 'move'; e.dataTransfer.setData('text/plain', String(i)); } catch (_) {}
         });
@@ -1127,7 +1160,7 @@
     app.append(card);
   });
 
-  if (spec.note) {
+  if (spec.note && responseRequired) {
     const note = el('textarea', { placeholder: 'optional note back to the agent…' });
     note.value = state.comment || '';
     note.addEventListener('input', () => {
@@ -1149,6 +1182,10 @@
   const hint = el('span', { class: 'hint' },
     QS.length && spec.allowPartial ? 'Unanswered questions are returned as skipped.' : '');
   const submitbar = el('div', { class: 'submitbar' }, submitBtn, hint, saveEl);
+  if (!responseRequired) {
+    submitbar.replaceChildren(el('span', { class: 'hint' }, 'Display only · no response requested'));
+    submitbar.classList.add('display-only');
+  }
   app.append(submitbar);
 
   function copyText(text, btn) {
@@ -1182,7 +1219,11 @@
       ),
       el('button', { class: 'share-choice', type: 'button', 'data-role': 'review' },
         el('span', { class: 'share-choice-title' }, 'Reviewer'),
-        el('span', { class: 'share-choice-sub' }, 'Can add comments only. No submit, answer edits, edit, or delete.')
+        el('span', { class: 'share-choice-sub' }, 'Can answer, comment, and submit a reference-only side review. Does not finalize the board.')
+      ),
+      el('button', { class: 'share-choice', type: 'button', 'data-role': 'read' },
+        el('span', { class: 'share-choice-title' }, 'Read only'),
+        el('span', { class: 'share-choice-sub' }, 'Can view the board and existing feedback. Cannot answer, comment, edit, or submit.')
       ),
       el('div', { class: 'share-result' })
     );
@@ -1207,7 +1248,7 @@
           const copy = el('button', { class: 'share-copy', type: 'button' }, 'Copy link');
           copy.addEventListener('click', () => copyText(body.url, copy));
           result.replaceChildren(
-            el('div', { class: 'share-ready' }, role === 'collab' ? 'Collaborator link active' : 'Reviewer link active'),
+            el('div', { class: 'share-ready' }, role === 'collab' ? 'Collaborator link active' : role === 'review' ? 'Reviewer link active' : 'Read-only link active'),
             el('a', { class: 'share-url', href: body.url, target: '_blank', rel: 'noreferrer' }, body.url),
             copy
           );
@@ -1226,18 +1267,33 @@
     return footer;
   }
 
-  if (!access.canSubmit) {
-    submitbar.style.display = 'none';
-    showNotice('Reviewer mode: comments are saved live. Answers and submission are disabled.', 'info');
-  } else if (access.role === 'collab') {
-    showNotice('Editor mode: answers, comments, and submit are enabled for this shared board.', 'info');
-  }
-  if (!access.canEditAnswers) {
-    document.documentElement.classList.add('relay-review');
-    for (const node of app.querySelectorAll('.card input, .card textarea, .card button, .card select')) {
-      node.disabled = true;
+  function applyAccessRestrictions() {
+    if (!access.canSubmit) submitbar.style.display = 'none';
+    if (!access.canEditAnswers) {
+      for (const node of app.querySelectorAll('.card input, .card textarea, .card button, .card select')) {
+        // Viewer controls inside question/option blocks remain useful in a
+        // read-only board (zoom, fit, full-screen, filtering, diff view). Block
+        // mutation controls are independently gated by canEditBlocks.
+        if (node.closest('.blocks')) continue;
+        node.disabled = true;
+      }
+      for (const item of app.querySelectorAll('.rank-item')) {
+        item.draggable = false;
+        item.setAttribute('aria-disabled', 'true');
+      }
     }
+    document.documentElement.classList.toggle('relay-review', access.canEditComments === false || access.canDeleteComments === false);
+  }
+  if (access.role === 'review') {
+    submitBtn.textContent = 'Submit side review';
+    hint.textContent = 'Reference only — the owner still submits the final answer.';
+    showNotice('Reviewer mode: your answers and comments are saved separately as a reference-only side review. Submitting here does not finalize the board or notify the waiting agent.', 'info');
+  } else if (access.role === 'read') {
+    showNotice('Read-only mode: you can view the board and existing feedback, but answers, comments, edits, and submission are disabled.', 'info');
+  } else if (access.role === 'collab') {
+    showNotice('Editor mode: answers, comments, and final submission are enabled for this shared board.', 'info');
   }
+  applyAccessRestrictions();
   app.append(buildFooter());
 
   // ---------- validation & submit ----------
@@ -1253,7 +1309,7 @@
     return !firstBad;
   }
 
-  function showDone(closing) {
+  function showDone(closing, sideReview = false) {
     stopHeartbeat();
     // Annotation pins/badges/popover float on <body> with elevated z-index —
     // remove them so they don't leak over the submitted screen.
@@ -1267,7 +1323,9 @@
     // If the agent already stopped waiting (soft timeout / dropped connection),
     // the submission won't be picked up automatically — tell the user to nudge
     // the agent. Otherwise the normal hand-back copy applies.
-    const note = handedBack
+    const note = sideReview
+      ? 'Saved for reference. This did not finalize the board or notify the waiting agent; the owner still needs to submit the final answer.'
+      : handedBack
       ? 'Saved. Your agent had stopped waiting — send it a message so it picks up your answers.'
       : closing
         ? 'Handing back to your agent — this tab will close itself…'
@@ -1275,7 +1333,7 @@
     app.replaceChildren(
       el('div', { class: 'done' },
         el('div', { class: 'mark' }, '✓'),
-        el('h2', {}, QS.length ? 'Submitted' : 'Acknowledged'),
+        el('h2', {}, sideReview ? 'Side review saved' : QS.length ? 'Submitted' : 'Acknowledged'),
         el('p', { id: 'done-note' }, note)
       )
     );
@@ -1302,14 +1360,16 @@
         throw netErr;
       }
       if (!res.ok) throw new Error('submit rejected');
+      const submitResult = await res.json().catch(() => null);
+      const sideReview = Boolean(submitResult && submitResult.sideReview === true && submitResult.final === false);
       submitted = true;
       // Submitted successfully → the local mirror is no longer needed and would
       // otherwise resurrect stale answers on a future reopen. Clear it.
       clearLocalDraft();
       // Don't auto-close when the agent had stopped waiting — the user needs to
       // read the "send your agent a message" note and act on it.
-      const autoClose = spec.autoClose && !handedBack;
-      showDone(autoClose);
+      const autoClose = !sideReview && spec.autoClose && !handedBack;
+      showDone(autoClose, sideReview);
       if (autoClose) {
         setTimeout(() => {
           window.close();
@@ -1324,7 +1384,7 @@
     } catch {
       // Restore the button so the user can retry.
       submitBtn.disabled = false;
-      submitBtn.textContent = spec.submitLabel;
+      submitBtn.textContent = access.role === 'review' ? 'Submit side review' : spec.submitLabel;
       if (!reached) {
         // The connection is gone — the submit (and any further input) can't be
         // persisted. Block hard so the user stops adding feedback that would be
@@ -1362,7 +1422,7 @@
   // the server had nothing — e.g. a freshly reopened board the user had typed
   // into in another tab during an outage), the server doesn't yet have this
   // input. Flush it once so a brand-new tab's view is also the server's truth.
-  if (initialPrefill && initialPrefill.__from === 'local' && !submitted) {
+  if (initialPrefill && initialPrefill.__from === 'local' && !submitted && canPersistFeedback) {
     saveDraft();
   }
 
@@ -1374,7 +1434,7 @@
   //   parent → {relay:'annotate-counts', counts:{ref:n}}     it draws badges
   // We own the annotation state, popover, and the submitted result; the iframe
   // owns hover/pin/badges over its own (cross-origin) DOM.
-  if (Annotate) {
+  if (Annotate && responseRequired) {
     const frameOf = (source) => {
       for (const f of document.querySelectorAll('iframe.viz')) {
         if (f.contentWindow === source) return f;
@@ -1456,7 +1516,7 @@
     // Piggyback presence on the heartbeat (best-effort; no-ops after submit).
     pingPresence();
     try {
-      const r = await fetch('/api/status', { cache: 'no-store' });
+      const r = await fetch('/api/status', { cache: 'no-store', headers: authHeaders() });
       if (!r.ok) throw new Error('bad status');
       misses = 0;
       // The heartbeat reaching the server is itself proof persistence is back —
@@ -1476,10 +1536,14 @@
       // user knows to prompt the agent after submitting.
       if (body && body.softTimedOut && !submitted) {
         handedBack = true;
-        showNotice(
-          'You’ve had this open a while, so the agent stopped waiting. Your changes save automatically — submit when you’re ready, then prompt the agent to pick them up.',
-          'info'
-        );
+        if (access.role === 'review') {
+          showNotice('This remains a reference-only side review. Submit when ready; the owner still needs to provide the final answer.', 'info');
+        } else if (access.role !== 'read') {
+          showNotice(
+            'You’ve had this open a while, so the agent stopped waiting. Your changes save automatically — submit when you’re ready, then prompt the agent to pick them up.',
+            'info'
+          );
+        }
       }
       if (body && typeof body.rev === 'number' && bootRev !== null && body.rev !== bootRev && !submitted && !reloading) {
         // Don't yank the board out from under someone mid-comment: an open