@khanglvm/relay 0.11.0 → 0.12.1

package/README.md

@@ -123,9 +123,12 @@ npm test     # zero-dep smoke tests (spawns real servers, fake-submits)
 - **Streamable HTTP transport for web/mobile/remote** — `rly mcp --http
   [--port N --host H --token SECRET --allow-origin ORIGIN]` serves the same tools
   over MCP's Streamable HTTP transport (single `/mcp` endpoint, JSON responses,
-  CORS, Origin validation, bearer auth, `Mcp-Session-Id`). Expose it via a tunnel
-  or small host and add it as a custom connector so a phone/web host can render
-  boards too — stdio stays the zero-setup path for local desktop.
+  CORS, Origin validation, bearer auth, `Mcp-Session-Id`, `$PORT`-aware). relay is
+  **stateless**, so one instance serves everyone — deploy it once with the repo
+  **`Dockerfile`** on any free MCP host (mcpdeploy.dev, mcphosting.io,
+  Render/Railway/Fly, Glama) or publish to **Smithery**, then add the URL as a
+  custom connector. Only the relay CLI is required — no tunnel/tailscale. stdio
+  stays the zero-setup path for local desktop.
 - **Native look** — the inline board **color-blends** onto the host's SEP-1865
   style variables (surfaces, text, borders, primary button, fonts), pins
   `color-scheme` so `light-dark()` tokens resolve, and uses the host's **own
@@ -138,6 +141,9 @@ npm test     # zero-dep smoke tests (spawns real servers, fake-submits)
   copies); mark one `featured` for a spotlight. **`color` question type** — native
   picker + hex field + optional `presets`, returns a hex string. Both work on the
   browser board and inline.
