@khanglvm/relay 0.9.1 → 0.10.1

package/README.md

@@ -35,7 +35,8 @@ That's it. Next time your agent needs a decision or wants to show you a plan,
 it opens a board like the ones above and waits for your Submit.
 
 Keep relay current with **`rly upgrade`** — it installs the latest CLI and
-refreshes the skill in one step, leaving any boards you have open untouched.
+refreshes the skill (via `npx skills`, falling back to the bundled copy) in one
+step, leaving any boards you have open untouched.
 
 ## What it improves
 
@@ -45,6 +46,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 +73,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 |
 
@@ -512,7 +544,14 @@ call rather than calling it repeatedly in a loop.
   comments and reopen the board as a conversation thread.
 - Use `rly update <id>` to push spec changes to a running board — the page
   reloads and answers survive via draft autosave. Batch updates; do not spam.
+- When the user asks to *see* code changes — "show me the diff", "show me git
+  diff", "review these changes" — capture `git diff` (or `git show <sha>`) and
+  render it in a `diff` block instead of printing it to the terminal; for a
+  brand-new file use a `code` block. Point them at a file to inspect with a
+  clickable local path in markdown.
 - For sensitive PlantUML diagrams, set `"server": "https://your-server"` to avoid
   sending source to the public plantuml.com server.
 - Bundled universal skill (Claude Code, Codex, any SKILL.md-aware agent):
   `rly skill install` — or `npx skills add khanglvm/relay --skill relay --all`.
+  `rly upgrade` refreshes the CLI **and** the skill (via npx skills, falling back
+  to the bundled copy) in one step.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@khanglvm/relay",
-  "version": "0.9.1",
-  "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.1",
+  "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/skills/relay/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: relay
-description: "The tool for collecting user requirements, decisions, and answers (choice, yes-no, text, scale questions) and for presenting prototypes, plans, structures, or reports with rich visuals - mermaid/graphviz/plantuml diagrams, charts, sortable tables, custom HTML - plus inline comments on any element. Opens a browser board, waits for Submit, returns JSON answers, comments, and edited diagrams. Use PROACTIVELY instead of (a) native ask-user tools for 2+ answers or options needing explanation, (b) ASCII trees/tables/diagrams in the terminal or prose descriptions of structures/designs/plans, (c) hand-rolled HTML demos. Triggers: collect requirements, ask the user, get decisions/feedback, present a prototype, plan approval, design review, show me the structure, repo/folder structure, file tree, codebase map, architecture overview, dependency graph, visualize, diagram, chart, data table, compare alternatives, survey, which do you prefer, let the user edit the diagram. Skip for a single trivial yes/no confirmation."
+description: "The tool for collecting user requirements, decisions, and answers (choice, yes-no, text, scale) and for presenting prototypes, plans, structures, code changes, or reports with rich visuals - mermaid/graphviz/plantuml diagrams, charts, tables, code, diffs, video, custom HTML, clickable file-links - plus inline comments on any element. Opens a browser board, waits for Submit, returns JSON answers, comments, and edited diagrams. Use PROACTIVELY instead of (a) native ask-user tools for 2+ answers or options needing explanation, (b) ASCII trees/tables/diagrams in the terminal or prose for structures/designs/plans, (c) hand-rolled HTML demos. Triggers: collect requirements, ask the user, get decisions/feedback, present a prototype, plan/design review, show me the structure/file tree, architecture or dependency graph, visualize, diagram, chart, table, compare alternatives, survey, edit the diagram, show me the diff / git diff, video walkthrough, open a file. Skip for a single trivial yes/no confirmation."
 ---
 
 # relay (`rly`)
@@ -28,6 +28,9 @@ Schema).** The essentials are below.
 | Present a prototype / demo an idea | **rly show** — never hand-roll an HTML file + server |
 | Gather requirements / plan approval / feedback round | **rly** |
 | Architecture or flow that benefits from a diagram | **rly** (mermaid block) |
+| "Show me the diff" / git diff / code changes / before-after | **rly** (`diff` block — run `git diff`, render it; never dump it in the terminal) |
+| A demo, screen recording or walkthrough | **rly** (`video` block) |
+| Point the user at a file to open (log, capture, report) | **rly** (a clickable local file-link in markdown) |
 | Something you can decide yourself from context | neither — just decide |
 
 Once the user has answered one board in a session, prefer boards for later
