@khanglvm/relay 0.9.0 → 0.10.0

package/README.md

@@ -45,6 +45,7 @@ refreshes the skill in one step, leaving any boards you have open untouched.
 | "Option B is the one with caching (see my last message)" | Each answer option carries its own image / chart / diagram — pick by looking |
 | ASCII architecture art | Mermaid, Graphviz, PlantUML — zoomable, full-screen, even user-editable |
 | Numbers buried in prose | Charts and sortable tables; screenshots and HTML prototypes in a sandbox |
+| "Here's the diff — paste it in your editor" | Side-by-side **diff** blocks, syntax-highlighted **code**, **video** walkthroughs, and **file paths you click to open** in the default app |
 | "Type *done* when finished reviewing" | A Submit button; answers, notes, and inline comments returned as JSON |
 | Feedback = another wall of text | Click any chart point, diagram node, table cell, or sentence to comment — the agent replies and the thread grows on the board |
 
@@ -71,6 +72,34 @@ npm test     # zero-dep smoke tests (spawns real servers, fake-submits)
 
 ## Changelog
 
+### 0.10.0 — open files, richer code, diffs & video
+- **Clickable local file-links.** Write a path in any markdown (`~/clip.mp4`,
+  `./src/app.ts`, `/abs/report.pdf`, a `file://` URL, a backtick-wrapped path,
+  or `[label](path)`) and it renders as a link that opens the file in the OS
+  default app — guarded by a same-origin check + an allowlist of paths the
+  board actually references. `RLY_OPEN_CMD` overrides the opener.
+- **`code` blocks leveled up** — syntax highlighting for ~20 languages (js, ts,
+  py, go, rust, java, c, cpp, csharp, ruby, php, swift, kotlin, sql, yaml, json,
+  sh, css, html…), a line-number gutter, a filename/lang header, and `codeFile`
+  to load source straight from a local file.
+- **`diff` block** — render a unified git diff as a colored, line-numbered
+  comparison with a live **Unified ⇄ Split (side-by-side)** toggle. No git
+  required; the agent supplies the diff text (`diff`/`diffFile`, `view`).
+- **`video` block** — YouTube/Vimeo embeds, a direct media URL, or a local
+  video file streamed from the server with HTTP Range (seekable), never
+  embedded in the payload.
+- **Durable drafts / rescue** — every autosave mirrors to `localStorage`; a
+  board whose connection drops blocks further input instead of losing it, and
+  `rly rescue <id>` re-serves on the same port so an open tab reconnects.
+- Still **zero runtime dependencies**, offline, and cross-platform.
+
+### 0.9.1
+- The board **intro renders as markdown** (bold/italic/code/links/lists).
+
+### 0.9.0 — interactive visual annotations
+- Drag/zoom/full-screen viewer, per-element **and** whole-block comments, chart
+  data-point comment badges, and inline-SVG PlantUML rendering.
+
 ### 0.8.1
 - `rly install` adds **OpenCode** (`~/.config/opencode/AGENTS.md`) and **Droid /
   Factory** (`~/.factory/AGENTS.md`) targets.

package/docs/AGENT.md

@@ -249,8 +249,28 @@ Rules of thumb:
 }
 // columns may also be plain string array; rows may be parallel arrays [[val,val],...]
 
-// Code — styled pre/code block
-{ "type": "code", "lang": "js", "code": "const x = 1 + 2;" }
+// Code — syntax-highlighted + line-numbered. Inline "code" or load a local
+// file with "codeFile" (lang then defaults from the extension). "filename"
+// shows a header label. Highlighted langs: js ts py go rust java c cpp csharp
+// ruby php swift kotlin sql yaml json sh css html (+ aliases) — others plain.
+{ "type": "code", "lang": "js", "code": "const x = 1 + 2;", "filename": "demo.js" }
+{ "type": "code", "codeFile": "src/server.js" }
+
+// Diff — a unified diff (git diff / `diff -u` output) rendered as a colored,
+// line-numbered comparison: +added / −removed / context, file & hunk headers.
+// No git needed — just write/paste the diff text. "lang" tints each code line;
+// "diffFile" loads it from a local file. "view":"split" starts side-by-side
+// (old vs new); the viewer has a live Unified⇄Split toggle either way.
+{
+  "type": "diff", "lang": "js", "filename": "src/auth.js", "view": "split",
+  "diff": "@@ -1,3 +1,3 @@\n function login(u) {\n-  return check(u)\n+  return check(u.trim())\n }"
+}
+
+// Video — a YouTube/Vimeo URL embeds a player; an http(s) media URL or a local
+// video file (mp4/webm/ogv/mov/mkv/m4v) plays inline. Local files STREAM from
+// the server (Range-enabled, seekable) and are never embedded in the payload.
+{ "type": "video", "src": "https://youtu.be/dQw4w9WgXcQ", "title": "Demo walkthrough" }
+{ "type": "video", "src": "recordings/demo.mp4", "title": "Local capture", "height": 360 }
 
 // HTML — sandboxed iframe; default height 360
 { "type": "html", "html": "<h1>Hello</h1>", "height": 360 }