+- **Element annotations inline** — comment on chart points, diagram nodes, table
+  cells, images and text selections in the MCP board too, returned in
+  `annotations` exactly like the CLI board.
 
 ### 0.10.0 — open files, richer code, diffs & video
 - **Clickable local file-links.** Write a path in any markdown (`~/clip.mp4`,

package/docs/AGENT.md

@@ -75,13 +75,25 @@ browser tab. `rly mcp` speaks the MCP **stdio** transport, so it pairs with a
 - **`relay_show`** — present a plan, diagram, diff, table, or prototype.
 
 **Web / mobile / remote hosts** can't reach a stdio subprocess, so for those run
-the **Streamable HTTP** transport instead: `rly mcp --http [--port N]` serves the
-same tools at `http://127.0.0.1:<port>/mcp`. Expose that URL (e.g. a
-cloudflared/ngrok tunnel, or a small always-on host) and register it as a custom
-connector; add `--token <secret>` + `--allow-origin <host>` when it's public.
-`rly mcp config` prints the recipe. Note: an HTTP server only sees local files if
-it runs on the machine those files live on (tunnel from your dev box to keep
-local `codeFile`/image blocks working).
+the **Streamable HTTP** transport: `rly mcp --http [--port N]` serves the same
+tools at `/mcp`. relay needs **only its own CLI** for this — no tunnel tool, no
+extra infra. Because relay is **stateless** (answers go iframe→host→model, never
+back to the server), **one deployed instance serves everyone**, so deploy it once
+on any address the app can reach and register that URL as a custom connector:
+
+- **Free MCP hosts** — the repo's `Dockerfile` runs relay with zero config on
+  **mcpdeploy.dev**, **mcphosting.io**, **Render / Railway / Fly**, or **Glama**;
+  the platform's `$PORT` is honored automatically. Set `RLY_MCP_TOKEN` for a
+  bearer-protected endpoint.
+- **Smithery** (largest MCP marketplace) — publish the deployed URL with
+  `smithery mcp publish <url> -n @you/relay` for discovery + an OAuth gateway, or
+  distribute relay as a stdio bundle clients run locally.
+- **Tunnel (optional, dev only)** — `cloudflared`/`tailscale` is *only* for
+  exposing a NAT'd laptop; it's never required and not a relay dependency.
+
+A hosted instance can't see your local files (so `codeFile`/local-image blocks
+won't resolve there — pass URLs or inline content); run it on your own machine if
+you need local-file access.
 
 Progressive rendering: if the host streams the tool call as you write it, the
 board renders valid blocks/questions incrementally (a "Composing…" preview) and
@@ -97,13 +109,15 @@ board stays live until the user submits and the host delivers the result.
 **Near-full parity with the browser board.** Local `codeFile` / `htmlFile` /
 `diffFile` and local **image** files work inline too — the server inlines them
 (images as data URIs) while normalizing your spec, so the sandboxed board needs
-no file access. The board also adopts the host's **theme, fonts and colors** and
-offers a **full-screen** toggle. The only inline-mode gaps vs. the browser board:
-**local video files** (use a YouTube/Vimeo/`https` URL instead — those play) and
-**element-level annotations** (comment-on-any-element) — per-question notes and
-the overall comment still carry feedback back to you. Everything else —
-questions plus markdown/code/diff/table/chart/mermaid/graphviz/plantuml/image/html
-— renders identically.
+no file access. **Element-level annotations work inline** — the user can comment
+on chart points, diagram nodes, table cells, images and text selections, returned
+in `annotations` just like the CLI. The board also adopts the host's **theme,
+fonts and colors** and uses the host's **full-screen** control. The only
+inline-mode gaps vs. the browser board: **local video files** (use a
+YouTube/Vimeo/`https` URL instead — those play) and commenting on elements
+*inside* a custom-HTML mockup (every other annotation target works). Everything
+else — questions plus markdown/code/diff/table/chart/mermaid/graphviz/plantuml/
+image/palette/html — renders identically.
 
 ## Creating boards
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@khanglvm/relay",
-  "version": "0.11.0",
+  "version": "0.12.1",
   "description": "Question boards with rich blocks (markdown, charts, mermaid, tables, code, diffs, video, sandboxed HTML), clickable local file-links, and element-level annotations for AI coding agents (Claude Code, Codex, …): ask users structured questions, present interactive visuals, collect inline comments, read answers as JSON — in a local browser board OR rendered INLINE inside the Claude & Codex apps as an MCP App (SEP-1865).",
   "keywords": [
     "ai-agents",

package/skills/relay/SKILL.md

@@ -104,8 +104,9 @@ answers and any annotations written so far.
 }
 ```
 
-Types: `single`, `multi`, `yesno`, `text`, `textarea`, `scale`. Users may
-submit with unanswered questions (returned in `skipped`) unless
+Types: `single`, `multi`, `yesno`, `text`, `textarea`, `scale`, `color`
+(native picker + hex; optional `"presets":["#…"]`, returns a hex string). Users
+may submit with unanswered questions (returned in `skipped`) unless
 `"allowPartial": false` or per-question `"required": true`.
 
 Set `"note": true` on a question to add a small optional free-text field under
@@ -155,6 +156,8 @@ single/multi question.
 //   screen + zoom (⌘/Ctrl+wheel or −/+, up to 8× native) + drag-to-pan viewer,
 //   so detail is always reachable regardless of height. Local images embed up
 //   to 8 MB; for a huge/high-detail image pass an http(s) URL (streamed, no cap).
+{ "type": "palette",  "palettes": [{ "name":"Brand", "colors":["#3B8EA5","#6DBAD1","#1E6278"], "featured": true }] }
+// ^ color palettes as swatch cards: hover=hex, click=copy. Shorthand {"type":"palette","colors":[…]}; pair with a `color` question.
 ```
 
 ### Visual options — show each choice, don't describe it

package/skills/relay/examples/palette-and-color.json

@@ -0,0 +1,42 @@
+{
+  "title": "Brand color direction",
+  "intro": "Pick a direction from the curated palettes, then choose the exact accent.",
+  "blocks": [
+    {
+      "type": "palette",
+      "title": "Candidate palettes — hover a swatch for its hex, click to copy",
+      "palettes": [
+        { "name": "Coastal Calm", "sub": "ocean, serene", "tag": "Cool", "tagTone": "cool", "featured": true,
+          "colors": ["#3B8EA5", "#6DBAD1", "#1E6278", "#A8DDE9", "#D6EEF5"] },
+        { "name": "Peach Fuzz", "mood": "warm, optimistic", "tag": "Warm", "tagTone": "warm",
+          "colors": ["#F2A07B", "#E8795A", "#C4543C", "#FBCFB8"] },
+        { "name": "Muted Sage", "mood": "earthy, wellness", "tag": "Nature", "tagTone": "nature",
+          "colors": ["#8DB87E", "#5D9252", "#3A6B34", "#BDD9B3"] }
+      ]
+    },
+    { "type": "palette", "name": "Current brand", "colors": ["#c2674b", "#1c1b19", "#fcfbf9"] }
+  ],
+  "questions": [
+    {
+      "id": "direction",
+      "type": "single",
+      "label": "Which palette direction?",
+      "required": true,
+      "options": [
+        { "value": "coastal", "label": "Coastal Calm" },
+        { "value": "peach", "label": "Peach Fuzz" },
+        { "value": "sage", "label": "Muted Sage" },
+        { "value": "keep", "label": "Keep current brand" }
+      ]
+    },
+    {
+      "id": "accent",
+      "type": "color",
+      "label": "Exact accent color",
+      "description": "Use the picker or paste a hex; presets are the featured palette.",
+      "presets": ["#3B8EA5", "#E8795A", "#5D9252", "#c2674b"],
+      "default": "#3B8EA5"
+    }
+  ],
+  "submitLabel": "Lock the palette"
+}

package/src/cli.js

@@ -1195,11 +1195,14 @@ async function cmdMcp(rest) {
   }
   const args = parseArgs(rest);
   if (args.http) {
+    // Port precedence: --port flag, then PaaS-injected $PORT / $RLY_MCP_PORT,
+    // then the default. PaaS hosts (Render, Railway, Fly, mcpdeploy, …) set $PORT.
+    const envPort = process.env.PORT || process.env.RLY_MCP_PORT;
     return runMcpHttp({
-      port: args.port ? Number(args.port) : (process.env.RLY_MCP_PORT ? Number(process.env.RLY_MCP_PORT) : undefined),
-      host: typeof args.host === 'string' ? args.host : '127.0.0.1',
+      port: args.port ? Number(args.port) : (envPort ? Number(envPort) : undefined),
+      host: typeof args.host === 'string' ? args.host : (process.env.RLY_MCP_HOST || '127.0.0.1'),
       token: typeof args.token === 'string' ? args.token : (process.env.RLY_MCP_TOKEN || ''),
-      allowOrigin: typeof args.allowOrigin === 'string' ? args.allowOrigin : '',
+      allowOrigin: typeof args.allowOrigin === 'string' ? args.allowOrigin : (process.env.RLY_MCP_ALLOW_ORIGIN || ''),
     });
   }
   // Default: be the stdio server. main() never resolves this, so the CLI's

package/src/mcp-ui/board.js

@@ -350,7 +350,9 @@
       theme: effectiveTheme,
       htmlSrc: (blockId) => htmlBlobSrc(blockId),
       questionId: questionId == null ? null : questionId,
-      annotate: null,
+      // No annotation during the streaming preview (it re-renders); on the final
+      // interactive render, wire the engine so blocks register their targets.
+      annotate: composing ? null : Annotate,
       edits: state.blockEdits,
       onBlockEdit: (blockId, codeOrNull) => {
         if (codeOrNull === null || codeOrNull === undefined) delete state.blockEdits[blockId];
@@ -379,7 +381,12 @@
   // ======================================================================
   let spec = null;
   let QS = [];
-  const state = { answers: {}, other: {}, notes: {}, comment: '', blockEdits: {} };
+  const state = { answers: {}, other: {}, notes: {}, comment: '', blockEdits: {}, annotations: [] };
+  // Element-level comments: the SAME self-contained annotate engine the browser
+  // board uses (no server — it reports the thread list via onChange). Charts,
+  // diagram nodes, table cells, images and text selections become commentable;
+  // the comments ride back in the submission alongside answers.
+  const Annotate = (window.RelayAnnotate && typeof window.RelayAnnotate.init === 'function') ? window.RelayAnnotate : null;
   let submitted = false;
   const cards = {};
   const app = document.getElementById('app');
@@ -434,7 +441,8 @@
     }
     const skipped = QS.filter((q) => !(q.id in answers)).map((q) => q.id);
     const blockEdits = Object.keys(state.blockEdits).length ? state.blockEdits : null;
-    return { answers, skipped, comment: (state.comment || '').trim(), notes, blockEdits };
+    const annotations = Array.isArray(state.annotations) && state.annotations.length ? state.annotations : null;
+    return { answers, skipped, comment: (state.comment || '').trim(), notes, blockEdits, annotations };
   }
 
   function clearErr(qid) { if (cards[qid]) cards[qid].classList.remove('error'); }
