@khanglvm/relay 0.13.4 → 0.13.6

package/README.md

@@ -61,10 +61,11 @@ rly mcp config
 
 When the agent calls a relay tool, the host renders relay's `ui://relay/board`
 resource in a sandboxed iframe, hands it the board spec, and the user's answers
-flow back to the agent over the bridge (`ui/update-model-context`) — markdown,
-code, diffs, tables, charts, mermaid/graphviz diagrams, images, and forms, all
-in-chat. The classic browser board (`rly ask` / `rly show`) is unchanged; pick
-whichever surface fits.
+flow back to the agent as a `ui/message` user turn, with
+`ui/update-model-context` used as a best-effort structured context sync —
+markdown, code, diffs, tables, charts, mermaid/graphviz diagrams, images, and
+forms, all in-chat. The classic browser board (`rly ask` / `rly show`) is
+unchanged; pick whichever surface fits.
 
 ## What it improves
 
@@ -87,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 |
@@ -114,10 +115,11 @@ npm test     # zero-dep smoke tests (spawns real servers, fake-submits)
 - **Same board, postMessage transport.** The inline board reuses relay's block
   renderer (markdown, code, diff, table, chart, mermaid, graphviz, image, html)
   over the MCP Apps JSON-RPC bridge: the spec arrives as the tool result, the
-  user's answers go back via `ui/update-model-context`, the iframe auto-sizes
-  via `ui/notifications/size-changed`, and vendored Chart.js / Mermaid / Viz.js
-  load on demand through the host's `resources/read` (no `/vendor` route, no
-  server in the sandbox).
+  user's submit goes back via `ui/message` so the agent resumes, the structured
+  payload is also offered through `ui/update-model-context`, the iframe
+  auto-sizes via `ui/notifications/size-changed`, and vendored Chart.js /
+  Mermaid / Viz.js load on demand through the host's `resources/read` (no
+  `/vendor` route, no server in the sandbox).
 - **One-command setup** — `rly mcp install --target claude|codex` writes the
   host config; `rly mcp config` prints the snippet for any MCP host. The classic
   browser board is untouched.
@@ -162,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

@@ -111,7 +111,8 @@ finalizes when your call completes — so the user sees it build, not a blank wa
 Both take **the exact same board spec** documented below (the tool `inputSchema`
 *is* this spec). Call the tool with your spec; the host shows the board, the user
 fills it in, and their answers come back to you (answers, per-question notes,
-comment) — read them just as you would the CLI's result JSON. There is **no
+comment) as a user-message turn, with structured context synced when the host
+supports it — read them just as you would the CLI's result JSON. There is **no
 `--detach`/`rly wait` dance, no stdout parsing, and no timeout** in this mode; the
 board stays live until the user submits and the host delivers the result.
 
@@ -150,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):
@@ -404,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 }
@@ -468,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 |
@@ -645,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.4",
+  "version": "0.13.6",
   "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

@@ -279,13 +279,12 @@ async function cmdDiff(rest) {
   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,6 +292,7 @@ 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 };
@@ -879,8 +879,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 +889,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 +908,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 +1394,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-ui/board.js

@@ -4,8 +4,9 @@
 // host app (Claude desktop/mobile, Codex, …) as a sandboxed inline iframe.
 // There is no local HTTP server here: every exchange with the host travels over
 // JSON-RPC on window.postMessage — the spec arrives as the tool result, the
-// user's answers go back via `ui/update-model-context`, and vendored libraries
-// (Chart.js / Mermaid / Viz.js) are pulled through the host's `resources/read`.
+// user's final submission goes back as a `ui/message` user turn, and vendored
+// libraries (Chart.js / Mermaid / Viz.js) are pulled through the host's
+// `resources/read`.
 //
 // Rich blocks are rendered by the SAME window.RelayBlocks as the browser board
 // (markdown, code, diff, table, chart, mermaid, graphviz, image, html), so the
@@ -957,19 +958,30 @@
       annotations: data.annotations,
     };
     const text = summarize(data);
