@khanglvm/relay 0.15.0 → 0.16.0

package/src/server.js

@@ -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]));
@@ -262,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) {
@@ -270,7 +329,11 @@ 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);
   }
@@ -628,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) —
@@ -673,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;
@@ -933,7 +1004,7 @@ export async function runBoard({ id, port = 0, open = true, timeoutSec = 1800, q
         const block = findHtmlBlock(record.spec, blockId);
         if (!block) return sendJson(res, 404, { error: `no html block "${blockId}"` });
         const access = accessFor(req, reqUrl);
-        sendHtml(res, wrapFragment(block.html || '', theme, access.canComment === true));
+        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));
@@ -942,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));
@@ -958,14 +1055,14 @@ export async function runBoard({ id, port = 0, open = true, timeoutSec = 1800, q
         // Legacy alias → the board's first html block.
         const block = firstBoardHtml(record.spec);
         const access = accessFor(req, reqUrl);
-        sendHtml(res, wrapFragment((block && block.html) || '', theme, access.canComment === true));
+        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);
         const access = accessFor(req, reqUrl);
-        sendHtml(res, wrapFragment((block && block.html) || '', theme, access.canComment === true));
+        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 });
@@ -998,6 +1095,7 @@ 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) {
@@ -1011,7 +1109,7 @@ export async function runBoard({ id, port = 0, open = true, timeoutSec = 1800, q
             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: {},
             draftRev: priorRev + 1,
             updatedAt: new Date().toISOString(),
@@ -1022,7 +1120,7 @@ export async function runBoard({ id, port = 0, open = true, timeoutSec = 1800, q
             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(),
           };
@@ -1034,6 +1132,7 @@ export async function runBoard({ id, port = 0, open = true, timeoutSec = 1800, q
           : 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 is read only' });
@@ -1052,7 +1151,7 @@ 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: {},
             submittedAt: new Date().toISOString(),
           };
@@ -1076,7 +1175,7 @@ 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') {

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 ----------
@@ -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();
   }
@@ -548,6 +583,7 @@
     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.
@@ -632,34 +668,35 @@
     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);
+    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;
+    popAnchorEl = anchorEl;
+    positionPopover();
+    pop.style.visibility = '';
     if (permissions.add) ta.focus();
     else popClose.focus();
   }
@@ -921,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,
@@ -29,7 +30,7 @@
     if (access.reviewSessionId) headers['x-relay-review-session'] = access.reviewSessionId;
     return headers;
   }
-  const canPersistFeedback = Boolean(access.canEditAnswers || access.canComment || access.canEditBlocks);
+  const canPersistFeedback = responseRequired && Boolean(access.canEditAnswers || access.canComment || access.canEditBlocks);
 
   // ---------- helpers ----------
   function el(tag, attrs = {}, ...children) {
@@ -541,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: {
@@ -558,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
@@ -575,6 +578,17 @@
     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) {
@@ -586,8 +600,9 @@
         return '/html/b/' + encodeURIComponent(blockId) + '?' + params.toString();
       },
       questionId: questionId == null ? null : questionId,
-      annotate: Annotate,
-      canComment: access.canComment !== false,
+      annotate: responseRequired ? Annotate : null,
+      canComment: responseRequired && access.canComment !== false,
+      saveArtifact: responseRequired && access.canComment !== false ? saveRegionArtifact : null,
       edits: state.blockEdits,
       onBlockEdit,
       canEditBlocks: access.canEditBlocks !== false,
@@ -1145,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', () => {
@@ -1167,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) {
@@ -1415,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;

package/src/ui/blocks.css

@@ -648,26 +648,35 @@
 }
 .blk-imagewrap .blk-img {
   display: block;
-  max-width: 100%;
+  width: 100%;
+  max-width: none;
   height: auto;
   border-radius: 6px;
   object-fit: contain;
   object-position: left top;
 }
+.blk-imgstage {
+  position: relative;
+  width: 100%;
+  max-width: 100%;
+  line-height: 0;
+}
 /* In full-screen a per-block height must never keep the image small — that
    height only shapes the inline preview; the detail view needs every pixel.
    (Belt-and-suspenders alongside the viewer's reapply() on full-screen toggle.) */
 .blk-imagewrap.blk-full .blk-img { max-height: none !important; }
 
 /* ---------- viewer controls (full-screen) ---------- */
-/* The full-screen button lives in a reserved strip ABOVE the visual (user
-   feedback: never overlay the content). padding-top reserves the strip;
-   the bar is a full-width transparent row with the button at the right. */
-.blk-viewer { position: relative; padding-top: 34px; }
+/* The controls participate in layout above the visual and use native sticky
+   positioning. The previous JS counter-translation chased scrollTop one event
+   behind the compositor, which made the bar visibly trail trackpad scrolling. */
+.blk-viewer { position: relative; }
 .blk-tools {
-  position: absolute; top: 4px; left: 4px; right: 4px; height: 26px;
+  position: sticky; top: 0; left: 0; width: 100%; height: 34px;
   display: flex; gap: 2px; align-items: center; justify-content: flex-end;
-  z-index: 5;
+  box-sizing: border-box; padding: 4px;
+  background: var(--bg-sunken); border-bottom: 1px solid var(--border);
+  z-index: 16;
 }
 .blk-tools button {
   background: var(--card); border: 1px solid var(--border); color: var(--fg-2);
@@ -693,6 +702,7 @@ body.blk-full-open { overflow: hidden; }
 /* detach the toolbar from the scrolling content and fix it to the viewport top */
 .blk-full > .blk-tools {
   position: fixed; top: 0; left: 0; right: 0; height: 44px;
+  width: auto;
   margin: 0; padding: 0 12px;
   background: var(--card); border-bottom: 1px solid var(--border);
   z-index: 51;
@@ -727,6 +737,7 @@ body.blk-full-open { overflow: hidden; }
 .blk-plantuml.blk-full > svg,
 .blk-plantuml.blk-full > .blk-plantuml-img,
 .blk-imagewrap.blk-full > .blk-img { margin: auto; }
+.blk-imagewrap.blk-full > .blk-imgstage { margin: auto; max-width: none; }
 
 /* Small frame on charts + mermaid so they read as a deliberate card, matching
    the graphviz/plantuml/image blocks (already framed). Scoped to the inner
@@ -898,7 +909,7 @@ body.blk-full-open { overflow: hidden; }
   20% { box-shadow: 0 0 0 3px var(--accent); }
 }
 
-/* ---------- image coordinate pins (block.pins) ---------- */
+/* ---------- image point + area comments ---------- */
 .blk-img-pinnable { cursor: crosshair; }
 .blk-imgpins { position: absolute; inset: 0; pointer-events: none; }
 .blk-imgpin {
@@ -912,3 +923,42 @@ body.blk-full-open { overflow: hidden; }
   display: grid; place-items: center;
 }
 .blk-imgpin:hover { filter: brightness(1.08); }
+.blk-region-layer { position: absolute; inset: 0; pointer-events: none; }
+.blk-region-selection,
+.blk-imgregion {
+  position: absolute;
+  border: 2px solid var(--accent);
+  background: color-mix(in srgb, var(--accent) 16%, transparent);
+  box-shadow: 0 0 0 1px rgba(255,255,255,0.75) inset;
+  border-radius: 5px;
+}
+.blk-region-selection { display: none; z-index: 7; }
+.blk-imgregion {
+  z-index: 6;
+  pointer-events: auto;
+  cursor: pointer;
+  color: var(--accent-fg);
+  padding: 0;
+  min-width: 10px;
+  min-height: 10px;
+}
+.blk-imgregion::after {
+  content: attr(data-count);
+  position: absolute; top: -11px; right: -11px;
+  min-width: 20px; height: 20px; padding: 0 5px;
+  display: grid; place-items: center;
+  border: 2px solid #fff; border-radius: 999px;
+  background: var(--accent); color: #fff;
+  font: 600 0.68rem/1 var(--sans);
+  box-shadow: 0 1px 4px rgba(0,0,0,0.3);
+}
+.blk-region-arming { cursor: crosshair !important; }
+.blk-region-selecting { cursor: crosshair !important; touch-action: none; }
+.blk-region-status {
+  position: absolute; left: 50%; bottom: 12px; z-index: 9;
+  transform: translateX(-50%);
+  padding: 6px 10px; border-radius: 8px;
+  background: rgba(28,27,25,0.86); color: #fff;
+  font: 500 0.74rem/1.2 var(--sans);
+  pointer-events: none;
+}