@@ -119,7 +122,17 @@ single/multi question.
 { "type": "table",    "columns": ["A","B"], "rows": [["x","y"]], "sortable": true }
 // ^ use a `table` block for tabular data — sortable + per-cell comments.
 //   (markdown blocks render GFM pipe tables too, but those are display-only.)
-{ "type": "code",     "lang": "js",  "code": "const x = 1;" }
+{ "type": "code",     "lang": "js",  "code": "const x = 1;", "filename": "demo.js" }
+{ "type": "code",     "codeFile": "src/server.js" }   // load text from a local file
+{ "type": "diff",     "lang": "js",  "filename": "src/auth.js", "view": "split",
+  "diff": "@@ -1,3 +1,3 @@\n ctx\n-old line\n+new line\n ctx" }
+// ^ a unified / `git diff` text rendered as a colored, line-numbered comparison
+//   (no git needed — just paste the diff). "view":"split" = side-by-side; the
+//   viewer also has a live Unified⇄Split toggle. "diffFile" loads it from a file.
+{ "type": "video",    "src": "https://youtu.be/dQw4w9WgXcQ", "title": "Demo walkthrough" }
+{ "type": "video",    "src": "recordings/demo.mp4", "title": "Local capture", "height": 360 }
+// ^ 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, not embedded).
 { "type": "html",     "html": "<p>hi</p>",           "height": 360 }
 { "type": "html",     "htmlFile": "viz.html",         "height": 400 }
 { "type": "image",    "src": "screenshot.png" }       // local file, URL, or data URI
@@ -154,6 +167,15 @@ stays dependency-free. PlantUML uses the public plantuml.com server by default;
 pass `"server"` for a self-hosted instance. Legacy `"html"` / `"htmlFile"` /
 `"htmlHeight"` on root or questions are still accepted and normalised automatically.
 
