@khanglvm/relay 0.15.0 → 0.16.0

package/README.md

@@ -78,7 +78,7 @@ unchanged; pick whichever surface fits.
 | "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 |
 | "Which commits should I pick? Resolve this conflict manually." | `rly git pick` / `rly git cherry-pick` boards and color-coded `git-conflict` resolvers with ours/theirs/custom hunk choices |
 | "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 |
+| Feedback = another wall of text | Click any chart point, diagram node, table cell, or sentence; hold+drag an image area to attach a local crop — the agent replies and the thread grows on the board |
 
 Everything autosaves in real time, detached board links keep serving after
 agent timeouts, multiple boards run at once, and the package has **zero npm
@@ -95,6 +95,7 @@ actually needs them.
 | `rly git conflict [files…]` | auto-detect unmerged conflict files, or open specific local paths, and return resolved content in `result.blockEdits` |
 | `rly share <board-id>` | activate/list/revoke same-Wi-Fi collaborator, reference-only reviewer, or read-only links for a running browser board |
 | `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 show --file spec.json --display-only` | present a browser board and continue immediately — no comment/note or acknowledgement required; inline `relay_show` uses this mode by default |
 | `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 |
@@ -110,6 +111,19 @@ npm test     # smoke tests with no external services (spawns real servers, fake-
 
 ## Changelog
 
+### 0.16.0 — native viewer chrome, area comments, and durable agent waits
+
+- Viewer toolbars now use browser-native sticky positioning instead of a
+  scroll-event counter-translation; open comment composers re-anchor on scroll
+  and preserve unsaved per-target drafts.
+- Hold then drag on an image to comment on an exact rectangular area. Relay
+  saves the crop beside the browser-board record and returns its path; comparison
+  crops also identify and capture the selected Before/After source.
+- Browser boards support `responseRequired:false` / `--display-only`; inline
+  `relay_show` is display-only by default. Board and waiter deadlines now default
+  to one day (`--timeout 0` removes Relay's deadline), with client-specific
+  background/polling guidance in the agent docs.
+
 ### 0.11.0 — render inline inside the Claude & Codex apps (MCP App)
 - **`rly mcp` — relay as an MCP App** ([SEP-1865](https://modelcontextprotocol.io/seps/1865-mcp-apps-interactive-user-interfaces-for-mcp),
   extension `io.modelcontextprotocol/ui`). A stdio MCP server with no npm runtime dependencies

package/docs/AGENT.md

@@ -54,7 +54,7 @@ stderr. Exit codes: `0` submitted/acknowledged · `2` timeout · `3` cancelled
 prints the result JSON:
 
 ```sh
-rly ask --file spec.json --timeout 1800
+rly ask --file spec.json --timeout 86400   # one day; 0 = no Relay deadline
 ```
 
 **2. Detached (recommended when your shell tool has an execution time limit).**
@@ -62,7 +62,7 @@ Returns immediately with the board URL; collect later:
 
 ```sh
 rly ask --file spec.json --detach     # → {"status":"open","boardId":"b-…","url":"…"}
-rly wait b-xxxxx --timeout 3500       # blocks until submit, prints result JSON
+rly wait b-xxxxx --timeout 86400      # default: one day; pass 0 for no deadline
 rly result b-xxxxx                    # non-blocking peek; while open it includes
                                       # the live autosaved draft of the user's answers
 ```
@@ -140,8 +140,9 @@ Both take **the exact same board spec** documented below (the tool `inputSchema`
 fills it in, and their answers come back to you (answers, per-question notes,
 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.
+`--detach`/`rly wait` dance, no stdout parsing, and no timeout** in this mode.
+`relay_ask` stays live until the user submits and the host delivers the result;
+`relay_show` is display-only by default and the agent continues immediately.
 
 **Near-full parity with the browser board.** Local `codeFile` / `htmlFile` /
 `diffFile` and local **image** files work inline too — the server inlines them
@@ -166,12 +167,25 @@ rly ask -q "Deploy to prod now?::yesno" -q "!Environment::single::dev,staging,pr
 #         label::type::comma,separated,options          leading "!" = required
 ```
 
