@khanglvm/relay 0.8.2 → 0.9.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@khanglvm/relay",
-  "version": "0.8.2",
+  "version": "0.9.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/src/ui/annotate.css

@@ -30,8 +30,12 @@
   user-select: none;
 }
 .ann-badge:hover { background: var(--accent-hover); }
-/* SVG targets (mermaid nodes) get the badge overlaid in document coords */
-.ann-badge-overlay { top: auto; right: auto; z-index: 58; }
+/* SVG / image targets get the badge overlaid (positioned as a child of the
+   scrollable diagram viewport so it rides with the content). z 15: above the
+   diagram it marks, but BELOW the sticky submit bar (z 30) so a badge near the
+   page bottom never covers the Submit button. Pins/popover/rail stay high —
+   they're transient and must clear the full-screen overlay. */
+.ann-badge-overlay { top: auto; right: auto; z-index: 15; }
 
 /* ---------- comment popover ---------- */
 .ann-pop {

package/src/ui/annotate.js

@@ -42,6 +42,8 @@
         return 'Diagram · ' + truncate(t.text || t.nodeId || 'node', 50);
       case 'graphviz-node':
         return 'Graph · ' + truncate(t.text || t.nodeId || 'node', 50);
+      case 'plantuml-node':
+        return 'Diagram · ' + truncate(t.text || 'element', 50);
       case 'image':
         return truncate(t.label || 'Image', 50);
       case 'table-cell': {
@@ -53,6 +55,8 @@
         return `“${truncate(t.quote || '', 60)}”`;
       case 'html-element':
         return truncate(t.label || 'Element', 50) + (t.detail ? ` — ${truncate(t.detail, 40)}` : '');
+      case 'block':
+        return 'Whole ' + truncate(t.label || 'block', 40);
       default:
         return t.kind || 'Element';
     }
@@ -405,10 +409,19 @@
     }, 0);
   }
 
+  // Hosts (e.g. blocks.js chart badge / comment button) subscribe here to be
+  // notified on every badge refresh — i.e. whenever annotations change — so
+  // their own indicators stay in sync. Returns an unsubscribe fn.
+  const badgeHooks = new Set();
+  function onBadgeRefresh(fn) {
+    if (typeof fn === 'function') badgeHooks.add(fn);
+    return () => badgeHooks.delete(fn);
+  }
+
   function refreshBadges() {
     for (const b of badges) b.remove();
     badges = [];
-    if (torndown) return;
+    if (torndown) { for (const fn of badgeHooks) { try { fn(); } catch (_) {} } return; }
     registered = registered.filter((r) => r.el.isConnected);
     // While a block is expanded full-screen, body-level overlay badges for
     // OTHER blocks would float above the overlay at stale positions — only
@@ -428,20 +441,36 @@
         hidePin();
         openPopover(entry.info, entry.el);
       });
-      if (entry.el instanceof HTMLElement) {
+      if (entry.el instanceof HTMLElement && !(entry.el instanceof HTMLImageElement)) {
+        // a normal HTML element hosts the badge as a child — it tracks naturally
         if (getComputedStyle(entry.el).position === 'static') entry.el.classList.add('ann-rel');
         entry.el.append(badge);
       } else {
-        // SVG targets (mermaid nodes) can't host an HTML child — overlay it
-        // in document coordinates so it scrolls with the content.
+        // SVG node or <img> — neither can host an HTML child. Anchor the badge
+        // INSIDE the scrollable diagram viewport in CONTENT coordinates: as an
+        // absolutely-positioned child of the scroll box it rides with the content
+        // on drag-pan / container-scroll / page-scroll, with no listener needed.
+        // (A document-body overlay stayed put when the diagram itself scrolled.)
         badge.classList.add('ann-badge-overlay');
-        document.body.append(badge);
+        const host = entry.el.closest ? entry.el.closest('.blk-viewer') : null;
         const r = entry.el.getBoundingClientRect();
-        badge.style.left = (r.right + window.scrollX - 10) + 'px';
-        badge.style.top = (r.top + window.scrollY - 6) + 'px';
+        if (host) {
+          const cr = host.getBoundingClientRect();
+          const cs = getComputedStyle(host);
+          const bL = parseFloat(cs.borderLeftWidth) || 0;
+          const bT = parseFloat(cs.borderTopWidth) || 0;
+          badge.style.left = (r.right - cr.left - bL + host.scrollLeft - 10) + 'px';
+          badge.style.top = (r.top - cr.top - bT + host.scrollTop - 6) + 'px';
+          host.append(badge);
+        } else {
+          badge.style.left = (r.right + window.scrollX - 10) + 'px';
+          badge.style.top = (r.top + window.scrollY - 6) + 'px';
+          document.body.append(badge);
+        }
       }
       badges.push(badge);
     }
+    for (const fn of badgeHooks) { try { fn(); } catch (_) {} }
   }
 
   // ---------- popover ----------
@@ -705,6 +734,11 @@
           const marks = highlightMap.get(sigOf(a.blockId, a.target));
           jump = marks && marks.find((m) => m.isConnected);
         }
