@khanglvm/relay 0.13.5 → 0.13.7

package/README.md

@@ -88,7 +88,7 @@ Node ≥ 18; Chart.js / Mermaid / Graphviz are vendored and lazy-loaded offline.
 | | |
 |---|---|
 | `rly help` | every command at a glance |
-| `rly view <file.md> …` | open a quick read-only board that renders local markdown file(s) — library-free; great for plans, READMEs, reports |
+| `rly view <file.md> …` | open a quick read-only board that renders local markdown file(s), data files, or PDFs — library-free; great for plans, READMEs, reports, quotes |
 | `rly install --target <agent>` | write relay's rules into an agent's instruction file — `claude` `codex` `cursor` `copilot` `kiro` `windsurf` `cline` `gemini` `opencode` `droid` `agents`; `--all`, `--scope`, `--print`, `--list` |
 | `rly upgrade` | update the CLI **and** refresh the skill in one step (safe around open boards; `--dry-run`, `--cli-only`, `--skill-only`) |
 | `rly mcp` | run relay as an MCP App server so boards render **inline** in the chat — **stdio** for local desktop hosts (Claude Desktop, Codex), or `rly mcp --http` (Streamable HTTP) for web/mobile/remote; `rly mcp config` / `rly mcp install --target claude\|codex` to register it |
@@ -164,6 +164,8 @@ npm test     # zero-dep smoke tests (spawns real servers, fake-submits)
 - **`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.
+- **`pdf` block** — render local `.pdf` files or PDF URLs inline. Local PDFs
+  stream from the board server and are never embedded in the page 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.

package/docs/AGENT.md

@@ -151,6 +151,7 @@ Read a markdown file (no questions; library-free renderer; submit reads "Done"):
 rly view PLAN.md                      # one file
 rly view README.md CHANGELOG.md       # several, each under a filename heading
 rly view data.csv                     # .csv/.tsv/.json → a sortable, filterable table
+rly view report.pdf                   # .pdf → inline PDF viewer
 ```
 
 Show a git diff in one step (sugar — runs git diff, opens a diff board):
@@ -405,6 +406,10 @@ Rules of thumb:
 { "type": "video", "src": "https://youtu.be/dQw4w9WgXcQ", "title": "Demo walkthrough" }
 { "type": "video", "src": "recordings/demo.mp4", "title": "Local capture", "height": 360 }
 
+// PDF — an http(s) PDF URL or a local .pdf file rendered inline. Local PDFs
+// stream from the server and are never embedded in the page payload.
+{ "type": "pdf", "src": "reports/quote.pdf", "title": "Quote", "height": 900 }
+
 // HTML — sandboxed iframe; default height 360
 { "type": "html", "html": "<h1>Hello</h1>", "height": 360 }
 { "type": "html", "htmlFile": "viz.html",   "height": 400 }