-Visualization-only (no questions; submit button reads "Acknowledge"):
+Visualization-only, with acknowledgement/feedback:
 
 ```sh
 rly show --html-file prototype.html --title "Dashboard concept" --height 600
 ```
 
+Display-only (the agent continues immediately; no note, comments, or
+Submit/Acknowledge action):
+
+```sh
+rly show --file spec.json --display-only
+# equivalent spec field: {"responseRequired": false, "blocks": [...]}
+```
+
+`--display-only` automatically detaches the browser board. In MCP App mode,
+`relay_show` is display-only by default; set `responseRequired:true` only when
+the user really needs to acknowledge or leave feedback. `relay_ask` remains the
+response-bearing tool.
+
 Read a markdown file (no questions; library-free renderer; submit reads "Done"):
 
 ```sh
@@ -219,6 +233,7 @@ choices plus the full resolved file in `result.blockEdits[blockId]`:
   "allowPartial": true,             // default true: user may submit with gaps -> "skipped"
   "note": true,                     // default true: optional free-text box -> result "comment"
   "autoClose": true,                // default true: tab tries to close itself after submit
+  "responseRequired": true,         // false = display-only; no feedback/action, agent continues
   "submitLabel": "Submit",
   "questions": [
     { "id": "approach", "type": "single", "label": "Which approach?", "required": true,
@@ -521,11 +536,11 @@ the question-types section above.
 | `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 |
+| `image` | screenshots, mockup exports, photos — local files embed and work offline; hold then drag to comment on an exact area |
 | `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 |
 | `typography` | type specimens (`specimens:[{label?,size?,weight?,font?,text?}]`) — react to type choices like a palette |
-| `compare` | before/after images with a draggable divider (`before`/`after` = url/path/`{src,label}`) — redesigns, before-after fixes |
+| `compare` | before/after images with a draggable divider (`before`/`after` = url/path/`{src,label}`); area comments preserve which side was selected |
 | `html` | anything else — pixel-perfect mockups, custom widgets, embeds |
 
 Two cross-block fields work on **any** block: `"ref":"name"` makes it openable in
@@ -534,6 +549,14 @@ shown earlier — no scrolling); `image` blocks also take `"pins":true` for
 click-to-drop coordinate pin-comments. `table` blocks take `"rowsFile"` (load
 rows from .csv/.tsv/.json), `"filterable"`, and `"exportable"` (CSV download).
 
+Every interactive `image` and `compare` block also supports area feedback:
+hold briefly, then drag a rectangle. Relay saves a pixel crop beside the board
+record and returns its local path with the annotation, so the agent can open the
+exact pixels instead of inferring from a whole-image comment. In a comparison,
+the side visible where the hold began is recorded as `before` or `after` and the
+crop comes from that source image. Remote images that prevent browser canvas
+access still return coordinates and a `cropUnavailable` marker.
+
 ### Height rules
 
 - `markdown`, `code`: natural flow (no fixed height).
@@ -633,6 +656,8 @@ intro. Annotations are autosaved with the draft and returned in the final result
 | `text` | `quote`, `prefix` (≤30 chars before), `suffix` (≤30 after) | selecting text in a markdown block |
 | `html-element` | `ref`, `label`, `detail?` | hovering any element in a custom-HTML block (auto), or a `data-relay-annotate` / `relayKit.commentable()` element |
 | `image` | `label` | clicking a PlantUML diagram or an image block |
+| `image-point` | `x`, `y`, `label` | clicking an image authored with `pins:true` |
+| `image-region` | `x`, `y`, `w`, `h`, `label`, optional `side`, `crop` | holding then dragging on an image or comparison; `crop.path` is the local image artifact in browser mode |
 
 Read annotations as first-class feedback — they often carry the sharpest insight
 (e.g. a user circling the one data point that concerns them, or quoting the exact
@@ -663,14 +688,15 @@ time). Use it instead of guessing timeouts:
 ```sh
 rly result b-xxxxx     # open board → includes "presence":
                        #   {open, seen, visible, focused, secondsSinceActivity, secondsSincePing}
