@khanglvm/relay 0.4.2 → 0.5.0

package/README.md

@@ -1,31 +1,20 @@
 # relay
 
-**The relay between AI agents and humans — boards, blocks, and element-level comments.**
+**The relay between AI agents and humans — browser boards instead of terminal walls.**
 
-`rly` lets an AI agent (Claude Code, Codex, or anything that can run a CLI) ask
-its user structured questions in a clean browser page — single/multi choice,
-yes-no, free text, rating scales — and/or present rich content blocks (markdown,
-charts, diagrams, tables, code, sandboxed HTML, Graphviz and PlantUML diagrams), then **block until the user clicks
-Submit** and read the answers as JSON. No more "type *done* in the terminal",
-no more hand-rolled HTML + throwaway servers.
+`rly` is a CLI that lets your AI agent ask questions and present work in a
+local browser board — real forms, charts, diagrams, sortable tables, images,
+and live prototypes instead of terminal text and ASCII art. You click, comment
+on any element, and Submit; the agent gets your answers and comments back as
+JSON and keeps working.
 
-Users can **hover chart points, diagram nodes, table cells, or select text to
-leave inline comments** — returned alongside answers as `result.annotations`.
-Agents can reply to those comments and reopen the board as a conversation thread.
+## See it
 
-- Zero runtime dependencies — plain Node ≥ 18, vanilla HTML/CSS/JS UI
-- Light/dark theme (auto + manual toggle), responsive, content-focused
-- Real-time answer autosave (drafts survive timeout/cancel)
-- Auto-closes the tab after submit and unblocks the CLI
-- Native content blocks: markdown, mermaid diagrams, Graphviz diagrams, PlantUML, Chart.js charts, tables, code, sandboxed HTML
-- Chart.js, Mermaid, and Graphviz are **vendored and lazy-loaded** only when a board uses them — the base board stays dependency-free and as fast as before
-- Element-level annotations: users comment on chart points, diagram nodes, table cells, text, or custom HTML elements; returned as `result.annotations`
-- **Threaded annotation replies**: agents can reply to user comments via `rly reopen --replies`; conversations shown inline in the board
-- **Live board mutation**: `rly update` lets an agent push a new spec to an already-open board; the page reloads and prefills answers from draft
-- Multiple boards at once, local history: reuse / modify / reopen / remove
-- Agent-first: JSON on stdout, logs on stderr, `--detach` + `wait` for shell tools with execution time limits, built-in agent guide & skill
+A real board from a real session — an agent presenting three animated UI
+prototypes, asking which to build, expanding one full-screen, and getting the
+answers on Submit:
 