+        // Fallback for targets with no registered element (e.g. chart data
+        // points / whole-block comments): flash the whole block container.
+        if (!jump && a.blockId != null) {
+          jump = document.querySelector('[data-block-id="' + String(a.blockId).replace(/"/g, '\\"') + '"]');
+        }
         if (!jump) return;
         // On narrow screens the rail overlays the page — close it so the
         // flashed target is actually visible.
@@ -816,5 +850,5 @@
     renderSummaryInto(target);
   }
 
-  window.RelayAnnotate = { init, register, enableTextSelection, openExternal, list, renderSummary, teardown };
+  window.RelayAnnotate = { init, register, enableTextSelection, openExternal, list, renderSummary, onBadgeRefresh, teardown };
 })();

package/src/ui/app.js

@@ -543,7 +543,13 @@
     Annotate?.register(titleEl, { blockId: null, questionId: null, target: { kind: 'html-element', label: spec.title } });
   }
   if (spec.intro) {
-    const intro = el('p', { class: 'intro' }, spec.intro);
+    // Render the intro as markdown (bold/italic/code/links/lists) — agents write
+    // markdown here by default. Falls back to plain text if blocks.js is absent.
+    // The .blk-markdown class scopes the shared markdown typography to it.
+    const md = typeof window.RelayBlocks !== 'undefined' && window.RelayBlocks.renderMarkdown;
+    const intro = md
+      ? el('div', { class: 'intro blk-markdown' }, window.RelayBlocks.renderMarkdown(spec.intro))
+      : el('p', { class: 'intro' }, spec.intro);
     app.append(intro);
     Annotate?.enableTextSelection(intro, { blockId: null, questionId: null });
   }

package/src/ui/blocks.css

@@ -160,6 +160,15 @@
   font-weight: 600;
   font-family: var(--sans);
   box-shadow: var(--shadow-card);
+  cursor: pointer;
+  z-index: 4; /* above the canvas, below the toolbar(5)/footer(30) */
+}
+.blk-chart-badge:hover { background: var(--accent-hover); }
+/* per-data-point badge: positioned via inline left/top, centered on the point */
+.blk-chart-badge-pt {
+  top: auto; right: auto;
+  transform: translate(-50%, -50%);
+  border: 1.5px solid var(--card);
 }
 
 /* ---------- mermaid ---------- */
@@ -336,3 +345,57 @@ body.blk-full-open { overflow: hidden; }
   height: calc(100vh - 44px) !important; width: 100%;
   margin: 0; border: 0; border-radius: 0;
 }
+
+/* Small frame on charts + mermaid so they read as a deliberate card, matching
+   the graphviz/plantuml/image blocks (already framed). Scoped to the inner
+   .blk-viewer element so the border isn't doubled on the outer .blk dispatch
+   wrapper; :not(.blk-full) drops it in the edge-to-edge full-screen overlay. */
+.blk-chart.blk-viewer:not(.blk-full),
+.blk-mermaid.blk-viewer:not(.blk-full) {
+  border: 1px solid var(--border);
+  border-radius: 10px;
+}
+/* keep the canvas corners inside the rounded frame (mermaid already clips via
+   its overflow:auto) */
+.blk-chart.blk-viewer:not(.blk-full) { overflow: hidden; }
+
+/* drag-to-pan affordance: grab when a visual overflows its box, grabbing while
+   dragging. During an active drag the inner svg/img/canvas ignore the pointer
+   so hover pins/cursors don't flicker and the whole surface shows "grabbing". */
+.blk-pannable { cursor: grab; }
+.blk-panning { cursor: grabbing; user-select: none; }
+.blk-panning svg,
+.blk-panning img,
+.blk-panning canvas { pointer-events: none; }
+
+/* The diagram type-class is shared by the dispatch wrapper (.blk.blk-graphviz)
+   and the inner card, so a bordered rule on the bare class paints TWO concentric
+   borders (the wrapper's padding:10px makes the gap). Strip the card off the
+   dispatch wrapper so only the inner element is framed — single clean border. */
+.blk.blk-graphviz,
+.blk.blk-plantuml {
+  border: 0;
+  background: none;
+  padding: 0;
+  overflow: visible;
+  max-height: none;
+}
+
+/* zoom −/+ buttons and the % (which doubles as reset-to-fit) */
+.blk-tools .tool-zoom {
+  font-size: 0.95rem; font-weight: 600; line-height: 1;
+  min-width: 24px; text-align: center;
+}
+.blk-tools .tool-pct.is-btn { cursor: pointer; transition: color 150ms var(--ease); }
+.blk-tools .tool-pct.is-btn:hover { color: var(--accent); }
+.blk-tools .tool-comment svg { display: block; }
+/* the comment button switches to a filled accent state once the block carries
+   a whole-block comment, so it's obvious at a glance */
+.blk-tools .tool-comment.has-comment {
+  background: var(--accent); border-color: var(--accent); color: var(--accent-fg);
+}
+.blk-tools .tool-comment.has-comment:hover { background: var(--accent-hover); border-color: var(--accent-hover); color: var(--accent-fg); }
+
+/* code blocks reuse the viewer toolbar (comment + full-screen); the pre keeps
+   its own card, the wrapper only hosts the toolbar strip */
+.blk-codewrap { position: relative; }