-rly wait b-xxxxx --timeout 550 --while-active --idle-grace 180
+rly wait b-xxxxx --timeout 86400 --while-active --idle-grace 3600
 ```
 
 `--while-active` keeps extending the wait as long as the user is demonstrably
 active (page visible/focused and interaction within `--idle-grace` seconds,
-default 180); once they go idle it returns the normal `wait-timeout` JSON,
-with `presence` attached so you can decide what to do next. Prefer this over
-raising `--timeout`.
+default 180); once the deadline is reached and they are idle it returns the
+normal `wait-timeout` JSON, with `presence` attached. Relay now defaults both a
+board and `rly wait` to 86,400 seconds (one day); pass `--timeout 0` for no Relay
+deadline when the host can safely own a long-running waiter.
 
 ### A `timeout` on a detached board is NOT the end
 
@@ -685,7 +711,7 @@ tells them you stopped waiting and to prompt you afterward. So if you got a
 so a late submit push-wakes you. A blocking `rly ask` (no `--detach`) still ends
 hard on timeout, since there's no separate waiter to hand back to.
 
-## Push-wake — get notified instead of polling
+## Waiting and push-wake across agent clients
 
 ```sh
 rly ask --file spec.json --detach --on-result 'curl -s -X POST localhost:9999/wake -d @-'
@@ -697,7 +723,19 @@ the board reaches a terminal status — submitted, acknowledged, timeout, or
 cancelled — with the full result JSON piped to stdin and `RLY_BOARD_ID`,
 `RLY_STATUS`, `RLY_URL` in the environment. `--notify-cmd` does the same from
 a `wait` that obtains a terminal result. Write a file your harness watches,