-## See it
+![relay demo — animated prototypes, picking an option, full-screen, submit](https://raw.githubusercontent.com/khanglvm/relay/main/docs/assets/demo.gif)
 
 | Light theme | Dark theme |
 |---|---|
@@ -35,350 +24,40 @@ Agents can reply to those comments and reopen the board as a conversation thread
 |---|---|
 | ![Annotation comment on a chart bar](https://raw.githubusercontent.com/khanglvm/relay/main/docs/assets/annotations.png) | ![Mobile view at 375px](https://raw.githubusercontent.com/khanglvm/relay/main/docs/assets/mobile.png) |
 
-![relay demo — board to annotation to summary](https://raw.githubusercontent.com/khanglvm/relay/main/docs/assets/demo.gif)
-
-## Install
-
-```sh
-npm i -g @khanglvm/relay     # provides `rly` (and `relay`)
-# or per-invocation:
-npx -y @khanglvm/relay help
-```
-
 ## Quick start
 
 ```sh
-# Quick inline questions ("!" = required, label::type::options)
-rly ask -q "Deploy to prod?::yesno" -q "!Environment::single::dev,staging,prod"
-
-# Full board from a spec
-rly ask --file spec.json --timeout 1800
-
-# Visualization-only (prototype/idea); submit button = "Acknowledge"
-rly show --html-file prototype.html --title "Dashboard concept" --height 600
-
-# Non-blocking pattern (for agent tools with exec timeouts)
-rly ask --file spec.json --detach   # → {"boardId":"b-…","url":"http://127.0.0.1:…"}
-rly wait b-xxxxx                    # blocks until submit, prints result JSON
-```
-
-The browser opens automatically; the user answers and clicks **Submit**; the
-CLI prints something like:
-
-```json
-{
-  "status": "submitted",
-  "boardId": "b-k3x9q2",
-  "answers": { "q1": "yes", "q2": "staging" },
-  "skipped": [],
-  "comment": "ship it",
-  "annotations": [],
-  "durationMs": 23000
-}
-```
-
-## Board spec
-
-```jsonc
-{
-  "title": "Feature direction",
-  "intro": "Context shown under the title.",
-  "blocks": [
-    { "type": "markdown", "md": "## Background\nUse this context when deciding." }
-  ],
-  "allowPartial": true,        // user may submit with gaps (returned in "skipped")
-  "note": true,                // optional free-text box → result "comment"
-  "autoClose": true,           // tab closes itself after submit
-  "questions": [
-    { "id": "approach", "type": "single", "label": "Which approach?", "required": true,
-      "options": [{ "value": "a", "label": "A", "description": "fast" }, "B"], "other": true },
-    { "id": "scope",  "type": "multi",    "label": "Include?", "options": ["api", "ui", "docs"] },
-    { "id": "ship",   "type": "yesno",    "label": "Ship this week?" },
-    { "id": "name",   "type": "text",     "label": "Codename?", "placeholder": "falcon" },
-    { "id": "notes",  "type": "textarea", "label": "Constraints?" },
-    { "id": "conf",   "type": "scale",    "label": "Confidence?", "min": 1, "max": 5,
-      "minLabel": "low", "maxLabel": "high",
-      "blocks": [{ "type": "markdown", "md": "Rate your confidence in the chosen approach." }] }
-  ]
-}
-```
-
-`rly schema` prints the full JSON Schema; `rly agent` prints the complete
-agent-oriented guide (answer shapes, block reference, annotation shape, patterns).
-
-## Content blocks
-
-Blocks can appear at the board level (`"blocks": [...]` on the root) or per question
-(`"blocks": [...]` on a question object). Legacy `"html"` / `"htmlFile"` fields are
-still accepted and normalised into a single `html` block automatically.
-
-### Markdown
-
-```json
-{ "type": "markdown", "md": "## Section\nAny **CommonMark** prose." }
-```
-
-Built-in mini renderer — no library loaded.
-
-### Mermaid diagram
-
-```json
-{ "type": "mermaid", "code": "graph TD; A-->B; B-->C", "height": 400 }
-```
-
-Lazy-loads the vendored Mermaid bundle only when used. `height` clamps to
-100–2400 px (default: natural flow, max 1200 px with scroll).
-
-### Chart — shorthand
-
-```json
-{
-  "type": "chart",
-  "kind": "bar",
-  "title": "Q1 velocity",
-  "labels": ["Jan", "Feb", "Mar"],
-  "series": [
-    { "label": "Shipped", "data": [12, 19, 14], "color": "#4d8a66" },
-    { "label": "Planned", "data": [15, 15, 15] }
-  ],
-  "height": 320
-}
-```
-
-`kind`: `bar` | `line` | `pie` | `doughnut` | `radar` | `scatter`.
-Omit `color` to use the built-in palette.
-
-### Chart — full Chart.js config
-
-```json
-{
-  "type": "chart",
-  "config": {
-    "type": "bar",
-    "data": { "labels": ["A", "B"], "datasets": [{ "label": "x", "data": [1, 2] }] },
-    "options": { "plugins": { "legend": { "display": false } } }
-  },
-  "height": 280
-}
-```
-
-Pass any valid Chart.js v4 config object to `config`. Lazy-loads the vendored
-Chart.js bundle.
-
-### Table
-
-```json
-{
-  "type": "table",
-  "columns": [
-    { "key": "name", "label": "Name" },
-    { "key": "status", "label": "Status", "align": "center" },
-    { "key": "score", "label": "Score", "align": "right" }
-  ],
-  "rows": [
-    { "name": "Alpha", "status": "done", "score": 92 },
-    { "name": "Beta",  "status": "wip",  "score": 71 }
-  ],
-  "sortable": true
-}
-```
-
-`columns` may also be a plain `["A", "B", "C"]` string array, with `rows` as
-parallel arrays: `[[val, val, val], ...]`. Users can click column headers to
-sort when `"sortable": true`.
-
-### Code
-
-```json
-{ "type": "code", "lang": "js", "code": "const x = 1 + 2;" }
-```
-
-Rendered in a styled pre/code block. `lang` is optional.
-
-### HTML (sandboxed iframe)
-
-```json
-{ "type": "html", "html": "<h1>Hello</h1>", "height": 360 }
-```
-
-or reference a file:
-
-```json
-{ "type": "html", "htmlFile": "viz.html", "height": 400 }
-```
-
-Rendered in a **sandboxed iframe** (`allow-scripts`, no parent access).
-Width: always 100% of the content column — ~820 px max on desktop, ~300 px min
-on phones. Height: 100–2400 px, default 360. Fragments (no `<html>` tag) are
-auto-wrapped to match the current theme; full documents receive a
-`?theme=light|dark` query param.
-
-### Graphviz diagram
-
-```json
-{ "type": "graphviz", "dot": "digraph { a -> b -> c }", "height": 300 }
-```
-
-Rendered entirely **offline** via the vendored `viz-standalone.js` (Graphviz compiled to
-WebAssembly). Never upscaled past the diagram's natural width; shrinks on narrow screens;
-container max-height 1200 px with scroll. Nodes (`g.node`) and edges (`g.edge`) are
-individually annotatable. Use Graphviz for precise dependency graphs, call graphs, or
-state machines where Mermaid's auto-layout doesn't give enough control.
-
-### PlantUML diagram
-
-```json
-{ "type": "plantuml", "code": "@startuml\nA -> B: request\n@enduml", "height": 340 }
-```
-
-Rendered via a **PlantUML server** (default: `https://www.plantuml.com/plantuml`). The
-diagram source is deflate-encoded client-side and sent as a URL parameter — no server
-round-trip for the page itself, just an `<img>` request. If the server is unreachable or
-the browser lacks `CompressionStream`, a muted error card is shown.
-
-**Privacy note:** diagram source is encoded and sent to the configured PlantUML server.
-For sensitive diagrams, host your own server and pass `"server": "https://plantuml.example.com"`.
-
-The rendered image is registered as a single annotatable element (target kind `image`).
-Use PlantUML for UML sequence diagrams, class diagrams, and component diagrams.
-
-## Annotations
-
-Users can leave inline comments on any annotatable element — chart data points,
-mermaid nodes, graphviz nodes and edges, table cells, text selections inside markdown, and labelled
-elements inside custom HTML. A small pin icon appears on hover; clicking opens a
-comment popover. Comments are autosaved with the draft and returned in the final
-result.
-
-**Threaded replies:** each annotation can have replies. Agents can read
-`result.annotations`, compose replies, and reopen the board as a conversation:
-
-```sh
-# After reading result.annotations from a previous board:
-rly reopen <id> --replies replies.json
-# replies.json: [{"annotationId":"a1","text":"Good catch — fixed in the next sprint."}]
-```
-
-The board reopens with agent replies shown inline under each comment. Users can reply
-back; the conversation grows with each `rly reopen --replies` cycle.
-
-### result.annotations shape
-
-```json
-{
-  "status": "submitted",
-  "boardId": "b-k3x9q2",
-  "answers": { "approach": "a" },
-  "annotations": [
-    {
-      "id": "a1",
-      "questionId": null,
-      "blockId": "b2",
-      "target": {
-        "kind": "chart-element",
-        "datasetIndex": 0,
-        "index": 1,
-        "label": "Feb",
-        "value": 19
-      },
-      "text": "Feb spike was due to the onboarding push — not repeatable.",
-      "author": "user",
-      "createdAt": "2026-06-11T10:23:00.000Z",
-      "replies": [
-        { "author": "agent", "text": "Confirmed — excluded from the trend line.", "createdAt": "2026-06-11T11:00:00.000Z" }
-      ]
-    }
-  ],
-  "durationMs": 58000
-}
+npm i -g @khanglvm/relay                  # the rly CLI
+npx -y skills add khanglvm/relay -g -y    # the agent skill (Claude Code, Codex, Cursor, …)
+rly skill rules >> ~/.claude/CLAUDE.md    # optional: skills are ignorable hints — this enforces usage (or >> AGENTS.md)
 ```
 
-Each annotation has an optional `author` (`"user"` | `"agent"`, default `"user"`) and
-an optional `replies` array (capped at 50; each reply: `{author, text, createdAt}`).
+That's it. Next time your agent needs a decision or wants to show you a plan,
+it opens a board like the ones above and waits for your Submit.
 
-### Annotation target kinds
+## What it improves
 
-| kind | what the user clicked |
+| Without relay | With relay |
 |---|---|
-| `chart-element` | a bar, point, or pie slice — includes `datasetIndex`, `index`, `label`, `value` |
-| `mermaid-node` | a node in a diagram — includes `nodeId`, `text` |
-| `graphviz-node` | a node or edge in a Graphviz diagram — includes `nodeId`, `text` |
-| `table-cell` | a cell — includes `row` (0-based), `col` (column key), `value` |
-| `text` | a text selection inside a markdown block — includes `quote`, `prefix`, `suffix` |
-| `html-element` | a labelled element inside custom HTML (via `kit.js`) — includes `label`, optional `detail` |
-| `image` | a PlantUML diagram image — includes `label` |
+| Six questions asked one at a time in the terminal | One board, all questions, real form controls, optional "Other" + notes |
+| "Option B is the one with caching (see my last message)" | Each answer option carries its own image / chart / diagram — pick by looking |
+| ASCII architecture art | Mermaid, Graphviz, PlantUML — zoomable, full-screen, even user-editable |
+| Numbers buried in prose | Charts and sortable tables; screenshots and HTML prototypes in a sandbox |
+| "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 |
 
-### kit.js — annotatable custom HTML
+Everything autosaves in real time (drafts survive timeouts), multiple boards
+run at once, and the package has **zero runtime dependencies** — plain
+Node ≥ 18; Chart.js / Mermaid / Graphviz are vendored and lazy-loaded offline.
 
-Inside a custom HTML iframe, load `/kit.js` to make elements commentable:
+## Learn more
 
-```html
-<script src="/kit.js"></script>
-<script>
-  // Make any element commentable — users see a hover outline + click to comment
-  relayKit.commentable(document.getElementById('revenue-chart'), 'Revenue chart', 'Q1 2026');
-  relayKit.commentable(document.getElementById('cta-button'), 'CTA button');
-</script>
-```
-
-`relayKit.commentable(el, label, detail?)` — outlines `el` on hover; clicking
-opens the annotation popover in the parent page anchored to that element.
-`label` is shown in the annotation summary; `detail` is optional extra context.
-
-## Commands
-
-| Command | What it does |
+| | |
 |---|---|
-| `rly ask [--file spec.json \| --file - \| -q "…"]` | Create board, open browser, block until submit, print answers JSON |
-| `rly ask … --detach` | Don't block — print `{boardId,url}` immediately |
-| `rly show --html-file viz.html` | Visualization-only board (acknowledge) |
-| `rly wait <id> [--timeout s]` | Block until board finishes, print result |
-| `rly result <id>` | Result/status now — includes **live autosaved draft** while open |
-| `rly list [--json]` | Running boards |
-| `rly open [id]` | Re-open the browser tab of a running board |
-| `rly reopen <id>` | Serve a saved board again, **prefilled with saved answers** |
-| `rly reopen <id> --replies file.json` | Reopen with agent replies appended to matching annotations |
-| `rly update <id> [--file spec.json \| --title T \| --intro I \| -q "…"]` | Push a new spec to a running board — page reloads, answers survive via draft |
-| `rly reuse <id> [--dump]` | Re-run a past board as a new one (blank) |
-| `rly stop <id> \| --all` | Stop running board(s) — draft preserved |
-| `rly history [--limit n] [--json]` | Saved boards |
-| `rly spec <id>` | Print a saved spec (edit → `rly ask --file`) |
-| `rly rm <id> \| --all` | Delete saved board(s) |
-| `rly schema` | JSON Schema of the spec |
-| `rly agent` | Full guide for AI agents |
-| `rly skill [install\|path]` | Bundled universal agent skill |
-
-Common flags: `--title --intro --html-file --height --submit-label
---timeout <sec> --port <n> --no-open --detach`.
-
-Exit codes: `0` submitted/acknowledged · `2` timeout · `3` cancelled ·
-`4` usage · `5` not found.
-
-Storage: `~/.relay` (override with `RLY_HOME`). Boards bind to `127.0.0.1` only.
-
-## Presence, push-wake & diagram co-editing (v0.4)
-
-While a board is open the page reports user activity; `rly result <id>`
-includes `presence` ({visible, focused, secondsSinceActivity}) and
-`rly wait <id> --while-active --idle-grace 180` keeps waiting while the user
-is demonstrably engaged instead of dying on a fixed timer. For pushes,
-`--on-result '<cmd>'` (on ask/show/reopen/reuse) and `rly wait --notify-cmd`
-execute your command with the result JSON on stdin the moment the board
-finishes. Mermaid blocks with `"editable": true` let the user edit the diagram
-source with live preview — their version returns as `result.blockEdits`.
-
-## Agent skill (Claude Code, Codex, …)
-
-A universal [SKILL.md](skills/relay/SKILL.md) is bundled:
-
-```sh
-rly skill install                  # auto-installs into ~/.claude/skills and ~/.codex/skills
-rly skill install --target claude  # or codex | both | <custom dir>
-npx skills add khanglvm/relay      # via the skills installer, straight from this repo
-```
-
-`rly help` and `rly agent` also point agents at the skill, so an agent that
-merely has the CLI installed can discover and self-install it.
+| `rly help` | every command at a glance |
+| `rly agent` | the full agent guide — spec format, all block types, annotations, patterns ([docs/AGENT.md](docs/AGENT.md)) |
+| `rly schema` | board spec JSON Schema |
+| [skills/relay/SKILL.md](skills/relay/SKILL.md) | the bundled skill |
 
 ## Development
 
@@ -388,15 +67,9 @@ npm test     # zero-dep smoke tests (spawns real servers, fake-submits)
 
 ## Migration from quest-board
 
-relay was formerly published as `@khanglvm/quest-board` (CLI: `qbd`). That
-package is deprecated; install `@khanglvm/relay` instead.
-
-- Storage moved from `~/.quest-board` to `~/.relay`. Override with `RLY_HOME`.
-  There is no automatic migration — copy boards manually if needed.
-- The old `QUEST_BOARD_HOME` env var is still read as a fallback during the
-  transition period.
-- Legacy `"html"` / `"htmlFile"` / `"htmlHeight"` fields in specs continue to
-  work and are silently normalised into an html block.
+relay was formerly `@khanglvm/quest-board` (CLI: `qbd`) — that package is
+deprecated. Storage moved from `~/.quest-board` to `~/.relay` (override with
+`RLY_HOME`); legacy `"html"` / `"htmlFile"` spec fields keep working.
 
 ## License
 

package/docs/AGENT.md

@@ -82,7 +82,14 @@ rly show --html-file prototype.html --title "Dashboard concept" --height 600
     { "id": "confidence", "type": "scale", "label": "Confidence?", "min": 1, "max": 5,
       "minLabel": "low", "maxLabel": "high" },
     { "id": "layout", "type": "single", "label": "Which layout?", "options": ["left", "right"],
-      "blocks": [{ "type": "markdown", "md": "Compare the two options above." }] }
+      "blocks": [{ "type": "markdown", "md": "Compare the two options above." }] },
+    { "id": "variant", "type": "single", "label": "Which design variant?",
+      "options": [                                      // blocks INSIDE an option = visual choice
+        { "value": "hero", "label": "Hero", "blocks": [
+          { "type": "image", "src": "hero-mock.png", "height": 180 } ] },
+        { "value": "split", "label": "Split", "blocks": [
+          { "type": "html", "html": "<div style='display:flex'>…</div>", "height": 180 } ] }
+      ] }
   ]
 }
 ```
@@ -136,9 +143,45 @@ so far.
 
 ## Blocks
 
-Blocks can appear at the board level (`"blocks": [...]` on the root object) or
-per question (`"blocks": [...]` on a question object). Heights clamp to
-100–2400 px.
+Every visual block (mermaid / graphviz / plantuml / chart / table / html /
+image) automatically gets a full-screen button (4-corner expand icon, Esc
+closes); diagrams and images also zoom with cmd/ctrl+wheel. Don't shrink large
+diagrams to make them fit — the user can always expand and zoom; annotations
+keep working at any zoom and inside full-screen.
+
+Blocks can appear at the board level (`"blocks": [...]` on the root object),
+per question (`"blocks": [...]` on a question object), or per OPTION of a
+single/multi question (`"blocks": [...]` on an option object). Heights clamp
+to 100–2400 px.
+
+### Option-level visuals — show each choice
+
+When a question's options are inherently visual — design variants, layouts,
+screenshots, palette/chart-style alternatives, competing architectures — give
+EACH option a compact block so the user picks by looking instead of reading a
+description and guessing:
+
+```jsonc
+{ "id": "scheme", "type": "single", "label": "Color scheme?",
+  "options": [
+    { "value": "warm", "label": "Warm", "description": "terracotta accent",
+      "blocks": [{ "type": "html", "html": "<div style='background:#C2674B;height:100%'></div>", "height": 140 }] },
+    { "value": "cool", "label": "Cool", "description": "slate accent",
+      "blocks": [{ "type": "image", "src": "cool-preview.png", "height": 140 }] }
+  ] }
+```
+
+Rules of thumb:
+
+- Any block type works inside an option (image, html, chart, mermaid,
+  graphviz, plantuml, table, code, markdown).
+- Keep option visuals **compact** — `"height"` ~140–260. They render inside the
+  option card, under the label/description.
+- Interacting with the visual (zoom, annotate, chart hover) never toggles the
+  option; the label row is what selects. Option visuals stay fully annotatable.
+- Use this whenever the choice has visual/example context; skip it for plainly
+  textual options. It beats one big side-by-side comparison block because the
+  selected visual is unambiguous.
 
 ### All block shapes
 
@@ -205,6 +248,11 @@ per question (`"blocks": [...]` on a question object). Heights clamp to
 // HTML — sandboxed iframe; default height 360
 { "type": "html", "html": "<h1>Hello</h1>", "height": 360 }
 { "type": "html", "htmlFile": "viz.html",   "height": 400 }
+
+// Image — local file path (embedded at spec time, works offline), http(s) URL,
+// or data URI. "height" caps the displayed height; zoom/full-screen included.
+{ "type": "image", "src": "screenshots/variant-a.png", "alt": "Variant A", "height": 220 }
+{ "type": "image", "src": "https://example.com/mock.png" }
 ```
 
 ### When to use which block