@@ -605,12 +613,17 @@
   // ======================================================================
   function render() {
     app.replaceChildren();
-    app.append(el('header', { class: 'qb-header' }, el('h1', {}, spec.title)));
+    const annotateOn = !composing && Annotate;
+    const titleEl = el('h1', {}, spec.title);
+    app.append(el('header', { class: 'qb-header' }, titleEl));
+    if (annotateOn) Annotate.register(titleEl, { blockId: null, questionId: null, target: { kind: 'html-element', label: spec.title } });
     if (spec.intro) {
       const md = window.RelayBlocks && RelayBlocks.renderMarkdown;
-      app.append(md
+      const introEl = md
         ? el('div', { class: 'intro blk-markdown' }, RelayBlocks.renderMarkdown(spec.intro))
-        : el('p', { class: 'intro' }, spec.intro));
+        : el('p', { class: 'intro' }, spec.intro);
+      app.append(introEl);
+      if (annotateOn) Annotate.enableTextSelection(introEl, { blockId: null, questionId: null });
     }
     renderBlocks(app, spec.blocks || [], null);
 
@@ -694,6 +707,13 @@
       }
     }
     if (data.comment) lines.push('', 'Comment: ' + data.comment);
+    if (data.annotations && data.annotations.length) {
+      lines.push('', 'Inline comments (' + data.annotations.length + '):');
+      for (const a of data.annotations) {
+        const where = (a.target && (a.target.label || a.target.text || a.target.kind)) || a.blockId || 'element';
+        lines.push('- [' + where + ']: ' + a.text);
+      }
+    }
     if (data.blockEdits) lines.push('', 'Edited diagrams: ' + Object.keys(data.blockEdits).join(', '));
     return lines.join('\n');
   }
@@ -712,6 +732,7 @@
       notes: data.notes,
       comment: data.comment,
       blockEdits: data.blockEdits,
+      annotations: data.annotations,
     };
     const text = summarize(data);
     let delivered = false;
