npm - @khanglvm/relay - Versions diffs - 0.14.2 → 0.16.0 - Mend

@khanglvm/relay 0.14.2 → 0.16.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (14) hide show

package/src/server.js CHANGED Viewed

@@ -5,13 +5,28 @@ 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 {
+  loadBoard,
+  saveBoard,
+  saveRunning,
+  removeRunning,
+  loadPref,
+  savePref,
+  saveBoardArtifact,
+  artifactDirPath,
+} from './store.js';
 import { openUrl } from './open.js';
 import { assertSpecReady } from './spec.js';
 const UI_DIR = path.join(path.dirname(fileURLToPath(import.meta.url)), 'ui');
 const PKG_ROOT = path.join(path.dirname(fileURLToPath(import.meta.url)), '..');
 const VENDOR_DIR = path.join(PKG_ROOT, 'vendor');
+const ARTIFACT_MAX_BYTES = 4 * 1024 * 1024;
+const ARTIFACT_MIMES = {
+  'image/png': 'png',
+  'image/jpeg': 'jpg',
+  'image/webp': 'webp',
+};
 const escapeHtml = (s) =>
   s.replace(/[&<>"']/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' }[c]));
@@ -162,17 +177,24 @@ function buildPage(record, rev, { access = null, draftRev = 0 } = {}) {
   };
   // 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.
-  const prefill = record.draft
+  // Reviewer answers are an independent, reference-only draft. They must never
+  // prefill from or overwrite the owner's final-answer draft. Read-only viewers
+  // see the owner's current state but cannot mutate it.
+  const reviewDrafts = record.reviewDrafts && typeof record.reviewDrafts === 'object' ? record.reviewDrafts : {};
+  const sourceDraft = access && access.role === 'review'
+    ? (reviewDrafts[access.reviewSessionId] || null)
+    : record.draft;
+  const prefill = sourceDraft
     ? {
-        answers: record.draft.answers || {},
-        comment: record.draft.comment || '',
-        notes: record.draft.notes || {},
-        annotations: record.draft.annotations || [],
-        blockEdits: record.draft.blockEdits || {},
+        answers: sourceDraft.answers || {},
+        comment: sourceDraft.comment || '',
+        notes: sourceDraft.notes || {},
+        annotations: sourceDraft.annotations || [],
+        blockEdits: sourceDraft.blockEdits || {},
         // The server draft's save time, so the client can pick the NEWER of this
         // vs. its localStorage mirror (a tab that kept typing while the server
         // was unreachable holds fresher input than the last server save).
-        updatedAt: record.draft.updatedAt || null,
+        updatedAt: sourceDraft.updatedAt || null,
       }
     : null;
   const boot = { boardId: record.id, spec: clientSpec, prefill, pref: loadPref(), vendor, rev, draftRev, access };
@@ -196,6 +218,45 @@ function buildLockedPage(title = 'Relay board') {
     '</head><body><div class="box"><div class="title">Share link not active</div><div class="sub">Ask the board owner to use Share and choose a permission before opening this board from another device.</div></div></body></html>';
 }
+const SHARE_STATE_VERSION = 2;
+const REVIEW_SESSION_COOKIE = 'relay_review_session';
+function reviewSessionId(req) {
+  if (req._relayReviewSessionId) return req._relayReviewSessionId;
+  const explicit = String(req.headers['x-relay-review-session'] || '');
+  const cookies = String(req.headers.cookie || '').split(';').map((s) => s.trim());
+  const cookie = cookies.find((s) => s.startsWith(REVIEW_SESSION_COOKIE + '='));
+  let value = explicit || (cookie ? decodeURIComponent(cookie.slice(REVIEW_SESSION_COOKIE.length + 1)) : '');
+  if (!/^[A-Za-z0-9_-]{8,80}$/.test(value)) value = 'rv-' + crypto.randomBytes(12).toString('hex');
+  req._relayReviewSessionId = value;
+  return value;
+}
+function reviewSessionCookie(sessionId) {
+  return `${REVIEW_SESSION_COOKIE}=${encodeURIComponent(sessionId)}; Path=/; HttpOnly; SameSite=Strict; Max-Age=2592000`;
+}
+function sideReviewState(record) {
+  const drafts = record.reviewDrafts && typeof record.reviewDrafts === 'object' ? record.reviewDrafts : {};
+  const submissions = Array.isArray(record.sideReviews) ? record.sideReviews : [];
+  return {
+    referenceOnly: true,
+    note: 'Side reviews are reference only. Wait for the board owner (or owner-authorized collaborator) to submit the final answer.',
+    submissions,
+    drafts,
+  };
+}
+function pruneReviewDrafts(record, max = 50) {
+  const drafts = record.reviewDrafts && typeof record.reviewDrafts === 'object' ? record.reviewDrafts : {};
+  const entries = Object.entries(drafts).sort((a, b) => {
+    const at = Date.parse(a[1] && a[1].updatedAt || '') || 0;
+    const bt = Date.parse(b[1] && b[1].updatedAt || '') || 0;
+    return bt - at;
+  });
+  record.reviewDrafts = Object.fromEntries(entries.slice(0, max));
+}
 // Validates + sanitizes one annotation's threaded replies. Keeps only
 // well-formed {author, text, createdAt} entries; caps at 50; coerces author.
 function sanitizeReplies(value) {
@@ -216,7 +277,51 @@ function sanitizeReplies(value) {
 // 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) {
+function sanitizeAnnotationCrop(value, boardId) {
+  if (!value || typeof value !== 'object' || Array.isArray(value) || !boardId) return null;
+  const rawPath = typeof value.path === 'string' ? value.path : '';
+  if (!rawPath) return null;
+  const base = path.resolve(artifactDirPath(boardId)) + path.sep;
+  const resolved = path.resolve(rawPath);
+  if (!resolved.startsWith(base)) return null;
+  let stat;
+  try { stat = fs.statSync(resolved); } catch { return null; }
+  if (!stat.isFile() || stat.size < 1 || stat.size > ARTIFACT_MAX_BYTES) return null;
+  const mime = ARTIFACT_MIMES[value.mime] ? value.mime : 'image/png';
+  return {
+    path: resolved,
+    name: path.basename(resolved),
+    mime,
+    bytes: stat.size,
+    width: Math.max(1, Math.min(10000, Number.parseInt(value.width, 10) || 1)),
+    height: Math.max(1, Math.min(10000, Number.parseInt(value.height, 10) || 1)),
+  };
+}
+function sanitizeAnnotationTarget(value, boardId) {
+  const clean = { ...value };
+  delete clean.cropDataUrl;
+  if (clean.kind !== 'image-region') {
+    delete clean.crop;
+    return clean;
+  }
+  const unit = (v) => Math.max(0, Math.min(1, Number(v) || 0));
+  clean.x = unit(clean.x);
+  clean.y = unit(clean.y);
+  clean.w = unit(clean.w);
+  clean.h = unit(clean.h);
+  if (clean.x + clean.w > 1) clean.w = 1 - clean.x;
+  if (clean.y + clean.h > 1) clean.h = 1 - clean.y;
+  clean.label = limitString(clean.label, 200);
+  if (clean.side === 'before' || clean.side === 'after') clean.side = clean.side;
+  else delete clean.side;
+  const crop = sanitizeAnnotationCrop(clean.crop, boardId);
+  if (crop) clean.crop = crop;
+  else delete clean.crop;
+  return clean;
+}
+function sanitizeAnnotations(value, boardId) {
   if (!Array.isArray(value)) return [];
   const out = [];
   for (const a of value) {
@@ -224,57 +329,17 @@ 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;
-    const clean = { ...a, author: a.author === 'agent' ? 'agent' : 'user' };
+    const clean = {
+      ...a,
+      target: sanitizeAnnotationTarget(a.target, boardId),
+      author: a.author === 'agent' ? 'agent' : 'user',
+    };
     if (a.replies !== undefined) clean.replies = sanitizeReplies(a.replies);
     out.push(clean);
   }
   return out;
 }
-function nextAnnotationId(existing, used) {
-  let max = 0;
-  for (const a of existing) {
-    const m = /^a(\d+)$/.exec(String(a && a.id || ''));
-    if (m) max = Math.max(max, Number.parseInt(m[1], 10) || 0);
-  }
-  let id;
-  do {
-    id = 'a' + (++max);
-  } while (used.has(id));
-  used.add(id);
-  return id;
-}
-function sameReply(a, b) {
-  return a && b && a.author === b.author && a.text === b.text && a.createdAt === b.createdAt;
-}
-function mergeReviewAnnotations(existingValue, incomingValue) {
-  const existing = sanitizeAnnotations(existingValue);
-  const incoming = sanitizeAnnotations(incomingValue);
-  const out = existing.map((a) => ({ ...a, replies: Array.isArray(a.replies) ? [...a.replies] : [] }));
-  const byId = new Map(out.map((a) => [String(a.id || ''), a]));
-  const used = new Set(out.map((a) => String(a.id || '')).filter(Boolean));
-  for (const ann of incoming) {
-    const id = String(ann.id || '');
-    const current = byId.get(id);
-    if (!current) {
-      const next = { ...ann, id: id && !used.has(id) ? id : nextAnnotationId(out, used) };
-      next.replies = Array.isArray(next.replies) ? next.replies : [];
-      out.push(next);
-      byId.set(next.id, next);
-      used.add(next.id);
-      continue;
-    }
-    const replies = Array.isArray(current.replies) ? current.replies : (current.replies = []);
-    for (const r of Array.isArray(ann.replies) ? ann.replies : []) {
-      if (replies.length >= 50) break;
-      if (!replies.some((x) => sameReply(x, r))) replies.push(r);
-    }
-  }
-  return out.slice(0, 500);
-}
 function limitString(v, max) {
   return typeof v === 'string' ? v.slice(0, max) : '';
 }
@@ -499,8 +564,8 @@ function sendJson(res, code, obj) {
   res.end(JSON.stringify(obj));
 }
-function sendHtml(res, body) {
-  res.writeHead(200, { 'content-type': 'text/html; charset=utf-8', 'cache-control': 'no-store' });
+function sendHtml(res, body, headers = {}) {
+  res.writeHead(200, { 'content-type': 'text/html; charset=utf-8', 'cache-control': 'no-store', ...headers });
   res.end(body);
 }
@@ -597,14 +662,15 @@ function injectBeforeBodyEnd(html, snippet) {
 // Custom-HTML fragments (no <html> tag) get wrapped in a minimal document that
 // matches the user's theme, so e.g. "<b>hi</b>" doesn't paint a stark white
 // block in dark mode. Full documents are served verbatim — their authors can
-// read the ?theme=light|dark query param themselves. Either way the annotate
-// bootstrap is injected so every element is hover-commentable.
-function wrapFragment(content, theme) {
-  if (/<html[\s>]/i.test(content)) return injectBeforeBodyEnd(content, ANNOTATE_BOOTSTRAP);
+// read the ?theme=light|dark query param themselves. The annotate bootstrap is
+// omitted for read-only shares so their iframe content has no false comment
+// affordances; existing feedback remains visible in the parent comments rail.
+function wrapFragment(content, theme, annotate = true) {
+  if (/<html[\s>]/i.test(content)) return annotate ? injectBeforeBodyEnd(content, ANNOTATE_BOOTSTRAP) : content;
   const dark = theme === 'dark';
   const bg = dark ? '#282624' : '#ffffff';
   const fg = dark ? '#edeae4' : '#1c1b19';
-  return `<!doctype html><html><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1"><style>:root{color-scheme:${dark ? 'dark' : 'light'}}body{margin:12px;font:14px/1.5 -apple-system,BlinkMacSystemFont,"Segoe UI",Roboto,"Helvetica Neue",Arial,sans-serif;background:${bg};color:${fg}}</style></head><body>${content}${ANNOTATE_BOOTSTRAP}</body></html>`;
+  return `<!doctype html><html><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1"><style>:root{color-scheme:${dark ? 'dark' : 'light'}}body{margin:12px;font:14px/1.5 -apple-system,BlinkMacSystemFont,"Segoe UI",Roboto,"Helvetica Neue",Arial,sans-serif;background:${bg};color:${fg}}</style></head><body>${content}${annotate ? ANNOTATE_BOOTSTRAP : ''}</body></html>`;
 }
 function readBody(req, limit = 5 * 1024 * 1024) {
@@ -625,6 +691,14 @@ function readBody(req, limit = 5 * 1024 * 1024) {
   });
 }
+function artifactBytesMatch(mime, bytes) {
+  if (!Buffer.isBuffer(bytes) || bytes.length < 4) return false;
+  if (mime === 'image/png') return bytes.subarray(0, 8).equals(Buffer.from([137, 80, 78, 71, 13, 10, 26, 10]));
+  if (mime === 'image/jpeg') return bytes[0] === 0xff && bytes[1] === 0xd8 && bytes[bytes.length - 2] === 0xff && bytes[bytes.length - 1] === 0xd9;
+  if (mime === 'image/webp') return bytes.subarray(0, 4).toString('ascii') === 'RIFF' && bytes.subarray(8, 12).toString('ascii') === 'WEBP';
+  return false;
+}
 // 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) —
@@ -670,7 +744,7 @@ function runOnResult(cmd, result, { quiet = false } = {}) {
 // (submitted / acknowledged / timeout / cancelled). The result is also
 // persisted into the board record so `rly wait` / `rly result` can read it
 // from another process.
-export async function runBoard({ id, port = 0, open = true, timeoutSec = 1800, quiet = false, keepAliveOnTimeout = false }) {
+export async function runBoard({ id, port = 0, open = true, timeoutSec = 86400, quiet = false, keepAliveOnTimeout = false }) {
   const record = loadBoard(id);
   if (!record) throw new Error(`board ${id} not found`);
   const spec = record.spec;
@@ -689,8 +763,17 @@ export async function runBoard({ id, port = 0, open = true, timeoutSec = 1800, q
         updatedAt: new Date().toISOString(),
       };
     }
-    record.pastResults = [...(record.pastResults || []), record.result].slice(-10);
+    // A soft-timeout result may predate side reviews submitted while the board
+    // stayed live. Refresh that reference-only snapshot before archiving so a
+    // later reopen does not discard late reviews/drafts from the historical run.
+    const archivedResult = { ...record.result, sideReviews: sideReviewState(record) };
+    record.pastResults = [...(record.pastResults || []), archivedResult].slice(-10);
     record.result = null;
+    // Side reviews belong to the archived run. A reopened board starts a fresh
+    // review round; carrying them forward would present stale reference input
+    // as current and duplicate it into the next final result.
+    record.sideReviews = [];
+    record.reviewDrafts = {};
     saveBoard(record);
   }
@@ -699,13 +782,20 @@ export async function runBoard({ id, port = 0, open = true, timeoutSec = 1800, q
   // can authenticate to POST /api/update. Never embedded in the page/boot.
   const token = crypto.randomBytes(16).toString('hex');
   const savedShares = record.share && typeof record.share === 'object' ? record.share : {};
+  const savedShareVersion = Number(savedShares.version) || 1;
   const shareTokens = {
     collab: typeof savedShares.collab?.token === 'string' ? savedShares.collab.token : crypto.randomBytes(16).toString('hex'),
-    review: typeof savedShares.review?.token === 'string' ? savedShares.review.token : crypto.randomBytes(16).toString('hex'),
+    // v1 reviewer links were comments-only. Rotate + deactivate them instead of
+    // silently granting answer/side-submit permission after this upgrade.
+    review: savedShareVersion >= SHARE_STATE_VERSION && typeof savedShares.review?.token === 'string'
+      ? savedShares.review.token
+      : crypto.randomBytes(16).toString('hex'),
+    read: typeof savedShares.read?.token === 'string' ? savedShares.read.token : crypto.randomBytes(16).toString('hex'),
   };
   const activeShares = {
     collab: savedShares.collab?.active === true,
-    review: savedShares.review?.active === true,
+    review: savedShareVersion >= SHARE_STATE_VERSION && savedShares.review?.active === true,
+    read: savedShares.read?.active === true,
   };
   let rev = 1;
   let draftRev = Number.isFinite(record.draftRev) ? record.draftRev : 0;
@@ -716,8 +806,9 @@ export async function runBoard({ id, port = 0, open = true, timeoutSec = 1800, q
   // working and still submit. Surfaced via /api/status so the page can show a
   // calm "agent stopped waiting" note instead of disconnecting.
   let softTimedOut = false;
-  // Latest client presence ping (null until the first ping arrives).
-  let presence = null;
+  // Presence that can lead to the terminal answer. Reviewer/read-only activity
+  // must not keep an agent waiting for a submission those roles cannot finalize.
+  const presenceByRole = { owner: null, collab: null, review: null, read: null };
   let actualPort = 0;
   let url = '';
   const advertisedHost = shareHost();
@@ -732,6 +823,8 @@ export async function runBoard({ id, port = 0, open = true, timeoutSec = 1800, q
         canComment: true,
         canEditComments: true,
         canDeleteComments: true,
+        canEditBlocks: true,
+        canFinalize: true,
       };
     }
     const tokenValue = String(req.headers['x-relay-share-token'] || (reqUrl && reqUrl.searchParams.get('token')) || '');
@@ -745,18 +838,37 @@ export async function runBoard({ id, port = 0, open = true, timeoutSec = 1800, q
         canComment: true,
         canEditComments: true,
         canDeleteComments: true,
+        canEditBlocks: true,
+        canFinalize: true,
       };
     }
     if (activeShares.review && tokenValue === shareTokens.review) {
       return {
         role: 'review',
         token: shareTokens.review,
+        reviewSessionId: reviewSessionId(req),
+        canShare: false,
+        canSubmit: true,
+        canEditAnswers: true,
+        canComment: true,
+        canEditComments: false,
+        canDeleteComments: false,
+        canEditBlocks: false,
+        canFinalize: false,
+      };
+    }
+    if (activeShares.read && tokenValue === shareTokens.read) {
+      return {
+        role: 'read',
+        token: shareTokens.read,
         canShare: false,
         canSubmit: false,
         canEditAnswers: false,
-        canComment: true,
+        canComment: false,
         canEditComments: false,
         canDeleteComments: false,
+        canEditBlocks: false,
+        canFinalize: false,
       };
     }
     return {
@@ -767,13 +879,17 @@ export async function runBoard({ id, port = 0, open = true, timeoutSec = 1800, q
       canComment: false,
       canEditComments: false,
       canDeleteComments: false,
+      canEditBlocks: false,
+      canFinalize: false,
     };
   };
   const shareUrlFor = (role) => advertisedHost ? `http://${advertisedHost}:${actualPort}/?share=${role}&token=${shareTokens[role]}` : null;
   const persistShareState = () => {
     record.share = {
+      version: SHARE_STATE_VERSION,
       collab: { active: activeShares.collab === true, token: shareTokens.collab },
       review: { active: activeShares.review === true, token: shareTokens.review },
+      read: { active: activeShares.read === true, token: shareTokens.read },
       updatedAt: new Date().toISOString(),
     };
     saveBoard(record);
@@ -782,6 +898,10 @@ export async function runBoard({ id, port = 0, open = true, timeoutSec = 1800, q
   const done = new Promise((r) => {
     resolveDone = r;
   });
+  const finalizerPresence = () => {
+    const candidates = [presenceByRole.owner, presenceByRole.collab].filter(Boolean);
+    return candidates.sort((a, b) => b.atMs - a.atMs)[0] || null;
+  };
   const server = http.createServer(async (req, res) => {
     const reqUrl = new URL(req.url, 'http://localhost');
@@ -793,17 +913,41 @@ export async function runBoard({ id, port = 0, open = true, timeoutSec = 1800, q
         if (access.role === 'locked') {
           sendHtml(res, buildLockedPage(record.spec.title));
         } else {
-          sendHtml(res, buildPage(record, rev, { access, draftRev }));
+          const accessDraftRev = access.role === 'review'
+            ? Number(record.reviewDrafts?.[access.reviewSessionId]?.draftRev) || 0
+            : draftRev;
+          const headers = access.role === 'review'
+            ? { 'set-cookie': reviewSessionCookie(access.reviewSessionId) }
+            : {};
+          sendHtml(res, buildPage(record, rev, { access, draftRev: accessDraftRev }), headers);
         }
       } else if (req.method === 'GET' && pathname === '/api/board') {
-        if (accessFor(req, reqUrl).role === 'locked') return sendJson(res, 403, { error: 'share link is not active' });
-        sendJson(res, 200, { id: record.id, spec: record.spec, draft: record.draft, result: record.result });
+        const access = accessFor(req, reqUrl);
+        if (access.role === 'locked') return sendJson(res, 403, { error: 'share link is not active' });
+        const sourceDraft = access.role === 'review'
+          ? (record.reviewDrafts?.[access.reviewSessionId] || null)
+          : record.draft;
+        sendJson(res, 200, { id: record.id, spec: record.spec, draft: sourceDraft, result: record.result });
       } else if (req.method === 'GET' && pathname === '/api/status') {
-        sendJson(res, 200, { status, rev, draftRev, softTimedOut });
+        const access = accessFor(req, reqUrl);
+        if (access.role === 'locked') return sendJson(res, 403, { error: 'share link is not active' });
+        const accessDraftRev = access.role === 'review'
+          ? Number(record.reviewDrafts?.[access.reviewSessionId]?.draftRev) || 0
+          : draftRev;
+        sendJson(res, 200, { status, rev, draftRev: accessDraftRev, softTimedOut });
       } else if (req.method === 'GET' && pathname === '/api/draft') {
-        if (accessFor(req, reqUrl).role === 'locked') return sendJson(res, 403, { error: 'share link is not active' });
-        sendJson(res, 200, { draft: record.draft || null, draftRev });
+        const access = accessFor(req, reqUrl);
+        if (access.role === 'locked') return sendJson(res, 403, { error: 'share link is not active' });
+        const sourceDraft = access.role === 'review'
+          ? (record.reviewDrafts?.[access.reviewSessionId] || null)
+          : record.draft;
+        const accessDraftRev = access.role === 'review'
+          ? Number(sourceDraft?.draftRev) || 0
+          : draftRev;
+        sendJson(res, 200, { draft: sourceDraft || null, draftRev: accessDraftRev });
       } else if (req.method === 'POST' && pathname === '/api/ping') {
+        const access = accessFor(req, reqUrl);
+        if (access.role === 'locked') return sendJson(res, 403, { error: 'share link is not active' });
         const body = JSON.parse((await readBody(req)) || '{}');
         // Validate body shape: visible/focused booleans, idleMs finite >= 0.
         if (
@@ -812,10 +956,11 @@ export async function runBoard({ id, port = 0, open = true, timeoutSec = 1800, q
           Number.isFinite(body.idleMs) &&
           body.idleMs >= 0
         ) {
-          presence = { atMs: Date.now(), visible: body.visible, focused: body.focused, idleMs: body.idleMs };
+          presenceByRole[access.role] = { 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') {
+        const presence = finalizerPresence();
         if (!presence) {
           sendJson(res, 200, { open: true, seen: false });
         } else {
@@ -858,7 +1003,8 @@ export async function runBoard({ id, port = 0, open = true, timeoutSec = 1800, q
         const blockId = decodeURIComponent(pathname.slice('/html/b/'.length));
         const block = findHtmlBlock(record.spec, blockId);
         if (!block) return sendJson(res, 404, { error: `no html block "${blockId}"` });
-        sendHtml(res, wrapFragment(block.html || '', theme));
+        const access = accessFor(req, reqUrl);
+        sendHtml(res, wrapFragment(block.html || '', theme, access.canComment === true && record.spec.responseRequired !== false));
       } else if (req.method === 'GET' && pathname.startsWith('/img/b/')) {
         // Embedded image bytes (image blocks authored from local files).
         const blockId = decodeURIComponent(pathname.slice('/img/b/'.length));
@@ -867,6 +1013,32 @@ export async function runBoard({ id, port = 0, open = true, timeoutSec = 1800, q
         if (!m) return sendJson(res, 404, { error: `no embedded image block "${blockId}"` });
         res.writeHead(200, { 'content-type': m[1], 'cache-control': 'no-store' });
         res.end(Buffer.from(m[2], 'base64'));
+      } else if (req.method === 'POST' && pathname === '/api/artifact') {
+        if (record.spec.responseRequired === false) return sendJson(res, 409, { error: 'display-only boards do not collect feedback' });
+        if (!sameOrigin(req, actualPort, [advertisedHost])) return sendJson(res, 403, { error: 'cross-origin artifact upload rejected' });
+        const access = accessFor(req, reqUrl);
+        if (!access.canComment) return sendJson(res, 403, { error: 'this share cannot add comments' });
+        const body = JSON.parse((await readBody(req, 6 * 1024 * 1024)) || '{}');
+        const blockId = typeof body.blockId === 'string' ? body.blockId : '';
+        const block = findBlock(record.spec, blockId, 'image') || findBlock(record.spec, blockId, 'compare');
+        if (!block) return sendJson(res, 404, { error: `no image or comparison block "${blockId}"` });
+        const match = typeof body.dataUrl === 'string'
+          ? body.dataUrl.match(/^data:(image\/(?:png|jpeg|webp));base64,([A-Za-z0-9+/=]+)$/)
+          : null;
+        if (!match || !ARTIFACT_MIMES[match[1]]) return sendJson(res, 400, { error: 'artifact must be a PNG, JPEG, or WebP data URL' });
+        const bytes = Buffer.from(match[2], 'base64');
+        if (bytes.length < 1 || bytes.length > ARTIFACT_MAX_BYTES) return sendJson(res, 400, { error: 'artifact image is empty or larger than 4 MB' });
+        if (!artifactBytesMatch(match[1], bytes)) return sendJson(res, 400, { error: 'artifact bytes do not match the declared image type' });
+        const target = saveBoardArtifact(record.id, bytes, ARTIFACT_MIMES[match[1]]);
+        sendJson(res, 200, {
+          ok: true,
+          path: target,
+          name: path.basename(target),
+          mime: match[1],
+          bytes: bytes.length,
+          width: Math.max(1, Math.min(10000, Number.parseInt(body.width, 10) || 1)),
+          height: Math.max(1, Math.min(10000, Number.parseInt(body.height, 10) || 1)),
+        });
       } else if ((req.method === 'GET' || req.method === 'HEAD') && pathname.startsWith('/video/b/')) {
         // Local video bytes, Range-streamed so the <video> element can seek.
         const blockId = decodeURIComponent(pathname.slice('/video/b/'.length));
@@ -882,13 +1054,15 @@ export async function runBoard({ id, port = 0, open = true, timeoutSec = 1800, q
       } else if (req.method === 'GET' && pathname === '/html/board') {
         // Legacy alias → the board's first html block.
         const block = firstBoardHtml(record.spec);
-        sendHtml(res, wrapFragment((block && block.html) || '', theme));
+        const access = accessFor(req, reqUrl);
+        sendHtml(res, wrapFragment((block && block.html) || '', theme, access.canComment === true && record.spec.responseRequired !== false));
       } else if (req.method === 'GET' && pathname.startsWith('/html/q/')) {
         const qid = decodeURIComponent(pathname.slice('/html/q/'.length));
         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));
+        const access = accessFor(req, reqUrl);
+        sendHtml(res, wrapFragment((block && block.html) || '', theme, access.canComment === true && record.spec.responseRequired !== false));
       } else if (req.method === 'POST' && pathname === '/api/pref') {
         const body = JSON.parse((await readBody(req)) || '{}');
         if (['auto', 'light', 'dark'].includes(body.theme)) savePref({ theme: body.theme });
@@ -921,40 +1095,79 @@ export async function runBoard({ id, port = 0, open = true, timeoutSec = 1800, q
         if (!openUrl(target)) return sendJson(res, 500, { error: 'could not open the file' });
         sendJson(res, 200, { ok: true, path: target, name: path.basename(target) });
       } else if (req.method === 'POST' && pathname === '/api/draft') {
+        if (record.spec.responseRequired === false) return sendJson(res, 409, { error: 'display-only boards do not collect feedback' });
         const access = accessFor(req, reqUrl);
         if (access.role === 'locked') return sendJson(res, 403, { error: 'share link is not active' });
+        if (!access.canEditAnswers && !access.canComment && !access.canEditBlocks) {
+          return sendJson(res, 403, { error: 'this share is read only' });
+        }
         const body = JSON.parse((await readBody(req)) || '{}');
         if (access.role === 'review') {
-          const current = record.draft && typeof record.draft === 'object' ? record.draft : {};
-          record.draft = {
-            answers: current.answers && typeof current.answers === 'object' ? current.answers : {},
-            comment: typeof current.comment === 'string' ? current.comment : '',
-            notes: current.notes && typeof current.notes === 'object' ? current.notes : {},
-            annotations: mergeReviewAnnotations(current.annotations, body.annotations),
-            blockEdits: current.blockEdits && typeof current.blockEdits === 'object' ? current.blockEdits : {},
+          record.reviewDrafts = record.reviewDrafts && typeof record.reviewDrafts === 'object' ? record.reviewDrafts : {};
+          const priorRev = Number(record.reviewDrafts[access.reviewSessionId]?.draftRev) || 0;
+          record.reviewDrafts[access.reviewSessionId] = {
+            answers: body.answers && typeof body.answers === 'object' ? body.answers : {},
+            comment: typeof body.comment === 'string' ? body.comment : '',
+            notes: body.notes && typeof body.notes === 'object' ? body.notes : {},
+            annotations: sanitizeAnnotations(body.annotations, record.id),
+            blockEdits: {},
+            draftRev: priorRev + 1,
             updatedAt: new Date().toISOString(),
           };
+          pruneReviewDrafts(record);
         } else {
           record.draft = {
             answers: body.answers && typeof body.answers === 'object' ? body.answers : {},
             comment: typeof body.comment === 'string' ? body.comment : '',
             notes: body.notes && typeof body.notes === 'object' ? body.notes : {},
-            annotations: sanitizeAnnotations(body.annotations),
+            annotations: sanitizeAnnotations(body.annotations, record.id),
             blockEdits: sanitizeBlockEdits(body.blockEdits),
             updatedAt: new Date().toISOString(),
           };
         }
-        record.draftRev = ++draftRev;
+        if (access.role !== 'review') record.draftRev = ++draftRev;
         saveBoard(record);
-        sendJson(res, 200, { ok: true, draftRev });
+        const accessDraftRev = access.role === 'review'
+          ? Number(record.reviewDrafts?.[access.reviewSessionId]?.draftRev) || 0
+          : draftRev;
+        sendJson(res, 200, { ok: true, draftRev: accessDraftRev });
       } else if (req.method === 'POST' && pathname === '/api/submit') {
+        if (record.spec.responseRequired === false) return sendJson(res, 409, { error: 'display-only boards do not accept submissions' });
         const access = accessFor(req, reqUrl);
         if (access.role === 'locked') return sendJson(res, 403, { error: 'share link is not active' });
-        if (!access.canSubmit) return sendJson(res, 403, { error: 'this share can comment only' });
+        if (!access.canSubmit) return sendJson(res, 403, { error: 'this share is read only' });
         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 = record.spec.questions.filter((q) => !(q.id in answers)).map((q) => q.id);
+        if (access.role === 'review') {
+          const review = {
+            id: 'sr-' + Date.now().toString(36) + '-' + crypto.randomBytes(3).toString('hex'),
+            status: 'side-review',
+            final: false,
+            referenceOnly: true,
+            reviewSessionId: access.reviewSessionId,
+            answers,
+            skipped,
+            comment: typeof body.comment === 'string' ? body.comment : '',
+            notes: body.notes && typeof body.notes === 'object' ? body.notes : {},
+            annotations: sanitizeAnnotations(body.annotations, record.id),
+            blockEdits: {},
+            submittedAt: new Date().toISOString(),
+          };
+          record.sideReviews = [...(Array.isArray(record.sideReviews) ? record.sideReviews : []), review].slice(-50);
+          if (record.reviewDrafts && typeof record.reviewDrafts === 'object') delete record.reviewDrafts[access.reviewSessionId];
+          saveBoard(record);
+          // Deliberately no finish(), record.result write, on-result hook, or
+          // server close: a side review never wakes/completes the waiting agent.
+          return sendJson(res, 200, {
+            ok: true,
+            sideReview: true,
+            final: false,
+            reviewId: review.id,
+            message: 'Saved as a reference-only side review. The board still awaits the owner final answer.',
+          });
+        }
         sendJson(res, 200, { ok: true });
         finish({
           status: record.spec.questions.length ? 'submitted' : 'acknowledged',
@@ -962,13 +1175,13 @@ export async function runBoard({ id, port = 0, open = true, timeoutSec = 1800, q
           skipped,
           comment: typeof body.comment === 'string' ? body.comment : '',
           notes: body.notes && typeof body.notes === 'object' ? body.notes : {},
-          annotations: sanitizeAnnotations(body.annotations),
+          annotations: sanitizeAnnotations(body.annotations, record.id),
           blockEdits: sanitizeBlockEdits(body.blockEdits),
         });
       } else if (req.method === 'GET' && pathname === '/api/share') {
         if (accessFor(req, reqUrl).role !== 'owner') return sendJson(res, 403, { error: 'only the board owner can manage sharing' });
         const roles = {};
-        for (const role of ['collab', 'review']) {
+        for (const role of ['collab', 'review', 'read']) {
           roles[role] = {
             active: activeShares[role] === true,
             url: activeShares[role] === true ? shareUrlFor(role) : null,
@@ -979,19 +1192,20 @@ export async function runBoard({ id, port = 0, open = true, timeoutSec = 1800, q
         if (accessFor(req, reqUrl).role !== 'owner') return sendJson(res, 403, { error: 'only the board owner can activate sharing' });
         if (!advertisedHost) return sendJson(res, 400, { error: 'no LAN IPv4 address found for sharing' });
         const body = JSON.parse((await readBody(req)) || '{}');
-        const role = body.role === 'review' ? 'review' : body.role === 'collab' ? 'collab' : null;
-        if (!role) return sendJson(res, 400, { error: 'role must be "collab" or "review"' });
+        const role = body.role === 'review' ? 'review' : body.role === 'collab' ? 'collab' : body.role === 'read' ? 'read' : null;
+        if (!role) return sendJson(res, 400, { error: 'role must be "collab", "review", or "read"' });
         activeShares[role] = true;
         persistShareState();
         sendJson(res, 200, { ok: true, role, url: shareUrlFor(role) });
       } else if (req.method === 'DELETE' && pathname === '/api/share') {
         if (accessFor(req, reqUrl).role !== 'owner') return sendJson(res, 403, { error: 'only the board owner can manage sharing' });
         const body = JSON.parse((await readBody(req)) || '{}');
-        const role = body.role === 'review' ? 'review' : body.role === 'collab' ? 'collab' : body.role === 'all' ? 'all' : null;
-        if (!role) return sendJson(res, 400, { error: 'role must be "collab", "review", or "all"' });
+        const role = body.role === 'review' ? 'review' : body.role === 'collab' ? 'collab' : body.role === 'read' ? 'read' : body.role === 'all' ? 'all' : null;
+        if (!role) return sendJson(res, 400, { error: 'role must be "collab", "review", "read", or "all"' });
         if (role === 'all') {
           activeShares.collab = false;
           activeShares.review = false;
+          activeShares.read = false;
         } else {
           activeShares[role] = false;
         }
@@ -1090,6 +1304,7 @@ export async function runBoard({ id, port = 0, open = true, timeoutSec = 1800, q
       notes: partial.notes ?? (record.draft?.notes || {}),
       annotations: partial.annotations ?? (record.draft?.annotations || []),
       blockEdits,
+      sideReviews: sideReviewState(record),
       createdAt: record.createdAt,
       finishedAt: new Date().toISOString(),
       durationMs: Date.now() - startedAt,