@@ -218,6 +266,7 @@ per question (`"blocks": [...]` on a question object). Heights clamp to
 | `table` | structured comparisons, option matrices, data grids |
 | `markdown` | prose context, background, instructions, section headings |
 | `code` | code snippets, config examples, command output |
+| `image` | screenshots, mockup exports, photos — local files embed and work offline |
 | `html` | anything else — pixel-perfect mockups, custom widgets, embeds |
 
 ### Height rules
@@ -226,8 +275,11 @@ per question (`"blocks": [...]` on a question object). Heights clamp to
 - `mermaid`: natural flow, max-height 1200 px with internal scroll. Override with `"height"`.
 - `chart`: default 320 px. Override with `"height"`.
 - `html`: default 360 px. Override with `"height"`.
+- `image`: natural size (never upscaled), max-height 1200 px with scroll. `"height"` caps it.
 - `table`: natural flow.
 - All heights clamp to 100–2400 px.
+- Inside OPTION cards, always set a compact `"height"` (~140–260) on
+  chart/html/image blocks — the per-scope defaults are tuned for full-width use.
 
 ## Custom HTML sizing contract
 
@@ -298,7 +350,7 @@ intro. Annotations are autosaved with the draft and returned in the final result
 | `table-cell` | `row` (0-based), `col` (column key), `value` | clicking a table cell |
 | `text` | `quote`, `prefix` (≤30 chars before), `suffix` (≤30 after) | selecting text in a markdown block |
 | `html-element` | `label`, `detail?` | clicking a `relayKit.commentable()` element |