@@ -729,6 +750,7 @@
   function showDone(delivered) {
     // Collapse: leave fullscreen, drop the whole form for a one-line confirmation
     // so the host shrinks the iframe to a small footprint in the transcript.
+    if (Annotate) { try { Annotate.teardown(); } catch { /* nothing to tear down */ } }
     document.documentElement.classList.remove('mcp-fullscreen');
     app.replaceChildren(el('div', { class: 'mcp-done' },
       el('span', { class: 'mark' }, '✓'),
@@ -765,6 +787,7 @@
     seedDefaults();
     indexHtmlBlocks(spec);
     setStatus('Preparing…');
+    if (Annotate) Annotate.init({ initial: [], onChange: (a) => { state.annotations = Array.isArray(a) ? a : []; } });
     try { await preloadVendors(spec); } catch { /* render anyway; blocks degrade individually */ }
     render();
     applyDisplayMode();

package/src/mcp-ui/index.html

@@ -7,6 +7,7 @@
 <title>__TITLE__</title>
 <style>/*__CSS__*/
 /*__BLOCKS_CSS__*/
+/*__ANNOTATE_CSS__*/
 /* MCP-app inline tweaks: the host owns the outer chrome, so the board paints
    edge-to-edge with no min-height / page background of its own. */
 :root{ color-scheme: light dark; }
@@ -31,6 +32,7 @@ body{ margin:0; }
 <script id="boot" type="application/json">__BOOT_JSON__</script>
 <div id="app" class="wrap"><div class="mcp-status" id="mcp-status">Loading the relay board…</div></div>
 <script>/*__BLOCKS_JS__*/</script>
+<script>/*__ANNOTATE_JS__*/</script>
 <script>/*__BOARD_JS__*/</script>
 </body>
 </html>

package/src/mcp.js

@@ -62,7 +62,9 @@ function buildBoardPage() {
     .split('__TITLE__').join('Relay')
     .split('/*__CSS__*/').join(readAsset(UI_DIR, 'style.css'))
     .split('/*__BLOCKS_CSS__*/').join(readAsset(UI_DIR, 'blocks.css'))
+    .split('/*__ANNOTATE_CSS__*/').join(readAsset(UI_DIR, 'annotate.css'))
     .split('/*__BLOCKS_JS__*/').join(readAsset(UI_DIR, 'blocks.js'))
+    .split('/*__ANNOTATE_JS__*/').join(readAsset(UI_DIR, 'annotate.js'))
     .split('/*__BOARD_JS__*/').join(readAsset(MCP_UI_DIR, 'board.js'))
     .split('__BOOT_JSON__').join(JSON.stringify(boot).replace(/</g, '\\u003c'));
   _cache.set('__page__', page);
@@ -441,11 +443,12 @@ export function mcpConfig({ command = 'rly', httpPort = DEFAULT_HTTP_PORT } = {}
     // Codex CLI (~/.codex/config.toml).
     toml: `[mcp_servers.relay]\ncommand = "${command}"\nargs = ["mcp"]\n`,
     // Remote / web+mobile hosts (Claude web/mobile custom connector, etc.):
-    // run `rly mcp --http` somewhere reachable and register the URL.
+    // run `rly mcp --http` on any reachable address and register the URL.
     http: {
       run: `${command} mcp --http --port ${httpPort}`,
       url: `http://127.0.0.1:${httpPort}${HTTP_PATH}`,
-      note: 'For web/mobile, expose this URL (e.g. a cloudflared/ngrok tunnel) and add it as a custom connector. Use --token <secret> + --allow-origin <host> when exposing it publicly.',
+      deploy: 'relay only needs its CLI — run `rly mcp --http` wherever the app can reach it. The repo Dockerfile deploys to any free MCP host (mcpdeploy.dev, mcphosting.io, Render/Railway/Fly, or Smithery) with zero config; $PORT is auto-honored. relay is stateless, so one instance serves everyone.',
+      note: 'Set RLY_MCP_TOKEN for a bearer-protected endpoint. A tunnel (cloudflared/tailscale) is ONLY for exposing a NAT\'d local machine — never required; deploying to a reachable host needs no extra tooling.',
     },
   };
 }

package/src/server.js

@@ -627,6 +627,9 @@ export async function runBoard({ id, port = 0, open = true, timeoutSec = 1800, q
       } else if (req.method === 'POST' && pathname === '/api/pref') {
         const body = JSON.parse((await readBody(req)) || '{}');
         if (['auto', 'light', 'dark'].includes(body.theme)) savePref({ theme: body.theme });
+        if (typeof body.fontScale === 'number' && body.fontScale >= 0.5 && body.fontScale <= 2) {
+          savePref({ fontScale: body.fontScale });
+        }
         sendJson(res, 200, { ok: true });
       } else if (req.method === 'POST' && pathname === '/api/open') {
         // Open a board-referenced local file in the OS default app. Guarded by

package/src/ui/annotate.js

@@ -107,6 +107,9 @@
   let popOpen = false;
   let popScrollY = 0;
   let popSave = null;
+  // Frozen by the host (e.g. relay's connection-lost block): suppress every way
+  // to START a comment, so the user can't type feedback that won't be saved.
+  let disabled = false;
   let badgeTimer = 0;
   let railOpen = false;
 
@@ -377,6 +380,7 @@
 
   // ---------- hover pin ----------
   function showPin(entry) {
+    if (disabled) return;
     clearTimeout(pinTimer);
     pinEntry = entry;
     const rect = entry.el.getBoundingClientRect();
@@ -483,6 +487,7 @@
   }
 
   function openPopover(info, anchorEl) {
+    if (disabled) return;
     ensureDom();
     closePopover();
     hidePin();
@@ -641,6 +646,7 @@
   }
 
   function maybeShowSelBtn(rootEl, baseInfo) {
+    if (disabled) return hideSelBtn();
     const sel = window.getSelection();
     if (!sel || sel.isCollapsed || !sel.rangeCount) return hideSelBtn();
     if (!rootEl.contains(sel.anchorNode) || !rootEl.contains(sel.focusNode)) return hideSelBtn();
@@ -844,11 +850,35 @@
     return annotations.slice();
   }
 
+  // True while the user is mid-comment: the popover is open, which hosts both
+  // the "Add a comment" box and every thread's reply input. That text lives
+  // only in the DOM until Save, so the board must not reload it away.
+  function isComposing() {
+    return popOpen;
+  }
+
+  // Commit a mid-typed comment (the open popover's "Add a comment" box) as a
+  // saved annotation, then close it — so freezing the board doesn't throw away
+  // text the user was in the middle of writing. ponytail: only the main comment
+  // box is flushed, not an in-progress thread reply (the rare case).
+  function flushOpen() {
+    if (popOpen && popSave) { try { popSave(); } catch { closePopover(); } }
+  }
+
+  // Freeze/unfreeze comment creation. While disabled, no pin, selection button,
+  // or popover appears, so the user can't start feedback that won't be saved.
+  function setDisabled(v) {
+    disabled = Boolean(v);
+    // Also close the rail flushOpen() may have just opened — otherwise it covers
+    // the host's top-right "connection lost" notice.
+    if (disabled) { closePopover(); hideSelBtn(); hidePin(); closeRail(); }
+  }
+
   function renderSummary(target) {
     ensureDom();
     summaryEls.add(target);
     renderSummaryInto(target);
   }
 
-  window.RelayAnnotate = { init, register, enableTextSelection, openExternal, list, renderSummary, onBadgeRefresh, teardown };
+  window.RelayAnnotate = { init, register, enableTextSelection, openExternal, list, renderSummary, onBadgeRefresh, teardown, isComposing, flushOpen, setDisabled };
 })();

package/src/ui/app.js

@@ -88,6 +88,31 @@
   }
   let themeBtn = null;
 
+  // ---------- font scale (A− / A+) ----------
+  // A page-zoom knob: scales the root font-size (every rem) so the whole board
+  // grows/shrinks. Persists like the theme — server pref + localStorage mirror —
+  // so the choice carries across the random-port boards.
+  const FS_KEY = 'qb-fontscale';
+  const FS_MIN = 0.85, FS_MAX = 1.5, FS_STEP = 0.1;
+  let fontScale = Number((boot.pref && boot.pref.fontScale) || localStorage.getItem(FS_KEY));
+  if (!Number.isFinite(fontScale) || fontScale <= 0) fontScale = 1;
+  const clampFs = (n) => Math.min(FS_MAX, Math.max(FS_MIN, Math.round(n * 100) / 100));
+  fontScale = clampFs(fontScale);
+  function applyFontScale() {
+    document.documentElement.style.setProperty('--fs', String(fontScale));
+  }
+  function setFontScale(next) {
+    fontScale = clampFs(next);
+    applyFontScale();
+    try { localStorage.setItem(FS_KEY, String(fontScale)); } catch { /* private mode */ }
+    fetch('/api/pref', {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ fontScale }),
+    }).catch(() => {});
+  }
+  applyFontScale();
+
   // ---------- localStorage draft mirror ----------
   // Every autosave is ALSO written to localStorage, keyed by board id. This is
   // the durability layer the server file alone can't provide: if the connection