package/src/ui/blocks.js

@@ -298,10 +298,16 @@
     return out;
   }
 
-  function renderCode(block) {
+  function renderCode(block, ctx, blockId) {
     const code = el('code');
     code.innerHTML = tintCode(block.code || '', block.lang);
-    return el('pre', { class: 'blk-pre', 'data-lang': block.lang || '' }, code);
+    const pre = el('pre', { class: 'blk-pre', 'data-lang': block.lang || '' }, code);
+    const wrap = el('div', { class: 'blk-codewrap' }, pre);
+    // select-to-comment on the code text (like markdown), plus a whole-block
+    // comment + full-screen via the shared viewer toolbar
+    ctx && ctx.annotate && ctx.annotate.enableTextSelection(pre, { blockId, questionId: ctx.questionId });
+    attachViewer(wrap, { zoomEl: null, label: 'code', comment: wholeBlockComment(ctx, blockId, 'code') });
+    return wrap;
   }
 
   // ---------- table ----------
@@ -537,13 +543,6 @@
     return config;
   }
 
-  function chartAnnotationCount(ctx, blockId) {
-    if (!ctx.annotate) return 0;
-    return ctx.annotate.list().filter(
-      (a) => a.blockId === blockId && a.target && a.target.kind === 'chart-element'
-    ).length;
-  }
-
   function renderChart(block, ctx, blockId) {
     const height = clampHeight(block.height, 320);
     const wrap = el('div', { class: 'blk-chart' });
@@ -551,37 +550,87 @@
     const canvas = el('canvas');
     wrap.append(canvas);
 
-    const badge = el('span', { class: 'blk-chart-badge' }, '');
-    function syncBadge() {
-      const n = chartAnnotationCount(ctx, blockId);
-      if (n > 0) { badge.textContent = String(n); badge.style.display = ''; }
-      else badge.style.display = 'none';
+    let chartInst = null;
+    let chartBadges = [];
+
+    const openFor = (target) => (anchor) =>
+      ctx.annotate.openExternal({ blockId, questionId: ctx.questionId, target }, anchor);
+    function makeBadge(count, cls, onClick) {
+      const b = el('span', { class: 'blk-chart-badge ' + cls }, String(count));
+      b.addEventListener('mousedown', (e) => e.stopPropagation());
+      b.addEventListener('click', (e) => { e.stopPropagation(); e.preventDefault(); onClick(b); });
+      return b;
+    }
+    // Rebuild the chart's comment badges: one at each annotated DATA POINT
+    // (positioned from the Chart.js element geometry) plus a top-right badge for
+    // whole-chart comments. Each badge opens that comment's popover on click.
+    // Runs on annotation change (onBadgeRefresh) and on chart (re)render/resize
+    // (afterRender plugin), so badges stay pinned to their points.
+    function syncChartBadges() {
+      if (!ctx.annotate) return;
+      for (const b of chartBadges) b.remove();
+      chartBadges = [];
+      const groups = new Map(); // "di:index" -> { target, count }
+      let blockCount = 0, blockTarget = null;
+      for (const a of ctx.annotate.list()) {
+        if (a.blockId !== blockId) continue;
+        const t = a.target || {};
+        if (t.kind === 'chart-element' && typeof t.datasetIndex === 'number' && typeof t.index === 'number') {
+          const k = t.datasetIndex + ':' + t.index;
+          const g = groups.get(k) || { target: t, count: 0 };
+          g.count++; groups.set(k, g);
+        } else {
+          blockCount++; blockTarget = blockTarget || t;
+        }
+      }
+      if (chartInst) {
+        for (const { target, count } of groups.values()) {
+          let elem;
+          try { const m = chartInst.getDatasetMeta(target.datasetIndex); elem = m && m.data[target.index]; } catch (_) {}
+          if (!elem) continue;
+          let pos; try { pos = elem.tooltipPosition(); } catch (_) { pos = { x: elem.x, y: elem.y }; }
+          if (!pos || !Number.isFinite(pos.x) || !Number.isFinite(pos.y)) continue;
+          const badge = makeBadge(count, 'blk-chart-badge-pt', openFor(target));
+          badge.style.left = (canvas.offsetLeft + pos.x) + 'px';
+          badge.style.top = (canvas.offsetTop + pos.y) + 'px';
+          wrap.append(badge);
+          chartBadges.push(badge);
+        }
+      }
+      if (blockCount > 0) {
+        const badge = makeBadge(blockCount, 'blk-chart-badge-corner', openFor(blockTarget || { kind: 'block', label: 'chart' }));
+        wrap.append(badge);
+        chartBadges.push(badge);
+      }
     }
-    syncBadge();
-    wrap.append(badge);
-    attachViewer(wrap, { zoomEl: null }); // full-screen only; charts redraw responsively
+
+    if (ctx.annotate && ctx.annotate.onBadgeRefresh) ctx.annotate.onBadgeRefresh(syncChartBadges);
+    // full-screen + whole-chart comment only; charts redraw responsively (no pixel zoom)
+    attachViewer(wrap, { zoomEl: null, label: 'chart', comment: wholeBlockComment(ctx, blockId, 'chart') });
 
     loadChart().then((Chart) => {
       let config = block.config
         ? JSON.parse(JSON.stringify(block.config))
         : simplifiedToConfig(block, ctx);
       config = applyChartTheme(config, ctx);
-      let chart;
+      // reposition our DOM badges after every (re)render/resize of the chart
+      config.plugins = Array.isArray(config.plugins) ? config.plugins : [];
+      config.plugins.push({ id: 'relayChartBadges', afterRender: () => syncChartBadges() });
       try {
-        chart = new Chart(canvas.getContext('2d'), config);
-        chartRegistry.push({ chart });
+        chartInst = new Chart(canvas.getContext('2d'), config);
+        chartRegistry.push({ chart: chartInst });
       } catch (err) {
         wrap.replaceChildren(el('div', { class: 'blk-error' }, 'Chart error: ' + (err && err.message ? err.message : String(err))));
         return;
       }
       // hover -> pointer cursor on a hit
       canvas.addEventListener('mousemove', (e) => {
-        const hits = chart.getElementsAtEventForMode(e, 'nearest', { intersect: true }, true);
+        const hits = chartInst.getElementsAtEventForMode(e, 'nearest', { intersect: true }, true);
         canvas.style.cursor = hits.length ? 'pointer' : 'default';
       });
       canvas.addEventListener('click', (e) => {
         if (!ctx.annotate) return;
-        const hits = chart.getElementsAtEventForMode(e, 'nearest', { intersect: true }, true);
+        const hits = chartInst.getElementsAtEventForMode(e, 'nearest', { intersect: true }, true);
         if (!hits.length) return;
         const { datasetIndex, index } = hits[0];
         const ds = config.data.datasets[datasetIndex] || {};
@@ -596,12 +645,11 @@
           wrap
         );
       });
+      syncChartBadges();
     }).catch((err) => {
       wrap.replaceChildren(el('div', { class: 'blk-error' }, 'Chart error: ' + (err && err.message ? err.message : String(err))));
     });
 
-    // expose a refresh hook so the list can update the badge after changes
-    wrap._relaySyncBadge = syncBadge;
     return wrap;
   }
 