@@ -262,6 +282,16 @@ Rules of thumb:
 { "type": "image", "src": "https://example.com/mock.png" }
 ```
 
+### Local file links — clickable, open in the default app
+
+Inside any **markdown** (the intro or a `markdown` block) just write a local
+file path — `~/clip.mp4`, `./src/app.ts`, `/abs/report.pdf`, a `file://` URL,
+or a backtick-wrapped path — and it renders as a click-to-open link. Clicking it
+asks relay to open that file in the user's OS default app (video player, editor,
+viewer, …); a `[label](~/path)` link works too. Only paths you actually wrote on
+the board can be opened (same-origin + allowlist guarded), so prefer surfacing a
+real path over telling the user to paste it into a terminal.
+
 ### When to use which block
 
 | Block | Best for |
@@ -272,7 +302,9 @@ Rules of thumb:
 | `chart` | numbers, trends, comparisons, metrics |
 | `table` | structured comparisons, option matrices, data grids — **use this for any tabular data**: it's sortable and every cell is commentable, unlike a markdown pipe table |
 | `markdown` | prose context, background, instructions, section headings (renders GFM pipe tables too, but reach for a `table` block for real data) |
-| `code` | code snippets, config examples, command output |
+| `code` | code snippets, config examples, command output — syntax-highlighted + line-numbered; load from a file with `codeFile` |
+| `diff` | proposed code changes / before-after — a unified diff rendered as a colored git-style comparison (no git needed) |
+| `video` | demos, screen recordings, walkthroughs — YouTube/Vimeo embeds, a media URL, or a local video file (streamed) |
 | `image` | screenshots, mockup exports, photos — local files embed and work offline |
 | `html` | anything else — pixel-perfect mockups, custom widgets, embeds |
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@khanglvm/relay",
-  "version": "0.9.0",
-  "description": "Browser-based question boards with rich blocks (markdown, charts, mermaid, tables, code, sandboxed HTML) and element-level annotations for AI coding agents (Claude Code, Codex, …): ask users structured questions, present interactive visuals, collect inline comments, wait for submit, read answers as JSON.",
+  "version": "0.10.0",
+  "description": "Browser-based question boards with rich blocks (markdown, charts, mermaid, tables, code, diffs, video, sandboxed HTML), clickable local file-links, and element-level annotations for AI coding agents (Claude Code, Codex, …): ask users structured questions, present interactive visuals, collect inline comments, wait for submit, read answers as JSON.",
   "keywords": [
     "ai-agents",
     "claude-code",

package/src/cli.js

@@ -295,6 +295,42 @@ async function cmdReopen(args) {
   return runOrDetach(record, args);
 }
 
+// Rescue a board whose browser tab is still open but disconnected (its server
+// died / the machine slept). Re-serves the SAME board on the SAME port it last
+// used, so the open tab's relative /api/* fetches reconnect on their own — the
+// page's recovery loop lifts its "connection lost" block and re-flushes the
+// draft (incl. anything the user mirrored to localStorage during the outage)
+// with zero action from the user. Defaults to NOT opening a new browser tab
+// (the point is the existing one); pass --open to also open a fresh tab.
+async function cmdRescue(args) {
+  const record = mustLoad(args._[0]);
+  const running = loadRunning(record.id);
+  if (running && isAlive(running.pid)) {
+    if (args.open) openUrl(running.url);
+    printJson({
+      status: 'open',
+      boardId: record.id,
+      url: running.url,
+      port: running.port,
+      note: 'already running — the open tab should be connected; reload it if not',
+    });
+    return 0;
+  }
+  if (!record.lastPort) {
+    throw new CliError(
+      `board "${record.id}" has no known port to reuse (never served in this version). Use \`rly reopen ${record.id}\` instead.`,
+      5
+    );
+  }
+  // Force the original port so the disconnected tab can reconnect; default to
+  // not opening a second tab. seedAgentReplies parity with reopen if provided.
+  if (args.replies !== undefined) {
+    const replies = parseJson(readFileOrThrow(args.replies), args.replies);
+    seedAgentReplies(record, replies);
+  }
+  return runOrDetach(record, { ...args, port: record.lastPort, open: args.open === true });
+}
+
 async function cmdReuse(args) {
   const src = mustLoad(args._[0]);
   if (args.dump) {
@@ -1141,6 +1177,9 @@ USAGE
   rly open [id]                       re-open the browser tab of a running board
   rly reopen <id> [--replies f.json]  serve a saved board again, prefilled with saved answers
                                       (--replies [{annotationId,text}] = agent answers to element comments)
+  rly rescue <id> [--open]            re-serve a board on its ORIGINAL port so a still-open but
+                                      disconnected browser tab auto-reconnects & re-saves (no new tab
+                                      unless --open). Use when a tab shows "connection lost".
   rly reuse <id> [--dump]             re-run a past board as a new board (--dump prints its spec)
   rly update <id> --file spec.json    live-mutate a RUNNING board (or --title/--intro/-q); page reloads
   rly stop <id> | --all               stop running board(s) (status: cancelled, draft preserved)
@@ -1196,6 +1235,8 @@ export async function main(argv) {
         return await cmdAsk(parseArgs(rest), 'show');
       case 'reopen':
         return await cmdReopen(parseArgs(rest));
+      case 'rescue':
+        return await cmdRescue(parseArgs(rest));
       case 'reuse':
         return await cmdReuse(parseArgs(rest));
       case 'update':

package/src/open.js

@@ -1,7 +1,19 @@
 import { spawn } from 'node:child_process';
 
+// Opens a URL OR a local file/folder path in the OS default handler (browser
+// for http(s), the registered app for a file). On success the file opens in
+// whatever the user set as default (video player, editor, image viewer, …).
+//
+// RLY_OPEN_CMD overrides the platform opener with a custom command — the target
+// is passed as its sole argument ("$1"). Power users can point it at a chooser;
+// the test suite points it at a no-op so opening a file launches nothing.
 export function openUrl(url) {
   try {
+    const custom = process.env.RLY_OPEN_CMD;
+    if (custom && custom.trim()) {
+      spawn('/bin/sh', ['-c', `${custom} "$1"`, 'sh', url], { stdio: 'ignore', detached: true }).unref();
+      return true;
+    }
     const p = process.platform;
     const [cmd, args] =
       p === 'darwin' ? ['open', [url]]

package/src/server.js

@@ -1,5 +1,6 @@
 import http from 'node:http';
 import fs from 'node:fs';
+import os from 'node:os';
 import path from 'node:path';
 import crypto from 'node:crypto';
 import { spawn } from 'node:child_process';
@@ -47,6 +48,11 @@ function clientBlock(b) {
   if (b && b.type === 'image' && typeof b.src === 'string' && b.src.startsWith('data:')) {
     return { id: b.id, type: 'image', alt: b.alt, height: b.height, hasData: true };
   }
+  // Local video: the absolute file path stays server-side; the client gets a
+  // flag + mime and loads the bytes (Range-streamed) from /video/b/<id>.
+  if (b && b.type === 'video' && typeof b.file === 'string') {
+    return { id: b.id, type: 'video', title: b.title, height: b.height, mime: b.mime, hasFile: true };
+  }
   return b;
 }
 
@@ -113,6 +119,10 @@ function buildPage(record, rev) {
         notes: record.draft.notes || {},
         annotations: record.draft.annotations || [],
         blockEdits: record.draft.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,
       }
     : null;
   const boot = { boardId: record.id, spec: clientSpec, prefill, pref: loadPref(), vendor, rev };
@@ -211,6 +221,103 @@ function firstQuestionHtml(q) {
   return (q.blocks || []).find((b) => b && b.type === 'html');
 }
 
+// ---------- local-file links (POST /api/open) ----------
+// The markdown renderer turns file paths an agent writes (~/x, ./x, /abs/x,
+// file://…) into click-to-open links. Clicking POSTs the raw path here; the
+// server resolves it against the board's authoring cwd and opens it in the OS
+// default app — BUT only if the path is one the board actually references
+// (allowlist below). That keeps a cross-site/blind POST from opening arbitrary
+// files: the only openable paths are ones the agent already put on the board.
+//
+// FILE_PATH_RE / looksLikeLocalPath MUST stay in sync with the same logic in
+// ui/blocks.js, so the set the server allows matches the set the page links.
+const FILE_PATH_RE =
+  /(?<![\w@:./])(?:file:\/\/\/?[^\s)<>"'`*]+|~\/[^\s)<>"'`*]+|\.{1,2}\/[^\s)<>"'`*]+|\/[^\s)<>"'`*]+|[A-Za-z]:[\\/][^\s)<>"'`*]+)/g;
+
+function looksLikeLocalPath(s) {
+  if (typeof s !== 'string') return false;
+  const t = s.trim();
+  if (!t || /\s/.test(t)) return false;
+  if (/^file:\/\//i.test(t)) return true;
+  if (/^[A-Za-z]:[\\/]/.test(t)) return true; // windows drive
+  if (t === '~' || /^~\//.test(t)) return true;
+  if (/^\.\.?\//.test(t)) return true; // ./ or ../
+  if (t.startsWith('/')) {
+    // a lone "/" or a one-segment "/word" is more likely punctuation/URL — only
+    // treat as a file when it has ≥2 segments or a file extension.
+    return /\/[^/]+\/[^/]/.test(t) || /\.[A-Za-z0-9]{1,8}$/.test(t);
+  }
+  return false;
+}
+
+// Expands ~ / file:// and resolves a (possibly relative) path to an absolute,
+// normalized one against the board's authoring cwd. null on a malformed URL.
+function resolveLocalPath(raw, baseCwd) {
+  let p = String(raw || '').trim();
+  if (!p) return null;
+  if (/^file:\/\//i.test(p)) {
+    try {
+      p = fileURLToPath(p);
+    } catch {
+      return null;
+    }
+  } else if (p === '~' || p.startsWith('~/')) {
+    p = path.join(os.homedir(), p.slice(1));
+  }
+  if (!path.isAbsolute(p)) p = path.resolve(baseCwd || process.cwd(), p);
+  return path.normalize(p);
+}
+
+// Every markdown source the page runs through its inline renderer (intro + any
+// markdown block, board / question / option scoped). These are the only places
+// file paths become clickable, so they define the open allowlist.
+function collectMarkdownSources(spec) {
+  const out = [];
+  if (typeof spec.intro === 'string') out.push(spec.intro);
+  const addBlocks = (blocks) => {
+    for (const b of Array.isArray(blocks) ? blocks : []) {
+      if (b && b.type === 'markdown' && typeof b.md === 'string') out.push(b.md);
+    }
+  };
+  addBlocks(spec.blocks);
+  for (const q of spec.questions || []) {
+    addBlocks(q.blocks);
+    for (const o of Array.isArray(q.options) ? q.options : []) {
+      if (o) addBlocks(o.blocks);
+    }
+  }
+  return out;
+}
+
+// The set of absolute paths the board references and is therefore allowed to
+// open. Rebuilt per request (specs are small) so it tracks live `rly update`s.
+function buildOpenAllowlist(spec, baseCwd) {
+  const set = new Set();
+  const text = collectMarkdownSources(spec).join('\n');
+  const re = new RegExp(FILE_PATH_RE.source, 'g');
+  let m;
+  while ((m = re.exec(text))) {
+    if (!looksLikeLocalPath(m[0])) continue;
+    const abs = resolveLocalPath(m[0], baseCwd);
+    if (abs) set.add(abs);
+  }
+  return set;
+}
+
+// True when an Origin header (if present) belongs to this board's own server.
+// Same-origin fetches send no Origin or our own; a foreign Origin is a
+// cross-site POST and must not be allowed to open a local file.
+function sameOrigin(req, port) {
+  const origin = req.headers.origin;
+  if (!origin) return true;
+  try {
+    const h = new URL(origin).host;
+    return h === `127.0.0.1:${port}` || h === `localhost:${port}`;
+  } catch {
+    return false;
+  }
+}
+
 function sendJson(res, code, obj) {
   if (res.headersSent) return;
   res.writeHead(code, { 'content-type': 'application/json; charset=utf-8', 'cache-control': 'no-store' });
@@ -243,6 +350,57 @@ function sendFromDir(res, dir, name, contentType) {
   return true;
 }
 
+// Streams a file with HTTP Range support so a <video>/<audio> element can seek
+// and the browser can request byte ranges instead of the whole clip. Honors a
+// single "bytes=start-end" range; falls back to the full body otherwise. Safe
+// for a HEAD probe (sends headers, no body).
+function streamFile(req, res, filePath, contentType) {
+  let stat;
+  try {
+    stat = fs.statSync(filePath);
+  } catch {
+    return sendJson(res, 404, { error: 'file not found' });
+  }
+  const total = stat.size;
+  const range = req.headers.range;
+  const baseHeaders = {
+    'content-type': contentType,
+    'accept-ranges': 'bytes',
+    'cache-control': 'no-store',
+  };
+  let start = 0;
+  let end = total - 1;
+  let status = 200;
+  if (range) {
+    const m = /^bytes=(\d*)-(\d*)$/.exec(range.trim());
+    if (m) {
+      if (m[1] === '' && m[2] === '') {
+        // "bytes=-" — unsatisfiable
+      } else if (m[1] === '') {
+        start = Math.max(0, total - Number(m[2])); // suffix range
+      } else {
+        start = Number(m[1]);
+        if (m[2] !== '') end = Math.min(end, Number(m[2]));
+      }
+    }
+    if (start > end || start >= total) {
+      res.writeHead(416, { 'content-range': `bytes */${total}`, 'cache-control': 'no-store' });
+      return res.end();
+    }
+    status = 206;
+    baseHeaders['content-range'] = `bytes ${start}-${end}/${total}`;
+  }
+  baseHeaders['content-length'] = String(end - start + 1);
+  res.writeHead(status, baseHeaders);
+  if (req.method === 'HEAD') return res.end();
+  const stream = fs.createReadStream(filePath, { start, end });
+  stream.on('error', () => {
+    if (!res.headersSent) sendJson(res, 500, { error: 'stream error' });
+    else res.destroy();
+  });
+  stream.pipe(res);
+}
+
 // Loaded into every custom-HTML iframe so users can hover any element to leave a
 // comment (relayKit.annotate.auto). Idempotent with an author-added /kit.js, and
 // a no-op when the author opts out via data-relay-annotate="off".
@@ -450,6 +608,12 @@ 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 === '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));
+        const block = findBlock(record.spec, blockId, 'video');
+        if (!block || typeof block.file !== 'string') return sendJson(res, 404, { error: `no local video block "${blockId}"` });
+        streamFile(req, res, block.file, block.mime || 'application/octet-stream');
       } else if (req.method === 'GET' && pathname === '/html/board') {
         // Legacy alias → the board's first html block.
         const block = firstBoardHtml(record.spec);
@@ -464,6 +628,28 @@ export async function runBoard({ id, port = 0, open = true, timeoutSec = 1800, q
         const body = JSON.parse((await readBody(req)) || '{}');
         if (['auto', 'light', 'dark'].includes(body.theme)) savePref({ theme: body.theme });
         sendJson(res, 200, { ok: true });
+      } else if (req.method === 'POST' && pathname === '/api/open') {
+        // Open a board-referenced local file in the OS default app. Guarded by
+        // a same-origin check + an allowlist of paths the board actually links.
+        if (!sameOrigin(req, actualPort)) return sendJson(res, 403, { error: 'cross-origin requests cannot open files' });
+        const body = JSON.parse((await readBody(req)) || '{}');
+        const raw = typeof body.path === 'string' ? body.path : '';
+        if (!raw.trim()) return sendJson(res, 400, { error: 'missing "path"' });
+        const baseCwd = record.cwd || process.cwd();
+        const target = resolveLocalPath(raw, baseCwd);
+        if (!target) return sendJson(res, 400, { error: 'invalid path' });
+        if (!buildOpenAllowlist(record.spec, baseCwd).has(target)) {
+          return sendJson(res, 403, { error: 'this path is not referenced on the board' });
+        }
+        let stat = null;
+        try {
+          stat = fs.statSync(target);
+        } catch {
+          stat = null;
+        }
+        if (!stat) return sendJson(res, 404, { error: 'file not found', path: target });
+        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') {
         const body = JSON.parse((await readBody(req)) || '{}');
         record.draft = {
@@ -505,6 +691,13 @@ export async function runBoard({ id, port = 0, open = true, timeoutSec = 1800, q
   });
   const actualPort = server.address().port;
   const url = `http://127.0.0.1:${actualPort}/`;
+  // Remember the port this board last bound, so `rly rescue <id>` can re-serve
+  // on the SAME port — letting a still-open (but disconnected) browser tab
+  // reconnect to its relative /api/* URLs without the user touching anything.
+  if (record.lastPort !== actualPort) {
+    record.lastPort = actualPort;
+    saveBoard(record);
+  }
   saveRunning({
     id: record.id,
     pid: process.pid,

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,