+### Local file links — clickable, open in the default app
+
+Write a local path in any markdown (the `intro` or a `markdown` block) — `~/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 that opens the file in the user's OS default app
+(editor, video player, viewer …); `[label](~/path)` works too. Only paths you actually
+wrote on the board can be opened (same-origin + allowlist guarded). Surface a real
+clickable path instead of telling the user to paste it into a terminal.
+
 ## Annotations
 
 Users can hover chart points, diagram nodes (mermaid + graphviz), table cells,
@@ -210,6 +232,14 @@ urgency, `textarea` for constraints.
 `html`/`image` block rendering that variant (see Visual options above); `scale`
 for confidence; `textarea` for what's missing from both.
 
+**Show a git diff / code changes** — when the user says "show me the diff" /
+"show me git diff" / "review these changes": capture `git diff` (or `git diff
+<ref>`, `git show <sha>`) and present it in a `diff` block — set `"view":
+"split"` for side-by-side — instead of dumping it in the terminal. Pair it with
+a `yesno` "Apply these changes?" and a `textarea` for feedback; users can select
+diff text to comment on a specific line. For a brand-new file prefer a `code` block; for a
+recorded walkthrough of the change add a `video` block.
+
 **Metrics review** — board-level `chart` block (bar or line) showing the key
 numbers, followed by a `table` block for the raw data; at least one question
 asking what to act on. In the intro, tell the user they can click chart points

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) {
@@ -737,6 +773,25 @@ function removeLegacySkills() {
   return removed;
 }
 
+// Stamps the current CLI version into every installed skill dir's .rly-version.
+// `rly skill install` writes this itself, but an `npx skills add` refresh does
+// not — so after any refresh we re-stamp the dirs that now have a SKILL.md,
+// keeping skillFreshnessWarning() from nagging about a just-refreshed skill.
+function stampSkillVersion() {
+  const stamped = [];
+  for (const dir of Object.values(KNOWN_SKILL_DIRS())) {
+    try {
+      if (fs.existsSync(path.join(dir, 'SKILL.md'))) {
+        fs.writeFileSync(path.join(dir, '.rly-version'), VERSION);
+        stamped.push(dir);
+      }
+    } catch {
+      // best effort — a marker we couldn't write just re-triggers the nudge
+    }
+  }
+  return stamped;
+}
+
 // Short instruction block for an agent's main instruction file (CLAUDE.md,
 // AGENTS.md, …). A skill is only a tier-1 hint that agents can ignore; these
 // rules, appended to the instructions the agent always reads, enforce usage.
@@ -747,8 +802,12 @@ const SKILL_RULES = `## relay — ask & show in the browser, not the terminal
   beyond one trivial yes/no)? Do NOT ask in plain terminal text. Build a board
   spec and run: \`rly ask --file spec.json --detach\`, then \`rly wait <boardId>\`.
 - Presenting a plan, structure, architecture, data, or a prototype? Show a
-  relay board with mermaid/graphviz/chart/table/image/html blocks — never
-  ASCII diagrams or walls of prose.
+  relay board with mermaid/graphviz/chart/table/code/diff/video/image/html
+  blocks — never ASCII diagrams or walls of prose.
+- "Show me the diff / git diff / these changes"? Run \`git diff\` (or \`git show\`)
+  and render the output in a \`diff\` block — never paste a raw diff in the
+  terminal. Point the user at a file with a clickable local path in a markdown
+  block, and embed a screen recording with a \`video\` block.
 - When answer choices are visual (designs, layouts, variants), give each
   option its own visual (\`options[].blocks\`) so the user picks by looking.
 - Read the result JSON from stdout; treat \`comment\` and \`annotations\` as
@@ -995,8 +1054,9 @@ function cmdAgent() {
   return 0;
 }
 
-// `rly upgrade` — install the latest CLI globally AND refresh the bundled skill
-// in one shot. (`update` is taken by the live-mutate command, so this is
+// `rly upgrade` — install the latest CLI globally AND refresh the skill (via the
+// npx-skills package manager, falling back to the bundled copy) in one shot.
+// (`update` is taken by the live-mutate command, so this is
 // `upgrade` / `self-update`.) Running boards are surfaced and handled: a global
 // reinstall overwrites relay's files, but live detached servers snapshot their
 // UI at first request and serve from memory, so they keep working on their own
@@ -1015,7 +1075,7 @@ async function cmdUpgrade(args) {
   if (args.dryRun === true) {
     printJson({
       dryRun: true,
-      wouldRun: [wantCli && `npm install -g ${PKG_NAME}@latest`, wantSkill && 'rly skill install'].filter(Boolean),
+      wouldRun: [wantCli && `npm install -g ${PKG_NAME}@latest`, wantSkill && 'npx skills add khanglvm/relay --skill relay --all'].filter(Boolean),
       runningBoards: running.map((r) => r.id),
       runningHandling: running.length
         ? doStop
@@ -1072,17 +1132,30 @@ async function cmdUpgrade(args) {
   }
 
   if (wantSkill) {
-    // Spawn the freshly installed binary (on PATH) so the NEW bundled skill is
-    // what lands — this process still holds the previous bundle in memory.
-    process.stderr.write('\nRefreshing the bundled skill  (rly skill install)\n');
-    const r = spawnSync('rly', ['skill', 'install'], { stdio: 'inherit', shell: true });
+    // Refresh the skill through the npx-skills package manager — the same channel
+    // the skill is normally managed by (skills-lock.json, ~/.agents, ~/.claude, …)
+    // — so the global install stays in sync and pulls the freshest skill for
+    // khanglvm/relay. `npx -y` so the one-off download needs no prompt.
+    process.stderr.write('\nRefreshing the relay skill  (npx skills add khanglvm/relay --skill relay --all)\n');
+    let r = spawnSync('npx', ['-y', 'skills', 'add', 'khanglvm/relay', '--skill', 'relay', '--all'], { stdio: 'inherit', shell: true });
+    let how = 'npx-skills';
+    if (r.error || r.status !== 0) {
+      // Fallback: install the skill bundled with the CLI we just upgraded. Works
+      // offline / when the skills CLI is unreachable, and matches this version.
+      process.stderr.write('\nnpx skills unavailable — falling back to the bundled skill  (rly skill install)\n');
+      r = spawnSync('rly', ['skill', 'install'], { stdio: 'inherit', shell: true });
+      how = 'bundled';
+    }
     if (r.error || r.status !== 0) {
       process.stderr.write(
         `Skill refresh did not complete${r.error ? ` (${r.error.message})` : ` (exit ${r.status})`} — ` +
-          'run `rly skill install` yourself (or `npx skills add khanglvm/relay --skill relay --all`).\n'
+          'run `npx skills add khanglvm/relay --skill relay --all` (or `rly skill install`) yourself.\n'
       );
     } else {
-      did.skill = 'installed';
+      // Keep the freshness marker accurate however the skill landed, so the next
+      // `rly` run doesn't nag that the just-refreshed skill is stale.
+      stampSkillVersion();
+      did.skill = how;
     }
   }
 
@@ -1141,6 +1214,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 +1272,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,