@khanglvm/relay 0.11.0 → 0.12.0

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.0",
   "description": "Question boards with rich blocks (markdown, charts, mermaid, tables, code, diffs, video, sandboxed HTML), clickable local file-links, and element-level annotations for AI coding agents (Claude Code, Codex, …): ask users structured questions, present interactive visuals, collect inline comments, read answers as JSON — in a local browser board OR rendered INLINE inside the Claude & Codex apps as an MCP App (SEP-1865).",
   "keywords": [
     "ai-agents",

package/skills/relay/SKILL.md

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

@@ -844,11 +844,18 @@
     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;
+  }
+
   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 };
 })();

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
@@ -744,6 +769,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 +786,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 +1052,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 +1103,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);