@@ -246,13 +271,15 @@
   // board's local HTTP server (server gone, port taken over, socket dropped,
   // machine slept). Autosaves then fail silently and the user keeps typing
   // answers/comments that are never persisted, then Submit fails too — all of it
-  // thrown away. When persistence is CONFIRMED lost we hard-block: disable every
-  // control and overlay an unmissable scrim with a Retry. Local `state` is never
-  // touched, so the moment the connection recovers we flush it and unblock —
-  // nothing the user typed during the outage is lost.
+  // thrown away. When persistence is CONFIRMED lost we DISABLE every control (and
+  // freeze new comments) and show a small, non-dismissable top-right notice with
+  // a Reconnect button — without blocking the page, so the user can still read
+  // and scroll. Local `state` is never touched, and a mid-typed comment is saved
+  // before the freeze, so nothing the user entered during the outage is lost; the
+  // moment the connection recovers we flush state and re-enable everything.
   let persistenceLost = false;
   let probing = false;
-  let lostOverlay = null;
+  let lostNote = null;
   let lostRetryBtn = null;
 
   // A direct, side-effect-free reachability probe. Resolves true when the local
@@ -268,46 +295,55 @@
     }
   }
 
-  function buildLostOverlay() {
-    if (lostOverlay) return lostOverlay;
-    lostRetryBtn = el('button', { class: 'lost-retry', type: 'button' }, 'Retry connection');
+  function buildLostNote() {
+    if (lostNote) return lostNote;
+    lostRetryBtn = el('button', { class: 'lost-retry', type: 'button' }, 'Reconnect');
     lostRetryBtn.addEventListener('click', retryConnection);
-    lostOverlay = el('div', { class: 'lost-overlay', role: 'alertdialog', 'aria-modal': 'true', 'aria-label': 'Connection lost' },
-      el('div', { class: 'lost-card' },
-        el('div', { class: 'lost-mark' }, '⚠'),
-        el('h2', {}, 'Connection lost — input isn’t being saved'),
-        el('p', {}, 'This board can no longer reach your agent’s session, so anything you type now won’t be saved. Editing is paused to keep you from losing work.'),
-        el('p', { class: 'lost-sub' }, 'Your input up to this point is kept in this tab. Click Retry once the agent’s session is back, or prompt the agent to reopen this board — your draft and unsaved edits will be restored.'),
-        lostRetryBtn
-      )
+    lostNote = el('div', { class: 'lost-note', role: 'status', 'aria-live': 'polite' },
+      el('span', { class: 'lost-note-dot', 'aria-hidden': 'true' }),
+      el('div', { class: 'lost-note-body' },
+        el('div', { class: 'lost-note-title' }, 'Connection lost'),
+        el('div', { class: 'lost-note-sub' }, 'Editing paused — your input is kept.')
+      ),
+      lostRetryBtn
     );
-    return lostOverlay;
+    return lostNote;
   }
 
-  // Enter the blocked state: disable controls, mount the overlay. Idempotent.
+  // Enter the blocked state: save a mid-typed comment, freeze comments, disable
+  // controls, and pin the small notice. Idempotent. Does NOT block the page —
+  // the user can still read and scroll; only editing is paused.
   function blockForLostPersistence() {
     if (persistenceLost || submitted) return;
     persistenceLost = true;
     document.documentElement.classList.add('relay-blocked');
-    // Disable every interactive control inside the form (inputs the user could
-    // otherwise keep typing into) plus Submit.
+    // Save whatever the user was typing into the comment popover BEFORE freezing
+    // it, so the in-progress comment is kept (in `state` + localStorage) instead
+    // of discarded; then stop any new comment from being started.
+    if (Annotate) {
+      if (typeof Annotate.flushOpen === 'function') { try { Annotate.flushOpen(); } catch { /* non-fatal */ } }
+      if (typeof Annotate.setDisabled === 'function') { try { Annotate.setDisabled(true); } catch { /* non-fatal */ } }
+    }
+    // Disable every interactive control inside the form. Values already entered
+    // stay in the DOM (and in `state`), so nothing typed so far is lost.
     for (const node of app.querySelectorAll('input, textarea, button, select')) {
       node.disabled = true;
     }
-    document.body.append(buildLostOverlay());
+    document.body.append(buildLostNote());
     if (saveEl) saveEl.textContent = 'connection lost — not saving';
   }
 
-  // Leave the blocked state: re-enable controls, remove the overlay, and flush
-  // whatever the user typed during the outage so it's persisted right away.
+  // Leave the blocked state: re-enable controls + comments, drop the notice, and
+  // flush whatever the user typed during the outage so it's persisted right away.
   function unblockAfterRecovery() {
     if (!persistenceLost) return;
     persistenceLost = false;
     document.documentElement.classList.remove('relay-blocked');
+    if (Annotate && typeof Annotate.setDisabled === 'function') { try { Annotate.setDisabled(false); } catch { /* non-fatal */ } }
     for (const node of app.querySelectorAll('input, textarea, button, select')) {
       node.disabled = false;
     }
-    if (lostOverlay) lostOverlay.remove();
+    if (lostNote) lostNote.remove();
     // Re-arm the heartbeat (it stops itself when it confirms loss) and persist
     // everything typed during the outage. saveDraft() updates the save label.
     startHeartbeat();
@@ -744,6 +780,12 @@
   });
   applyTheme();
 
+  const fsDown = el('button', { class: 'fs-btn', type: 'button', title: 'Smaller text', 'aria-label': 'Decrease text size' }, 'A−');
+  const fsUp = el('button', { class: 'fs-btn', type: 'button', title: 'Larger text', 'aria-label': 'Increase text size' }, 'A+');
+  fsDown.addEventListener('click', () => setFontScale(fontScale - FS_STEP));
+  fsUp.addEventListener('click', () => setFontScale(fontScale + FS_STEP));
+  const fsCtrl = el('div', { class: 'fs-ctrl' }, fsDown, fsUp);
+
   // Just reloaded after a live `rly update`? Flag set before reload below.
   try {
     if (sessionStorage.getItem('relay-updated') === '1') {
@@ -755,7 +797,7 @@
   }
 
   const titleEl = el('h1', {}, spec.title);
-  app.append(el('header', { class: 'qb-header' }, titleEl, themeBtn));
+  app.append(el('header', { class: 'qb-header' }, titleEl, el('div', { class: 'qb-controls' }, fsCtrl, themeBtn)));
   // The board title is commentable too: hovering it shows the pin, like the
   // intro and every other content element. (themeBtn stays out of it.)
   if (spec.title) {
@@ -1021,6 +1063,24 @@
   }
 
   // ---------- heartbeat ----------
+  // True when the user is actively typing — an open annotation comment popover,
+  // or focus in any text-entry field (comment box, notes, text/color answers,
+  // "Other" inputs). Used to defer the live-update reload so in-progress
+  // comments aren't destroyed mid-keystroke.
+  function isEditable(node) {
+    if (!node) return false;
+    if (node.tagName === 'TEXTAREA') return true;
+    if (node.tagName === 'INPUT') {
+      const t = (node.type || 'text').toLowerCase();
+      return ['text', 'search', 'email', 'url', 'tel', 'number', 'color'].includes(t);
+    }
+    return node.isContentEditable === true;
+  }
+  function userIsComposing() {
+    if (window.RelayAnnotate && typeof RelayAnnotate.isComposing === 'function' && RelayAnnotate.isComposing()) return true;
+    return isEditable(document.activeElement);
+  }
+
   let misses = 0;
   let reloading = false;
   let hb = null;
@@ -1054,6 +1114,16 @@
         );
       }
       if (body && typeof body.rev === 'number' && bootRev !== null && body.rev !== bootRev && !submitted && !reloading) {
+        // Don't yank the board out from under someone mid-comment: an open
+        // annotation popover (its add-comment box + reply inputs) holds text
+        // that isn't in the draft until Save, so a reload would discard it —
+        // and reloading while any field is focused drops the user's cursor and
+        // last keystrokes. Defer until they're done; the heartbeat re-checks
+        // every tick, so the update applies the moment they close/blur.
+        if (userIsComposing()) {
+          showNotice('The agent updated this board — it’ll refresh as soon as you finish your comment.', 'info');
+          return;
+        }
         reloading = true;
         stopHeartbeat();
         clearTimeout(saveTimer);

package/src/ui/blocks.css

@@ -491,6 +491,21 @@ body.blk-full-open { overflow: hidden; }
   height: calc(100vh - 44px) !important; width: 100%;
   margin: 0; border: 0; border-radius: 0;
 }