-hit a webhook — whatever wakes you.
+hit a webhook — whatever wakes you. This is passive only when that client or
+harness has an actual inbound wake mechanism; Relay does not pretend that a
+file write alone starts a new model turn.
+
+| Client/surface | Recommended Relay return path |
+|---|---|
+| MCP App (`relay_ask`) | No CLI wait. The inline board stays live and sends `ui/message` on submit, which starts the user-return turn. |
+| MCP App (`relay_show`) | Display-only by default. Present it and continue immediately; no acknowledgement is requested. |
+| Claude Code | Run `rly wait <id> --timeout 0` as a [background Bash task](https://docs.anthropic.com/en/docs/claude-code/interactive-mode#background-bash-commands); retain its task id/output rather than opening a second board. |
+| Gemini CLI | Run the waiter in the background and set [`tools.shell.backgroundCompletionBehavior` to `"inject"`](https://geminicli.com/docs/reference/configuration/) so completion is returned to the agent; `"notify"` only informs the chat UI. |
+| Codex | Keep one foreground waiter. Codex background terminals use explicit `write_stdin` polling (the [poll window defaults to five minutes](https://developers.openai.com/codex/config-reference)); the process can outlive each poll, but no portable browser-submit API wakes a stopped turn. |
+| OpenCode | Core Bash is foreground. Its [ecosystem](https://opencode.ai/docs/ecosystem/) lists background-PTY extensions; use one only when installed, otherwise keep the waiter foreground. |
+| Pi | Core intentionally has [no background Bash](https://github.com/badlogic/pi-mono/blob/main/packages/coding-agent/docs/usage.md); keep the waiter foreground or use an explicitly installed background-task extension. |
 
 ### Codex browser-board pattern
 
@@ -709,7 +747,7 @@ submits:
 
 ```sh
 rly ask --file spec.json --detach
-rly wait b-xxxxx --timeout 1800 --while-active --idle-grace 300
+rly wait b-xxxxx --timeout 86400 --while-active --idle-grace 3600
 ```
 
 If `rly wait` exits with `wait-timeout`, immediately run `rly result <boardId>`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@khanglvm/relay",
-  "version": "0.15.0",
+  "version": "0.16.0",
   "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

@@ -85,8 +85,8 @@ priority call in a `rank` question — not in paragraphs. Unsure which exists? R
 | `code` | source / config / command output — highlighted, line numbers, hover-a-line to comment |
 | `diff` | code changes — colored unified/split, multi-file (`rly diff` builds the whole board) |
 | `git-conflict` | conflict-marker files — side-by-side ours/theirs/base with hunk choices; returns resolved content in `result.blockEdits[blockId]` |
-| `image` | screenshots / mockups / renders — zoom+pan; `pins:true` → click-to-drop point comments |
-| `compare` | a before/after pair — draggable divider |
+| `image` | screenshots / mockups / renders — zoom+pan; hold+drag → area crop comment; `pins:true` → point comments |
+| `compare` | a before/after pair — draggable divider; area comments retain the selected side |
 | `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 |
@@ -130,7 +130,7 @@ blocking `rly ask` that gets killed cancels the board. Always prefer:
 
 ```sh
 rly ask --file spec.json --detach    # returns {"boardId":"b-…","url":…} immediately
-rly wait b-xxxxx --timeout 550       # blocks until submit, prints result JSON
+rly wait b-xxxxx --timeout 86400     # default: one day; 0 = no Relay deadline
                                      # (on exit 2 "wait-timeout" just run wait again)
 rly result b-xxxxx                   # non-blocking peek (includes live draft)
 ```
@@ -142,7 +142,7 @@ create a new board just because a wait timed out.
 For long waits prefer presence-aware waiting over a huge --timeout:
 
 ```sh
-rly wait b-xxxxx --timeout 550 --while-active --idle-grace 180
+rly wait b-xxxxx --timeout 86400 --while-active --idle-grace 3600
 # keeps extending while the user is demonstrably viewing/typing on the board;
 # returns wait-timeout promptly once they are idle/gone (presence included)
 rly result b-xxxxx        # while open also shows presence {visible, focused, secondsSinceActivity}
@@ -159,7 +159,7 @@ 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
+rly wait b-xxxxx --timeout 86400 --while-active --idle-grace 3600
 ```
 
 If `rly wait` exits with `wait-timeout`, immediately run `rly result <boardId>`.
@@ -168,9 +168,30 @@ If it is still open and the user may continue, run `rly wait` again. Do not use
 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
+Blocking mode (`rly ask --file spec.json --timeout 86400`, no `--detach`) is fine
 ONLY when your shell tool has no execution time limit.
 
+Relay defaults board and waiter deadlines to one day; use `--timeout 0` when the
+client can safely own an indefinite process. Choose the return path by host:
+
+- Inline MCP `relay_ask`: no CLI wait; its `ui/message` submission wakes the
+  return turn. Inline `relay_show` is display-only by default and does not wait.
+- Claude Code: background `rly wait <id> --timeout 0` as a background Bash task.
+- Gemini CLI: background the waiter and use
+  `tools.shell.backgroundCompletionBehavior: "inject"`.
+- Codex: keep one foreground waiter; background terminals require explicit
+  polling and do not expose a portable browser-submit wake API.
+- OpenCode/Pi: keep it foreground unless a background-task extension is
+  explicitly installed (Pi core has no background Bash).
+
+Use `--on-result`/`--notify-cmd` only when the surrounding harness exposes a real
+webhook, file watcher, or inbound wake path.
+
+To present without asking for any response, use
+`rly show --file spec.json --display-only` (equivalent to
+`"responseRequired":false`). It returns immediately and shows no note,
+comments, or Submit/Acknowledge action.
+
 Useful flags: `--no-open` (don't auto-open the browser — for tests/CI; real
 users need the tab, so omit it normally) · `--title` · `--timeout <sec>`.
 
@@ -418,6 +439,15 @@ Add `"pins": true` to an `image` block: the user clicks any point on the image t
 drop a comment anchored to that exact spot (Figma-style), returned as an
 `{kind:"image-point", x, y}` annotation. Ideal for design/mockup review.
 
+### Comment on an exact image area (local crop)
+
+Every interactive `image` and `compare` block supports hold-then-drag area
+feedback without another spec flag. Relay returns an `image-region` target with
+normalized `x`, `y`, `w`, and `h`; browser boards also save the selected pixels
+beside the board and return `target.crop.path`, which the agent should open with
+its image viewer. Comparison targets include `side:"before"|"after"`, and the
+crop comes from that source image rather than the composited slider view.
+
 ### Show a git diff in one step — `rly diff`
 
 `rly diff [git args…]` runs `git diff` and opens the result as a diff board —
@@ -449,7 +479,7 @@ mention annotation in the board intro.
   "id": "a1",
   "questionId": "q-id or null",
   "blockId": "b2",
-  "target": { "kind": "chart-element | mermaid-node | graphviz-node | table-cell | text | html-element | image | image-point | code-line", "..." },
+  "target": { "kind": "chart-element | mermaid-node | graphviz-node | table-cell | text | html-element | image | image-point | image-region | code-line", "..." },
   "text": "user comment",
   "author": "user",
   "createdAt": "ISO",

package/src/cli.js

@@ -28,6 +28,8 @@ const BIN = path.join(PKG_ROOT, 'bin', 'rly.js');
 const PKG_JSON = JSON.parse(fs.readFileSync(path.join(PKG_ROOT, 'package.json'), 'utf8'));
 const VERSION = PKG_JSON.version;
 const PKG_NAME = PKG_JSON.name; // e.g. "@khanglvm/relay" — the global package to upgrade
+const DEFAULT_BOARD_TIMEOUT_SEC = 86400;
+const DEFAULT_WAIT_TIMEOUT_SEC = 86400;
 
 const VALUED_FLAGS = new Set([
   'file', 'html', 'html-file', 'title', 'intro', 'timeout', 'port',
@@ -171,6 +173,7 @@ async function resolveSpecInput(args, mode) {
   if (args.htmlFile) raw.htmlFile = args.htmlFile;
   if (args.height) raw.htmlHeight = args.height;
   if (args.submitLabel) raw.submitLabel = args.submitLabel;
+  if (args.displayOnly === true) raw.responseRequired = false;
   if (args.q.length) {
     raw.questions = [...(raw.questions || []), ...args.q.map((s, i) => questionFromInline(s, i))];
   }
@@ -198,7 +201,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 timeoutSec = args.timeout !== undefined ? Math.max(0, Number.parseInt(args.timeout, 10) || 0) : DEFAULT_BOARD_TIMEOUT_SEC;
   const port = args.port !== undefined ? Number.parseInt(args.port, 10) || 0 : 0;
   const open = args.open !== false;
 
@@ -231,7 +234,9 @@ async function runOrDetach(record, args) {
       boardId: record.id,
       url: info.url,
       port: info.port,
-      hint: `block for the answers with: rly wait ${record.id}`,
+      hint: record.spec.responseRequired === false
+        ? 'display-only board opened; no response will be collected'
+        : `block for the answers with: rly wait ${record.id}`,
     });
     return 0;
   }
@@ -247,7 +252,7 @@ async function cmdAsk(args, mode) {
   const spec = normalizeSpec(raw);
   await assertSpecReady(spec);
   const record = createBoard(spec);
-  return runOrDetach(record, args);
+  return runOrDetach(record, spec.responseRequired === false ? { ...args, detach: true } : args);
 }
 
 // `rly diff [git args…]` — run `git diff` for the user and open the result as a
@@ -639,11 +644,11 @@ async function fetchPresence(url) {
 async function cmdWait(args) {
   const id = args._[0];
   if (!id) throw new CliError('usage: rly wait <board-id> [--timeout <sec>] [--while-active] [--idle-grace <sec>] [--notify-cmd <cmd>]');
-  const timeoutSec = args.timeout !== undefined ? Math.max(1, Number.parseInt(args.timeout, 10) || 1) : 3600;
+  const timeoutSec = args.timeout !== undefined ? Math.max(0, Number.parseInt(args.timeout, 10) || 0) : DEFAULT_WAIT_TIMEOUT_SEC;
   const whileActive = args.whileActive === true;
   const idleGrace = args.idleGrace !== undefined ? Math.max(0, Number.parseInt(args.idleGrace, 10) || 0) : 180;
   const notifyCmd = typeof args.notifyCmd === 'string' && args.notifyCmd.trim() ? args.notifyCmd : null;
-  let deadline = Date.now() + timeoutSec * 1000;
+  let deadline = timeoutSec === 0 ? Number.POSITIVE_INFINITY : Date.now() + timeoutSec * 1000;
   mustLoad(id);
 
   // Push-wake: run the agent's --notify-cmd after a TERMINAL result, then print.
@@ -1086,7 +1091,7 @@ the user should view — put it in relay instead of printing it.**
   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\`.
+  \`rly wait <boardId> --timeout 86400 --while-active --idle-grace 3600\`.
   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
@@ -1094,6 +1099,10 @@ the user should view — put it in relay instead of printing it.**
   Detached boards are durable: a board timeout hands the agent a \`timeout\`
   result but keeps the same URL/port serving until Submit or \`rly stop\`. Do
   not create a new board just because a wait timed out.
+- **No response needed** → \`rly show --file spec.json --display-only\`. It
+  returns immediately and shows no note, comments, or Submit/Acknowledge action.
+  In MCP App mode, \`relay_show\` is display-only by default; \`relay_ask\` is the
+  response-bearing tool.
 - **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 →
@@ -1116,7 +1125,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\`, \`git-conflict\`, \`image\` (+\`pins\`), \`compare\` (before/after), \`video\`, \`pdf\`, \`palette\`,
+  \`code\`, \`diff\`, \`git-conflict\`, \`image\` (hold+drag area crops; +\`pins\` for points), \`compare\` (before/after with side-aware area crops), \`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
@@ -1580,7 +1589,7 @@ async function cmdServeInternal(args) {
     id,
     port: args.port !== undefined ? Number.parseInt(args.port, 10) || 0 : 0,
     open: args.open !== false,
-    timeoutSec: args.timeout !== undefined ? Math.max(0, Number.parseInt(args.timeout, 10) || 0) : 1800,
+    timeoutSec: args.timeout !== undefined ? Math.max(0, Number.parseInt(args.timeout, 10) || 0) : DEFAULT_BOARD_TIMEOUT_SEC,
     quiet: true,
     // Detached board: timeout hands back to the agent but keeps the same
     // URL/port serving until Submit or explicit stop.
@@ -1600,7 +1609,9 @@ USAGE
                                       quick inline questions ("!" = required, label::type::options)
   rly ask ... --detach                no blocking: prints {boardId,url} now; collect via \`rly wait <id>\`
   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 show --html-file viz.html       visualization board (submit button = acknowledge)
+  rly show --file spec.json --display-only
+                                      present without comments/acknowledgement; returns immediately
   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;
                                        .pdf streams in an inline PDF viewer)
@@ -1611,7 +1622,7 @@ USAGE
                                       add --code for split code view with per-hunk Apply/Skip/Hold
   rly git conflict [files…]           board for resolving conflict-marker files; with no files, auto-detects
                                       unmerged git files and returns resolved content in result.blockEdits
-  rly wait <id> [--timeout 3600]      block until board finishes, print result JSON
+  rly wait <id> [--timeout 86400]     block up to one day until the board finishes (0 = no deadline)
                                       --while-active [--idle-grace 180]: keep waiting past the deadline
                                         while the user is still viewing/focused & recently active
                                       --notify-cmd "<cmd>": run <cmd> on a terminal result (JSON on stdin)
@@ -1655,7 +1666,7 @@ USAGE
 
 COMMON FLAGS
   --title <s> --intro <s> --html-file <f> --height <px> --submit-label <s>
-  --timeout <sec> (default 1800; 0 = none) --port <n> --no-open --detach
+  --timeout <sec> (default 86400; 0 = none) --port <n> --no-open --detach --display-only
 
 EXIT CODES   0 submitted/acknowledged · 2 timeout · 3 cancelled · 4 usage · 5 not found
 

package/src/mcp-ui/board.js

@@ -219,6 +219,7 @@
       allowPartial: raw.allowPartial !== false,
       note: raw.note !== false,
       autoClose: raw.autoClose !== false,
+      responseRequired: raw.responseRequired !== false,
       questions: [],
       submitLabel: typeof raw.submitLabel === 'string' ? raw.submitLabel : '',
     };
@@ -388,7 +389,13 @@
       questionId: questionId == null ? null : questionId,
       // No annotation during the streaming preview (it re-renders); on the final
       // interactive render, wire the engine so blocks register their targets.
-      annotate: composing ? null : Annotate,
+      annotate: composing || (spec && spec.responseRequired === false) ? null : Annotate,
+      canComment: Boolean(spec && spec.responseRequired !== false),
+      saveArtifact: async ({ dataUrl, mime, width, height }) => {
+        const comma = typeof dataUrl === 'string' ? dataUrl.indexOf(',') : -1;
+        if (comma < 0) throw new Error('invalid image crop');
+        return { data: dataUrl.slice(comma + 1), mime: mime || 'image/png', width, height };
+      },
       edits: state.blockEdits,
       onBlockEdit: (blockId, codeOrNull) => {
         if (codeOrNull === null || codeOrNull === undefined) delete state.blockEdits[blockId];
@@ -882,7 +889,7 @@
       app.append(card);
     });
 
-    if (spec.note) {
+    if (spec.note && spec.responseRequired !== false) {
       const note = el('textarea', { placeholder: 'optional note back to the agent…' });
       note.value = state.comment || '';
       note.addEventListener('input', () => { state.comment = note.value; });
@@ -898,6 +905,12 @@
       reportSize();
       return;
     }
+    if (spec.responseRequired === false) {
+      app.append(el('div', { class: 'submitbar display-only' },
+        el('span', { class: 'hint' }, 'Display only · no response requested')));
+      reportSize();
+      return;
+    }
     const submitBtn = el('button', { class: 'submit', type: 'button' }, spec.submitLabel);
     const saveEl = el('span', { class: 'savestate' }, '');
     const hint = el('span', { class: 'hint' }, QS.length && spec.allowPartial ? 'Unanswered questions are returned as skipped.' : '');
@@ -940,7 +953,9 @@
       lines.push('', 'Inline comments (' + data.annotations.length + '):');
       for (const a of data.annotations) {
         const where = (a.target && (a.target.label || a.target.text || a.target.kind)) || a.blockId || 'element';
-        lines.push('- [' + where + ']: ' + a.text);
+        const crop = a.target && a.target.crop;
+        const cropNote = crop && crop.path ? ' · crop: ' + crop.path : crop && crop.data ? ' · image crop attached' : '';
+        lines.push('- [' + where + ']: ' + a.text + cropNote);
       }
     }
     if (data.blockEdits) lines.push('', 'Edited diagrams: ' + Object.keys(data.blockEdits).join(', '));
@@ -964,24 +979,43 @@
       annotations: data.annotations,
     };
     const text = summarize(data);
+    const messageContent = [{ type: 'text', text }];
+    for (const a of data.annotations || []) {
+      const crop = a && a.target && a.target.crop;
+      if (!crop || typeof crop.data !== 'string' || !crop.data) continue;
+      messageContent.push({ type: 'image', data: crop.data, mimeType: crop.mime || 'image/png' });
+    }
     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 } });
+      await request('ui/message', { role: 'user', content: messageContent });
       messageDelivered = true;
     } catch {
-      // Older/leaner hosts may not expose app-initiated messages.
+      // Older hosts may not advertise image content or may implement the early
+      // single-content draft. Preserve the text wake path before giving up.
+      try {
+        await request('ui/message', { role: 'user', content: [{ type: 'text', text }] });
+        messageDelivered = true;
+      } catch {
+        try {
+          await request('ui/message', { role: 'user', content: { type: 'text', text } });
+          messageDelivered = true;
+        } catch { /* app-initiated messages unavailable */ }
+      }
     }
     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 });
+      await request('ui/update-model-context', { content: messageContent, structuredContent: structured });
       contextDelivered = true;
     } catch {
-      // If ui/message worked, the agent still receives the submission transcript.
+      try {
+        await request('ui/update-model-context', { content: [{ type: 'text', text }], structuredContent: structured });
+        contextDelivered = true;
+      } catch { /* ui/message may still have delivered the result */ }
     }
     submitted = true;
     showDone(messageDelivered, contextDelivered);
@@ -1029,7 +1063,11 @@
     seedDefaults();
     indexHtmlBlocks(spec);
     setStatus('Preparing…');
-    if (Annotate) Annotate.init({ initial: [], onChange: (a) => { state.annotations = Array.isArray(a) ? a : []; } });
+    if (Annotate && spec.responseRequired !== false) {
+      Annotate.init({ initial: [], onChange: (a) => { state.annotations = Array.isArray(a) ? a : []; } });
+    } else if (Annotate && typeof Annotate.teardown === 'function') {
+      Annotate.teardown();
+    }
     try { await preloadVendors(spec); } catch { /* render anyway; blocks degrade individually */ }
     render();
     applyDisplayMode();

package/src/mcp.js

@@ -111,7 +111,7 @@ function tools() {
     {
       name: 'relay_show',
       description:
-        'Present work to the user on an inline board WITHOUT necessarily asking questions — a plan, an architecture diagram, data, a diff, a prototype — using rich blocks (markdown, mermaid, graphviz, chart, table, code, diff, image, html). The board shows a Submit/Acknowledge button. Same spec as relay_ask; typically blocks-only.',
+        'Present work to the user on an inline display-only board — a plan, architecture diagram, data, diff, prototype, or image — using rich blocks. It returns immediately and does not ask the user to acknowledge. Set responseRequired:true only when feedback or acknowledgement is actually needed.',
       inputSchema: schema,
       _meta: uiToolMeta(),
     },
@@ -157,7 +157,7 @@ async 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. When the user submits, relay sends their answers back as a user message so the agent continues.',
+          'relay renders boards inline. Call relay_ask to collect decisions/feedback and wait for its user-message submission. Call relay_show to present plans/diagrams/data without waiting; it is display-only unless responseRequired:true is explicit.',
       };
     case 'ping':
       return {};
@@ -209,9 +209,12 @@ async function callTool(params) {
     return { content: [{ type: 'text', text: 'unknown tool: ' + name }], isError: true };
   }
   const args = (params && params.arguments && typeof params.arguments === 'object') ? params.arguments : {};
+  const normalizedArgs = name === 'relay_show' && args.responseRequired === undefined
+    ? { ...args, responseRequired: false }
+    : args;
   let spec;
   try {
-    spec = normalizeSpec(args);
+    spec = normalizeSpec(normalizedArgs);
     await assertSpecReady(spec);
   } catch (err) {
     const msg = err instanceof CliError ? err.message : String((err && err.message) || err);
@@ -232,6 +235,9 @@ async function callTool(params) {
 // when the board clearly didn't render for the user.
 function boardText(spec) {
   const nQ = spec.questions.length;
+  if (spec.responseRequired === false) {
+    return `Relay board "${spec.title}" is now displayed to the user. No acknowledgement is requested; continue your work without waiting.`;
+  }
   if (!nQ) {
     return `Relay board "${spec.title}" is now displayed to the user. They can review it and acknowledge; any feedback will be delivered back to you.`;
   }