-| `image` | `label` | clicking the PlantUML diagram image |
+| `image` | `label` | clicking a PlantUML diagram or an image block |
 
 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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@khanglvm/relay",
-  "version": "0.4.2",
+  "version": "0.5.0",
   "description": "Browser-based question boards with rich blocks (markdown, charts, mermaid, tables, code, sandboxed HTML) and element-level annotations for AI coding agents (Claude Code, Codex, …): ask users structured questions, present interactive visuals, collect inline comments, wait for submit, read answers as JSON.",
   "keywords": [
     "ai-agents",

package/skills/relay/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: relay
-description: "Show the user anything visual in an interactive browser board - repo/file structures, architecture diagrams (mermaid, graphviz, plantuml, uml), charts, sortable tables, code, prototypes - and/or ask structured questions (choice, yes-no, text, scale), then wait for Submit and read JSON answers plus element comments and user-edited diagrams. PROACTIVELY use instead of (a) drawing an ASCII tree/table/diagram in the terminal or describing a structure/design/plan in prose, (b) a native ask-user tool for 2+ questions or options needing explanation, (c) hand-rolling an HTML demo + server. Triggers: show me the structure, repo/folder structure, file tree, directory layout, codebase map, architecture overview, dependency graph, sequence/class diagram, uml, visualize, diagram, chart, data table, metrics review, prototype review, plan approval, design feedback, compare alternatives, edit the diagram, clarify requirements, survey, ask the user, show the user, get feedback. Skip for a single trivial yes/no confirmation."
+description: "The tool for collecting user requirements, decisions, and answers (choice, yes-no, text, scale questions) and for presenting prototypes, plans, structures, or reports with rich visuals - mermaid/graphviz/plantuml diagrams, charts, sortable tables, custom HTML - plus inline comments on any element. Opens a browser board, waits for Submit, returns JSON answers, comments, and edited diagrams. Use PROACTIVELY instead of (a) native ask-user tools for 2+ answers or options needing explanation, (b) ASCII trees/tables/diagrams in the terminal or prose descriptions of structures/designs/plans, (c) hand-rolled HTML demos. Triggers: collect requirements, ask the user, get decisions/feedback, present a prototype, plan approval, design review, show me the structure, repo/folder structure, file tree, codebase map, architecture overview, dependency graph, visualize, diagram, chart, data table, compare alternatives, survey, which do you prefer, let the user edit the diagram. Skip for a single trivial yes/no confirmation."
 ---
 
 # relay (`rly`)
@@ -23,6 +23,7 @@ Schema).** The essentials are below.
 | One trivial confirmation ("proceed?") | native tool |
 | 2+ questions, or options that need descriptions | **rly** |
 | Choice is easier to make visually (layouts, designs, diagrams) | **rly** (blocks per question) |
+| Each OPTION has its own visual (design variants, screenshots, charts) | **rly** (blocks per option) |
 | Show metrics / trends / data comparisons | **rly** (chart + table blocks) |
 | Present a prototype / demo an idea | **rly show** — never hand-roll an HTML file + server |
 | Gather requirements / plan approval / feedback round | **rly** |