@@ -469,6 +474,7 @@ the question-types section above.
 | `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) |
+| `pdf` | quotes, reports, exports, forms — local `.pdf` files or PDF URLs rendered inline; local files stream from the board server |
 | `image` | screenshots, mockup exports, photos — local files embed and work offline |
 | `palette` | color palettes / themes — swatch cards with hover-hex + click-to-copy; pair with a `color` question to let the user pick |
 | `kpi` | big-number metric cards (`items:[{label,value,delta?,dir?,sub?}]`) with up/down/flat-tinted deltas — at-a-glance numbers without a chart |
@@ -646,6 +652,25 @@ cancelled — with the full result JSON piped to stdin and `RLY_BOARD_ID`,
 a `wait` that obtains a terminal result. Write a file your harness watches,
 hit a webhook — whatever wakes you.
 
+### Codex browser-board pattern
+
+Codex does not have a normal, user-facing "wake this agent turn from a browser
+submit" command. If the Codex turn stops waiting, a later board submit can leave
+the user needing to prompt manually. So when an agent is running in Codex and
+uses the browser board path, keep the waiter in the foreground until the user
+submits:
+
+```sh
+rly ask --file spec.json --detach
+rly wait b-xxxxx --timeout 1800 --while-active --idle-grace 300
+```
+
+If `rly wait` exits with `wait-timeout`, immediately run `rly result <boardId>`.
+If it is still open and the user may continue, run `rly wait` again. Do not use
+`--on-result` as the primary Codex return path; it can write files or hit
+webhooks, but normal Codex CLI sessions do not expose a portable inbound API
+that wakes the current agent turn.
+
 ## Editable diagrams — let the user redraw your mermaid
 
 Add `"editable": true` to any mermaid block. The user gets an "Edit diagram"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@khanglvm/relay",
-  "version": "0.13.5",
+  "version": "0.13.7",
   "description": "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, read answers as JSON — in a local browser board OR rendered INLINE inside the Claude & Codex apps as an MCP App (SEP-1865).",
   "keywords": [
     "ai-agents",

package/skills/relay/SKILL.md

@@ -86,6 +86,7 @@ priority call in a `rank` question — not in paragraphs. Unsure which exists? R
 | `image` | screenshots / mockups / renders — zoom+pan; `pins:true` → click-to-drop point comments |
 | `compare` | a before/after pair — draggable divider |
 | `video` | a demo / screen recording / walkthrough |
+| `pdf` | a quote / report / exported document that should render inline |
 | `palette` | color schemes — swatch cards, hover-hex, click-to-copy |
 | `typography` | type choices — specimens at given size/weight/font |
 | `html` | anything bespoke — custom widgets, pixel-perfect mockups |
@@ -145,6 +146,22 @@ Push-wake instead of polling: add --on-result '<shell cmd>' to ask/show/reopen
 (or --notify-cmd on wait) - the command runs the moment the board finishes,
 with the full result JSON on stdin and RLY_BOARD_ID/RLY_STATUS/RLY_URL in env.
 
+**Codex browser-board pattern.** Codex does not have a normal, user-facing
+"wake this agent turn from a browser submit" command. If the Codex turn stops
+waiting, a later board submit can leave the user needing to prompt manually.
+So in Codex, keep the waiter in the foreground until the user submits:
+
+```sh
+rly ask --file spec.json --detach
+rly wait b-xxxxx --timeout 1800 --while-active --idle-grace 300
+```
+
+If `rly wait` exits with `wait-timeout`, immediately run `rly result <boardId>`.
+If it is still open and the user may continue, run `rly wait` again. Do not use
+`--on-result` as the primary Codex return path; it can write files or hit
+webhooks, but normal Codex CLI sessions do not expose a portable inbound API
+that wakes the current agent turn.
+
 Blocking mode (`rly ask --file spec.json --timeout 1800`, no --detach) is fine
 ONLY when your shell tool has no execution time limit.
 
@@ -270,6 +287,8 @@ single/multi question.
 { "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": "pdf",      "src": "reports/quote.pdf", "title": "Quote", "height": 900 }
+// ^ local .pdf files and http(s) PDF URLs render 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

package/src/cli.js

@@ -4,7 +4,7 @@ import os from 'node:os';
 import { spawn, spawnSync } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
 import { CliError, sleep, pollFor } from './util.js';
-import { normalizeSpec, questionFromInline, SPEC_SCHEMA } from './spec.js';
+import { assertSpecReady, normalizeSpec, questionFromInline, SPEC_SCHEMA } from './spec.js';
 import {
   createBoard,
   loadBoard,
@@ -197,6 +197,7 @@ function readFileOrThrow(p) {
 }
 
 async function runOrDetach(record, args) {
+  await assertSpecReady(record.spec);
   const timeoutSec = args.timeout !== undefined ? Math.max(0, Number.parseInt(args.timeout, 10) || 0) : 1800;
   const port = args.port !== undefined ? Number.parseInt(args.port, 10) || 0 : 0;
   const open = args.open !== false;
@@ -244,6 +245,7 @@ async function runOrDetach(record, args) {
 async function cmdAsk(args, mode) {
   const raw = await resolveSpecInput(args, mode);
   const spec = normalizeSpec(raw);
+  await assertSpecReady(spec);
   const record = createBoard(spec);
   return runOrDetach(record, args);
 }
@@ -275,17 +277,17 @@ async function cmdDiff(rest) {
   }
   const title = args.title || ('git diff' + (gitArgs.length ? ' ' + gitArgs.join(' ') : ''));
   const spec = normalizeSpec({ title, blocks: [{ type: 'diff', diff, view: args.split ? 'split' : 'unified' }] });
+  await assertSpecReady(spec);
   const record = createBoard(spec);
   return runOrDetach(record, args);
 }
 
-// `rly view <file.md> [more.md …]` — quick read-only board that renders one or
-// more markdown files (README, plan, report) with the built-in no-library
-// renderer. Each file becomes a markdown block; with 2+ files a small filename
-// heading separates them. Sugar over `rly show` with markdown mdFile blocks.
+// `rly view <file.md> [more.md …]` — quick read-only board that renders files
+// with purpose-built blocks (markdown, data tables, PDF). With 2+ files a small
+// filename heading separates them. Sugar over `rly show`.
 async function cmdView(args) {
   const files = args._;
-  if (!files.length) throw new CliError('usage: rly view <file.md|.csv|.json> [more …] [--title T] [--detach]');
+  if (!files.length) throw new CliError('usage: rly view <file.md|.csv|.json|.pdf> [more …] [--title T] [--detach]');
   const multi = files.length > 1;
   const DATA_EXT = new Set(['csv', 'tsv', 'json']);
   const blocks = [];
@@ -293,12 +295,14 @@ async function cmdView(args) {
     if (multi) blocks.push({ type: 'markdown', md: `## ${path.basename(f)}` });
     const ext = path.extname(f).slice(1).toLowerCase();
     if (DATA_EXT.has(ext)) blocks.push({ type: 'table', rowsFile: f, sortable: true, filterable: true, exportable: true });