-    let delivered = false;
+    let messageDelivered = false;
+    let contextDelivered = false;
     try {
+      // A completed relay form is a user reply, not passive context. Some hosts
+      // ACK `ui/update-model-context` without starting a new model turn, so send
+      // the transcript as a user message first to wake the agent reliably.
+      await request('ui/message', { role: 'user', content: { type: 'text', text } });
+      messageDelivered = true;
+    } catch {
+      // Older/leaner hosts may not expose app-initiated messages.
+    }
+    try {
+      // Keep the structured payload available to hosts that attach app context.
+      // This is best-effort because context updates are intentionally silent.
       await request('ui/update-model-context', { content: [{ type: 'text', text }], structuredContent: structured });
-      delivered = true;
+      contextDelivered = true;
     } catch {
-      // Fallback for hosts without update-model-context: post a chat message.
-      try { await request('ui/message', { role: 'user', content: { type: 'text', text } }); delivered = true; } catch { /* give up gracefully */ }
+      // If ui/message worked, the agent still receives the submission transcript.
     }
     submitted = true;
-    showDone(delivered);
+    showDone(messageDelivered, contextDelivered);
   }
 
-  function showDone(delivered) {
+  function showDone(messageDelivered, contextDelivered) {
     // Collapse: leave fullscreen, drop the whole form for a one-line confirmation
     // so the host shrinks the iframe to a small footprint in the transcript.
     if (Annotate) { try { Annotate.teardown(); } catch { /* nothing to tear down */ } }
@@ -977,8 +989,10 @@
     app.replaceChildren(el('div', { class: 'mcp-done' },
       el('span', { class: 'mark' }, '✓'),
       el('span', { class: 'lead' }, QS.length ? 'Submitted' : 'Acknowledged'),
-      el('span', { class: 'sub' }, delivered
+      el('span', { class: 'sub' }, messageDelivered
         ? '· sent back to the agent'
+        : contextDelivered
+          ? '· saved; send the agent a message to continue'
         : '· tell the agent you’ve responded')));
     // Report the small height immediately, then again next frame / after layout
     // settles — beats hosts that only grow on debounced size events.

package/src/mcp.js

@@ -8,8 +8,8 @@
 //   • the tools `relay_ask` / `relay_show` link to it via _meta.ui.resourceUri
 //   • calling a tool returns the (normalized) board spec as structuredContent;
 //     the host renders the resource in a sandboxed iframe and forwards the spec
-//   • the iframe collects the user's answers and sends them back to the model
-//     via `ui/update-model-context`
+//   • the iframe collects the user's answers and sends them back as a user
+//     message; it also syncs model context when the host supports it
 //
 // Framing is the MCP stdio transport: newline-delimited JSON-RPC, one message
 // per line, never embedded newlines. stdout carries ONLY protocol messages;
@@ -156,7 +156,7 @@ function buildResult(method, params, clientProtocol) {
         },
         serverInfo: { name: 'relay', version: PKG.version },
         instructions:
-          'relay renders interactive boards inline. Call relay_ask to collect decisions/feedback with real form controls, or relay_show to present plans/diagrams/data — instead of asking in plain text. Read the user\'s answers from the structuredContent that returns after they submit.',
+          'relay renders interactive boards inline. Call relay_ask to collect decisions/feedback with real form controls, or relay_show to present plans/diagrams/data — instead of asking in plain text. When the user submits, relay sends their answers back as a user message so the agent continues.',
       };
     case 'ping':
       return {};
@@ -198,9 +198,10 @@ function readResource(params) {
 
 // A tool call: normalize the spec and hand it to the host as structuredContent.
 // The host renders ui://relay/board and forwards this spec to the iframe, which
-// collects the answers and returns them via ui/update-model-context. Spec errors
-// come back as an isError tool result (not a protocol error) so the model can
-// see and fix them.
+// collects the answers and returns them via a UI-originated user message (with
+// 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) {
   const name = params && params.name;
   if (name !== 'relay_ask' && name !== 'relay_show') {

package/src/server.js

@@ -40,7 +40,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 +60,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;
 }
 
@@ -619,6 +624,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

@@ -39,7 +39,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 +55,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 = {
@@ -343,6 +346,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);