@khanglvm/relay 0.9.1 → 0.10.1

package/src/spec.js

@@ -25,9 +25,22 @@ const HTML_HEIGHT = { min: 100, max: 2400, boardDefault: 400, questionDefault: 3
 
 // Block heights clamp to the same window; defaults vary per block type.
 const BLOCK_HEIGHT = { min: 100, max: 2400 };
-export const BLOCK_TYPES = ['markdown', 'mermaid', 'graphviz', 'plantuml', 'chart', 'table', 'code', 'html', 'image'];
+export const BLOCK_TYPES = ['markdown', 'mermaid', 'graphviz', 'plantuml', 'chart', 'table', 'code', 'diff', 'video', 'html', 'image'];
 const CHART_KINDS = ['bar', 'line', 'pie', 'doughnut', 'radar', 'scatter'];
 
+// code/diff blocks may load their text from a local file (like htmlFile). Caps
+// keep a runaway file from bloating the board payload.
+const TEXT_FILE_MAX_BYTES = 512 * 1024;
+
+// video blocks: a YouTube/Vimeo link embeds via iframe; an http(s) media URL or
+// a local file plays in a <video> element (local files stream from the server,
+// never embedded, so large clips don't bloat the board).
+const VIDEO_MIMES = {
+  mp4: 'video/mp4', m4v: 'video/x-m4v', webm: 'video/webm', ogv: 'video/ogg',
+  ogg: 'video/ogg', mov: 'video/quicktime', mkv: 'video/x-matroska',
+};
+const VIDEO_MAX_BYTES = 512 * 1024 * 1024;
+
 // image blocks: local files are embedded as data URIs at spec time (the page
 // then loads them via /img/b/<id>), so boards stay self-contained offline.
 const IMAGE_MIMES = {
@@ -71,6 +84,45 @@ function readBlockHtml(block, cwd, where) {
   return '';
 }
 
+// Reads a code/diff block body from an inline string field or a local file.
+// `inlineKey` is the inline field (e.g. "code"/"diff"); `fileKey` its file
+// twin (e.g. "codeFile"/"diffFile"). Returns '' when neither is present.
+function readTextSource(block, inlineKey, fileKey, cwd, where) {
+  if (typeof block[inlineKey] === 'string' && block[inlineKey] !== '') return block[inlineKey];
+  if (typeof block[fileKey] === 'string' && block[fileKey].trim()) {
+    const p = path.resolve(cwd, block[fileKey]);
+    let buf;
+    try {
+      buf = fs.readFileSync(p);
+    } catch {
+      throw new CliError(`${where}: cannot read ${fileKey} "${block[fileKey]}" (resolved: ${p})`);
+    }
+    if (buf.length > TEXT_FILE_MAX_BYTES) {
+      throw new CliError(`${where}: ${fileKey} "${block[fileKey]}" is ${(buf.length / 1024).toFixed(0)}KB — max ${TEXT_FILE_MAX_BYTES / 1024}KB.`);
+    }
+    return buf.toString('utf8');
+  }
+  return '';
+}
+
+// Recognizes a YouTube / Vimeo URL (or a bare YouTube id) and returns
+// {provider, videoId, start} for an iframe embed, else null. Cross-platform —
+// pure string parsing, no URL host assumptions beyond the known providers.
+function parseVideoEmbed(src) {
+  const s = String(src).trim();
+  // bare 11-char YouTube id
+  if (/^[\w-]{11}$/.test(s)) return { provider: 'youtube', videoId: s, start: 0 };
+  let m;
+  if ((m = s.match(/(?:youtube\.com\/(?:watch\?(?:.*&)?v=|embed\/|shorts\/|v\/)|youtu\.be\/)([\w-]{11})/i))) {
+    const t = s.match(/[?&](?:t|start)=(\d+)/);
+    return { provider: 'youtube', videoId: m[1], start: t ? Number(t[1]) : 0 };
+  }
+  if ((m = s.match(/vimeo\.com\/(?:video\/)?(\d+)/i))) {
+    return { provider: 'vimeo', videoId: m[1], start: 0 };
+  }
+  return null;
+}
+
 // Normalizes one block object. `id` is the already-assigned block id.
 // Returns the normalized block (with a guaranteed string `type` + `id`).
 function normalizeBlock(rawBlock, id, cwd, where) {
@@ -126,14 +178,75 @@ function normalizeBlock(rawBlock, id, cwd, where) {
   }
 
   if (type === 'code') {
-    const code = asStr(rawBlock.code);
-    if (!code) throw new CliError(`${where}: code block needs a "code" string.`);
+    const code = readTextSource(rawBlock, 'code', 'codeFile', cwd, where);
+    if (!code) throw new CliError(`${where}: code block needs a "code" string or a readable "codeFile".`);
     const block = { id, type: 'code', code };
     if (rawBlock.lang !== undefined) block.lang = asStr(rawBlock.lang);
+    // lang defaults from the codeFile extension when not given explicitly.
+    else if (typeof rawBlock.codeFile === 'string' && rawBlock.codeFile.trim()) {
+      const ext = path.extname(rawBlock.codeFile).slice(1).toLowerCase();
+      if (ext) block.lang = ext;
+    }
+    if (rawBlock.filename !== undefined) block.filename = asStr(rawBlock.filename);
     if (hasHeight) block.height = clampInt(rawBlock.height, BLOCK_HEIGHT.min, BLOCK_HEIGHT.max, undefined);
     return block;
   }
 
+  if (type === 'diff') {
+    const diff = readTextSource(rawBlock, 'diff', 'diffFile', cwd, where);
+    if (!diff.trim()) throw new CliError(`${where}: diff block needs a non-empty "diff" string (unified diff) or a readable "diffFile".`);
+    const block = { id, type: 'diff', diff };
+    if (rawBlock.lang !== undefined) block.lang = asStr(rawBlock.lang);
+    if (rawBlock.filename !== undefined) block.filename = asStr(rawBlock.filename);
+    const view = asStr(rawBlock.view).trim().toLowerCase();
+    if (view === 'split' || view === 'unified') block.view = view;
+    if (hasHeight) block.height = clampInt(rawBlock.height, BLOCK_HEIGHT.min, BLOCK_HEIGHT.max, undefined);
+    return block;
+  }
+
+  if (type === 'video') {
+    const src = asStr(rawBlock.src ?? rawBlock.file ?? rawBlock.url).trim();
+    if (!src) throw new CliError(`${where}: video block needs a "src" (YouTube/Vimeo URL, http(s) media URL, or local file path).`);
+    const block = { id, type: 'video' };
+    if (rawBlock.title !== undefined) block.title = asStr(rawBlock.title);
+    if (rawBlock.alt !== undefined) block.title = asStr(rawBlock.alt);
+    if (hasHeight) block.height = clampInt(rawBlock.height, BLOCK_HEIGHT.min, BLOCK_HEIGHT.max, undefined);
+    const embed = parseVideoEmbed(src);
+    if (embed) {
+      block.provider = embed.provider;
+      block.videoId = embed.videoId;
+      if (embed.start) block.start = embed.start;
+      return block;
+    }
+    if (/^https?:/i.test(src)) {
+      block.src = src;
+      const ext = path.extname(src.split(/[?#]/)[0]).slice(1).toLowerCase();
+      if (VIDEO_MIMES[ext]) block.mime = VIDEO_MIMES[ext];
+      return block;
+    }
+    // local file — kept as an absolute path the server streams (never embedded
+    // in the payload). The client only learns a flag + mime via /video/b/<id>.
+    const p = path.resolve(cwd, src);
+    const ext = path.extname(p).slice(1).toLowerCase();
+    const mime = VIDEO_MIMES[ext];
+    if (!mime) {
+      throw new CliError(`${where}: unsupported video extension ".${ext}" — use ${Object.keys(VIDEO_MIMES).join('/')}, a YouTube/Vimeo URL, or an http(s) media URL.`);
+    }
+    let stat;
+    try {
+      stat = fs.statSync(p);
+    } catch {
+      throw new CliError(`${where}: cannot read video "${src}" (resolved: ${p})`);
+    }
+    if (stat.size > VIDEO_MAX_BYTES) {
+      throw new CliError(`${where}: video "${src}" is ${(stat.size / 1024 / 1024).toFixed(0)}MB — max ${VIDEO_MAX_BYTES / 1024 / 1024}MB.`);
+    }
+    block.file = p;
+    block.mime = mime;
+    if (!block.title) block.title = path.basename(p);
+    return block;
+  }
+
   if (type === 'chart') {
     const hasConfig = rawBlock.config && typeof rawBlock.config === 'object' && !Array.isArray(rawBlock.config);
     const hasShorthand =
@@ -412,11 +525,16 @@ const BLOCK_SCHEMA = {
     properties: {
       type: { type: 'string', enum: BLOCK_TYPES },
       md: { type: 'string', description: 'markdown: built-in mini renderer (no external library) — headings, lists, code, quotes, links, and GFM pipe tables. Text selections are commentable. For real tabular data prefer a "table" block (sortable + per-cell comments).' },
-      code: { type: 'string', description: 'mermaid: diagram source (e.g. "graph TD; A-->B"); plantuml: the @startuml…@enduml source; code: the source to display.' },
+      code: { type: 'string', description: 'mermaid: diagram source (e.g. "graph TD; A-->B"); plantuml: the @startuml…@enduml source; code: the source to display (syntax-highlighted with line numbers).' },
+      codeFile: { type: 'string', description: 'code: path to a local source file to load + display instead of inline "code". Resolved against the CWD; lang defaults from the file extension.' },
+      filename: { type: 'string', description: 'code/diff: optional file name/path shown as a header label above the block.' },
       editable: { type: 'boolean', description: 'mermaid: when true, render an "Edit diagram" toggle so the user can edit the diagram source live. The edited source is returned in result.blockEdits[<blockId>].' },
       dot: { type: 'string', description: 'graphviz: DOT source (e.g. "digraph { a -> b }"). Rendered offline via vendored Viz.js; nodes and edges are individually commentable.' },
       server: { type: 'string', description: 'plantuml: PlantUML server base URL (http(s)). Defaults to https://www.plantuml.com/plantuml. Diagrams render via this server (needs network).' },
-      lang: { type: 'string', description: 'code block: language hint for display.' },
+      lang: { type: 'string', description: 'code/diff block: language hint for syntax highlighting (js, ts, py, go, rust, java, c, cpp, csharp, ruby, php, swift, kotlin, sql, yaml, json, sh, css, html, …).' },
+      diff: { type: 'string', description: 'diff: a unified diff (git diff / diff -u output) — rendered as a colored, line-numbered comparison with +added / −removed / context rows and file/hunk headers. No git needed; just write/paste the diff text.' },
+      diffFile: { type: 'string', description: 'diff: path to a local file containing a unified diff (alternative to "diff"). Resolved against the CWD.' },
+      view: { type: 'string', enum: ['unified', 'split'], description: 'diff: initial layout — "unified" (default, one column) or "split" (side-by-side old vs new). The viewer also has a live toggle either way.' },
       config: { type: 'object', description: 'chart: a full Chart.js config object.' },
       kind: { type: 'string', enum: CHART_KINDS, description: 'chart shorthand: chart kind (alternative to "config").' },
       labels: { type: 'array', description: 'chart shorthand: x-axis / category labels.' },
@@ -425,7 +543,7 @@ const BLOCK_SCHEMA = {
         description: 'chart shorthand: [{label, data:[...], color?}]. Chart data points are individually commentable.',
         items: { type: 'object', properties: { label: { type: 'string' }, data: { type: 'array' }, color: { type: 'string' } } },
       },
-      title: { type: 'string', description: 'chart shorthand: chart title.' },
+      title: { type: 'string', description: 'chart shorthand: chart title. video: title/caption shown under the player.' },
       columns: {
         type: 'array',
         description: 'table: strings, or {key, label, align?}. Cells are commentable.',
@@ -435,8 +553,8 @@ const BLOCK_SCHEMA = {
       sortable: { type: 'boolean', description: 'table: enable click-to-sort headers.' },
       html: { type: 'string', description: 'html: custom markup rendered in a sandboxed iframe.' },
       htmlFile: { type: 'string', description: 'html: path to an HTML file (alternative to "html").' },
-      src: { type: 'string', description: 'image: http(s)/data URL, or a local file path (png/jpg/gif/webp/svg/avif/bmp — embedded at spec time, served offline).' },
-      alt: { type: 'string', description: 'image: alt text / annotation label.' },
+      src: { type: 'string', description: 'image: http(s)/data URL, or a local file path (png/jpg/gif/webp/svg/avif/bmp — embedded at spec time, served offline). video: a YouTube/Vimeo URL (embeds an iframe player), an http(s) media URL, or a local video file (mp4/webm/ogv/mov/mkv/m4v — streamed from the server, never embedded).' },
+      alt: { type: 'string', description: 'image: alt text / annotation label. video: accessible title for the player.' },
       height: { type: 'integer', minimum: BLOCK_HEIGHT.min, maximum: BLOCK_HEIGHT.max, description: 'Block height in px. Defaults: chart 320, html 360; markdown/table/code flow naturally; mermaid/graphviz/plantuml/image natural (max 1200, scrolls).' },
     },
   },

package/src/store.js

@@ -28,6 +28,10 @@ export function createBoard(spec) {
     id: newId(),
     createdAt: new Date().toISOString(),
     title: spec.title,
+    // The directory the board was authored in. Relative file paths an agent
+    // writes into the spec (markdown links, ~/… paths) resolve against this, so
+    // the live server can open them in the user's default app (POST /api/open).
+    cwd: process.cwd(),
     spec,
     draft: null,
     result: null,

package/src/ui/app.js

@@ -88,6 +88,68 @@
   }
   let themeBtn = null;
 
+  // ---------- localStorage draft mirror ----------
+  // Every autosave is ALSO written to localStorage, keyed by board id. This is
+  // 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');
+  function writeLocalDraft(p, updatedAt) {
+    try {
+      localStorage.setItem(LOCAL_DRAFT_KEY, JSON.stringify({
+        v: 1,
+        boardId: boot.boardId,
+        rev: bootRev,
+        updatedAt: updatedAt || new Date().toISOString(),
+        payload: p,
+      }));
+    } catch {
+      // localStorage may be full or unavailable (privacy mode) — non-fatal; the
+      // server file remains the primary persistence path.
+    }
+  }
+  function clearLocalDraft() {
+    try { localStorage.removeItem(LOCAL_DRAFT_KEY); } catch { /* non-fatal */ }
+  }
+  // Returns the saved local mirror only if it's valid for THIS board+rev,
+  // otherwise null (and clears a now-stale entry). rev mismatch ⇒ the agent
+  // re-published the board, so old local answers may not map — discard them.
+  function loadLocalDraft() {
+    let raw;
+    try { raw = localStorage.getItem(LOCAL_DRAFT_KEY); } catch { return null; }
+    if (!raw) return null;
+    let obj;
+    try { obj = JSON.parse(raw); } catch { clearLocalDraft(); return null; }
+    if (!obj || obj.boardId !== boot.boardId || !obj.payload || typeof obj.payload !== 'object') {
+      clearLocalDraft();
+      return null;
+    }
+    // rev-guard: a changed spec rev means the local answers may reference a
+    // different question set — don't resurrect them.
+    if (bootRev !== null && obj.rev !== undefined && obj.rev !== null && obj.rev !== bootRev) {
+      clearLocalDraft();
+      return null;
+    }
+    return obj;
+  }
+
+  // Choose the prefill source: the NEWER of the server draft (boot.prefill) and
+  // the local mirror. The server draft shape mirrors a payload() plus updatedAt.
+  function chooseInitialPrefill() {
+    const server = boot.prefill || null;
+    const local = loadLocalDraft();
+    if (!local) return server;
+    if (!server) return { ...local.payload, __from: 'local' };
+    const sT = Date.parse(server.updatedAt || '') || 0;
+    const lT = Date.parse(local.updatedAt || '') || 0;
+    // Newest wins; ties favor local (the tab that was last typing into).
+    return lT >= sT ? { ...local.payload, __from: 'local' } : server;
+  }
+  const initialPrefill = chooseInitialPrefill();
+
   // ---------- state ----------
   // state.answers holds raw control state; state.other holds the "Other"
   // free-text per question; getValue() derives the final answer value.
@@ -97,11 +159,11 @@
     other: {},
     notes: {},
     comment: '',
-    annotations: (boot.prefill && boot.prefill.annotations) || [],
+    annotations: (initialPrefill && initialPrefill.annotations) || [],
     // Editable-mermaid edits: blockId -> edited source. Seeded from the live
     // draft so a reload/reopen restores the user's edited diagram. Mutated via
     // the blocks ctx.onBlockEdit callback below; returned in payload().
-    blockEdits: (boot.prefill && boot.prefill.blockEdits) || {},
+    blockEdits: (initialPrefill && initialPrefill.blockEdits) || {},
   };
   let submitted = false;
 
@@ -125,8 +187,11 @@
       }
     }
   }
-  if (boot.prefill) seedFromPrefill(boot.prefill);
+  if (initialPrefill) seedFromPrefill(initialPrefill);
   else for (const q of QS) if (q.default !== undefined) state.answers[q.id] = q.default;
+  // If the local mirror was newer than the server (or the server had nothing),
+  // the in-memory state now holds input the server hasn't seen — flush it once
+  // the rest of the app is wired (see the post-init flush near the heartbeat).
 
   function getValue(q) {
     const v = state.answers[q.id];
@@ -176,27 +241,149 @@
     };
   }
 
+  // ---------- persistence-lost block ----------
+  // The dead-end this guards against: the client can lose its connection to the
+  // board's local HTTP server (server gone, port taken over, socket dropped,
+  // machine slept). Autosaves then fail silently and the user keeps typing
+  // answers/comments that are never persisted, then Submit fails too — all of it
+  // thrown away. When persistence is CONFIRMED lost we hard-block: disable every
+  // control and overlay an unmissable scrim with a Retry. Local `state` is never
+  // touched, so the moment the connection recovers we flush it and unblock —
+  // nothing the user typed during the outage is lost.
+  let persistenceLost = false;
+  let probing = false;
+  let lostOverlay = null;
+  let lostRetryBtn = null;
+
+  // A direct, side-effect-free reachability probe. Resolves true when the local
+  // server answers /api/status, false on any network/HTTP failure. Used to
+  // CONFIRM loss before blocking (so a single dropped request never blocks) and
+  // to detect recovery from the Retry button / heartbeat.
+  async function probeServer() {
+    try {
+      const r = await fetch('/api/status', { cache: 'no-store' });
+      return r.ok;
+    } catch {
+      return false;
+    }
+  }
+
+  function buildLostOverlay() {
+    if (lostOverlay) return lostOverlay;
+    lostRetryBtn = el('button', { class: 'lost-retry', type: 'button' }, 'Retry connection');
+    lostRetryBtn.addEventListener('click', retryConnection);
+    lostOverlay = el('div', { class: 'lost-overlay', role: 'alertdialog', 'aria-modal': 'true', 'aria-label': 'Connection lost' },
+      el('div', { class: 'lost-card' },
+        el('div', { class: 'lost-mark' }, '⚠'),
+        el('h2', {}, 'Connection lost — input isn’t being saved'),
+        el('p', {}, 'This board can no longer reach your agent’s session, so anything you type now won’t be saved. Editing is paused to keep you from losing work.'),
+        el('p', { class: 'lost-sub' }, 'Your input up to this point is kept in this tab. Click Retry once the agent’s session is back, or prompt the agent to reopen this board — your draft and unsaved edits will be restored.'),
+        lostRetryBtn
+      )
+    );
+    return lostOverlay;
+  }
+
+  // Enter the blocked state: disable controls, mount the overlay. Idempotent.
+  function blockForLostPersistence() {
+    if (persistenceLost || submitted) return;
+    persistenceLost = true;
+    document.documentElement.classList.add('relay-blocked');
+    // Disable every interactive control inside the form (inputs the user could
+    // otherwise keep typing into) plus Submit.
+    for (const node of app.querySelectorAll('input, textarea, button, select')) {
+      node.disabled = true;
+    }
+    document.body.append(buildLostOverlay());
+    if (saveEl) saveEl.textContent = 'connection lost — not saving';
+  }
+
+  // Leave the blocked state: re-enable controls, remove the overlay, and flush
+  // whatever the user typed during the outage so it's persisted right away.
+  function unblockAfterRecovery() {
+    if (!persistenceLost) return;
+    persistenceLost = false;
+    document.documentElement.classList.remove('relay-blocked');
+    for (const node of app.querySelectorAll('input, textarea, button, select')) {
+      node.disabled = false;
+    }
+    if (lostOverlay) lostOverlay.remove();
+    // Re-arm the heartbeat (it stops itself when it confirms loss) and persist
+    // everything typed during the outage. saveDraft() updates the save label.
+    startHeartbeat();
+    misses = 0;
+    saveFailures = 0;
+    saveDraft();
+  }
+
+  // Retry button: probe once; recover on success, otherwise tell the user it's
+  // still down (without un-blocking).
+  async function retryConnection() {
+    if (probing) return;
+    probing = true;
+    if (lostRetryBtn) { lostRetryBtn.disabled = true; lostRetryBtn.textContent = 'Checking…'; }
+    const ok = await probeServer();
+    probing = false;
+    if (lostRetryBtn) { lostRetryBtn.disabled = false; lostRetryBtn.textContent = 'Retry connection'; }
+    if (ok) unblockAfterRecovery();
+    else if (lostRetryBtn) {
+      lostRetryBtn.textContent = 'Still unreachable — try again';
+      setTimeout(() => { if (lostRetryBtn && persistenceLost) lostRetryBtn.textContent = 'Retry connection'; }, 2500);
+    }
+  }
+
+  // Called when a save/heartbeat fails. Confirms loss with a probe (so one
+  // dropped request never blocks) before hard-blocking. `force` skips the probe
+  // for callers (the heartbeat) that already represent repeated failures.
+  async function considerPersistenceLost(force) {
+    if (persistenceLost || submitted || probing) return;
+    if (!force) {
+      probing = true;
+      const ok = await probeServer();
+      probing = false;
+      if (ok || persistenceLost || submitted) return; // recovered or already handled
+    }
+    blockForLostPersistence();
+  }
+
   // ---------- real-time autosave ----------
   let saveTimer = null;
   let saveSeq = 0;
   let saveEl = null;
+  // Consecutive failed /api/draft saves. Two in a row triggers a confirming
+  // probe → block. Any success resets it.
+  let saveFailures = 0;
   function scheduleSave() {
     if (submitted) 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.
+    writeLocalDraft(payload());
+    if (persistenceLost) return; // network save is futile while disconnected
     if (saveEl) saveEl.textContent = 'saving…';
     clearTimeout(saveTimer);
     saveTimer = setTimeout(saveDraft, 450);
   }
   async function saveDraft() {
     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).
+    writeLocalDraft(payload());
     try {
-      await fetch('/api/draft', {
+      const r = await fetch('/api/draft', {
         method: 'POST',
         headers: { 'content-type': 'application/json' },
         body: JSON.stringify(payload()),
       });
-      if (seq === saveSeq && saveEl && !submitted) saveEl.textContent = 'draft saved ✓';
+      if (!r.ok) throw new Error('draft rejected');
+      saveFailures = 0;
+      if (seq === saveSeq && saveEl && !submitted && !persistenceLost) saveEl.textContent = 'draft saved ✓';
     } catch {
-      if (seq === saveSeq && saveEl && !submitted) saveEl.textContent = 'draft save failed';
+      if (seq === saveSeq && saveEl && !submitted && !persistenceLost) saveEl.textContent = 'draft save failed';
+      // A save couldn't be persisted to the SERVER — the core data-loss signal.
+      // (The local mirror above still captured it.) After two in a row, confirm
+      // with a probe and block so the user stops typing into the void.
+      if (++saveFailures >= 2) considerPersistenceLost(false);
     }
   }
 
@@ -656,14 +843,26 @@
     submitBtn.disabled = true;
     submitBtn.textContent = 'Submitting…';
     clearTimeout(saveTimer);
+    let reached = true;
     try {
-      const res = await fetch('/api/submit', {
-        method: 'POST',
-        headers: { 'content-type': 'application/json' },
-        body: JSON.stringify(payload()),
-      });
+      let res;
+      try {
+        res = await fetch('/api/submit', {
+          method: 'POST',
+          headers: { 'content-type': 'application/json' },
+          body: JSON.stringify(payload()),
+        });
+      } catch (netErr) {
+        // A thrown fetch (vs. an HTTP error response) means we never reached the
+        // server — the connection is gone, so this submit was never delivered.
+        reached = false;
+        throw netErr;
+      }
       if (!res.ok) throw new Error('submit rejected');
       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;
@@ -680,22 +879,33 @@
         }, 700);
       }
     } catch {
-      // The server is gone, so this submit couldn't be delivered. Keep the
-      // button live and tell the user how to get their input to the agent —
-      // their draft was autosaved up to the last edit.
+      // Restore the button so the user can retry.
       submitBtn.disabled = false;
       submitBtn.textContent = spec.submitLabel;
-      showNotice(
-        'Couldn’t reach the agent to submit just now — your draft is saved. Prompt the agent to reopen this board so your input isn’t lost.',
-        'warn'
-      );
+      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
+        // lost; the block's probe loop / heartbeat lifts it on recovery, and the
+        // user can then submit. force=true: the failed submit already confirms
+        // the server is unreachable.
+        stopHeartbeat();
+        considerPersistenceLost(true);
+        startBlockedProbeLoop();
+      } else {
+        // The server answered with an error (e.g. 409 board already finished) —
+        // it's reachable, so don't show the scary block; just guide the user.
+        showNotice(
+          'Couldn’t submit — the board may have already closed. Prompt the agent to reopen this board so your input isn’t lost.',
+          'warn'
+        );
+      }
     }
   });
 
   // ---------- prefilled load: jump past what's already answered ----------
   // On reload/reopen with saved answers, scroll to the first unanswered
   // question so the user doesn't re-scan questions they already did.