+    else if (ext === 'pdf') blocks.push({ type: 'pdf', src: f, title: path.basename(f) });
     else blocks.push({ type: 'markdown', mdFile: f });
   }
   const raw = { blocks };
   raw.title = args.title || (multi ? `${files.length} files` : path.basename(files[0]));
   raw.submitLabel = args.submitLabel || 'Done';
   const spec = normalizeSpec(raw); // reads + validates each file, clear error if unreadable
+  await assertSpecReady(spec);
   const record = createBoard(spec);
   return runOrDetach(record, args);
 }
@@ -445,6 +449,7 @@ async function cmdUpdate(args) {
   } else {
     throw new CliError('update needs --file <spec.json>, --title, --intro, or -q "...".', 4);
   }
+  await assertSpecReady(spec);
 
   let res;
   try {
@@ -879,8 +884,8 @@ what you're about to output would look better than monospace text — or is a fi
 the user should view — put it in relay instead of printing it.**
 
 - **Markdown file / doc / README / plan / report** → \`rly view file.md\` (renders it
-  in the browser, no library; \`.csv\`/\`.json\` → a sortable table). Never \`cat\` a
-  doc into the terminal for the user to read.
+  in the browser, no library; \`.csv\`/\`.json\` → a sortable table; \`.pdf\` → an
+  inline PDF viewer). Never \`cat\` a doc into the terminal for the user to read.
 - **Image / screenshot / mockup / diagram / chart / table** → a relay board with an
   \`image\` block (or \`mermaid\`/\`graphviz\`/\`chart\`/\`table\`/\`kpi\`/\`compare\`). The
   terminal can't show pixels; relay can — with click-to-zoom and comment-in-place.
@@ -889,6 +894,15 @@ the user should view — put it in relay instead of printing it.**
   \`AskUserQuestion\` / ask-user tool. Build a spec and run
   \`rly ask --file spec.json --detach\`, then \`rly wait <boardId>\`. **Holds in plan
   mode too**; reserve \`ExitPlanMode\` for the final plan-approval gate only.
+- **Codex-specific browser-board pattern:** Codex does not have a normal,
+  user-facing "wake this agent turn from a browser submit" command. In Codex,
+  keep the waiter in the foreground until the user submits:
+  \`rly ask --file spec.json --detach\` then
+  \`rly wait <boardId> --timeout 1800 --while-active --idle-grace 300\`.
+  If wait exits with \`wait-timeout\`, immediately run \`rly result <boardId>\`;
+  if it is still open and the user may continue, run \`rly wait\` again. Do not
+  use \`--on-result\` as the primary Codex return path; normal Codex CLI sessions
+  do not expose a portable inbound API that wakes the current agent turn.
 - **A plan, structure, architecture, data, or prototype** → a relay board with
   diagram/chart/table/code/image/html blocks — never ASCII diagrams or walls of prose.
 - **"Show me the diff / git diff / these changes"** → \`rly diff\` (runs git diff →
@@ -899,7 +913,7 @@ the user should view — put it in relay instead of printing it.**
 - **There's a purpose-built component for most content — use the MOST SPECIFIC one,
   never plain prose when a block fits.** Blocks: \`table\` (sortable/filterable/CSV,
   load from .csv/.json), \`chart\`, \`kpi\` (stat cards), \`mermaid\`/\`graphviz\`/\`plantuml\`,
-  \`code\`, \`diff\`, \`image\` (+\`pins\`), \`compare\` (before/after), \`video\`, \`palette\`,
+  \`code\`, \`diff\`, \`image\` (+\`pins\`), \`compare\` (before/after), \`video\`, \`pdf\`, \`palette\`,
   \`typography\`, \`html\`. Question types: \`single\`/\`multi\`/\`yesno\`/\`scale\`/\`color\`/
   \`text\`/\`textarea\` plus \`rank\` (prioritize), \`allocate\` (split a budget), \`checklist\`
   (per-item sign-off). For a business user, reach for \`kpi\`+\`chart\`+\`table\` and
@@ -1385,7 +1399,8 @@ USAGE
   rly ask ... --on-result "<cmd>"     push-wake: run <cmd> when the board finishes (result JSON on stdin)
   rly show --html-file viz.html       visualization-only board (submit button = acknowledge)
   rly view <file.md> [more.md …]      quick read-only board rendering markdown file(s) (no lib)
-                                      (.csv/.tsv/.json render as a filterable, sortable table)
+                                      (.csv/.tsv/.json render as a filterable, sortable table;
+                                       .pdf streams in an inline PDF viewer)
   rly diff [git args…]                run git diff and show it in a diff board (--split, --detach,
                                       --title; other args pass to git: rly diff --staged | HEAD~1 | -- path)
   rly wait <id> [--timeout 3600]      block until board finishes, print result JSON

package/src/mcp.js

@@ -19,7 +19,7 @@ import path from 'node:path';
 import http from 'node:http';
 import crypto from 'node:crypto';
 import { fileURLToPath } from 'node:url';
-import { normalizeSpec, SPEC_SCHEMA } from './spec.js';
+import { assertSpecReady, normalizeSpec, SPEC_SCHEMA } from './spec.js';
 import { CliError } from './util.js';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
@@ -143,7 +143,7 @@ function resourceMeta() {
 }
 
 // ---------- request routing ----------
-function buildResult(method, params, clientProtocol) {
+async function buildResult(method, params, clientProtocol) {
   switch (method) {
     case 'initialize':
       return {
@@ -202,7 +202,7 @@ function readResource(params) {
 // ui/update-model-context as a best-effort context sync). Spec errors come back
 // as an isError tool result (not a protocol error) so the model can see and fix
 // them.
-function callTool(params) {
+async function callTool(params) {
   const name = params && params.name;
   if (name !== 'relay_ask' && name !== 'relay_show') {
     return { content: [{ type: 'text', text: 'unknown tool: ' + name }], isError: true };
@@ -211,6 +211,7 @@ function callTool(params) {
   let spec;
   try {
     spec = normalizeSpec(args);
+    await assertSpecReady(spec);
   } catch (err) {
     const msg = err instanceof CliError ? err.message : String((err && err.message) || err);
     return { content: [{ type: 'text', text: 'relay: invalid board spec — ' + msg }], isError: true };
@@ -265,7 +266,7 @@ export function runMcp() {
     catch { stdoutOpen = false; }
   };
 
-  function handleLine(line) {
+  async function handleLine(line) {
     let msg;
     try { msg = JSON.parse(line); } catch {
       send({ jsonrpc: '2.0', id: null, error: { code: -32700, message: 'parse error' } });
@@ -278,7 +279,7 @@ export function runMcp() {
       if (typeof m.method !== 'string') continue; // a response to us — we issue none
       let result;
       try {
-        result = buildResult(m.method, m.params || {});
+        result = await buildResult(m.method, m.params || {});
       } catch (err) {
         if (isRequest) {
           send({ jsonrpc: '2.0', id: m.id, error: { code: err.code || -32603, message: err.message || String(err) } });
@@ -290,6 +291,7 @@ export function runMcp() {
   }
 
   let buf = '';
+  let queue = Promise.resolve();
   process.stdin.setEncoding('utf8');
   process.stdin.on('data', (chunk) => {
     buf += chunk;
@@ -298,7 +300,7 @@ export function runMcp() {
       const line = buf.slice(0, idx);
       buf = buf.slice(idx + 1);
       const trimmed = line.trim();
-      if (trimmed) handleLine(trimmed);
+      if (trimmed) queue = queue.then(() => handleLine(trimmed)).catch(() => {});
     }
   });
 
@@ -406,7 +408,7 @@ export function runMcpHttp({ port = DEFAULT_HTTP_PORT, host = '127.0.0.1', token
     let body = '';
     let aborted = false;
     req.on('data', (c) => { body += c; if (body.length > MAX_BODY) { aborted = true; req.destroy(); } });
-    req.on('end', () => {
+    req.on('end', async () => {
       if (aborted) { res.writeHead(413, base); return res.end(); }
       let msg;
       try { msg = JSON.parse(body); } catch {
@@ -421,7 +423,7 @@ export function runMcpHttp({ port = DEFAULT_HTTP_PORT, host = '127.0.0.1', token
         if (m.method === 'initialize') isInit = true;
         const isRequest = m.id !== undefined && m.id !== null;
         try {
-          const result = buildResult(m.method, m.params || {});
+          const result = await buildResult(m.method, m.params || {});
           if (isRequest) responses.push({ jsonrpc: '2.0', id: m.id, result });
         } catch (err) {
           if (isRequest) responses.push({ jsonrpc: '2.0', id: m.id, error: { code: err.code || -32603, message: err.message || String(err) } });

package/src/server.js

@@ -7,6 +7,7 @@ import { spawn } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
 import { loadBoard, saveBoard, saveRunning, removeRunning, loadPref, savePref } from './store.js';
 import { openUrl } from './open.js';
+import { assertSpecReady } from './spec.js';
 
 const UI_DIR = path.join(path.dirname(fileURLToPath(import.meta.url)), 'ui');
 const PKG_ROOT = path.join(path.dirname(fileURLToPath(import.meta.url)), '..');
@@ -40,7 +41,9 @@ function readUi(name) {
 
 // Strips block bodies for the client payload: html blocks ship only metadata
 // (their bodies are served via /html/b/<id>), embedded images ship only
-// metadata (bytes served via /img/b/<id>), everything else ships as-is.
+// metadata (bytes served via /img/b/<id>), streamed local media ships only
+// metadata (bytes served via /video/b/<id> or /pdf/b/<id>), everything else
+// ships as-is.
 function clientBlock(b) {
   // Cross-block fields preserved when we ship metadata-only (ref = reference-link
   // target name; pins = image coordinate comments). The default `return b` path
@@ -58,6 +61,9 @@ function clientBlock(b) {
   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, ...extra };
   }
+  if (b && b.type === 'pdf' && typeof b.file === 'string') {
+    return { id: b.id, type: 'pdf', title: b.title, height: b.height, mime: b.mime, hasFile: true, ...extra };
+  }
   return b;
 }
 
@@ -587,6 +593,11 @@ export async function runBoard({ id, port = 0, open = true, timeoutSec = 1800, q
             !Array.isArray(next.questions) || !Array.isArray(next.blocks)) {
           return sendJson(res, 400, { error: 'spec must be an object with questions[] and blocks[] arrays' });
         }
+        try {
+          await assertSpecReady(next);
+        } catch (err) {
+          return sendJson(res, 400, { error: err && err.message ? err.message : String(err) });
+        }
         record.spec = next;
         rev++;
         saveBoard(record);
@@ -619,6 +630,12 @@ export async function runBoard({ id, port = 0, open = true, timeoutSec = 1800, q
         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' || req.method === 'HEAD') && pathname.startsWith('/pdf/b/')) {
+        // Local PDF bytes, Range-streamed for the browser's built-in PDF viewer.
+        const blockId = decodeURIComponent(pathname.slice('/pdf/b/'.length));
+        const block = findBlock(record.spec, blockId, 'pdf');
+        if (!block || typeof block.file !== 'string') return sendJson(res, 404, { error: `no local pdf block "${blockId}"` });
+        streamFile(req, res, block.file, block.mime || 'application/pdf');
       } else if (req.method === 'GET' && pathname === '/html/board') {
         // Legacy alias → the board's first html block.
         const block = firstBoardHtml(record.spec);

package/src/spec.js

@@ -1,5 +1,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
+import vm from 'node:vm';
+import { fileURLToPath } from 'node:url';
 import { CliError } from './util.js';
 
 export const TYPES = ['single', 'multi', 'yesno', 'text', 'textarea', 'scale', 'color', 'rank', 'checklist', 'allocate'];
@@ -39,7 +41,7 @@ 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', 'diff', 'video', 'html', 'image', 'palette', 'kpi', 'typography', 'compare'];
+export const BLOCK_TYPES = ['markdown', 'mermaid', 'graphviz', 'plantuml', 'chart', 'table', 'code', 'diff', 'video', 'pdf', 'html', 'image', 'palette', 'kpi', 'typography', 'compare'];
 const CHART_KINDS = ['bar', 'line', 'pie', 'doughnut', 'radar', 'scatter'];
 
 // code/diff blocks may load their text from a local file (like htmlFile). Caps
@@ -55,6 +57,9 @@ const VIDEO_MIMES = {
 };
 const VIDEO_MAX_BYTES = 512 * 1024 * 1024;
 
+const PDF_MIME = 'application/pdf';
+const PDF_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 = {
@@ -62,6 +67,9 @@ const IMAGE_MIMES = {
   webp: 'image/webp', svg: 'image/svg+xml', avif: 'image/avif', bmp: 'image/bmp',
 };
 const IMAGE_MAX_BYTES = 8 * 1024 * 1024;
+const VENDOR_DIR = path.join(path.dirname(fileURLToPath(import.meta.url)), '..', 'vendor');
+
+let mermaidValidatorPromise = null;
 
 const asStr = (v) => (typeof v === 'string' ? v : v == null ? '' : String(v));
 
@@ -219,6 +227,99 @@ function parseVideoEmbed(src) {
   return null;
 }
 
+function compactError(err) {
+  const raw = err && (err.str || err.message) ? (err.str || err.message) : String(err || 'unknown error');
+  const msg = String(raw).replace(/\s+/g, ' ').trim();
+  return msg.length > 500 ? msg.slice(0, 497) + '...' : msg;
+}
+
+async function mermaidValidator() {
+  if (mermaidValidatorPromise) return mermaidValidatorPromise;
+  mermaidValidatorPromise = (async () => {
+    const sourcePath = path.join(VENDOR_DIR, 'mermaid.min.js');
+    let source;
+    try {
+      source = fs.readFileSync(sourcePath, 'utf8');
+    } catch {
+      throw new CliError('mermaid blocks need the vendored parser (vendor/mermaid.min.js is missing).');
+    }
+    const quietConsole = { log() {}, info() {}, warn() {}, error() {}, debug() {} };
+    const context = {
+      console: quietConsole,
+      setTimeout,
+      clearTimeout,
+    };
+    context.globalThis = context;
+    context.window = { addEventListener() {} };
+    vm.createContext(context);
+    try {
+      vm.runInContext(source, context, { filename: sourcePath });
+    } catch (err) {
+      throw new CliError(`could not load mermaid parser: ${compactError(err)}`);
+    }
+    if (!context.mermaid || typeof context.mermaid.parse !== 'function') {
+      throw new CliError('could not load mermaid parser: vendor/mermaid.min.js did not expose mermaid.parse.');
+    }
+    try {
+      context.mermaid.initialize({
+        startOnLoad: false,
+        securityLevel: 'strict',
+        suppressErrorRendering: true,
+      });
+    } catch {
+      // Some Mermaid versions dislike repeated initialize calls; parse below is
+      // the real readiness gate.
+    }
+    return context.mermaid;
+  })();
+  return mermaidValidatorPromise;
+}
+
+async function assertMermaidSyntax(code, where) {
+  const mermaid = await mermaidValidator();
+  try {
+    const parsed = mermaid.parse(code);
+    if (parsed && typeof parsed.then === 'function') await parsed;
+  } catch (err) {
+    throw new CliError(`${where}: invalid mermaid syntax — ${compactError(err)}`);
+  }
+}
+
+function* allBlocks(spec) {
+  const boardBlocks = Array.isArray(spec.blocks) ? spec.blocks : [];
+  for (let i = 0; i < boardBlocks.length; i++) {
+    yield { block: boardBlocks[i], where: `board.blocks[${i}]${boardBlocks[i]?.id ? ` (${boardBlocks[i].id})` : ''}` };
+  }
+  const questions = Array.isArray(spec.questions) ? spec.questions : [];
+  for (let qi = 0; qi < questions.length; qi++) {
+    const q = questions[qi] || {};
+    const qBlocks = Array.isArray(q.blocks) ? q.blocks : [];
+    for (let bi = 0; bi < qBlocks.length; bi++) {
+      yield { block: qBlocks[bi], where: `questions[${qi}].blocks[${bi}]${qBlocks[bi]?.id ? ` (${qBlocks[bi].id})` : ''}` };
+    }
+    const opts = Array.isArray(q.options) ? q.options : [];
+    for (let oi = 0; oi < opts.length; oi++) {
+      const oBlocks = Array.isArray(opts[oi]?.blocks) ? opts[oi].blocks : [];
+      for (let bi = 0; bi < oBlocks.length; bi++) {
+        yield {
+          block: oBlocks[bi],
+          where: `questions[${qi}].options[${oi}].blocks[${bi}]${oBlocks[bi]?.id ? ` (${oBlocks[bi].id})` : ''}`,
+        };
+      }
+    }
+  }
+}
+
+export async function assertSpecReady(spec) {
+  if (!spec || typeof spec !== 'object') return spec;
+  if (spec.__relayReady === true) return spec;
+  for (const { block, where } of allBlocks(spec)) {
+    if (block && block.type === 'mermaid') await assertMermaidSyntax(block.code || '', where);
+  }
+  Object.defineProperty(spec, '__relayReady', { value: true, enumerable: false, configurable: true });
+  return spec;
+}
+
 // 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) {
@@ -343,6 +444,37 @@ function normalizeBlock(rawBlock, id, cwd, where) {
     return block;
   }
 
+  if (type === 'pdf') {
+    const src = asStr(rawBlock.src ?? rawBlock.file ?? rawBlock.url).trim();
+    if (!src) throw new CliError(`${where}: pdf block needs a "src" (http(s) PDF URL or local .pdf file path).`);
+    const block = { id, type: 'pdf' };
+    if (rawBlock.title !== undefined) block.title = asStr(rawBlock.title);
+    if (rawBlock.alt !== undefined && block.title === undefined) block.title = asStr(rawBlock.alt);
+    if (hasHeight) block.height = clampInt(rawBlock.height, BLOCK_HEIGHT.min, BLOCK_HEIGHT.max, undefined);
+    if (/^https?:/i.test(src)) {
+      block.src = src;
+      block.mime = PDF_MIME;
+      if (!block.title) block.title = path.basename(src.split(/[?#]/)[0]) || 'PDF';
+      return block;
+    }
+    const p = path.resolve(cwd, src);
+    const ext = path.extname(p).slice(1).toLowerCase();
+    if (ext !== 'pdf') throw new CliError(`${where}: unsupported pdf extension ".${ext}" — use a local .pdf file or an http(s) PDF URL.`);
+    let stat;
+    try {
+      stat = fs.statSync(p);
+    } catch {
+      throw new CliError(`${where}: cannot read pdf "${src}" (resolved: ${p})`);
+    }
+    if (stat.size > PDF_MAX_BYTES) {
+      throw new CliError(`${where}: pdf "${src}" is ${(stat.size / 1024 / 1024).toFixed(0)}MB — max ${PDF_MAX_BYTES / 1024 / 1024}MB.`);
+    }
+    block.file = p;
+    block.mime = PDF_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 =

package/src/ui/blocks.css

@@ -278,6 +278,14 @@
 .blk-video-embed { aspect-ratio: 16 / 9; height: auto; }
 .blk-videocap { margin-top: 8px; font-size: 0.84rem; color: var(--muted); text-align: center; }
 
+/* ---------- PDF (local stream / direct URL) ---------- */
+.blk-pdfwrap { margin: 0; }
+.blk-pdf {
+  display: block; width: 100%; height: min(900px, 78vh); min-height: 420px;
+  border: 0; border-radius: 10px; background: var(--card);
+}
+.blk-pdfwrap.blk-full .blk-pdf { height: calc(100vh - 92px); min-height: 0; }
+
 /* ---------- table ---------- */
 .blk-table {
   width: 100%;

package/src/ui/blocks.js

@@ -692,6 +692,27 @@
     return wrap;
   }
 
+  // ---------- PDF (local stream or direct URL) ----------
+  function renderPdf(block, ctx, blockId) {
+    const wrap = el('div', { class: 'blk-pdfwrap' });
+    const src = block.hasFile ? '/pdf/b/' + encodeURIComponent(blockId) : block.src;
+    const title = block.title || 'PDF';
+    const frame = el('iframe', {
+      class: 'blk-pdf',
+      src,
+      title,
+      loading: 'lazy',
+    });
+    if (block.height != null) frame.style.height = clampHeight(block.height, 900) + 'px';
+    frame.addEventListener('error', () => {
+      wrap.replaceChildren(el('div', { class: 'blk-error' }, 'PDF failed to load'));
+    });
+    wrap.append(frame);
+    if (block.title) wrap.append(el('div', { class: 'blk-videocap' }, block.title));
+    attachViewer(wrap, { zoomEl: null, label: 'pdf', comment: wholeBlockComment(ctx, blockId, 'pdf') });
+    return wrap;
+  }
+
   // ---------- table ----------
   function normalizeColumns(columns) {
     return (columns || []).map((c, idx) => {
@@ -2199,6 +2220,10 @@
         inner = renderVideo(block, ctx, blockId);
         wrapper.append(inner);
         break;
+      case 'pdf':
+        inner = renderPdf(block, ctx, blockId);
+        wrapper.append(inner);
+        break;
       case 'chart':
         inner = renderChart(block, ctx, blockId);
         wrapper.append(inner);