@khanglvm/relay 0.12.2 → 0.13.0

package/src/ui/blocks.js

@@ -95,6 +95,23 @@
     s = s.replace(/`([^`]+)`/g, (_m, c) =>
       looksLikeLocalPath(c) ? keep(fileLinkHtml(c.trim(), c, true)) : keep(`<code>${c}</code>`)
     );
+    // reference links [label](#ref:name) / [label](#block:id) open the named/identified
+    // block in a full-screen modal — so a question can point back to a chart/image
+    // shown earlier without the user scrolling up. Runs before the generic link
+    // pass so the #ref:/#block: target isn't rendered as a plain href.
+    s = s.replace(/\[([^\]]+)\]\(#(ref|block):([^)\s]+)\)/g, (_m, label, kind, target) =>
+      keep(`<a class="rly-reflink" role="button" tabindex="0" data-rly-${kind === 'block' ? 'refid' : 'ref'}="${target}" title="Open this visual">` +
+        `<span class="rly-reflink-ico" aria-hidden="true"></span><span>${label}</span></a>`));
+    // images ![alt](src) BEFORE links so the leading "!" isn't stranded as text.
+    // A remote/data image embeds inline; a local path stays a click-to-open link
+    // (the board server doesn't serve the source file's directory).
+    // ponytail: remote/data images embed; local-relative images open in the app
+    // rather than render — add directory serving only if users need inline locals.
+    s = s.replace(/!\[([^\]]*)\]\(([^)\s]+)\)/g, (_m, alt, url) => {
+      if (/^(https?:|data:image\/)/i.test(url)) return keep(`<img class="md-img" src="${url}" alt="${alt}" loading="lazy">`);
+      if (looksLikeLocalPath(url)) return keep(fileLinkHtml(url, alt || url, false));
+      return `![${alt}](${url})`; // unknown scheme — leave literal, don't link
+    });
     // links [text](url) — url is already escaped; a local-path target becomes a
     // click-to-open link, otherwise a normal link (guarding odd schemes).
     s = s.replace(/\[([^\]]+)\]\(([^)\s]+)\)/g, (_m, text, url) => {
@@ -107,6 +124,10 @@
     // bold then italic (bold uses ** so must run before single *)
     s = s.replace(/\*\*([^*]+)\*\*/g, (_m, c) => `<strong>${c}</strong>`);
     s = s.replace(/\*([^*]+)\*/g, (_m, c) => `<em>${c}</em>`);
+    // underscore emphasis __bold__ / _italic_, only at word boundaries so
+    // snake_case and RLY_BOARD_ID are left alone (CommonMark intraword rule).
+    s = s.replace(/(^|[^A-Za-z0-9_])__([^_]+)__(?![A-Za-z0-9_])/g, (_m, p, c) => `${p}<strong>${c}</strong>`);
+    s = s.replace(/(^|[^A-Za-z0-9_])_([^_]+)_(?![A-Za-z0-9_])/g, (_m, p, c) => `${p}<em>${c}</em>`);
     // restore the stashed HTML — loop so a placeholder nested inside another
     // stashed fragment (e.g. a code span inside a link's text) is also resolved.
     let guard = 0;
@@ -373,14 +394,25 @@
     return out;
   }
 
-  // A line-number gutter element for `text` (aria-hidden + non-selectable so a
-  // select-to-comment grabs only the code, not the numbers). `startAt` default 1.
-  function lineGutter(text, startAt) {
+  // A line-number gutter for `text` (non-selectable so a select-to-comment grabs
+  // only the code, not the numbers). When annotation is on, each number becomes a
+  // hover/click target to comment on that exact line (kind:'code-line'); the
+  // numbers still don't enter a text selection. `startAt` default 1.
+  function lineGutter(text, startAt, ctx, blockId, filename) {
     const n = Math.max(1, String(text).replace(/\n+$/, '').split('\n').length);
-    const g = el('div', { class: 'blk-gutter', 'aria-hidden': 'true' });
-    let s = '';
-    for (let i = 0; i < n; i++) s += (startAt || 1) + i + '\n';
-    g.textContent = s;
+    const annotate = ctx && ctx.annotate;
+    const g = el('div', { class: 'blk-gutter' + (annotate ? ' blk-gutter-c' : ''), 'aria-hidden': annotate ? null : 'true' });
+    for (let i = 0; i < n; i++) {
+      const ln = (startAt || 1) + i;
+      const lineEl = el('div', { class: 'blk-gutterline' }, String(ln));
+      if (annotate) {
+        annotate.register(lineEl, {
+          blockId, questionId: ctx.questionId,
+          target: { kind: 'code-line', line: ln, file: filename || '' },
+        });
+      }
+      g.append(lineEl);
+    }
     return g;
   }
 
@@ -391,7 +423,7 @@
     const code = el('code');
     code.innerHTML = tintCode(raw, block.lang);
     const pre = el('pre', { class: 'blk-pre', 'data-lang': block.lang || '' }, code);
-    const row = el('div', { class: 'blk-coderow' }, lineGutter(raw), pre);
+    const row = el('div', { class: 'blk-coderow' }, lineGutter(raw, 1, ctx, blockId, block.filename), pre);
     const wrap = el('div', { class: 'blk-codewrap' });
     // Optional file-name + language header above the code.
     if (block.filename || block.lang) {
@@ -513,18 +545,62 @@
     return el('table', { class: 'blk-difftable blk-difftable-split' }, tbody);
   }
 
+  // Split a (possibly multi-file) unified diff into per-file chunks. Each
+  // `diff --git a/x b/x` starts a new file; the name comes from that line (or a
+  // following `+++ b/...`). A plain hunk-only diff (no `diff --git`) is one
+  // unnamed file, preserving the single-file path that uses block.filename.
+  function splitDiffFiles(text) {
+    const lines = String(text || '').replace(/\r\n?/g, '\n').split('\n');
+    const files = [];
+    let cur = null;
+    for (const line of lines) {
+      if (/^diff --git /.test(line)) {
+        const m = line.match(/^diff --git a\/(.+?) b\/(.+)$/);
+        cur = { name: m ? m[2] : 'file', lines: [line] };
+        files.push(cur);
+      } else {
+        if (!cur) { cur = { name: null, lines: [] }; files.push(cur); }
+        cur.lines.push(line);
+        if (cur.name === null) {
+          const pm = line.match(/^\+\+\+ b?\/(.+)$/);
+          if (pm) cur.name = pm[1];
+        }
+      }
+    }
+    return files.map((f) => ({ name: f.name, text: f.lines.join('\n') }));
+  }
+
+  // Per-file header lines are redundant once we render a filename header bar.
+  const DIFF_NOISE = /^(diff --git |index |--- |\+\+\+ )/;
+
   function renderDiff(block, ctx, blockId) {
-    const rows = parseDiff(block.diff);
+    const files = splitDiffFiles(block.diff);
+    const named = files.filter((f) => f.name);
+    const multi = named.length > 1;
     let view = block.view === 'split' ? 'split' : 'unified';
     const scroll = el('div', { class: 'blk-diffscroll' });
+    const sections = [];
+
     const paint = () => {
-      scroll.innerHTML = '';
-      scroll.append(view === 'split' ? buildSplitDiff(rows, block.lang) : buildUnifiedDiff(rows, block.lang));
+      scroll.replaceChildren();
+      sections.length = 0;
+      files.forEach((f) => {
+        const name = f.name || (files.length === 1 ? (block.filename || '') : '');
+        let rows = parseDiff(f.text);
+        // drop the pure file-header noise when we show a filename bar
+        if (name) rows = rows.filter((r) => !(r.kind === 'meta' && DIFF_NOISE.test(r.text)));
+        if (!rows.length) return;
+        const sec = el('div', { class: 'diff-file' });
+        if (name) sec.append(el('div', { class: 'diff-filehead' }, name));
+        sec.append(view === 'split' ? buildSplitDiff(rows, block.lang) : buildUnifiedDiff(rows, block.lang));
+        scroll.append(sec);
+        sections.push({ name, el: sec });
+      });
     };
     paint();
 
     const wrap = el('div', { class: 'blk-codewrap blk-diffwrap' });
-    // header: file name (left) + a Unified/Split view toggle (right)
+    // header: file count / single name (left) + a Unified/Split view toggle (right)
     const toggle = el('button', { class: 'blk-difftoggle', type: 'button', title: 'Toggle side-by-side view' });
     const syncToggle = () => { toggle.textContent = view === 'split' ? 'Unified view' : 'Split view'; };
     syncToggle();
@@ -537,10 +613,26 @@
       syncToggle();
       paint();
     });
+    const headLabel = multi ? `${named.length} files changed` : (named[0] && named[0].name) || block.filename || '';
     wrap.append(el('div', { class: 'blk-codehead' },
-      el('span', { class: 'blk-codename' }, block.filename || ''),
+      el('span', { class: 'blk-codename' }, headLabel),
       toggle
     ));
+    // jump bar of file chips for a multi-file diff (click scrolls to that file)
+    if (multi) {
+      const bar = el('div', { class: 'diff-files' });
+      named.forEach((f) => {
+        const chip = el('button', { type: 'button', class: 'diff-file-chip' }, f.name);
+        chip.addEventListener('mousedown', (e) => e.stopPropagation());
+        chip.addEventListener('click', (e) => {
+          e.stopPropagation();
+          const s = sections.find((x) => x.name === f.name);
+          if (s) s.el.scrollIntoView({ behavior: 'smooth', block: 'start' });
+        });
+        bar.append(chip);
+      });
+      wrap.append(bar);
+    }
     wrap.classList.toggle('is-split', view === 'split');
     wrap.append(scroll);
     // select-to-comment stays bound to the stable scroll container across toggles
@@ -615,10 +707,32 @@
     return String(a).localeCompare(String(b), undefined, { numeric: true, sensitivity: 'base' });
   }
 
+  // CSV-encode a value (quote when it contains a comma/quote/newline).
+  function csvCell(v) {
+    const s = v === undefined || v === null ? '' : String(v);
+    return /[",\n]/.test(s) ? '"' + s.replace(/"/g, '""') + '"' : s;
+  }
+  // Trigger a client-side download of `text` as `filename` (browser board). In a
+  // sandboxed/MCP host this may be blocked — best effort, no error if it no-ops.
+  function downloadText(filename, text, mime) {
+    try {
+      const blob = new Blob([text], { type: mime || 'text/plain' });
+      const url = URL.createObjectURL(blob);
+      const a = el('a', { href: url, download: filename });
+      document.body.append(a);
+      a.click();
+      a.remove();
+      setTimeout(() => URL.revokeObjectURL(url), 1000);
+    } catch (_) { /* sandbox without download permission */ }
+  }
+
   function renderTable(block, ctx, blockId) {
     const cols = normalizeColumns(block.columns);
     const rows = block.rows || [];
     const sortable = block.sortable === true;
+    const filterable = block.filterable === true;
+    const exportable = block.exportable === true;
+    let filterText = '';
     // sortState: column index in cols (-1 none) + dir
     let sortCol = -1;
     let sortDir = 0; // 0 none, 1 asc, -1 desc
@@ -647,9 +761,17 @@
     const tbody = el('tbody');
     table.append(thead, tbody);
 
-    function rebuild() {
-      // keep original row indices stable across sorts
+    // rows (as original indices) passing the current filter — used by both the
+    // table body and the CSV export so export honors the visible/filtered set.
+    function filteredOrder() {
       let order = rows.map((_r, idx) => idx);
+      if (filterText) {
+        const q = filterText.toLowerCase();
+        order = order.filter((idx) => cols.some((col) => {
+          const v = cellValue(rows[idx], col);
+          return v !== undefined && v !== null && String(v).toLowerCase().includes(q);
+        }));
+      }
       if (sortable && sortCol >= 0 && sortDir !== 0) {
         const col = cols[sortCol];
         order.sort((ia, ib) => {
@@ -657,6 +779,11 @@
           return sortDir === 1 ? r : -r;
         });
       }
+      return order;
+    }
+
+    function rebuild() {
+      const order = filteredOrder();
       headCells.forEach((hc, ci) => {
         hc.arrow.textContent = sortable && ci === sortCol && sortDir !== 0 ? (sortDir === 1 ? ' ↑' : ' ↓') : '';
       });
@@ -681,7 +808,32 @@
     rebuild();
     // Tables are visual too: wrap so they get the full-screen viewer like
     // every other visual block (wide tables squeeze in the column).
-    const wrap = el('div', { class: 'blk-tablewrap' }, table);
+    const wrap = el('div', { class: 'blk-tablewrap' });
+    // Optional toolbar: live filter box + CSV export of the filtered rows.
+    if (filterable || exportable) {
+      const bar = el('div', { class: 'blk-tablebar' });
+      if (filterable) {
+        const input = el('input', { type: 'text', class: 'blk-tablefilter', placeholder: 'Filter rows…', 'aria-label': 'Filter table rows' });
+        input.addEventListener('input', () => { filterText = input.value.trim(); rebuild(); });
+        // don't let a click in the filter start a drag-pan / full-screen
+        input.addEventListener('mousedown', (e) => e.stopPropagation());
+        bar.append(input);
+      }
+      if (exportable) {
+        const btn = el('button', { type: 'button', class: 'blk-tableexport', title: 'Download the filtered rows as CSV' }, 'CSV');
+        btn.addEventListener('mousedown', (e) => e.stopPropagation());
+        btn.addEventListener('click', (e) => {
+          e.stopPropagation();
+          const order = filteredOrder();
+          const head = cols.map((c) => csvCell(c.label)).join(',');
+          const body = order.map((idx) => cols.map((c) => csvCell(cellValue(rows[idx], c))).join(',')).join('\n');
+          downloadText('table.csv', head + '\n' + body + '\n', 'text/csv');
+        });
+        bar.append(btn);
+      }
+      wrap.append(bar);
+    }
+    wrap.append(table);
     attachViewer(wrap, { zoomEl: null });
     return wrap;
   }
@@ -1401,10 +1553,12 @@
       alt: block.alt || 'image',
       loading: 'lazy',
     });
-    // The per-block height only caps the COMPACT inline preview — the viewer
-    // lifts it on zoom / full-screen so the user can always reach full detail.
-    const fitMaxHeight = block.height ? clampHeight(block.height, 360) : null;
-    if (fitMaxHeight) img.style.maxHeight = fitMaxHeight + 'px';
+    // Inline default: the image fills its full width (container width, never
+    // upscaled past natural) so it's readable without manual zoom; the CONTAINER
+    // caps the height (default 800 via CSS, or block.height) and SCROLLS — we
+    // never cap the image's own height, which would shrink its width. Full-screen
+    // lifts the cap (the .blk-full rule).
+    if (block.height != null) container.style.maxHeight = clampHeight(block.height, 800) + 'px';
     img.addEventListener('error', () => {
       container.replaceChildren(el('div', { class: 'blk-error' }, 'Image failed to load'));
     });
@@ -1415,11 +1569,12 @@
         natural: () => (img.naturalWidth > 0 ? { w: img.naturalWidth, h: img.naturalHeight } : null),
         label: 'image',
         comment: wholeBlockComment(ctx, blockId, 'image'),
-        fitMaxHeight,
       });
     if (img.complete && img.naturalWidth > 0) attachImgViewer();
     else img.addEventListener('load', attachImgViewer, { once: true });
-    if (ctx.annotate) {
+    if (ctx.annotate && block.pins === true) {
+      enableImagePins(container, img, ctx, blockId, block.alt || 'Image');
+    } else if (ctx.annotate) {
       ctx.annotate.register(img, {
         blockId,
         questionId: ctx.questionId,
@@ -1429,6 +1584,56 @@
     return container;
   }
 
+  // Coordinate pin-comments on an image (block.pins): click any point to drop a
+  // comment anchored to that (x,y) fraction; a numbered pin marks each one and
+  // tracks the image as it scales/scrolls (positions are % of the displayed img,
+  // so they ride zoom/full-screen/pan for free). Mirrors the chart-badge model.
+  function enableImagePins(container, img, ctx, blockId, label) {
+    const layer = el('div', { class: 'blk-imgpins' });
+    container.append(layer);
+    img.classList.add('blk-img-pinnable');
+    let down = null; // {x,y} at pointerdown — used to reject drags (pan) as clicks
+    img.addEventListener('pointerdown', (e) => { down = { x: e.clientX, y: e.clientY }; });
+    img.addEventListener('click', (e) => {
+      if (down && (Math.abs(e.clientX - down.x) > 4 || Math.abs(e.clientY - down.y) > 4)) { down = null; return; }
+      const r = img.getBoundingClientRect();
+      if (!r.width || !r.height) return;
+      const x = Math.min(1, Math.max(0, (e.clientX - r.left) / r.width));
+      const y = Math.min(1, Math.max(0, (e.clientY - r.top) / r.height));
+      ctx.annotate.openExternal(
+        { blockId, questionId: ctx.questionId, target: { kind: 'image-point', x: Math.round(x * 1000) / 1000, y: Math.round(y * 1000) / 1000, label } },
+        img
+      );
+    });
+    const syncPins = () => {
+      layer.replaceChildren();
+      const groups = new Map(); // "x:y" -> {target, count}
+      let n = 0;
+      for (const a of ctx.annotate.list()) {
+        if (a.blockId !== blockId) continue;
+        const t = a.target || {};
+        if (t.kind !== 'image-point') continue;
+        const k = t.x + ':' + t.y;
+        const g = groups.get(k) || { target: t, count: 0 };
+        g.count++; groups.set(k, g);
+      }
+      for (const { target, count } of groups.values()) {
+        n++;
+        const pin = el('button', { class: 'blk-imgpin', type: 'button', title: count + (count === 1 ? ' comment' : ' comments') }, String(count));
+        pin.style.left = (target.x * 100) + '%';
+        pin.style.top = (target.y * 100) + '%';
+        pin.addEventListener('mousedown', (e) => e.stopPropagation());
+        pin.addEventListener('click', (e) => {
+          e.stopPropagation(); e.preventDefault();
+          ctx.annotate.openExternal({ blockId, questionId: ctx.questionId, target }, pin);
+        });
+        layer.append(pin);
+      }
+    };
+    if (ctx.annotate.onBadgeRefresh) ctx.annotate.onBadgeRefresh(syncPins);
+    syncPins();
+  }
+
   // ---------- palette ----------
   // Color palettes as swatch cards: hover a swatch to reveal its hex, click to
   // copy it. One palette may be {featured:true} → a larger spotlight row. Lets
@@ -1488,6 +1693,104 @@
     return wrap;
   }
 
+  // ---------- kpi (stat cards) ----------
+  function renderKpi(block, ctx, blockId) {
+    const wrap = el('div', { class: 'blk-kpi' });
+    if (block.title) wrap.append(el('div', { class: 'kpi-title' }, block.title));
+    const grid = el('div', { class: 'kpi-grid' });
+    for (const it of block.items || []) {
+      const card = el('div', { class: 'kpi-card' });
+      if (it.label) card.append(el('div', { class: 'kpi-label' }, it.label));
+      card.append(el('div', { class: 'kpi-value' }, it.value || ''));
+      if (it.delta) {
+        const glyph = it.dir === 'up' ? '▲ ' : it.dir === 'down' ? '▼ ' : it.dir === 'flat' ? '▬ ' : '';
+        card.append(el('div', { class: 'kpi-delta' + (it.dir ? ' kpi-' + it.dir : '') }, glyph + it.delta));
+      }
+      if (it.sub) card.append(el('div', { class: 'kpi-sub' }, it.sub));
+      if (ctx.annotate) {
+        ctx.annotate.register(card, {
+          blockId, questionId: ctx.questionId,
+          target: { kind: 'html-element', label: ((it.label ? it.label + ' · ' : '') + (it.value || 'KPI')) },
+        });
+      }
+      grid.append(card);
+    }
+    wrap.append(grid);
+    return wrap;
+  }
+
+  // ---------- typography (type specimens) ----------
+  function renderTypography(block, ctx, blockId) {
+    const wrap = el('div', { class: 'blk-typography' });
+    if (block.title) wrap.append(el('div', { class: 'typo-title' }, block.title));
+    for (const s of block.specimens || []) {
+      const meta = [];
+      if (s.label) meta.push(s.label);
+      if (s.size) meta.push(s.size);
+      if (s.weight) meta.push('w' + s.weight);
+      const sample = el('div', { class: 'typo-sample' }, s.text);
+      // set via DOM style props (browser ignores invalid values — no injection)
+      if (s.size) sample.style.fontSize = s.size;
+      if (s.weight) sample.style.fontWeight = s.weight;
+      if (s.font || block.font) sample.style.fontFamily = s.font || block.font;
+      if (s.lineHeight) sample.style.lineHeight = s.lineHeight;
+      if (s.letterSpacing) sample.style.letterSpacing = s.letterSpacing;
+      wrap.append(el('div', { class: 'typo-row' },
+        meta.length ? el('div', { class: 'typo-meta' }, meta.join(' · ')) : null,
+        sample
+      ));
+    }
+    ctx.annotate && ctx.annotate.enableTextSelection(wrap, { blockId, questionId: ctx.questionId });
+    return wrap;
+  }
+
+  // ---------- compare (before/after image slider) ----------
+  // The "after" image is the base layer (defines the frame size); the "before"
+  // image sits in an overflow-clipped layer whose width the divider drives, so
+  // dragging reveals more of one image and less of the other.
+  function renderCompare(block, ctx, blockId) {
+    const wrap = el('div', { class: 'blk-comparewrap' });
+    const frame = el('div', { class: 'cmp-frame' });
+    if (block.height) frame.style.maxHeight = clampHeight(block.height, 1200) + 'px';
+    const afterImg = el('img', { class: 'cmp-img', src: block.after, alt: block.afterLabel || 'after', draggable: 'false', loading: 'lazy' });
+    const beforeImg = el('img', { class: 'cmp-img cmp-img-before', src: block.before, alt: block.beforeLabel || 'before', draggable: 'false', loading: 'lazy' });
+    const beforeLayer = el('div', { class: 'cmp-before' }, beforeImg);
+    const handle = el('div', { class: 'cmp-handle', tabindex: '0', role: 'slider', 'aria-label': 'Compare before and after' },
+      el('div', { class: 'cmp-handle-grip' }, '⟺'));
+    frame.append(
+      afterImg, beforeLayer, handle,
+      el('span', { class: 'cmp-tag cmp-tag-before' }, block.beforeLabel || 'Before'),
+      el('span', { class: 'cmp-tag cmp-tag-after' }, block.afterLabel || 'After')
+    );
+    wrap.append(frame);
+
+    let pos = 50;
+    const apply = () => { beforeLayer.style.width = pos + '%'; handle.style.left = pos + '%'; };
+    // pin the before image to the frame's pixel width so the clip reveals it in
+    // place (rather than squishing it as the clip narrows)
+    const sizeBefore = () => { beforeImg.style.width = frame.clientWidth + 'px'; };
+    const refresh = () => { sizeBefore(); apply(); };
+    if (afterImg.complete && afterImg.naturalWidth) refresh();
+    else afterImg.addEventListener('load', refresh, { once: true });
+    window.addEventListener('resize', sizeBefore);
+
+    let dragging = false;
+    const setFromX = (clientX) => {
+      const r = frame.getBoundingClientRect();
+      if (r.width) { pos = Math.max(0, Math.min(100, ((clientX - r.left) / r.width) * 100)); apply(); }
+    };
+    frame.addEventListener('pointerdown', (e) => { dragging = true; setFromX(e.clientX); try { frame.setPointerCapture(e.pointerId); } catch (_) {} e.preventDefault(); });
+    frame.addEventListener('pointermove', (e) => { if (dragging) setFromX(e.clientX); });
+    frame.addEventListener('pointerup', () => { dragging = false; });
+    frame.addEventListener('pointercancel', () => { dragging = false; });
+    handle.addEventListener('keydown', (e) => {
+      if (e.key === 'ArrowLeft') { pos = Math.max(0, pos - 2); apply(); e.preventDefault(); }
+      else if (e.key === 'ArrowRight') { pos = Math.min(100, pos + 2); apply(); e.preventDefault(); }
+    });
+    attachViewer(wrap, { zoomEl: null, label: 'comparison', comment: wholeBlockComment(ctx, blockId, 'comparison') });
+    return wrap;
+  }
+
   // ---------- viewer controls (zoom / fit / full-screen) ----------
   // Large diagrams get squeezed to the column width; these controls let the
   // user zoom (buttons or cmd/ctrl+wheel) and expand any visual block into a
@@ -1525,6 +1828,91 @@
     if (e.key === 'Escape' && fullOpen) exitFull();
   });
 
+  // Enter full-screen for a viewer container (shared by the toolbar button and
+  // the markdown reference-link → modal path).
+  function enterFull(container) {
+    if (fullOpen === container) return;
+    exitFull();
+    container.classList.add('blk-full');
+    document.body.classList.add('blk-full-open');
+    fullOpen = container;
+    const btn = container.querySelector('.blk-tools .tool-full');
+    if (btn) btn.textContent = '✕';
+    window.dispatchEvent(new Event('resize'));
+    if (container._rlyToolsSync) container._rlyToolsSync();
+    if (container._rlyZoom) container._rlyZoom.reapply();
+  }
+
+  // CSS.escape fallback for attribute-selector building from a block id/ref.
+  function cssEsc(s) {
+    return window.CSS && CSS.escape ? CSS.escape(String(s)) : String(s).replace(/["\\\]]/g, '\\$&');
+  }
+
+  // Open a block as a modal: full-screen its viewer if it has one (chart, image,
+  // diagram, table, compare, code…); otherwise scroll to it and flash. `host` is
+  // the .blk[data-block-id] wrapper. Returns true if it found something to show.
+  function openFullEl(host) {
+    if (!host) return false;
+    const viewer = host.classList.contains('blk-viewer') ? host : host.querySelector('.blk-viewer');
+    // Visuals open as a full-screen modal — context-safe (an overlay; × returns
+    // to the exact spot). Non-modal blocks (kpi/markdown/table-less) have no
+    // viewer, so we jump + highlight AND show a "↩ Back" button so the user can
+    // return after the jump — no lost context across the data↔question distance.
+    if (viewer && viewer._rlyTools) { enterFull(viewer); return true; }
+    const fromY = window.scrollY || window.pageYOffset || 0;
+    host.scrollIntoView({ behavior: 'smooth', block: 'center' });
+    host.classList.remove('rly-refflash');
+    void host.offsetWidth;
+    host.classList.add('rly-refflash');
+    setTimeout(() => host.classList.remove('rly-refflash'), 1200);
+    showRefBack(fromY);
+    return true;
+  }
+
+  // A floating "↩ Back" pill that returns to the pre-jump scroll position. Self-
+  // removes once the user is back near where they started, or after a timeout.
+  let refBackBtn = null;
+  function showRefBack(fromY) {
+    if (refBackBtn) refBackBtn.remove();
+    const btn = el('button', { class: 'rly-refback', type: 'button', title: 'Back to where you were' }, '↩ Back');
+    const cleanup = () => { btn.remove(); window.removeEventListener('scroll', onScroll); if (refBackBtn === btn) refBackBtn = null; };
+    const onScroll = () => { if (Math.abs((window.scrollY || 0) - fromY) < 120) cleanup(); };
+    btn.addEventListener('click', () => { window.scrollTo({ top: fromY, behavior: 'smooth' }); cleanup(); });
+    window.addEventListener('scroll', onScroll, { passive: true });
+    document.body.append(btn);
+    refBackBtn = btn;
+    setTimeout(() => { if (refBackBtn === btn) cleanup(); }, 12000);
+  }
+  function openFull(blockId) {
+    return openFullEl(document.querySelector('[data-block-id="' + cssEsc(blockId) + '"]'));
+  }
+
+  // Delegated handler for markdown reference links (data-rly-ref / data-rly-refid).
+  function initRefLinks() {
+    if (window.__relayRefLinksReady) return;
+    window.__relayRefLinksReady = true;
+    const open = (a) => {
+      const host = a.dataset.rlyRefid
+        ? document.querySelector('[data-block-id="' + cssEsc(a.dataset.rlyRefid) + '"]')
+        : document.querySelector('[data-block-ref="' + cssEsc(a.dataset.rlyRef) + '"]');
+      if (host) openFullEl(host);
+      else fileToast('Referenced visual not found on this board', 'err');
+    };
+    document.addEventListener('click', (e) => {
+      const a = e.target.closest ? e.target.closest('a.rly-reflink') : null;
+      if (!a) return;
+      e.preventDefault();
+      open(a);
+    });
+    document.addEventListener('keydown', (e) => {
+      if (e.key !== 'Enter' && e.key !== ' ' && e.key !== 'Spacebar') return;
+      const a = e.target.closest ? e.target.closest('a.rly-reflink') : null;
+      if (!a) return;
+      e.preventDefault();
+      open(a);
+    });
+  }
+
   // 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
@@ -1651,7 +2039,9 @@
         // (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;
+        // subtract the docked comment rail (≥980px) so the fit doesn't run under it
+        const railInset = (document.body.classList.contains('ann-rail-open') && window.innerWidth >= 980) ? 340 : 0;
+        const availW = window.innerWidth - railInset - 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';
@@ -1733,15 +2123,8 @@
     fullBtn.innerHTML = ICON_EXPAND;
     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();
-      if (container._rlyZoom) container._rlyZoom.reapply(); // lift any inline height cap
+      if (fullOpen === container) exitFull();
+      else enterFull(container);
     });
     tools.append(fullBtn);
 
@@ -1782,6 +2165,7 @@
   function renderBlock(block, ctx) {
     const blockId = block.id;
     const wrapper = el('div', { class: 'blk blk-' + block.type, 'data-block-id': blockId });
+    if (block.ref) wrapper.setAttribute('data-block-ref', block.ref);
     let inner = null;
     switch (block.type) {
       case 'markdown': {
@@ -1834,6 +2218,18 @@
         inner = renderPalette(block, ctx, blockId);
         wrapper.append(inner);
         break;
+      case 'kpi':
+        inner = renderKpi(block, ctx, blockId);
+        wrapper.append(inner);
+        break;
+      case 'typography':
+        inner = renderTypography(block, ctx, blockId);
+        wrapper.append(inner);
+        break;
+      case 'compare':
+        inner = renderCompare(block, ctx, blockId);
+        wrapper.append(inner);
+        break;
       default:
         wrapper.append(el('div', { class: 'blk-error' }, 'Unknown block type: ' + esc(String(block.type))));
     }
@@ -1919,6 +2315,7 @@
     });
   }
   initFileLinks();
+  initRefLinks();
 
-  window.RelayBlocks = { render, onThemeChange, renderMarkdown };
+  window.RelayBlocks = { render, onThemeChange, renderMarkdown, openFull };
 })();