+/* Full-screen diagrams/images: apply() sizes the child to fit the viewport
+   (FULL_PAD_* in blocks.js mirrors this padding). margin:auto on the single
+   child centers it on both axes AND keeps it scrollable when zoomed past the
+   fit — plain flex centering would clip the top/left and trap the overflow. */
+.blk-mermaid.blk-full,
+.blk-graphviz.blk-full,
+.blk-plantuml.blk-full,
+.blk-imagewrap.blk-full {
+  display: flex; padding: 44px 24px 24px;
+}
+.blk-mermaid.blk-full > svg,
+.blk-graphviz.blk-full > svg,
+.blk-plantuml.blk-full > svg,
+.blk-plantuml.blk-full > .blk-plantuml-img,
+.blk-imagewrap.blk-full > .blk-img { margin: auto; }
 
 /* Small frame on charts + mermaid so they read as a deliberate card, matching
    the graphviz/plantuml/image blocks (already framed). Scoped to the inner

package/src/ui/blocks.js

@@ -31,7 +31,9 @@
 
   // ---------- chart palette (from contract) ----------
   const PALETTE_LIGHT = ['#c2674b', '#4d8a66', '#5a7ca8', '#b9913f', '#8a6da3', '#57534e'];
-  const PALETTE_DARK = ['#d98e67', '#6fbf92', '#7c9fcc', '#d4b061', '#ad8fc2', '#a29c93'];
+  // Brighter/more saturated than the surfaces behind them so series stay legible
+  // on the dark card (#282624) — the muted set washed out at a glance.
+  const PALETTE_DARK = ['#e8a07a', '#74cfa0', '#88b4e8', '#e3c46a', '#c4a0db', '#c2b9ad'];
 
   function cssVar(name) {
     return getComputedStyle(document.documentElement).getPropertyValue(name).trim();
@@ -743,7 +745,8 @@
 
   function themeDefaults(ctx) {
     const grid = cssVar('--border') || '#ece9e4';
-    const tick = cssVar('--muted') || '#8a8580';
+    // axis/legend/title text: --fg-2 reads clearly on dark; --muted was too dim
+    const tick = cssVar('--fg-2') || '#57534e';
     const fontFamily = cssVar('--sans') || 'sans-serif';
     return { grid, tick, fontFamily };
   }
@@ -1492,6 +1495,9 @@
   // the annotation pins/badges/popover usable while expanded (they live on
   // <body>, which native fullscreen would hide).
   let fullOpen = null; // container currently expanded
+  // full-screen content insets — must mirror the .blk-full padding in blocks.css
+  // so the fit-to-screen scale clears the fixed toolbar + leaves a small margin.
+  const FULL_PAD_X = 24, FULL_PAD_TOP = 44, FULL_PAD_BOTTOM = 24;
 
   // Toolbar icons: full-screen (4-corner expand) and a speech-bubble for the
   // "comment on the whole block" button. Zoom is both cmd/ctrl+wheel AND
@@ -1633,14 +1639,26 @@
       const target = opts.zoomEl;
       const nat = opts.natural();
       const z = container._rlyZ;
+      const full = container.classList.contains('blk-full');
       // A per-block height caps only the compact inline preview. The moment the
       // user zooms in (z !== null) or goes full-screen they want pixel detail, so
       // lift the cap there; restore it when back to the inline fit view.
       if (opts.fitMaxHeight != null) {
-        const fit = z === null && !container.classList.contains('blk-full');
-        target.style.maxHeight = fit ? opts.fitMaxHeight + 'px' : 'none';
+        target.style.maxHeight = z === null && !full ? opts.fitMaxHeight + 'px' : 'none';
       }
-      if (z === null || !nat || !nat.w) {
+      if (z === null && full && nat && nat.w && nat.h) {
+        // Full-screen default: scale the diagram/image to fill the viewport
+        // (contain — enlarge a small one, shrink a big one) so it's readable at
+        // a glance without reaching for the zoom buttons. CSS margin:auto centers
+        // it; it stays pannable once the user zooms past this fit.
+        const availW = window.innerWidth - FULL_PAD_X * 2;
+        const availH = window.innerHeight - FULL_PAD_TOP - FULL_PAD_BOTTOM;
+        const scale = Math.min(availW / nat.w, availH / nat.h);
+        target.style.maxWidth = 'none';
+        target.style.width = Math.max(1, Math.round(nat.w * scale)) + 'px';
+        target.style.height = 'auto';
+        pct.textContent = 'fit';
+      } else if (z === null || !nat || !nat.w) {
         target.style.width = '100%';
         target.style.maxWidth = nat && nat.w ? Math.ceil(nat.w) + 'px' : '100%';
         target.style.height = 'auto';

package/src/ui/style.css

@@ -68,14 +68,17 @@
 
 * { box-sizing: border-box; }
 html, body { margin: 0; padding: 0; }
+/* Root font size drives every rem on the page; --fs is the user's text-size
+   knob (A−/A+ next to the theme toggle). Base bumped 16→17px for readability. */
+html { font-size: calc(17px * var(--fs, 1)); }
 body {
   background: var(--bg);
   color: var(--fg);
-  font: 16px/1.6 var(--sans);
+  font: 1rem/1.6 var(--sans);
   -webkit-font-smoothing: antialiased;
   transition: background 200ms var(--ease), color 200ms var(--ease), padding 240ms var(--ease);
 }