-  if (boot.prefill && QS.length) {
+  if (initialPrefill && QS.length) {
     const answered = QS.filter((q) => getValue(q) !== undefined).length;
     const firstOpen = QS.find((q) => getValue(q) === undefined);
     if (answered > 0 && firstOpen) {
@@ -705,6 +915,14 @@
     }
   }
 
+  // If the chosen prefill came from the local mirror (newer than the server, or
+  // 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) {
+    saveDraft();
+  }
+
   // ---------- iframe annotate bridge ----------
   // Custom-HTML iframes (via /kit.js relayKit.annotate, auto-injected by the
   // server) talk to the parent over postMessage:
@@ -772,13 +990,20 @@
   // ---------- heartbeat ----------
   let misses = 0;
   let reloading = false;
-  let hb = setInterval(async () => {
+  let hb = null;
+  async function heartbeatTick() {
     // Piggyback presence on the heartbeat (best-effort; no-ops after submit).
     pingPresence();
     try {
       const r = await fetch('/api/status', { cache: 'no-store' });
       if (!r.ok) throw new Error('bad status');
       misses = 0;
+      // The heartbeat reaching the server is itself proof persistence is back —
+      // if we were blocked (saves had been failing), recover now and flush.
+      if (persistenceLost) {
+        unblockAfterRecovery();
+        return;
+      }
       // Live update: the agent ran `rly update`, advancing the server rev.
       // Flush whatever the user has typed so far (the reload re-prefills from
       // the live draft — answers for now-removed question ids are ignored),
@@ -812,22 +1037,55 @@
         location.reload();
       }
     } catch {
-      // Lost the live connection (the session ended, or the machine slept).
-      // Keep the board usable — do NOT disable Submit — and show a calm note
-      // rather than the old red "closed" banner. A submit attempt that can't
-      // reach the server falls back to the same guidance below.
-      if (++misses >= 2 && !submitted) {
+      // Lost the live connection (the session ended, or the machine slept). Two
+      // consecutive misses means the local server is unreachable — so input can
+      // no longer be persisted. Hard-block: disable editing and overlay the
+      // unmissable "connection lost" scrim, so the user can't keep typing
+      // feedback that would be silently discarded. The block re-arms its own
+      // probe loop and the heartbeat recovers it once the server answers again.
+      if (++misses >= 2 && !submitted && !persistenceLost) {
         handedBack = true;
-        showNotice(
-          'Lost the live connection to your agent’s session — your latest edits were saved. You can still try Submit; if it doesn’t go through, prompt the agent to reopen this board.',
-          'warn'
-        );
         stopHeartbeat();
+        // force=true: two heartbeat misses already confirm the server is gone,
+        // so block immediately without a redundant probe.
+        considerPersistenceLost(true);
+        // While blocked, keep probing so an automatic recovery (server back,
+        // machine woke) lifts the block even if the user never clicks Retry.
+        startBlockedProbeLoop();
       }
     }
-  }, 3000);
+  }
+  function startHeartbeat() {
+    if (hb || submitted) return;
+    hb = setInterval(heartbeatTick, 3000);
+  }
   function stopHeartbeat() {
     if (hb) clearInterval(hb);
     hb = null;
   }
+
+  // While blocked, the heartbeat is stopped — so run a lightweight probe loop
+  // that lifts the block automatically the moment the server is reachable again
+  // (no Retry click needed). Stops itself on recovery or after submit.
+  let blockedProbe = null;
+  function startBlockedProbeLoop() {
+    if (blockedProbe) return;
+    blockedProbe = setInterval(async () => {
+      if (!persistenceLost || submitted) {
+        clearInterval(blockedProbe);
+        blockedProbe = null;
+        return;
+      }
+      if (probing) return;
+      probing = true;
+      const ok = await probeServer();
+      probing = false;
+      if (ok) {
+        clearInterval(blockedProbe);
+        blockedProbe = null;
+        unblockAfterRecovery();
+      }
+    }, 3000);
+  }
+  startHeartbeat();
 })();