@@ -628,6 +676,10 @@
 
   function renderMermaid(block, ctx, blockId) {
     const container = el('div', { class: 'blk-mermaid' });
+    // Honor an authored height as the scrollable viewport: a diagram taller than
+    // this overflows and becomes drag-pannable in place (was silently ignored —
+    // diagrams only ever fit-to-width). No height keeps the 1200px CSS cap.
+    if (block.height != null) container.style.maxHeight = clampHeight(block.height, 1200) + 'px';
     const entry = { container, block, ctx, blockId };
     entry.code = effectiveMermaidCode(entry);
     mermaidRegistry.push(entry);
@@ -783,7 +835,7 @@
           });
         }
         // re-attach per render: innerHTML replacement above wiped the old bar
-        if (svgEl) attachViewer(container, { zoomEl: svgEl, natural: svgNatural(svgEl) });
+        if (svgEl) attachViewer(container, { zoomEl: svgEl, natural: svgNatural(svgEl), label: 'diagram', comment: wholeBlockComment(ctx, blockId, 'diagram') });
         if (onDone) onDone();
       };
       try {
@@ -863,13 +915,15 @@
 
   function renderGraphviz(block, ctx, blockId) {
     const container = el('div', { class: 'blk-graphviz' });
+    // honor authored height as the scrollable viewport (see renderMermaid)
+    if (block.height != null) container.style.maxHeight = clampHeight(block.height, 1200) + 'px';
     loadViz()
       .then((Viz) => Viz.instance())
       .then((viz) => {
         const svgEl = viz.renderSVGElement(block.dot || '');
         sizeDiagramSvg(svgEl);
         container.replaceChildren(svgEl);
-        attachViewer(container, { zoomEl: svgEl, natural: svgNatural(svgEl) });
+        attachViewer(container, { zoomEl: svgEl, natural: svgNatural(svgEl), label: 'graph', comment: wholeBlockComment(ctx, blockId, 'graph') });
         if (!ctx.annotate) return;
         const parts = svgEl.querySelectorAll('g.node, g.edge');
         parts.forEach((g) => {
@@ -928,6 +982,59 @@
     return encode64(new Uint8Array(compressed));
   }
 
+  // Fetch a remote SVG and return a sanitized inline <svg> element, so its parts
+  // become annotatable. Rejects on network/CORS failure (caller falls back to an
+  // <img>). The SVG is sanitized — it comes from a remote, author-set server, so
+  // strip scripts / foreignObject / on* handlers / javascript: links before it
+  // ever touches the document.
+  function fetchInlineSvg(url) {
+    return fetch(url, { credentials: 'omit', mode: 'cors' })
+      .then((r) => {
+        if (!r.ok) throw new Error('http ' + r.status);
+        // only trust a declared SVG/XML payload; anything else → <img> fallback
+        const ct = (r.headers.get('content-type') || '').toLowerCase();
+        if (ct && !ct.includes('svg') && !ct.includes('xml')) throw new Error('not svg: ' + ct);
+        return r.text();
+      })
+      .then((text) => {
+        const doc = new DOMParser().parseFromString(text, 'image/svg+xml');
+        if (doc.querySelector('parsererror')) throw new Error('bad svg');
+        const svg = doc.querySelector('svg');
+        if (!svg) throw new Error('no svg');
+        sanitizeSvg(svg);
+        return document.importNode(svg, true);
+      });
+  }
+
+  // The SVG comes from a remote, author-set server, so strip everything active
+  // or capable of fetching an external resource before it touches the document.
+  // Script execution is already impossible here (DOMParser doesn't run scripts;
+  // importNode+appendChild never starts an SVG <script>), but we still drop
+  // <script>/<foreignObject>/<style>, on* handlers, non-fragment href/xlink:href
+  // (<use>/<image>/<a>), and any url(...) that doesn't point at a #fragment —
+  // those are client-side SSRF / beacon vectors and there is no CSP backstop.
+  function sanitizeSvg(root) {
+    root.querySelectorAll('script, foreignObject, style').forEach((n) => n.remove());
+    const walk = (n) => {
+      if (n.nodeType === 1) {
+        for (const attr of Array.from(n.attributes)) {
+          const name = attr.name.toLowerCase();
+          const val = (attr.value || '').replace(/\s+/g, '').toLowerCase();
+          const isHref = name === 'href' || name.endsWith(':href');
+          if (
+            name.startsWith('on') ||                 // event handlers
+            (isHref && !val.startsWith('#')) ||       // only same-document fragment refs
+            /url\((?!['"]?#)/.test(val)               // url() to anything but a #fragment
+          ) {
+            n.removeAttribute(attr.name);
+          }
+        }
+      }
+      n.childNodes.forEach(walk);
+    };
+    walk(root);
+  }
+
   function renderPlantuml(block, ctx, blockId) {
     const container = el('div', { class: 'blk-plantuml' });
     const fail = () =>
@@ -937,34 +1044,66 @@
     encodePlantUml(block.code || '')
       .then((encoded) => {
         const server = block.server || 'https://www.plantuml.com/plantuml';
-        const img = el('img', {
-          class: 'blk-plantuml-img',
-          src: server + '/svg/' + encoded,
-          alt: 'PlantUML diagram',
-          loading: 'lazy',
-        });
-        if (block.height) img.style.height = clampHeight(block.height, 360) + 'px';
-        img.addEventListener('error', fail);
-        container.replaceChildren(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: 'PlantUML diagram' },
-          });
-        }
+        const url = server + '/svg/' + encoded;
+        // Prefer inline SVG (per-element annotation); fall back to an opaque
+        // <img> if the server blocks cross-origin fetch or anything fails.
+        fetchInlineSvg(url)
+          .then((svg) => mountPlantumlSvg(container, svg, block, ctx, blockId))
+          .catch(() => mountPlantumlImg(container, url, fail, block, ctx, blockId));
       })
       .catch(fail);
     return container;
   }
 
+  function mountPlantumlSvg(container, svg, block, ctx, blockId) {
+    if (block.height != null) container.style.maxHeight = clampHeight(block.height, 1200) + 'px';
+    sizeDiagramSvg(svg);
+    container.replaceChildren(svg);
+    attachViewer(container, {
+      zoomEl: svg,
+      natural: svgNatural(svg),
+      label: 'diagram',
+      comment: wholeBlockComment(ctx, blockId, 'diagram'),
+    });
+    if (!ctx.annotate) return;
+    // register the text labels as annotation targets (participant boxes, message
+    // labels, …) — the meaningful, clickable parts of a PlantUML diagram.
+    // `idx` disambiguates: PlantUML repeats participant labels top AND bottom,
+    // so without a unique key one comment would badge BOTH identical-text nodes.
+    svg.querySelectorAll('text').forEach((t, idx) => {
+      const text = (t.textContent || '').trim();
+      if (!text) return;
+      ctx.annotate.register(t, {
+        blockId,
+        questionId: ctx.questionId,
+        target: { kind: 'plantuml-node', idx, text: text.slice(0, 120) },
+      });
+    });
+  }
+
+  function mountPlantumlImg(container, url, fail, block, ctx, blockId) {
+    const img = el('img', { class: 'blk-plantuml-img', src: url, alt: 'PlantUML diagram', loading: 'lazy' });
+    if (block.height != null) img.style.height = clampHeight(block.height, 360) + 'px';
+    img.addEventListener('error', fail);
+    container.replaceChildren(img);
+    const attachImgViewer = () =>
+      attachViewer(container, {
+        zoomEl: img,
+        natural: () => (img.naturalWidth > 0 ? { w: img.naturalWidth, h: img.naturalHeight } : null),
+        label: 'diagram',
+        comment: wholeBlockComment(ctx, blockId, 'diagram'),
+      });
+    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: 'PlantUML diagram' },
+      });
+    }
+  }
+
   // ---------- 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
@@ -989,6 +1128,8 @@
       attachViewer(container, {
         zoomEl: img,
         natural: () => (img.naturalWidth > 0 ? { w: img.naturalWidth, h: img.naturalHeight } : null),
+        label: 'image',
+        comment: wholeBlockComment(ctx, blockId, 'image'),
       });
     if (img.complete && img.naturalWidth > 0) attachImgViewer();
     else img.addEventListener('load', attachImgViewer, { once: true });
@@ -1010,39 +1151,145 @@
   // <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.
+  // 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
+  // explicit −/+ buttons (the % doubles as a reset-to-fit button).
   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>';
+  const ICON_COMMENT =
+    '<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="M21 11.5a8.38 8.38 0 0 1-.9 3.8 8.5 8.5 0 0 1-7.6 4.7 8.38 8.38 0 0 1-3.8-.9L3 21l1.9-5.7a8.38 8.38 0 0 1-.9-3.8 8.5 8.5 0 0 1 4.7-7.6 8.38 8.38 0 0 1 3.8-.9h.5a8.48 8.48 0 0 1 8 8z"/></svg>';
 
   function exitFull() {
     if (!fullOpen) return;
-    fullOpen.classList.remove('blk-full');
+    const c = fullOpen;
+    c.classList.remove('blk-full');
     document.body.classList.remove('blk-full-open');
-    const btn = fullOpen.querySelector('.blk-tools .tool-full');
+    const btn = c.querySelector('.blk-tools .tool-full');
     if (btn) btn.innerHTML = ICON_EXPAND;
     fullOpen = null;
     window.dispatchEvent(new Event('resize'));
+    if (c._rlyToolsSync) c._rlyToolsSync(); // re-pin toolbar to its scrolled corner
   }
   document.addEventListener('keydown', (e) => {
     if (e.key === 'Escape' && fullOpen) exitFull();
   });
 
-  // opts: { zoomEl: svg|img|null, natural: () => ({w,h}|null) } — zoomEl null
-  // means full-screen only (charts, html iframes).
+  // Drag-to-pan: grab anywhere on a scrollable visual (a tall/zoomed diagram or
+  // oversized image) and drag to move across it, instead of hunting for the
+  // scrollbars. Self-gates on overflow, so charts and html iframes — which are
+  // always sized to fit — never engage. Annotation on diagrams/images is
+  // hover-pin based (not a node click), so a pan can't create a stray
+  // annotation; a real drag still swallows the trailing click as a guard.
+  // Returns a refresh() the viewer calls whenever content size changes (zoom,
+  // full-screen, re-render) so the grab affordance tracks pannability.
+  function enablePan(scrollEl) {
+    let pending = false, active = false;
+    let sx = 0, sy = 0, sl = 0, st = 0, pid = null;
+    const THRESH = 4; // px before a press becomes a drag (keeps clicks clickable)
+
+    const pannable = () =>
+      scrollEl.scrollWidth - scrollEl.clientWidth > 1 ||
+      scrollEl.scrollHeight - scrollEl.clientHeight > 1;
+    const refresh = () => scrollEl.classList.toggle('blk-pannable', pannable());
+
+    scrollEl.addEventListener('pointerdown', (e) => {
+      if (e.button !== 0 || !pannable()) return;
+      // leave the toolbar, the diagram editor, and real controls interactive
+      if (e.target.closest && e.target.closest('.blk-tools, .blk-editor, button, a, input, textarea, select')) return;
+      pending = true; active = false;
+      sx = e.clientX; sy = e.clientY;
+      sl = scrollEl.scrollLeft; st = scrollEl.scrollTop;
+      pid = e.pointerId;
+    });
+    scrollEl.addEventListener('pointermove', (e) => {
+      if (!pending) return;
+      const dx = e.clientX - sx, dy = e.clientY - sy;
+      if (!active) {
+        if (Math.abs(dx) < THRESH && Math.abs(dy) < THRESH) return;
+        active = true;
+        scrollEl.classList.add('blk-panning');
+        try { scrollEl.setPointerCapture(pid); } catch (_) {}
+      }
+      e.preventDefault();
+      scrollEl.scrollLeft = sl - dx;
+      scrollEl.scrollTop = st - dy;
+    });
+    const end = () => {
+      if (active) {
+        scrollEl.classList.remove('blk-panning');
+        try { scrollEl.releasePointerCapture(pid); } catch (_) {}
+        // a drag ends in a click on whatever was under the release — swallow it
+        // once so it can't trigger anything the user didn't mean to click
+        const swallow = (ev) => { ev.stopPropagation(); ev.preventDefault(); };
+        scrollEl.addEventListener('click', swallow, { capture: true, once: true });
+        setTimeout(() => scrollEl.removeEventListener('click', swallow, true), 0);
+      }
+      pending = false; active = false; pid = null;
+    };
+    scrollEl.addEventListener('pointerup', end);
+    scrollEl.addEventListener('pointercancel', end);
+    window.addEventListener('resize', refresh);
+    return refresh;
+  }
+
+  // Build the onComment thunk for attachViewer: opens the annotation popover
+  // with a block-scoped target ("Whole chart/diagram/…") so a user can comment
+  // on the visual as a whole. null when annotation is off (omits the button).
+  function wholeBlockComment(ctx, blockId, label) {
+    if (!ctx || !ctx.annotate) return null;
+    const a = ctx.annotate;
+    return {
+      open: (anchorEl) =>
+        a.openExternal({ blockId, questionId: ctx.questionId, target: { kind: 'block', label } }, anchorEl),
+      // true once this block carries a whole-block comment
+      active: () => a.list().some((x) => x.blockId === blockId && x.target && x.target.kind === 'block'),
+      // fires on any annotation change; returns an unsubscribe
+      subscribe: (fn) => (a.onBadgeRefresh ? a.onBadgeRefresh(fn) : () => {}),
+    };
+  }
+
+  // opts: { zoomEl, natural, comment, label } — zoomEl null means no pixel
+  // zoom (charts/html/code: full-screen + comment only, no zoom buttons).
+  // comment (optional) = { open(anchor), active(), subscribe(fn) } wiring the
+  // "comment on the whole block" button + its already-commented style.
   function attachViewer(container, opts) {
     if (container._rlyTools) container._rlyTools.remove();
     container.classList.add('blk-viewer');
     const zoomable = Boolean(opts && opts.zoomEl);
-    let z = null; // null = fit-to-width
+    const label = (opts && opts.label) || 'visual';
+
+    // pan listeners bind once per container; mermaid re-renders re-call
+    // attachViewer, so reuse the existing refresh() instead of re-binding
+    if (!container._rlyPan) container._rlyPan = enablePan(container);
+    const refreshPan = container._rlyPan;
+
+    // The toolbar is absolute inside the scroll box, so it scrolls away when the
+    // user pans/scrolls. Counter-translate it by the scroll offset to pin it to
+    // the visible corner (off in full-screen, where it is position:fixed). Bound
+    // once; always re-reads the current toolbar (mermaid rebuilds it on render).
+    if (!container._rlyToolsSync) {
+      const sync = () => {
+        const tb = container._rlyTools;
+        if (!tb) return;
+        if (container.classList.contains('blk-full')) { tb.style.transform = ''; return; }
+        const x = container.scrollLeft, y = container.scrollTop;
+        tb.style.transform = x || y ? 'translate(' + x + 'px,' + y + 'px)' : '';
+      };
+      container.addEventListener('scroll', sync);
+      container._rlyToolsSync = sync;
+    }
 
+    // zoom level persists across re-renders; the wheel handler (bound once)
+    // delegates through container._rlyZoom so it never holds a stale zoomEl
+    if (container._rlyZ === undefined) container._rlyZ = null; // null = fit-to-width
     const pct = el('span', { class: 'tool-pct' }, 'fit');
     function apply() {
       if (!zoomable) return;
       const target = opts.zoomEl;
       const nat = opts.natural();
+      const z = container._rlyZ;
       if (z === null || !nat || !nat.w) {
         target.style.width = '100%';
         target.style.maxWidth = nat && nat.w ? Math.ceil(nat.w) + 'px' : '100%';
@@ -1054,52 +1301,88 @@
         target.style.height = 'auto';
         pct.textContent = Math.round(z * 100) + '%';
       }
-      // annotation overlay badges reposition on resize
-      window.dispatchEvent(new Event('resize'));
+      window.dispatchEvent(new Event('resize')); // annotation badges reposition
+      refreshPan();                              // content size → grab affordance
+      container._rlyToolsSync();                 // keep the toolbar pinned
     }
     function currentZ() {
-      if (z !== null) return z;
+      if (container._rlyZ !== null) return container._rlyZ;
       const nat = opts.natural();
       if (!nat || !nat.w) return 1;
       const shown = opts.zoomEl.getBoundingClientRect().width;
       return shown > 0 ? shown / nat.w : 1;
     }
     function setZoom(next) {
-      z = next === null ? null : Math.min(5, Math.max(0.2, next));
+      container._rlyZ = next === null ? null : Math.min(5, Math.max(0.2, next));
       apply();
     }
+    container._rlyZoom = { setZoom, currentZ };
 
     const tools = el('div', { class: 'blk-tools' });
+
+    // comment on the whole block (leftmost) — opens the annotation popover with
+    // a block-scoped target so a user can comment without picking an element.
+    // The button gains a .has-comment style once the block carries one, kept in
+    // sync via the annotate badge-refresh subscription (bound once per container).
+    if (opts && opts.comment) {
+      const cmt = opts.comment;
+      const cBtn = el('button', { class: 'tool-comment', type: 'button', title: 'Comment on this whole ' + label });
+      cBtn.innerHTML = ICON_COMMENT;
+      cBtn.addEventListener('click', (e) => { e.stopPropagation(); cmt.open(container); });
+      tools.append(cBtn);
+      container._rlyCmtSync = () => {
+        const b = container._rlyTools && container._rlyTools.querySelector('.tool-comment');
+        if (b && cmt.active) b.classList.toggle('has-comment', !!cmt.active());
+      };
+      if (!container._rlyCmtHook && cmt.subscribe) {
+        container._rlyCmtHook = cmt.subscribe(() => container._rlyCmtSync && container._rlyCmtSync());
+      }
+    }
+
     if (zoomable) {
-      // zoom lives on cmd/ctrl+wheel only — the toolbar is full-screen-only
-      container.addEventListener(
-        'wheel',
-        (e) => {
-          if (!(e.ctrlKey || e.metaKey)) return;
+      // cmd/ctrl+wheel zoom, bound ONCE (re-binding per render would stack);
+      // delegates to the current controller so it never uses a stale zoomEl
+      if (!container._rlyWheel) {
+        const onWheel = (e) => {
+          if (!(e.ctrlKey || e.metaKey) || !container._rlyZoom) return;
           e.preventDefault();
-          setZoom(currentZ() * (e.deltaY < 0 ? 1.15 : 1 / 1.15));
-        },
-        { passive: false }
-      );
+          container._rlyZoom.setZoom(container._rlyZoom.currentZ() * (e.deltaY < 0 ? 1.15 : 1 / 1.15));
+        };
+        container.addEventListener('wheel', onWheel, { passive: false });
+        container._rlyWheel = onWheel;
+      }
+      const zoomOut = el('button', { class: 'tool-zoom', type: 'button', title: 'Zoom out' }, '−');
+      const zoomIn = el('button', { class: 'tool-zoom', type: 'button', title: 'Zoom in' }, '+');
+      zoomOut.addEventListener('click', (e) => { e.stopPropagation(); setZoom(currentZ() / 1.2); });
+      zoomIn.addEventListener('click', (e) => { e.stopPropagation(); setZoom(currentZ() * 1.2); });
+      pct.classList.add('is-btn');
+      pct.title = 'Reset to fit';
+      pct.addEventListener('click', (e) => { e.stopPropagation(); setZoom(null); });
+      tools.append(zoomOut, pct, zoomIn);
     }
-    const fullBtn = el('button', { class: 'tool-full', type: 'button', title: 'Full screen (Esc closes; cmd/ctrl+wheel zooms)' });
+
+    const fullBtn = el('button', { class: 'tool-full', type: 'button', title: 'Full screen (Esc closes; ⌘/Ctrl+wheel zooms)' });
     fullBtn.innerHTML = ICON_EXPAND;
-    fullBtn.addEventListener('click', () => {
-      if (fullOpen === container) {
-        exitFull();
-        return;
-      }
+    fullBtn.addEventListener('click', (e) => {
+      e.stopPropagation();
+      if (fullOpen === container) { exitFull(); return; }
       exitFull();
       container.classList.add('blk-full');
       document.body.classList.add('blk-full-open');
       fullOpen = container;
       fullBtn.textContent = '✕';
       window.dispatchEvent(new Event('resize'));
+      container._rlyToolsSync();
     });
     tools.append(fullBtn);
+
     container.append(tools);
     container._rlyTools = tools;
     if (zoomable) apply();
+    // non-zoomable diagrams (tall mermaid, oversized image) can still overflow
+    refreshPan();
+    container._rlyToolsSync();
+    if (container._rlyCmtSync) container._rlyCmtSync(); // reflect existing comment
   }
 
   function svgNatural(svgEl) {
@@ -1122,7 +1405,7 @@
       loading: 'lazy',
     });
     const wrap = el('div', { class: 'blk-htmlwrap' }, iframe);
-    attachViewer(wrap, { zoomEl: null });
+    attachViewer(wrap, { zoomEl: null, label: 'embed', comment: wholeBlockComment(ctx, blockId, 'embed') });
     return wrap;
   }
 
@@ -1143,7 +1426,7 @@
         wrapper.append(inner);
         break;
       case 'code':
-        inner = renderCode(block);
+        inner = renderCode(block, ctx, blockId);
         wrapper.append(inner);
         break;
       case 'chart':
@@ -1196,5 +1479,5 @@
     }
   }
 