-.wrap { max-width: 860px; margin: 0 auto; padding: 32px 20px 28px; }
+.wrap { max-width: 1280px; margin: 0 auto; padding: 32px 20px 28px; }
 
 .qb-header { display: flex; align-items: flex-start; justify-content: space-between; gap: 12px; margin-bottom: 4px; }
 h1 {
@@ -101,6 +104,18 @@ h1 {
   transition: border-color 150ms var(--ease), color 150ms var(--ease);
 }
 .theme-btn:hover { border-color: var(--accent); color: var(--accent); }
+/* header controls: font-size knob + theme toggle, grouped at the right */
+.qb-controls { display: flex; align-items: center; gap: 8px; flex: none; }
+.fs-ctrl { display: inline-flex; border: 1px solid var(--border-strong); border-radius: 999px; overflow: hidden; }
+.fs-btn {
+  background: transparent; color: var(--fg-2); border: 0;
+  padding: 6px 11px; cursor: pointer; line-height: 1; font-family: var(--sans);
+  transition: color 150ms var(--ease), background 150ms var(--ease);
+}
+.fs-btn:first-child { font-size: 0.72rem; }
+.fs-btn:last-child { font-size: 0.92rem; }
+.fs-btn + .fs-btn { border-left: 1px solid var(--border-strong); }
+.fs-btn:hover { color: var(--accent); background: var(--accent-soft); }
 
 .card {
   background: var(--card);
@@ -267,46 +282,35 @@ textarea { min-height: 90px; resize: vertical; }
   .scale button { width: 40px; height: 40px; }
 }
 
-/* Persistence-lost block: when the board can no longer save the user's input
+/* Persistence-lost notice: when the board can no longer save the user's input
    (server gone / port taken / machine slept) AND recovery probes have failed,
-   we disable every control and overlay this unmissable scrim so the user is
-   physically prevented from typing feedback that would be silently discarded.
-   Sits above everything (full-screen overlay z 49 / popover / rail / toast). */
-.relay-blocked #app { filter: grayscale(0.4) blur(1px); pointer-events: none; user-select: none; }
-.lost-overlay {
-  position: fixed; inset: 0; z-index: 60;
-  display: flex; align-items: center; justify-content: center;
-  padding: 24px;
-  background: color-mix(in srgb, var(--bg) 78%, transparent);
-  backdrop-filter: blur(3px); -webkit-backdrop-filter: blur(3px);
-}
-.lost-card {
-  max-width: 460px; width: 100%;
+   we disable every control (and freeze new comments) and pin this SMALL,
+   non-dismissable note top-right with a Reconnect button. It does NOT block the
+   page — the user can still read and scroll; only editing is paused. Recovery
+   re-enables everything and removes the note. */
+.lost-note {
+  position: fixed; top: 12px; right: 12px; z-index: 60;
+  display: flex; align-items: center; gap: 10px;
+  max-width: min(320px, calc(100vw - 24px));
   background: var(--card); color: var(--fg);
-  border: 1px solid var(--border-strong); border-radius: 14px;
+  border: 1px solid var(--danger); border-radius: 11px;
   box-shadow: var(--shadow-lift);
-  padding: 28px 26px; text-align: center;
-}
-.lost-card .lost-mark {
-  width: 52px; height: 52px; border-radius: 50%;
-  background: var(--danger); color: var(--danger-fg);
-  font-size: 1.6rem; line-height: 52px; margin: 0 auto 16px;
-}
-.lost-card h2 {
-  font-family: var(--serif); font-weight: 500; letter-spacing: -0.015em;
-  font-size: 1.3rem; margin: 0 0 10px;
+  padding: 9px 11px;
 }
-.lost-card p { color: var(--fg-2); font-size: 0.92rem; line-height: 1.55; margin: 0 0 8px; }
-.lost-card .lost-sub { color: var(--muted); font-size: 0.82rem; margin: 12px 0 18px; }
-.lost-card .lost-retry {
+.lost-note-dot { flex: none; width: 9px; height: 9px; border-radius: 50%; background: var(--danger); }
+.lost-note-body { flex: 1; min-width: 0; line-height: 1.3; }
+.lost-note-title { font-size: 0.82rem; font-weight: 600; }
+.lost-note-sub { font-size: 0.72rem; color: var(--muted); margin-top: 1px; }
+.lost-note .lost-retry {
+  flex: none;
   background: var(--accent); color: var(--accent-fg);
-  border: none; border-radius: 10px;
-  padding: 11px 26px; font: inherit; font-size: 0.95rem; font-weight: 600; cursor: pointer;
+  border: none; border-radius: 8px;
+  padding: 6px 12px; font: inherit; font-size: 0.78rem; font-weight: 600; cursor: pointer;
   transition: background 150ms var(--ease);
 }
-.lost-card .lost-retry:hover { background: var(--accent-hover); }
-.lost-card .lost-retry:disabled { opacity: 0.6; cursor: default; }
-.lost-card .lost-retry:focus-visible { outline: 2px solid var(--accent); outline-offset: 2px; }
+.lost-note .lost-retry:hover { background: var(--accent-hover); }
+.lost-note .lost-retry:disabled { opacity: 0.6; cursor: default; }
+.lost-note .lost-retry:focus-visible { outline: 2px solid var(--accent); outline-offset: 2px; }
 
 @media (prefers-reduced-motion: reduce) {
   * { transition: none !important; animation: none !important; }