claude-code-kanban 6.1.2 → 7.0.0

package/README.md

@@ -107,9 +107,10 @@ Run `claude` in any project. You do not configure anything per project. Claude C
 
 With no subcommand, `claude-code-kanban` starts the server. Subcommands talk to a server that already runs:
 
-- `session list|search|open|view|plan|agents|pin|pins|peek` to read and focus sessions.
+- `session list|search|open|view|plan|agents|pin` to read and focus sessions.
 - `task list` and `project list` to read tasks and projects.
-- `preview-doc` and `link-doc` to show or link a file on the board.
+- `doc link|unlink|list|preview` to link a file or URL to a session, or show it in the preview.
+- `pane add|rm|list` to add live panes to a session's view.
 - `dispatch start|list` to start sessions with a task in the board's terminal.
 
 Run `claude-code-kanban --help` or see the [CLI reference](https://nikiforovall.blog/claude-code-kanban/reference/cli/).

package/cli.js

@@ -4,36 +4,99 @@ const { getClaudeDir, displayPath } = require('./lib/claude-dir');
 const { isGroupName, suggestGroupName } = require('./lib/dispatch-groups');
 const { linkUrl } = require('./public/link-url');
 // Help is auto-generated from this table — keep flags/usage in sync with `run` behavior.
+const SESSION_FLAG = '--session <id>';
+const SESSION_FLAG_HELP = 'Session, full id or unique prefix (default: $PREVIEW_SESSION, else $CLAUDE_CODE_SESSION_ID)';
+
 const COMMANDS = {
-  'preview-doc': {
-    summary: 'Open a markdown or HTML file in the preview modal on connected browser tabs',
-    usage: 'claude-code-kanban preview-doc <file.md|file.html|url> [--session <id>]',
-    flags: {
-      '--session <id>': 'Switch focused session in the browser (does not link the file). Required for a URL.',
+  doc: {
+    summary: 'Show documents to the user: link them to a session, or open the preview',
+    verbs: {
+      link: {
+        summary: 'Link a file or URL to a session, with no modal',
+        usage: 'claude-code-kanban doc link <file|url> [--session <id>]',
+        flags: {
+          '<file|url>': 'Any file type; one the preview cannot render opens in the editor. An http(s) URL opens in a new tab.',
+          [SESSION_FLAG]: SESSION_FLAG_HELP,
+        },
+        notes: 'The server keeps the link, so it shows when a browser tab opens later. Prefer this over `doc preview` while the user works.',
+        examples: [
+          'claude-code-kanban doc link ./design.md',
+          'claude-code-kanban doc link https://github.com/org/repo/pull/12',
+        ],
+        run: runDocLinkCli,
+      },
+      unlink: {
+        summary: 'Remove a linked file or URL from a session',
+        usage: 'claude-code-kanban doc unlink <file|url> [--session <id>]',
+        flags: {
+          '<file|url>': 'The linked path or URL; the file need not exist',
+          [SESSION_FLAG]: SESSION_FLAG_HELP,
+        },
+        examples: ['claude-code-kanban doc unlink ./design.md'],
+        run: runDocLinkCli,
+      },
+      list: {
+        summary: 'Print the docs linked to a session',
+        usage: 'claude-code-kanban doc list [--session <id>] [--json]',
+        flags: {
+          [SESSION_FLAG]: SESSION_FLAG_HELP,
+          '--json': 'Output JSON',
+        },
+        run: runDocListCli,
+      },
+      preview: {
+        summary: 'Open a markdown or HTML file in the preview modal on connected browser tabs',
+        usage: 'claude-code-kanban doc preview <file.md|file.html|url> [--session <id>]',
+        flags: {
+          [SESSION_FLAG]: 'Switch focused session in the browser (does not link the file; default: $PREVIEW_SESSION). For a URL, the session it links to (default: $PREVIEW_SESSION, else $CLAUDE_CODE_SESSION_ID).',
+        },
+        notes: 'The modal opens on the user\'s screen: the only command that does. HTML renders in a sandboxed iframe; local stylesheets, scripts and images are inlined. Relative paths resolve against the current dir. An http(s) URL is linked to the session instead, and the tab on screen shows an Open button.',
+        examples: [
+          'claude-code-kanban doc preview ./notes.md --session $CLAUDE_SESSION_ID',
+        ],
+        run: runPreviewCli,
+      },
     },
-    notes: 'HTML renders in a sandboxed iframe; local stylesheets, scripts and images are inlined. Relative paths resolve against the current dir. An http(s) URL is linked to the session instead, and the tab on screen shows an Open button.',
-    examples: [
-      'claude-code-kanban preview-doc ./notes.md --session $CLAUDE_SESSION_ID',
-    ],
-    run: runPreviewCli,
   },
-  'link-doc': {
-    summary: 'Link a file or URL to a session in the sidebar without opening the preview modal',
-    usage: 'claude-code-kanban link-doc <file|url> --session <id> [--unlink] | link-doc --list --session <id> [--json]',
-    flags: {
-      '<file|url>': 'Any file type; one the preview cannot render opens in the editor. An http(s) URL opens in a new tab.',
-      '--session <id>': 'Session to link the file to (required unless $PREVIEW_SESSION is set); full id or unique prefix',
-      '--unlink': 'Remove the link instead of adding it (the file need not exist)',
-      '--list': 'Print the docs the server holds for the session',
-      '--json': 'With --list: output JSON',
+  pane: {
+    summary: 'Add live panes (a URL or a local file) to a session\'s view, without switching to them',
+    verbs: {
+      add: {
+        summary: 'Add a pane to a session; it opens as a tab next to Board, in the background',
+        usage: 'claude-code-kanban pane add <url|file> [--title <text>] [--session <id>] [--json]',
+        flags: {
+          '<url|file>': 'An http(s) URL, or a local HTML, markdown, text or image file (relative paths resolve against the current dir)',
+          '--title <text>': 'Tab title (default: the host or file name)',
+          [SESSION_FLAG]: SESSION_FLAG_HELP,
+          '--json': 'Output JSON (the new pane, with frameable: true, false, or null when unknown)',
+        },
+        notes: 'The board does not switch to the new pane; the user opens it. Prints the pane id. The same target added again prints the pane it already has. A URL on the board\'s or the hub\'s own origin is refused, and a file must be one the board can preview. A site whose headers refuse framing (X-Frame-Options, CSP frame-ancestors) is still added, but its pane shows an "Open in new tab" card, and a note line says so.',
+        examples: [
+          'claude-code-kanban pane add http://localhost:5173',
+          'claude-code-kanban pane add ./report.html --title Report',
+        ],
+        run: runPaneAddCli,
+      },
+      rm: {
+        summary: 'Remove a pane from a session',
+        usage: 'claude-code-kanban pane rm <pane-id> [--session <id>]',
+        flags: {
+          '<pane-id>': 'The id `pane add` or `pane list` printed',
+          [SESSION_FLAG]: SESSION_FLAG_HELP,
+        },
+        examples: ['claude-code-kanban pane rm p3'],
+        run: runPaneRmCli,
+      },
+      list: {
+        summary: 'List the panes of a session, in tab order',
+        usage: 'claude-code-kanban pane list [--session <id>] [--json]',
+        flags: {
+          [SESSION_FLAG]: SESSION_FLAG_HELP,
+          '--json': 'Output JSON ({rev, panes: [{id, kind, target, title, addedAt}], updatedAt})',
+        },
+        run: runPaneListCli,
+      },
     },
-    notes: 'The server keeps the link, so it shows when a browser tab opens later.',
-    examples: [
-      'claude-code-kanban link-doc ./design.md --session $CLAUDE_SESSION_ID',
-      'claude-code-kanban link-doc https://github.com/org/repo/pull/12 --session $CLAUDE_SESSION_ID',
-      'claude-code-kanban link-doc --list --session $CLAUDE_SESSION_ID',
-    ],
-    run: runLinkDocCli,
   },
   session: {
     summary: 'List, search, open and inspect Claude Code sessions',
@@ -78,12 +141,13 @@ const COMMANDS = {
         run: runSessionOpenCli,
       },
       view: {
-        summary: 'Show full session stats (metadata + context window + cost)',
+        summary: 'Show full session stats (metadata + context window + cost) and the transcript path',
         usage: 'claude-code-kanban session view <id> [--json]',
         flags: {
           '<id>': 'Full session id, or a unique prefix',
           '--json': 'Output JSON instead of formatted sections',
         },
+        notes: 'To learn what a session did, read its transcript (a .jsonl file, newest lines last).',
         examples: ['claude-code-kanban session view $CLAUDE_SESSION_ID'],
         run: runSessionViewCli,
       },
@@ -122,26 +186,6 @@ const COMMANDS = {
         ],
         run: runSessionPinCli,
       },
-      pins: {
-        summary: 'List sessions pinned/stickied via the dashboard or CLI',
-        usage: 'claude-code-kanban session pins [--sticky] [--json]',
-        flags: {
-          '--sticky': 'Only sessions in sticky state',
-          '--json': 'Output JSON instead of a table',
-        },
-        run: runSessionPinsCli,
-      },
-      peek: {
-        summary: 'Show the last N messages from a session',
-        usage: 'claude-code-kanban session peek <id> [--limit <n>] [--json]',
-        flags: {
-          '<id>': 'Full session id, or a unique prefix',
-          '--limit <n>': 'Number of messages (default: 10, max: 50)',
-          '--json': 'Output JSON instead of formatted lines',
-        },
-        examples: ['claude-code-kanban session peek 3fa9c1 --limit 20'],
-        run: runSessionPeekCli,
-      },
     },
   },
   task: {
@@ -231,7 +275,6 @@ for (const [noun, cmd] of Object.entries(COMMANDS)) {
   cmd.name = noun;
   for (const [verb, v] of Object.entries(cmd.verbs || {})) v.name = `${noun} ${verb}`;
 }
-
 function runCli(argv) {
   if (argv.includes('--version') || argv.includes('-v')) {
     console.log(require('./package.json').version);
@@ -266,7 +309,7 @@ function runCli(argv) {
       printLeafHelp(cli.entry);
       process.exit(0);
     }
-    cli.entry.run(cli.args)
+    cli.entry.run(cli.args, cli.entry)
       .then(code => { process.exitCode = code; })
       .catch(e => { console.error(e.message); process.exitCode = 1; });
     return true;
@@ -423,12 +466,14 @@ async function cliFetch(urlPath, init) {
   }
 }
 
-// Every write verb posts JSON and reports failure the same way; `label` names the verb
-// in the error line. Returns false when the server refused, so callers just return 1.
-// Returns the parsed response body ({} when empty), or null after printing the failure.
-async function cliPostJson(urlPath, body, label, headers = {}) {
+const cliPostJson = (urlPath, body, label, headers) => cliSendJson('POST', urlPath, body, label, headers);
+
+// Every write verb sends JSON and reports failure the same way; `label` names the verb
+// in the error line. Returns the parsed response body ({} when empty), or null after
+// printing the failure, so callers just return 1.
+async function cliSendJson(method, urlPath, body, label, headers = {}) {
   const res = await cliFetch(urlPath, {
-    method: 'POST',
+    method,
     headers: { 'Content-Type': 'application/json', ...headers },
     body: JSON.stringify(body)
   });
@@ -447,13 +492,15 @@ function reportCliError(e) {
 async function runPreviewCli(args) {
   const filePathArg = args.find(a => !a.startsWith('--'));
   if (!filePathArg) {
-    printLeafHelp(COMMANDS['preview-doc']);
+    printLeafHelp(COMMANDS.doc.verbs.preview);
     return 1;
   }
-  const sessionId = getArgValue(args, 'session') || process.env.PREVIEW_SESSION || null;
   const url = linkUrl(filePathArg);
-  if (url) return previewUrlCli(url, sessionId);
-  const abs = path.resolve(filePathArg);
+  if (url) return previewUrlCli(url, args);
+  // No $CLAUDE_CODE_SESSION_ID fallback: a session here switches the board's focus, and the
+  // agent must not move the board unless asked.
+  const sessionId = getArgValue(args, 'session') || process.env.PREVIEW_SESSION || null;
+  const abs = cliPath(filePathArg);
   try {
     if (!await cliPostJson('/api/preview', { path: abs, sessionId }, 'Preview')) return 1;
     console.log(`Preview opened: ${abs}${sessionId ? ` (session ${sessionId})` : ''}`);
@@ -463,12 +510,9 @@ async function runPreviewCli(args) {
 
 // The modal cannot show a web page, so a URL is linked instead and the tab on screen
 // offers to open it.
-async function previewUrlCli(url, sessionArg) {
-  const entry = COMMANDS['preview-doc'];
-  if (!sessionArg) return usageError(entry, '--session is required for a URL: it is linked to the session.');
-  const resolved = await resolveSessionByIdOrPrefix(sessionArg);
-  if (!resolved) return 1;
-  return postDocLink(url, resolved.id, { open: true });
+async function previewUrlCli(url, args) {
+  const resolved = await resolveSessionArg(COMMANDS.doc.verbs.preview, args, 'a URL is linked to the session.');
+  return resolved ? postDocLink(url, resolved.id, { open: true }) : 1;
 }
 
 async function postDocLink(target, sessionId, { unlink = false, open = false } = {}) {
@@ -482,22 +526,94 @@ async function postDocLink(target, sessionId, { unlink = false, open = false } =
   } catch (e) { reportCliError(e); return 1; }
 }
 
-async function runLinkDocCli(args) {
-  const entry = COMMANDS['link-doc'];
+// Resolved to the full id because the browser keys linked docs by it, so a prefix won't match.
+async function resolveSessionArg(entry, args, why) {
+  const sessionArg = getArgValue(args, 'session') || process.env.PREVIEW_SESSION || process.env.CLAUDE_CODE_SESSION_ID;
+  if (!sessionArg) {
+    usageError(entry, `--session is required: ${why}`);
+    return null;
+  }
+  return resolveSessionByIdOrPrefix(sessionArg);
+}
+
+async function runDocLinkCli(args, entry) {
   const [filePathArg] = positionals(args, ['--session']);
-  const sessionArg = getArgValue(args, 'session') || process.env.PREVIEW_SESSION || null;
-  const list = args.includes('--list');
-  if (!filePathArg && !list) {
+  if (!filePathArg) {
     printLeafHelp(entry);
     return 1;
   }
-  if (!sessionArg) return usageError(entry, '--session is required: linked docs are stored per session.');
-  const unlink = args.includes('--unlink');
-  // Resolved here because the browser keys linked docs by full id, so a prefix won't match.
-  const resolved = await resolveSessionByIdOrPrefix(sessionArg);
+  const resolved = await resolveSessionArg(entry, args, 'linked docs are stored per session.');
   if (!resolved) return 1;
-  if (list) return printLinkedDocs(resolved.id, args.includes('--json'));
-  return postDocLink(linkUrl(filePathArg) || path.resolve(filePathArg), resolved.id, { unlink });
+  const unlink = entry === COMMANDS.doc.verbs.unlink;
+  return postDocLink(cliTarget(filePathArg), resolved.id, { unlink });
+}
+
+async function runDocListCli(args, entry) {
+  const resolved = await resolveSessionArg(entry, args, 'linked docs are stored per session.');
+  return resolved ? printLinkedDocs(resolved.id, args.includes('--json')) : 1;
+}
+
+// The server resolves a path against its own cwd, so a relative one is made absolute here.
+const cliTarget = (arg) => linkUrl(arg) || cliPath(arg);
+
+const PANES_WHY = 'panes are stored per session.';
+
+const panesPath = (sessionId, paneId) =>
+  `/api/panes/${encodeURIComponent(sessionId)}${paneId ? `/${encodeURIComponent(paneId)}` : ''}`;
+
+async function runPaneAddCli(args, entry) {
+  const [target] = positionals(args, ['--session', '--title']);
+  if (!target) {
+    printLeafHelp(entry);
+    return 1;
+  }
+  const resolved = await resolveSessionArg(entry, args, PANES_WHY);
+  if (!resolved) return 1;
+  try {
+    const body = { target: cliTarget(target), title: getArgValue(args, 'title') || '' };
+    const out = await cliPostJson(panesPath(resolved.id), body, 'Pane add');
+    if (!out) return 1;
+    const { pane } = out;
+    let frameable;
+    if (pane.kind === 'url') {
+      try {
+        ({ frameable } = await cliGetJson(`${panesPath(resolved.id, pane.id)}/framing`, 'Pane framing'));
+      } catch {}
+    }
+    if (args.includes('--json')) console.log(JSON.stringify({ ...pane, frameable }, null, 2));
+    else console.log(`${pane.id}  ${pane.title}${out.added ? '' : ' (already there)'}`);
+    if (frameable === false && !args.includes('--json')) {
+      console.log(`note: ${new URL(pane.target).host} refuses framing, so the pane shows an "Open in new tab" card. Look for a URL of the same content that allows framing.`);
+    }
+    return 0;
+  } catch (e) { reportCliError(e); return 1; }
+}
+
+async function runPaneRmCli(args, entry) {
+  const [paneId] = positionals(args, ['--session']);
+  if (!paneId) {
+    printLeafHelp(entry);
+    return 1;
+  }
+  const resolved = await resolveSessionArg(entry, args, PANES_WHY);
+  if (!resolved) return 1;
+  try {
+    if (!await cliSendJson('DELETE', panesPath(resolved.id, paneId), undefined, 'Pane rm')) return 1;
+    console.log(`Removed pane ${paneId} from session ${resolved.id.slice(0, 8)}`);
+    return 0;
+  } catch (e) { reportCliError(e); return 1; }
+}
+
+async function runPaneListCli(args, entry) {
+  const resolved = await resolveSessionArg(entry, args, PANES_WHY);
+  if (!resolved) return 1;
+  try {
+    const layout = await cliGetJson(panesPath(resolved.id), 'Pane list');
+    if (args.includes('--json')) console.log(JSON.stringify(layout, null, 2));
+    else if (!layout.panes.length) console.log(`No panes for session ${resolved.id.slice(0, 8)}.`);
+    else printTable(['ID', 'KIND', 'TITLE', 'TARGET'], layout.panes.map((p) => [p.id, p.kind, p.title, p.target]));
+    return 0;
+  } catch (e) { reportCliError(e); return 1; }
 }
 
 async function printLinkedDocs(sessionId, asJson) {
@@ -693,53 +809,6 @@ async function runSessionPinCli(args) {
   } catch (e) { reportCliError(e); return 1; }
 }
 
-async function runSessionPinsCli(args) {
-  const stickyOnly = args.includes('--sticky');
-  const asJson = args.includes('--json');
-  const pinsMap = await fetchPinsMap();
-  const items = Object.entries(pinsMap)
-    .filter(([, state]) => !stickyOnly || state === 'sticky')
-    .map(([id, state]) => ({ id, state }));
-  if (!items.length) {
-    if (asJson) console.log('[]'); else console.log('No pinned sessions.');
-    return 0;
-  }
-  let sessions;
-  try {
-    sessions = await fetchSessionsList(items.length, items.map(p => p.id));
-  } catch (e) { reportCliError(e); return 1; }
-  const byId = new Map(sessions.map(s => [s.id, s]));
-  const rows = items
-    .map(p => {
-      const s = byId.get(p.id) || {};
-      return {
-        id: p.id,
-        state: p.state,
-        status: s.id ? sessionStatus(s) : '-',
-        age: s.modifiedAt ? formatAge(Date.now() - new Date(s.modifiedAt).getTime()) : '-',
-        project: path.basename(s.project || ''),
-        title: s.customTitle || s.name || s.slug || '',
-      };
-    })
-    .sort((a, b) => (a.state === b.state ? 0 : a.state === 'sticky' ? -1 : 1));
-  if (asJson) {
-    console.log(JSON.stringify(rows, null, 2));
-    return 0;
-  }
-  const w = {
-    id: 8,
-    state: Math.max(5, ...rows.map(r => r.state.length)),
-    status: Math.max(6, ...rows.map(r => r.status.length)),
-    age: Math.max(3, ...rows.map(r => r.age.length)),
-    project: Math.max(7, ...rows.map(r => r.project.length)),
-  };
-  console.log(`${'ID'.padEnd(w.id)}  ${'STATE'.padEnd(w.state)}  ${'STATUS'.padEnd(w.status)}  ${'AGE'.padEnd(w.age)}  ${'PROJECT'.padEnd(w.project)}  TITLE`);
-  for (const r of rows) {
-    console.log(`${r.id.slice(0, 8).padEnd(w.id)}  ${r.state.padEnd(w.state)}  ${r.status.padEnd(w.status)}  ${r.age.padEnd(w.age)}  ${r.project.padEnd(w.project)}  ${r.title}`);
-  }
-  return 0;
-}
-
 async function runSessionViewCli(args) {
   const idArg = args.find(a => !a.startsWith('--'));
   if (!idArg) {
@@ -796,49 +865,11 @@ async function runSessionViewCli(args) {
   if (rl.five_hour || rl.seven_day) {
     lines.push(`  Limits: 5h ${rl.five_hour?.used_percentage ?? '-'}% · 7d ${rl.seven_day?.used_percentage ?? '-'}%`);
   }
+  if (s.jsonlPath) lines.push(`  Transcript: ${s.jsonlPath}`);
   console.log(lines.join('\n'));
   return 0;
 }
 
-async function runSessionPeekCli(args) {
-  const idArg = args.find(a => !a.startsWith('--'));
-  if (!idArg) {
-    printLeafHelp(COMMANDS.session.verbs.peek);
-    return 1;
-  }
-  const parsed = parseLimit(args, { fallback: 10 });
-  if (!parsed.ok) return usageError(COMMANDS.session.verbs.peek, parsed.error);
-  const limit = parsed.limit;
-  const asJson = args.includes('--json');
-  const resolved = await resolveSessionByIdOrPrefix(idArg);
-  if (!resolved) return 1;
-  try {
-    const res = await cliFetch(`/api/sessions/${resolved.id}/messages?limit=${Math.min(limit, 50)}`);
-    if (!res.ok) {
-      console.error(`Peek failed (${res.status}): ${await res.text()}`);
-      return 1;
-    }
-    const { messages } = await res.json();
-    const ordered = [...messages].reverse();
-    if (asJson) {
-      console.log(JSON.stringify(ordered, null, 2));
-      return 0;
-    }
-    if (!ordered.length) {
-      console.log(`No messages for session ${resolved.id.slice(0, 8)}.`);
-      return 0;
-    }
-    console.log(`Session ${resolved.id.slice(0, 8)}${resolved.customTitle ? ` — ${resolved.customTitle}` : ''}`);
-    for (const m of ordered) {
-      const ts = m.timestamp ? new Date(m.timestamp).toLocaleTimeString('en-GB', { hour12: false }) : '--:--:--';
-      const label = (m.type === 'tool_use' ? (m.tool || 'tool') : m.type).padEnd(10);
-      const body = (m.text || m.detail || m.description || '').replace(/\s+/g, ' ').trim();
-      console.log(`[${ts}] ${label} ${body.slice(0, 120)}${body.length > 120 ? '…' : ''}`);
-    }
-    return 0;
-  } catch (e) { reportCliError(e); return 1; }
-}
-
 function printTable(header, rows) {
   const last = header.length - 1;
   const width = header.map((h, i) => Math.max(h.length, ...rows.map(r => String(r[i]).length)));
@@ -1008,12 +1039,17 @@ function positionals(args, valueFlags) {
 // The server matches the folder against known project paths by string, so an 8.3 short name
 // or a differently cased drive letter from the shell must become the long, canonical form.
 function canonicalDir(dir) {
-  try { return fs.realpathSync.native(path.resolve(dir)); } catch (_) { return path.resolve(dir); }
+  try { return fs.realpathSync.native(cliPath(dir)); } catch (_) { return cliPath(dir); }
+}
+
+// Every path argument goes through here. Git Bash hands a native node `/c/x` for `C:\x`.
+function cliPath(arg) {
+  return path.resolve(process.platform === 'win32' ? arg.replace(/^\/([a-zA-Z])(?=\/|$)/, '$1:/') : arg);
 }
 
 function textArg(args, name) {
   const file = getArgValue(args, `${name}-file`);
-  return file ? fs.readFileSync(path.resolve(file), 'utf8') : getArgValue(args, name);
+  return file ? fs.readFileSync(cliPath(file), 'utf8') : getArgValue(args, name);
 }
 
 async function runDispatchStartCli(argv) {
@@ -1086,4 +1122,4 @@ async function runSkillsGetCli(args) {
   return 0;
 }
 
-module.exports = { runCli };
+module.exports = { runCli, COMMANDS };

package/lib/frame-policy.js

@@ -0,0 +1,79 @@
+// Whether a page lets the board frame it, from its response headers. The parent page gets no
+// signal when a cross-origin frame is refused (Chrome fires `load` on its error page), so the
+// server reads the headers instead. Rules: CSP3 frame-ancestors (it wins over X-Frame-Options
+// when present) and the HTML spec's X-Frame-Options processing.
+
+const { portOf } = require('./panes');
+
+const PROBE_TIMEOUT_MS = 5000;
+
+function parseOrigin(value) {
+  try {
+    const u = new URL(value);
+    return u.protocol === 'http:' || u.protocol === 'https:' ? u : null;
+  } catch {
+    return null;
+  }
+}
+
+// CSP3 lets an http source match https too.
+const schemeOk = (want, got) => want === got || (want === 'http:' && got === 'https:');
+
+function matchesSource(source, ancestor, self) {
+  const s = source.toLowerCase();
+  if (s === "'self'") return ancestor.origin === self.origin;
+  if (s === '*') return true;
+  if (/^[a-z][a-z0-9+.-]*:$/.test(s)) return schemeOk(s, ancestor.protocol);
+  const m = /^(?:([a-z][a-z0-9+.-]*):\/\/)?(\*|(?:\*\.)?[^:/]+)(?::(\d+|\*))?(?:\/.*)?$/.exec(s);
+  if (!m) return false;
+  const [, scheme, host, port] = m;
+  const want = scheme ? `${scheme}:` : self.protocol;
+  if (!schemeOk(want, ancestor.protocol)) return false;
+  const hostOk = host === '*' || (host.startsWith('*.') ? ancestor.hostname.endsWith(host.slice(1)) : host === ancestor.hostname);
+  if (!hostOk) return false;
+  if (port === '*' || (!port && ancestor.port === '')) return true;
+  return Number(port) === portOf(ancestor) || (port === '80' && ancestor.protocol === 'https:' && ancestor.port === '');
+}
+
+function frameAncestorsLists(csp) {
+  const lists = [];
+  for (const policy of String(csp || '').split(',')) {
+    for (const directive of policy.split(';')) {
+      const [name, ...sources] = directive.trim().split(/\s+/);
+      if (name?.toLowerCase() === 'frame-ancestors') {
+        lists.push(sources);
+        break;
+      }
+    }
+  }
+  return lists;
+}
+
+// headers: Fetch Headers. target: the final URL of the response. ancestors: every origin above
+// the frame. Answers true, false, or null when it cannot tell.
+function framingVerdict(headers, { target, ancestors }) {
+  const self = parseOrigin(target);
+  const chain = ancestors.map(parseOrigin).filter(Boolean);
+  if (!self || !chain.length) return null;
+  const lists = frameAncestorsLists(headers.get('content-security-policy'));
+  if (lists.length) return lists.every((sources) => chain.every((a) => sources.some((src) => matchesSource(src, a, self))));
+  const xfo = String(headers.get('x-frame-options') || '')
+    .split(',')
+    .map((v) => v.trim().toLowerCase());
+  if (xfo.includes('deny')) return false;
+  return !xfo.includes('sameorigin') || chain.every((a) => a.origin === self.origin);
+}
+
+// GETs the page and drops the body once the headers arrive. A network error or a timeout
+// answers null, and the board frames the page anyway.
+async function probeFraming(target, ancestors, { fetchImpl = fetch } = {}) {
+  try {
+    const res = await fetchImpl(target, { redirect: 'follow', signal: AbortSignal.timeout(PROBE_TIMEOUT_MS) });
+    res.body?.cancel().catch(() => {});
+    return framingVerdict(res.headers, { target: res.url || target, ancestors });
+  } catch {
+    return null;
+  }
+}
+
+module.exports = { framingVerdict, parseOrigin, probeFraming };

package/lib/http-error.js

@@ -0,0 +1,6 @@
+// An error a route answers with `status`; `code` is the machine-readable reason, where one is set.
+function httpError(status, message, code) {
+  return Object.assign(new Error(message), { status, code });
+}
+
+module.exports = { httpError };

package/lib/linked-docs.js

@@ -1,10 +1,8 @@
 // Server copy of each session's linked docs: file paths and http(s) URLs. The browser keeps its own list in localStorage
-// and merges this one in when it connects, so a `link-doc` sent while no tab is open is not lost.
+// and merges this one in when it connects, so a `doc link` sent while no tab is open is not lost.
 // Newest first, capped like the browser list.
 
-const { linkUrl } = require('../public/link-url');
-
-const MAX_PER_SESSION = 20;
+const { linkUrl, MAX_LINKED_DOCS } = require('../public/link-url');
 
 // Same rule as `canonicalPath` in public/app.js: one Windows file is reached as `C:\a` and `c:/a`.
 function canonicalPath(p) {
@@ -23,7 +21,7 @@ function createLinkedDocStore({ load, save }) {
   if (saved && typeof saved === 'object') {
     for (const [id, paths] of Object.entries(saved)) {
       const clean = Array.isArray(paths) ? paths.filter((p) => typeof p === 'string' && p) : [];
-      if (clean.length) bySession.set(id, clean.slice(0, MAX_PER_SESSION));
+      if (clean.length) bySession.set(id, clean.slice(0, MAX_LINKED_DOCS));
     }
   }
 
@@ -32,7 +30,7 @@ function createLinkedDocStore({ load, save }) {
   function link(sessionId, filePath) {
     const key = canonicalPath(filePath);
     const rest = (bySession.get(sessionId) || []).filter((p) => canonicalPath(p) !== key);
-    bySession.set(sessionId, [filePath, ...rest].slice(0, MAX_PER_SESSION));
+    bySession.set(sessionId, [filePath, ...rest].slice(0, MAX_LINKED_DOCS));
     persist();
   }
 
@@ -55,4 +53,4 @@ function createLinkedDocStore({ load, save }) {
   return { link, unlink, get, all };
 }
 
-module.exports = { createLinkedDocStore, canonicalPath, linkUrl, MAX_PER_SESSION };
+module.exports = { createLinkedDocStore, canonicalPath, linkUrl, MAX_LINKED_DOCS };

package/lib/one-line.js

@@ -0,0 +1,6 @@
+function oneLine(text, max) {
+  // biome-ignore lint/suspicious/noControlCharactersInRegex: strips control characters on purpose
+  return String(text ?? '').replace(/[\x00-\x1f\x7f]/g, ' ').trim().slice(0, max);
+}
+
+module.exports = { oneLine };