-  window.RelayBlocks = { render, onThemeChange };
+  window.RelayBlocks = { render, onThemeChange, renderMarkdown };
 })();

package/src/ui/style.css

@@ -87,7 +87,12 @@ h1 {
   line-height: 1.25;
   text-wrap: balance;
 }
-.intro { color: var(--fg-2); white-space: pre-wrap; margin: 10px 0 18px; }
+.intro { color: var(--fg-2); margin: 10px 0 18px; }
+/* the intro renders markdown; keep it muted (out-specificity .blk-markdown .md)
+   and trim its block margins so it reads as a lead paragraph, not a content block */
+.intro.blk-markdown .md { color: var(--fg-2); }
+.intro.blk-markdown .md > :first-child { margin-top: 0; }
+.intro.blk-markdown .md > :last-child { margin-bottom: 0; }
 .theme-btn {
   background: transparent; color: var(--fg-2);
   border: 1px solid var(--border-strong); border-radius: 999px;
@@ -203,6 +208,10 @@ textarea { min-height: 90px; resize: vertical; }
   background: linear-gradient(transparent, var(--bg) 38%);
   padding: 22px 0 16px;
   display: flex; align-items: center; gap: 14px;
+  /* above content-anchored annotation badges (z 15) so the Submit bar is never
+     covered; still below the full-screen overlay (49) and the modal popover/
+     rail/toast, which are intentional and must sit on top */
+  z-index: 30;
 }
 .submit {
   background: var(--accent); color: var(--accent-fg);