@khanglvm/relay 0.13.5 → 0.13.6

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.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/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);