@@ -102,7 +103,8 @@ rly ask -q "Deploy now?::yesno" -q "!Env::single::dev,staging,prod"   # "!" = re
 
 ## Blocks cheat-sheet
 
-Add `"blocks": [...]` to the root or to any question.
+Add `"blocks": [...]` to the root, to any question, or to any OPTION of a
+single/multi question.
 
 ```jsonc
 { "type": "markdown", "md": "## Section\n**prose**" }
@@ -117,8 +119,33 @@ Add `"blocks": [...]` to the root or to any question.
 { "type": "code",     "lang": "js",  "code": "const x = 1;" }
 { "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
+{ "type": "image",    "src": "https://…/mock.png", "alt": "Mockup B", "height": 220 }
 ```
 
+### Visual options — show each choice, don't describe it
+
+When the options themselves are visual (design variants, layouts, color
+schemes, chart styles, architecture alternatives, screenshots), put a compact
+block INSIDE each option so the user compares by looking, not by reading and
+guessing:
+
+```jsonc
+{ "id": "layout", "type": "single", "label": "Which landing layout?",
+  "options": [
+    { "value": "hero",  "label": "Hero",  "description": "big banner",
+      "blocks": [{ "type": "image", "src": "hero.png", "height": 180 }] },
+    { "value": "split", "label": "Split", "description": "text + visual",
+      "blocks": [{ "type": "html", "html": "<div style='display:flex'>…</div>", "height": 180 }] }
+  ] }
+```
+
+Any block type works per option. Keep option visuals compact (`height`
+~140–260) — they sit inside the option card. Clicking a visual never toggles
+the option (and stays annotatable); the label row selects. Use per-option
+blocks whenever a question's choices have visual/example context; skip them
+for plainly textual options.
+
 Chart.js, Mermaid, and Graphviz are **vendored and lazy-loaded** — the base board
 stays dependency-free. PlantUML uses the public plantuml.com server by default;
 pass `"server"` for a self-hosted instance. Legacy `"html"` / `"htmlFile"` /
@@ -172,8 +199,8 @@ one `textarea` for concerns.
 (options with `description`s + `"other": true`), `multi` for scope, `scale` for
 urgency, `textarea` for constraints.
 
-**A/B design review** — `single` question with a `blocks` array containing an
-`html` block showing both options side by side; options `["A", "B"]`; `scale`
+**A/B design review** — `single` question where EACH option carries its own
+`html`/`image` block rendering that variant (see Visual options above); `scale`
 for confidence; `textarea` for what's missing from both.
 
 **Metrics review** — board-level `chart` block (bar or line) showing the key

package/src/cli.js

@@ -735,8 +735,29 @@ function removeLegacySkills() {
   return removed;
 }
 
