@khanglvm/relay 0.4.3 → 0.5.1

package/README.md

@@ -1,31 +1,26 @@
 # 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
+**Visual answer options** — every choice carries its own chart/image/diagram, so you pick by looking:
 
-## See it
+![Visual answer options: clicking between two options that each carry their own chart](https://raw.githubusercontent.com/khanglvm/relay/main/docs/assets/feature-options.gif)
+
+**Comment on anything** — click a chart bar, diagram node, table cell, or sentence; comments return to the agent with the answers:
+
+![Clicking a chart bar and leaving an inline comment](https://raw.githubusercontent.com/khanglvm/relay/main/docs/assets/feature-annotate.gif)
+
+**Full-screen any visual** — one button above every chart, diagram, table, image, and prototype:
+
+![Expanding a diagram into the full-screen overlay](https://raw.githubusercontent.com/khanglvm/relay/main/docs/assets/feature-fullscreen.gif)
 
 | Light theme | Dark theme |
 |---|---|
@@ -35,350 +30,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 +73,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,15 +143,45 @@ so far.
 
 ## Blocks
 
-Every visual block (mermaid / graphviz / plantuml / chart / html) automatically
-gets viewer controls: zoom in/out (or cmd/ctrl+wheel), 1:1, fit-to-width, and a
-full-screen overlay (Esc closes). 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.
+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) or
-per question (`"blocks": [...]` on a question object). Heights clamp to
-100–2400 px.
+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
 
@@ -211,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
@@ -224,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
@@ -232,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
 
@@ -304,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.3",
+  "version": "0.5.1",
   "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

@@ -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

@@ -132,15 +132,17 @@
 .blk-table tbody tr:last-child td { border-bottom: 0; }
 
 /* ---------- chart ---------- */
+/* NO height here: renderChart always sets the inline height, and this class
+   also lands on the outer .blk.blk-chart dispatch wrapper — a CSS height
+   would force every custom-height chart into a 320px box (dead space). */
 .blk-chart {
   position: relative;
   width: 100%;
-  height: 320px;
 }
 .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 +268,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);