+// Short instruction block for an agent's main instruction file (CLAUDE.md,
+// AGENTS.md, …). A skill is only a tier-1 hint that agents can ignore; these
+// rules, appended to the instructions the agent always reads, enforce usage.
+// Printed to stdout so `rly skill rules >> CLAUDE.md` is the whole install.
+const SKILL_RULES = `## relay — ask & show in the browser, not the terminal
+
+- Need the user's decisions, feedback, requirements, or approval (anything
+  beyond one trivial yes/no)? Do NOT ask in plain terminal text. Build a board
+  spec and run: \`rly ask --file spec.json --detach\`, then \`rly wait <boardId>\`.
+- Presenting a plan, structure, architecture, data, or a prototype? Show a
+  relay board with mermaid/graphviz/chart/table/image/html blocks — never
+  ASCII diagrams or walls of prose.
+- When answer choices are visual (designs, layouts, variants), give each
+  option its own visual (\`options[].blocks\`) so the user picks by looking.
+- Read the result JSON from stdout; treat \`comment\` and \`annotations\` as
+  first-class feedback. Full guide: \`rly agent\`.`;
+
 function cmdSkill(rest) {
   const sub = rest[0];
+  if (sub === 'rules') {
+    console.log(SKILL_RULES);
+    return 0;
+  }
   if (sub === 'path') {
     console.log(SKILL_SRC);
     process.stderr.write('(bundled skill source — copy into your agent with `rly skill install`)\n');
@@ -759,9 +780,11 @@ function cmdSkill(rest) {
   console.log(`relay ships a universal agent skill (Claude Code, Codex, and any SKILL.md-aware agent).
 
   bundled at:  ${SKILL_SRC}
-  install it:  rly skill install            # auto-detects ~/.claude and ~/.codex
+  install it:  rly skill install            # auto-detects ~/.claude, ~/.codex, ~/.agents
                rly skill install --target claude|codex|both|<dir>
   from repo:   npx skills add khanglvm/relay
+  enforce it:  rly skill rules >> CLAUDE.md # or AGENTS.md — short always-read rules,
+                                            # because a skill alone is an ignorable hint
 
 The skill teaches your agent the board spec format (questions + rich blocks +
 annotations), the blocking vs --detach patterns, and visualization sizing.
@@ -816,7 +839,8 @@ USAGE
   rly rm <id> | --all                 delete saved board(s)
   rly schema                          JSON Schema of the board spec
   rly agent                           FULL GUIDE for AI agents (spec format, blocks, sizing, patterns)
-  rly skill [install|path]            bundled universal agent skill (Claude Code, Codex, …)
+  rly skill [install|rules|path]      bundled universal agent skill (Claude Code, Codex, …)
+                                      \`rly skill rules >> CLAUDE.md\` adds always-read usage rules
 
 COMMON FLAGS
   --title <s> --intro <s> --html-file <f> --height <px> --submit-label <s>

package/src/server.js

@@ -25,19 +25,37 @@ function readUi(name) {
 }
 
 // Strips block bodies for the client payload: html blocks ship only metadata
-// (their bodies are served via /html/b/<id>), everything else ships as-is.
+// (their bodies are served via /html/b/<id>), embedded images ship only
+// metadata (bytes served via /img/b/<id>), everything else ships as-is.
 function clientBlock(b) {
   if (b && b.type === 'html') {
     return { id: b.id, type: 'html', height: b.height, hasHtml: Boolean(b.html) };
   }
+  if (b && b.type === 'image' && typeof b.src === 'string' && b.src.startsWith('data:')) {
+    return { id: b.id, type: 'image', alt: b.alt, height: b.height, hasData: true };
+  }
   return b;
 }
 
+// One question for the client payload: strip block bodies at the question
+// level AND inside each option's blocks.
+function clientQuestion(q) {
+  const out = { ...q, blocks: (q.blocks || []).map(clientBlock) };
+  if (Array.isArray(q.options)) {
+    out.options = q.options.map((o) =>
+      o && Array.isArray(o.blocks) && o.blocks.length ? { ...o, blocks: o.blocks.map(clientBlock) } : o
+    );
+  }
+  return out;
+}
+
 // True when any block in the spec needs a given vendored library.
 function specNeeds(spec, type) {
   const has = (blocks) => Array.isArray(blocks) && blocks.some((b) => b && b.type === type);
   if (has(spec.blocks)) return true;
-  return spec.questions.some((q) => has(q.blocks));
+  return spec.questions.some(
+    (q) => has(q.blocks) || (Array.isArray(q.options) && q.options.some((o) => o && has(o.blocks)))
+  );
 }
 
 function vendorPresent(file) {
@@ -62,7 +80,7 @@ function buildPage(record, rev) {
   const clientSpec = {
     ...spec,
     blocks: (spec.blocks || []).map(clientBlock),
-    questions: spec.questions.map((q) => ({ ...q, blocks: (q.blocks || []).map(clientBlock) })),
+    questions: spec.questions.map(clientQuestion),
   };
   // Tell the client which vendored libraries to lazy-load — true only when a
   // block needs it AND the vendored asset is actually present.
@@ -150,18 +168,26 @@ function sanitizeBlockEdits(value) {
   return out;
 }
 
-// Resolves an html block body by id from the board or any question scope.
-function findHtmlBlock(spec, blockId) {
-  const scan = (blocks) => (Array.isArray(blocks) ? blocks.find((b) => b && b.id === blockId && b.type === 'html') : undefined);
+// Resolves a block by id + type from the board, any question, or any option.
+function findBlock(spec, blockId, type) {
+  const scan = (blocks) => (Array.isArray(blocks) ? blocks.find((b) => b && b.id === blockId && b.type === type) : undefined);
   const board = scan(spec.blocks);
   if (board) return board;
   for (const q of spec.questions) {
     const hit = scan(q.blocks);
     if (hit) return hit;
+    for (const o of Array.isArray(q.options) ? q.options : []) {
+      const opt = o && scan(o.blocks);
+      if (opt) return opt;
+    }
   }
   return undefined;
 }
 
+function findHtmlBlock(spec, blockId) {
+  return findBlock(spec, blockId, 'html');
+}
+
 // The board's first html block (legacy /html/board alias).
 function firstBoardHtml(spec) {
   return (spec.blocks || []).find((b) => b && b.type === 'html');
@@ -379,6 +405,14 @@ export async function runBoard({ id, port = 0, open = true, timeoutSec = 1800, q
         const block = findHtmlBlock(record.spec, blockId);
         if (!block) return sendJson(res, 404, { error: `no html block "${blockId}"` });
         sendHtml(res, wrapFragment(block.html || '', theme));
+      } else if (req.method === 'GET' && pathname.startsWith('/img/b/')) {
+        // Embedded image bytes (image blocks authored from local files).
+        const blockId = decodeURIComponent(pathname.slice('/img/b/'.length));
+        const block = findBlock(record.spec, blockId, 'image');
+        const m = block && typeof block.src === 'string' ? block.src.match(/^data:([^;,]+);base64,(.*)$/s) : null;
+        if (!m) return sendJson(res, 404, { error: `no embedded image block "${blockId}"` });
+        res.writeHead(200, { 'content-type': m[1], 'cache-control': 'no-store' });
+        res.end(Buffer.from(m[2], 'base64'));
       } else if (req.method === 'GET' && pathname === '/html/board') {
         // Legacy alias → the board's first html block.
         const block = firstBoardHtml(record.spec);

package/src/spec.js

@@ -25,9 +25,17 @@ 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', 'html'];
+export const BLOCK_TYPES = ['markdown', 'mermaid', 'graphviz', 'plantuml', 'chart', 'table', 'code', 'html', 'image'];
 const CHART_KINDS = ['bar', 'line', 'pie', 'doughnut', 'radar', 'scatter'];
 
+// 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 = {
+  png: 'image/png', jpg: 'image/jpeg', jpeg: 'image/jpeg', gif: 'image/gif',
+  webp: 'image/webp', svg: 'image/svg+xml', avif: 'image/avif', bmp: 'image/bmp',
+};
+const IMAGE_MAX_BYTES = 8 * 1024 * 1024;
+
 const asStr = (v) => (typeof v === 'string' ? v : v == null ? '' : String(v));
 
 function clampInt(v, min, max, def) {
@@ -210,6 +218,35 @@ function normalizeBlock(rawBlock, id, cwd, where) {
     return block;
   }
 
+  if (type === 'image') {
+    const src = asStr(rawBlock.src ?? rawBlock.file ?? rawBlock.url).trim();
+    if (!src) throw new CliError(`${where}: image block needs a "src" (http(s)/data URL or local file path).`);
+    const block = { id, type: 'image' };
+    if (rawBlock.alt !== undefined) block.alt = asStr(rawBlock.alt);
+    if (hasHeight) block.height = clampInt(rawBlock.height, BLOCK_HEIGHT.min, BLOCK_HEIGHT.max, undefined);
+    if (/^(https?:|data:)/i.test(src)) {
+      block.src = src;
+      return block;
+    }
+    const p = path.resolve(cwd, src);
+    const ext = path.extname(p).slice(1).toLowerCase();
+    const mime = IMAGE_MIMES[ext];
+    if (!mime) {
+      throw new CliError(`${where}: unsupported image extension ".${ext}" — use ${Object.keys(IMAGE_MIMES).join('/')}, or an http(s)/data URL.`);
+    }
+    let buf;
+    try {
+      buf = fs.readFileSync(p);
+    } catch {
+      throw new CliError(`${where}: cannot read image "${src}" (resolved: ${p})`);
+    }
+    if (buf.length > IMAGE_MAX_BYTES) {
+      throw new CliError(`${where}: image "${src}" is ${(buf.length / 1024 / 1024).toFixed(1)}MB — max ${IMAGE_MAX_BYTES / 1024 / 1024}MB.`);
+    }
+    block.src = `data:${mime};base64,${buf.toString('base64')}`;
+    return block;
+  }
+
   // type === 'html'
   const html = readBlockHtml(rawBlock, cwd, where);
   if (!html) {
@@ -312,9 +349,14 @@ export function normalizeSpec(raw, { cwd = process.cwd() } = {}) {
           if (!value) throw new CliError(`${where}.options[${j}]: needs "value" or "label".`);
           const out = { value, label: olabel || value };
           if (o.description) out.description = asStr(o.description);
+          // Per-option visuals: any block type, rendered inside the option card
+          // (ids <qid>-o<n>-b<m>). Lets a choice show its example instead of
+          // making the user read-and-guess.
+          const oblocks = buildBlocks(o, cwd, `${where}.options[${j}]`, `${id}-o${j + 1}-`);
+          if (oblocks.length) out.blocks = oblocks;
           return out;
         }
-        throw new CliError(`${where}.options[${j}]: must be a string or {value, label, description?}.`);
+        throw new CliError(`${where}.options[${j}]: must be a string or {value, label, description?, blocks?}.`);
       });
       if (q.options.length < 1) {
         throw new CliError(`${where}: type "${type}" needs at least 1 option.`);
@@ -390,7 +432,9 @@ const BLOCK_SCHEMA = {
       sortable: { type: 'boolean', description: 'table: enable click-to-sort headers.' },
       html: { type: 'string', description: 'html: custom markup rendered in a sandboxed iframe.' },
       htmlFile: { type: 'string', description: 'html: path to an HTML file (alternative to "html").' },
-      height: { type: 'integer', minimum: BLOCK_HEIGHT.min, maximum: BLOCK_HEIGHT.max, description: 'Block height in px. Defaults: chart 320, html 360; markdown/table/code flow naturally; mermaid/graphviz/plantuml natural (max 1200, scrolls).' },
+      src: { type: 'string', description: 'image: http(s)/data URL, or a local file path (png/jpg/gif/webp/svg/avif/bmp — embedded at spec time, served offline).' },
+      alt: { type: 'string', description: 'image: alt text / annotation label.' },
+      height: { type: 'integer', minimum: BLOCK_HEIGHT.min, maximum: BLOCK_HEIGHT.max, description: 'Block height in px. Defaults: chart 320, html 360; markdown/table/code flow naturally; mermaid/graphviz/plantuml/image natural (max 1200, scrolls).' },
     },
   },
 };
@@ -425,13 +469,18 @@ export const SPEC_SCHEMA = {
           required: { type: 'boolean', default: false },
           options: {
             type: 'array',
-            description: 'For single/multi. Strings, or {value, label, description}.',
+            description: 'For single/multi. Strings, or {value, label, description, blocks?}. An option\'s "blocks" render INSIDE that option card — use them to show each choice (image/chart/mermaid/html…) instead of describing it in words.',
             items: {
               anyOf: [
                 { type: 'string' },
                 {
                   type: 'object',
-                  properties: { value: { type: 'string' }, label: { type: 'string' }, description: { type: 'string' } },
+                  properties: {
+                    value: { type: 'string' },
+                    label: { type: 'string' },
+                    description: { type: 'string' },
+                    blocks: { ...BLOCK_SCHEMA, description: 'Visuals for THIS option, rendered inside its card. Same block types as everywhere else. Keep them compact (height ~140–260).' },
+                  },
                 },
               ],
             },

package/src/ui/app.js

@@ -286,9 +286,22 @@
     for (const lab of group.querySelectorAll('label.opt')) {
       const input = lab.querySelector('input');
       lab.classList.toggle('sel', input.checked);
+      // options with visuals: the bordered card is the wrapper, not the label
+      const wrap = lab.closest('.optwrap');
+      if (wrap) wrap.classList.toggle('sel', input.checked);
     }
   }
 
+  // Options may carry their own blocks (visual examples of the choice). The
+  // blocks render in a wrapper card OUTSIDE the <label> so interacting with a
+  // chart/diagram/image doesn't toggle the option.
+  function withOptionBlocks(labelEl, o, questionId) {
+    if (!Array.isArray(o.blocks) || !o.blocks.length) return labelEl;
+    const wrap = el('div', { class: 'optwrap' + (labelEl.classList.contains('sel') ? ' sel' : '') }, labelEl);
+    renderBlocks(wrap, o.blocks, questionId);
+    return wrap;
+  }
+
   function controlSingle(q) {
     const group = el('div');
     const entries = [];
@@ -327,12 +340,16 @@
         syncSingle();
       });
       group.append(
-        el('label', { class: 'opt' + (input.checked ? ' sel' : '') },
-          input,
-          el('div', {},
-            el('div', { class: 'ol' }, o.label),
-            o.description ? el('div', { class: 'od' }, o.description) : null
-          )
+        withOptionBlocks(
+          el('label', { class: 'opt' + (input.checked ? ' sel' : '') },
+            input,
+            el('div', {},
+              el('div', { class: 'ol' }, o.label),
+              o.description ? el('div', { class: 'od' }, o.description) : null
+            )
+          ),
+          o,
+          q.id
         )
       );
     }
@@ -391,12 +408,16 @@
       input.checked = selected.has(o.value);
       input.addEventListener('change', readChecked);
       group.append(
-        el('label', { class: 'opt' + (input.checked ? ' sel' : '') },
-          input,
-          el('div', {},
-            el('div', { class: 'ol' }, o.label),
-            o.description ? el('div', { class: 'od' }, o.description) : null
-          )
+        withOptionBlocks(
+          el('label', { class: 'opt' + (input.checked ? ' sel' : '') },
+            input,
+            el('div', {},
+              el('div', { class: 'ol' }, o.label),
+              o.description ? el('div', { class: 'od' }, o.description) : null
+            )
+          ),
+          o,
+          q.id
         )
       );
     }

package/src/ui/blocks.css

@@ -140,7 +140,7 @@
 .blk-chart canvas { display: block; }
 .blk-chart-badge {
   position: absolute;
-  top: 6px;
+  top: 40px; /* below the viewer bar strip */
   right: 6px;
   min-width: 18px;
   height: 18px;
@@ -266,26 +266,43 @@
   height: auto;
 }
 
-/* ---------- viewer controls (zoom / fit / full-screen) ---------- */
-.blk-viewer { position: relative; }
+/* ---------- image ---------- */
+.blk-imagewrap {
+  overflow: auto;
+  max-height: 1200px;
+  border: 1px solid var(--border);
+  border-radius: 10px;
+  background: var(--bg-sunken);
+  padding: 6px;
+}
+.blk-imagewrap .blk-img {
+  display: block;
+  max-width: 100%;
+  height: auto;
+  border-radius: 6px;
+  object-fit: contain;
+  object-position: left top;
+}
+
+/* ---------- viewer controls (full-screen) ---------- */
+/* The full-screen button lives in a reserved strip ABOVE the visual (user
+   feedback: never overlay the content). padding-top reserves the strip;
+   the bar is a full-width transparent row with the button at the right. */
+.blk-viewer { position: relative; padding-top: 34px; }
 .blk-tools {
-  position: absolute; top: 6px; right: 6px;
-  display: flex; gap: 2px; align-items: center;
-  background: var(--card); border: 1px solid var(--border);
-  border-radius: 8px; padding: 2px 4px;
-  opacity: 0.35; transition: opacity 150ms var(--ease);
+  position: absolute; top: 4px; left: 4px; right: 4px; height: 26px;
+  display: flex; gap: 2px; align-items: center; justify-content: flex-end;
   z-index: 5;
 }
-.blk-viewer:hover .blk-tools, .blk-full .blk-tools { opacity: 1; }
 .blk-tools button {
-  background: none; border: none; color: var(--fg-2);
+  background: var(--card); border: 1px solid var(--border); color: var(--fg-2);
   font: inherit; font-size: 0.8rem; line-height: 1;
-  padding: 4px 6px; border-radius: 6px; cursor: pointer;
+  padding: 5px 7px; border-radius: 7px; cursor: pointer;
+  transition: color 150ms var(--ease), border-color 150ms var(--ease);
 }
-.blk-tools button:hover { background: var(--bg-sunken); color: var(--accent); }
+.blk-tools button:hover { color: var(--accent); border-color: var(--accent); }
+.blk-tools .tool-full svg { display: block; }
 .blk-tools .tool-pct { color: var(--muted); font-size: 0.72rem; min-width: 30px; text-align: center; }
-/* charts keep their annotation-count badge top-right; tools go top-left there */
-.blk-chart .blk-tools { right: auto; left: 6px; }
 
 /* full-screen = fixed overlay (NOT native fullscreen: annotation pins/badges/
    popover live on <body> and must stay visible above the expanded block) */

package/src/ui/blocks.js

@@ -339,7 +339,11 @@
       }
     }
     rebuild();
-    return table;
+    // Tables are visual too: wrap so they get the full-screen viewer like
+    // every other visual block (wide tables squeeze in the column).
+    const wrap = el('div', { class: 'blk-tablewrap' }, table);
+    attachViewer(wrap, { zoomEl: null });
+    return wrap;
   }
 
   // ---------- lazy vendor loaders (cached promises) ----------
@@ -908,6 +912,43 @@
     return container;
   }
 
+  // ---------- image ----------
+  // src is a remote URL, or absent for embedded local files (served by the
+  // board server at /img/b/<id>). Same sizing rule as diagrams: never upscale
+  // past natural width; zoom/full-screen viewer attached once loaded.
+  function renderImage(block, ctx, blockId) {
+    const container = el('div', { class: 'blk-imagewrap' });
+    const src = typeof block.src === 'string' && block.src
+      ? block.src
+      : '/img/b/' + encodeURIComponent(blockId);
+    const img = el('img', {
+      class: 'blk-img',
+      src,
+      alt: block.alt || 'image',
+      loading: 'lazy',
+    });
+    if (block.height) img.style.maxHeight = clampHeight(block.height, 360) + 'px';
+    img.addEventListener('error', () => {
+      container.replaceChildren(el('div', { class: 'blk-error' }, 'Image failed to load'));
+    });
+    container.append(img);
+    const attachImgViewer = () =>
+      attachViewer(container, {
+        zoomEl: img,
+        natural: () => (img.naturalWidth > 0 ? { w: img.naturalWidth, h: img.naturalHeight } : null),
+      });
+    if (img.complete && img.naturalWidth > 0) attachImgViewer();
+    else img.addEventListener('load', attachImgViewer, { once: true });
+    if (ctx.annotate) {
+      ctx.annotate.register(img, {
+        blockId,
+        questionId: ctx.questionId,
+        target: { kind: 'image', label: block.alt || 'Image' },
+      });
+    }
+    return container;
+  }
+
   // ---------- viewer controls (zoom / fit / full-screen) ----------
   // Large diagrams get squeezed to the column width; these controls let the
   // user zoom (buttons or cmd/ctrl+wheel) and expand any visual block into a
@@ -916,12 +957,19 @@
   // <body>, which native fullscreen would hide).
   let fullOpen = null; // container currently expanded
 
+  // 4-corner expand icon. The toolbar deliberately holds ONLY the full-screen
+  // button (user feedback: the zoom button row was noise) — zooming stays
+  // available via cmd/ctrl+wheel on zoomable blocks.
+  const ICON_EXPAND =
+    '<svg viewBox="0 0 24 24" width="13" height="13" fill="none" stroke="currentColor" stroke-width="2.2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true">' +
+    '<path d="M3 9V3h6M10 10 3 3M15 3h6v6M14 10l7-7M9 21H3v-6M10 14l-7 7M21 15v6h-6M14 14l7 7"/></svg>';
+
   function exitFull() {
     if (!fullOpen) return;
     fullOpen.classList.remove('blk-full');
     document.body.classList.remove('blk-full-open');
     const btn = fullOpen.querySelector('.blk-tools .tool-full');
-    if (btn) btn.textContent = '⛶';
+    if (btn) btn.innerHTML = ICON_EXPAND;
     fullOpen = null;
     window.dispatchEvent(new Event('resize'));
   }
@@ -970,13 +1018,7 @@
 
     const tools = el('div', { class: 'blk-tools' });
     if (zoomable) {
-      tools.append(
-        el('button', { type: 'button', title: 'Zoom out', onclick: () => setZoom(currentZ() / 1.25) }, '−'),
-        pct,
-        el('button', { type: 'button', title: 'Zoom in', onclick: () => setZoom(currentZ() * 1.25) }, '+'),
-        el('button', { type: 'button', title: 'Actual size', onclick: () => setZoom(1) }, '1:1'),
-        el('button', { type: 'button', title: 'Fit to width', onclick: () => setZoom(null) }, 'fit')
-      );
+      // zoom lives on cmd/ctrl+wheel only — the toolbar is full-screen-only
       container.addEventListener(
         'wheel',
         (e) => {
@@ -987,7 +1029,8 @@
         { passive: false }
       );
     }
-    const fullBtn = el('button', { class: 'tool-full', type: 'button', title: 'Full screen (Esc closes)' }, '⛶');
+    const fullBtn = el('button', { class: 'tool-full', type: 'button', title: 'Full screen (Esc closes; cmd/ctrl+wheel zooms)' });
+    fullBtn.innerHTML = ICON_EXPAND;
     fullBtn.addEventListener('click', () => {
       if (fullOpen === container) {
         exitFull();
@@ -1070,6 +1113,10 @@
         inner = renderHtml(block, ctx, blockId);
         wrapper.append(inner);
         break;
+      case 'image':
+        inner = renderImage(block, ctx, blockId);
+        wrapper.append(inner);
+        break;
       default:
         wrapper.append(el('div', { class: 'blk-error' }, 'Unknown block type: ' + esc(String(block.type))));
     }

package/src/ui/style.css

@@ -144,6 +144,23 @@ h1 {
 .opt .od { color: var(--muted); font-size: 0.85rem; }
 .opt .otherbox { margin-top: 6px; }
 
+/* options carrying visual blocks: the wrapper card is the selectable unit;
+   the inner label stays clickable, the blocks below it don't toggle */
+.optwrap {
+  border: 1px solid var(--border); border-radius: 10px;
+  margin: 8px 0;
+  transition: border-color 150ms var(--ease), background 150ms var(--ease);
+}
+.optwrap:hover { border-color: var(--accent); }
+.optwrap.sel { border-color: var(--accent); background: var(--accent-soft); }
+.optwrap > .opt { border: none; margin: 0; background: none; }
+.optwrap > .blocks { padding: 0 14px 12px 40px; }
+.optwrap .blk { margin-top: 10px; }
+.optwrap .blk:first-child { margin-top: 0; }
+@media (max-width: 600px) {
+  .optwrap > .blocks { padding-left: 14px; }
+}
+
 .seg { display: flex; gap: 8px; flex-wrap: wrap; }
 .seg button, .scale button {
   background: var(--card); color: var(--fg);