@khanglvm/relay 0.12.3 → 0.13.0

package/src/ui/app.js

@@ -212,8 +212,41 @@
       }
     }
   }
+  // Coerce any prior rank value (draft/default) into a complete, deduped
+  // permutation of the option values: keep the known ones in their given order,
+  // then append any options the prior list missed (in authored order).
+  function seedRankOrder(q, prior) {
+    const opts = (q.options || []).map((o) => o.value);
+    const arr = Array.isArray(prior) ? prior : [];
+    const order = arr.filter((v, i) => opts.includes(v) && arr.indexOf(v) === i);
+    for (const v of opts) if (!order.includes(v)) order.push(v);
+    return order;
+  }
+  // Allocate: a complete map {optionValue: number≥0}, seeded from a prior/default.
+  function seedAllocate(q, prior) {
+    const m = prior && typeof prior === 'object' && !Array.isArray(prior) ? prior : {};
+    const out = {};
+    for (const o of q.options || []) out[o.value] = Math.max(0, Number(m[o.value]) || 0);
+    return out;
+  }
+  // Checklist: keep only {knownOption: knownStatus} entries from a prior/default.
+  function seedChecklist(q, prior) {
+    const m = prior && typeof prior === 'object' && !Array.isArray(prior) ? prior : {};
+    const optVals = new Set((q.options || []).map((o) => o.value));
+    const stVals = new Set((q.statuses || []).map((s) => s.value));
+    const out = {};
+    for (const k of Object.keys(m)) if (optVals.has(k) && stVals.has(m[k])) out[k] = m[k];
+    return out;
+  }
+
   if (initialPrefill) seedFromPrefill(initialPrefill);
   else for (const q of QS) if (q.default !== undefined) state.answers[q.id] = q.default;
+  // Rank questions always carry a full, valid permutation of their option values
+  // (from a draft/default if present, else the authored order), so a never-touched
+  // rank still returns a meaningful ordering.
+  for (const q of QS) if (q.type === 'rank') state.answers[q.id] = seedRankOrder(q, state.answers[q.id]);
+  for (const q of QS) if (q.type === 'allocate') state.answers[q.id] = seedAllocate(q, state.answers[q.id]);
+  for (const q of QS) if (q.type === 'checklist') state.answers[q.id] = seedChecklist(q, state.answers[q.id]);
   // If the local mirror was newer than the server (or the server had nothing),
   // the in-memory state now holds input the server hasn't seen — flush it once
   // the rest of the app is wired (see the post-init flush near the heartbeat).
@@ -241,6 +274,18 @@
         return v === 'yes' || v === 'no' ? v : undefined;
       case 'scale':
         return typeof v === 'number' ? v : undefined;
+      case 'rank':
+        // always a full, valid permutation (seeded below) → always answered
+        return Array.isArray(v) && v.length ? [...v] : undefined;
+      case 'checklist': {
+        const m = v && typeof v === 'object' && !Array.isArray(v) ? v : {};
+        return Object.keys(m).length ? { ...m } : undefined;
+      }
+      case 'allocate': {
+        const m = v && typeof v === 'object' && !Array.isArray(v) ? v : {};
+        const sum = Object.values(m).reduce((a, n) => a + (Number(n) || 0), 0);
+        return sum > 0 ? { ...m } : undefined;
+      }
       default: {
         const t = typeof v === 'string' ? v.trim() : '';
         return t || undefined;
@@ -721,6 +766,144 @@
     return row;
   }
 
+  // Reorderable priority list. The user drags an item or uses ↑/↓; the answer is
+  // the ordered array of option values (highest priority first). state.answers[q.id]
+  // is kept a full, valid permutation by seedRankOrder so it's always submittable.
+  function controlRank(q) {
+    const wrap = el('div', { class: 'rank' });
+    const byVal = new Map(q.options.map((o) => [o.value, o]));
+    let dragFrom = null;
+    function move(from, to) {
+      const arr = state.answers[q.id];
+      if (!Array.isArray(arr) || to < 0 || to >= arr.length || from === to) return;
+      const [x] = arr.splice(from, 1);
+      arr.splice(to, 0, x);
+      paint();
+      clearErr(q.id);
+      scheduleSave();
+    }
+    function paint() {
+      wrap.replaceChildren();
+      const order = state.answers[q.id] || [];
+      order.forEach((val, i) => {
+        const o = byVal.get(val);
+        if (!o) return;
+        const up = el('button', { type: 'button', class: 'rank-btn', title: 'Move up', 'aria-label': `Move "${o.label}" up` }, '↑');
+        const down = el('button', { type: 'button', class: 'rank-btn', title: 'Move down', 'aria-label': `Move "${o.label}" down` }, '↓');
+        up.disabled = i === 0;
+        down.disabled = i === order.length - 1;
+        up.addEventListener('click', () => move(i, i - 1));
+        down.addEventListener('click', () => move(i, i + 1));
+        const item = el('div', { class: 'rank-item', draggable: 'true' },
+          el('span', { class: 'rank-badge', 'aria-hidden': 'true' }, String(i + 1)),
+          el('div', { class: 'rank-body' },
+            el('div', { class: 'ol' }, o.label),
+            o.description ? el('div', { class: 'od' }, o.description) : null),
+          el('div', { class: 'rank-ctrls' }, up, down)
+        );
+        item.addEventListener('dragstart', (e) => {
+          dragFrom = i; item.classList.add('dragging');
+          try { e.dataTransfer.effectAllowed = 'move'; e.dataTransfer.setData('text/plain', String(i)); } catch (_) {}
+        });
+        item.addEventListener('dragend', () => { dragFrom = null; item.classList.remove('dragging'); });
+        item.addEventListener('dragover', (e) => { if (dragFrom !== null) { e.preventDefault(); item.classList.add('drop-into'); } });
+        item.addEventListener('dragleave', () => item.classList.remove('drop-into'));
+        item.addEventListener('drop', (e) => {
+          e.preventDefault();
+          const from = dragFrom; dragFrom = null;
+          if (from !== null && from !== i) move(from, i);
+        });
+        wrap.append(item);
+      });
+    }
+    paint();
+    return wrap;
+  }
+
+  // Checklist: each option is a row with a segmented status control (Pass/Fail/
+  // N/A by default). Answer is a map {optionValue: statusValue} for set rows.
+  function controlChecklist(q) {
+    const wrap = el('div', { class: 'checklist' });
+    const cur = () => (state.answers[q.id] && typeof state.answers[q.id] === 'object' && !Array.isArray(state.answers[q.id])
+      ? state.answers[q.id]
+      : (state.answers[q.id] = {}));
+    for (const o of q.options) {
+      const seg = el('div', { class: 'chk-seg' });
+      const buttons = [];
+      for (const s of q.statuses) {
+        const b = el('button', { type: 'button', class: 'chk-status' + (s.tone ? ' tone-' + s.tone : '') }, s.label);
+        if (cur()[o.value] === s.value) b.classList.add('sel');
+        b.addEventListener('click', () => {
+          const m = cur();
+          if (m[o.value] === s.value) delete m[o.value];
+          else m[o.value] = s.value;
+          for (const x of buttons) x.btn.classList.toggle('sel', m[o.value] === x.val);
+          clearErr(q.id);
+          scheduleSave();
+        });
+        buttons.push({ btn: b, val: s.value });
+        seg.append(b);
+      }
+      wrap.append(el('div', { class: 'chk-row' },
+        el('div', { class: 'chk-body' },
+          el('div', { class: 'ol' }, o.label),
+          o.description ? el('div', { class: 'od' }, o.description) : null),
+        seg
+      ));
+    }
+    return wrap;
+  }
+
+  // Allocate: distribute q.total across the options with per-option sliders; a
+  // live total bar shows the running sum / remaining / overage. Answer is a map
+  // {optionValue: number}; an all-zero allocation submits as unanswered.
+  function controlAllocate(q) {
+    const wrap = el('div', { class: 'allocate' });
+    const total = q.total || 100;
+    const unit = q.unit ? ' ' + q.unit : '';
+    const cur = () => (state.answers[q.id] = seedAllocate(q, state.answers[q.id]));
+    const sumEl = el('span', { class: 'alloc-sum' });
+    const fill = el('div', { class: 'alloc-bar-fill' });
+    const nums = [];
+    const refresh = () => {
+      const m = cur();
+      const sum = (q.options || []).reduce((a, o) => a + (Number(m[o.value]) || 0), 0);
+      const tail = sum > total ? ` (over by ${sum - total})` : sum < total ? ` (${total - sum} left)` : ' ✓';
+      sumEl.textContent = `${sum} / ${total}${unit}${tail}`;
+      sumEl.classList.toggle('over', sum > total);
+      sumEl.classList.toggle('exact', sum === total);
+      fill.style.width = Math.min(100, (sum / total) * 100) + '%';
+      fill.classList.toggle('over', sum > total);
+      for (const n of nums) n.el.textContent = String(m[n.value] || 0);
+    };
+    for (const o of q.options) {
+      const m = cur();
+      const range = el('input', { type: 'range', min: '0', max: String(total), step: '1', class: 'alloc-range', 'aria-label': o.label });
+      range.value = String(m[o.value] || 0);
+      const num = el('span', { class: 'alloc-num' }, String(m[o.value] || 0));
+      range.addEventListener('input', () => {
+        cur()[o.value] = Number(range.value) || 0;
+        refresh();
+        clearErr(q.id);
+        scheduleSave();
+      });
+      nums.push({ value: o.value, el: num });
+      wrap.append(el('div', { class: 'alloc-row' },
+        el('div', { class: 'alloc-rowhead' },
+          el('div', { class: 'ol' }, o.label),
+          num),
+        range,
+        o.description ? el('div', { class: 'od' }, o.description) : null
+      ));
+    }
+    wrap.append(el('div', { class: 'alloc-total' },
+      el('div', { class: 'alloc-bar' }, fill),
+      el('div', { class: 'alloc-sumwrap' }, 'Total: ', sumEl)
+    ));
+    refresh();
+    return wrap;
+  }
+
   function controlText(q, multiline) {
     const input = multiline
       ? el('textarea', { placeholder: q.placeholder || '' })
@@ -734,35 +917,73 @@
     return input;
   }
 
-  // Normalize any CSS color to the #rrggbb the native <input type=color> needs.
-  function toHex6(c) {
-    const s = String(c || '').trim();
+  // Resolve ANY CSS color (named / rgb() / hsl() / hex) to #rrggbb for the
+  // native <input type=color>, using the browser's own parser — multi color-
+  // system support with no library. Returns null for an unparseable color.
+  function cssColorToHex(str) {
+    const s = String(str || '').trim();
     let m = /^#?([0-9a-fA-F]{6})$/.exec(s);
     if (m) return '#' + m[1].toLowerCase();
     m = /^#?([0-9a-fA-F]{3})$/.exec(s);
     if (m) return '#' + m[1].split('').map((x) => x + x).join('').toLowerCase();
-    return '#000000';
+    try {
+      const d = document.createElement('div');
+      d.style.color = '';
+      d.style.color = s;
+      if (!d.style.color) return null; // browser rejected it → invalid color
+      d.style.display = 'none';
+      document.body.appendChild(d);
+      const rgb = getComputedStyle(d).color;
+      document.body.removeChild(d);
+      const mm = rgb.match(/(\d+)[,\s]+(\d+)[,\s]+(\d+)/);
+      if (!mm) return null;
+      const h = (n) => Math.max(0, Math.min(255, Number(n))).toString(16).padStart(2, '0');
+      return '#' + h(mm[1]) + h(mm[2]) + h(mm[3]);
+    } catch { return null; }
   }
+  function toHex6(c) { return cssColorToHex(c) || '#000000'; }
+
   function controlColor(q) {
     const wrap = el('div', { class: 'colorpick' });
     const init = (typeof state.answers[q.id] === 'string' && state.answers[q.id]) || (typeof q.default === 'string' ? q.default : '');
     const swatch = el('input', { type: 'color', class: 'colorswatch' });
-    const hex = el('input', { type: 'text', class: 'colorhex', placeholder: q.placeholder || '#rrggbb', spellcheck: 'false', autocapitalize: 'off' });
+    const hex = el('input', { type: 'text', class: 'colorhex', placeholder: q.placeholder || '#rrggbb / rgb() / name', spellcheck: 'false', autocapitalize: 'off' });
     swatch.value = toHex6(init || '#888888');
     if (init) { hex.value = init; state.answers[q.id] = init; }
-    const set = (val) => { state.answers[q.id] = val; clearErr(q.id); scheduleSave(); };
+    let syncPaletteSel = () => {};
+    const set = (val) => { state.answers[q.id] = val; syncPaletteSel(); clearErr(q.id); scheduleSave(); };
     swatch.addEventListener('input', () => { hex.value = swatch.value; set(swatch.value); });
-    hex.addEventListener('input', () => { const v = hex.value.trim(); if (/^#?([0-9a-fA-F]{3}|[0-9a-fA-F]{6})$/.test(v)) swatch.value = toHex6(v); set(v); });
+    hex.addEventListener('input', () => { const v = hex.value.trim(); const h = cssColorToHex(v); if (h) swatch.value = h; set(v); });
+
+    // "Pick from a palette" — labeled swatch cards. Click selects that color as
+    // the answer; each card is registered for annotation (per-color comments).
+    if (Array.isArray(q.palette) && q.palette.length) {
+      const grid = el('div', { class: 'colorpalette' });
+      const cards = [];
+      for (const p of q.palette) {
+        const labelled = p.label && p.label !== p.value;
+        const card = el('button', { type: 'button', class: 'colorpal-sw', style: 'background:' + p.value, title: (labelled ? p.label + ' · ' : '') + p.value });
+        if (labelled) card.append(el('span', { class: 'colorpal-label' }, p.label));
+        card.addEventListener('click', () => { const h = cssColorToHex(p.value); if (h) swatch.value = h; hex.value = p.value; set(p.value); });
+        if (Annotate) Annotate.register(card, { blockId: null, questionId: q.id, target: { kind: 'swatch', label: (labelled ? p.label + ' · ' : '') + p.value } });
+        cards.push({ card, val: p.value });
+        grid.append(card);
+      }
+      syncPaletteSel = () => { for (const c of cards) c.card.classList.toggle('sel', state.answers[q.id] === c.val); };
+      wrap.append(grid);
+    }
+
     wrap.append(el('div', { class: 'colorrow' }, swatch, hex));
     if (Array.isArray(q.presets) && q.presets.length) {
       const presets = el('div', { class: 'colorpresets' });
       for (const c of q.presets) {
         const b = el('button', { type: 'button', class: 'colorpreset', style: 'background:' + c, title: c });
-        b.addEventListener('click', () => { swatch.value = toHex6(c); hex.value = c; set(c); });
+        b.addEventListener('click', () => { const h = cssColorToHex(c); if (h) swatch.value = h; hex.value = c; set(c); });
         presets.append(b);
       }
       wrap.append(presets);
     }
+    syncPaletteSel();
     return wrap;
   }
 
@@ -832,6 +1053,9 @@
     else if (q.type === 'yesno') control.append(segButtons(q, ['yes', 'no'], ['Yes', 'No']));
     else if (q.type === 'scale') control.append(controlScale(q));
     else if (q.type === 'color') control.append(controlColor(q));
+    else if (q.type === 'rank') control.append(controlRank(q));
+    else if (q.type === 'checklist') control.append(controlChecklist(q));
+    else if (q.type === 'allocate') control.append(controlAllocate(q));
     else control.append(controlText(q, q.type === 'textarea'));
     card.append(control);
     if (q.note) {

package/src/ui/blocks.css

@@ -33,6 +33,7 @@
 .blk-markdown .md h2 { font-size: 1.2rem; }
 .blk-markdown .md h3 { font-size: 1.05rem; }
 .blk-markdown .md p { margin: 10px 0; }
+.blk-markdown .md img.md-img { max-width: 100%; height: auto; border-radius: 8px; margin: 8px 0; }
 .blk-markdown .md a { color: var(--accent); text-decoration: none; border-bottom: 1px solid transparent; transition: border-color 150ms var(--ease); }
 .blk-markdown .md a:hover { border-bottom-color: var(--accent); }
 .blk-markdown .md strong { font-weight: 600; }
@@ -237,6 +238,36 @@
 }
 .blk-difftoggle:hover { color: var(--accent); border-color: var(--accent); }
 
+/* multi-file diff: per-file filename header + a jump bar of file chips */
+.diff-file + .diff-file { margin-top: 6px; }
+.diff-filehead {
+  position: sticky; top: 0; z-index: 1;
+  padding: 5px 12px; font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace;
+  font-size: 0.76rem; color: var(--fg-2);
+  background: var(--card); border-bottom: 1px solid var(--border);
+}
+.diff-files {
+  display: flex; flex-wrap: wrap; gap: 6px;
+  padding: 8px 0;
+}
+.diff-file-chip {
+  cursor: pointer; font: inherit; font-size: 0.72rem;
+  font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace;
+  color: var(--fg-2); background: var(--bg-sunken);
+  border: 1px solid var(--border); border-radius: 6px; padding: 3px 8px;
+  max-width: 260px; overflow: hidden; text-overflow: ellipsis; white-space: nowrap;
+  transition: color 150ms var(--ease), border-color 150ms var(--ease);
+}
+.diff-file-chip:hover { color: var(--accent); border-color: var(--accent); }
+
+/* clickable line-number gutter: hover a number to comment on that line */
+.blk-gutter-c { padding: 14px 0; }
+.blk-gutter-c .blk-gutterline {
+  padding: 0 10px 0 14px; cursor: pointer; position: relative;
+  transition: background 120ms var(--ease), color 120ms var(--ease);
+}
+.blk-gutter-c .blk-gutterline:hover { background: var(--accent-soft); color: var(--accent); }
+
 /* ---------- video (iframe embed / local stream / direct URL) ---------- */
 .blk-videowrap { margin: 0; }
 .blk-video, .blk-video-embed {
@@ -277,6 +308,23 @@
 .blk-table tbody tr:hover { background: var(--bg-sunken); }
 .blk-table tbody tr:last-child td { border-bottom: 0; }
 
+/* table toolbar: live filter box + CSV export (opt-in via filterable/exportable) */
+.blk-tablebar { display: flex; align-items: center; gap: 8px; margin-bottom: 8px; }
+.blk-tablefilter {
+  flex: 1; min-width: 0; max-width: 280px;
+  padding: 6px 10px; font: inherit; font-size: 0.85rem;
+  background: var(--bg-sunken); color: var(--fg);
+  border: 1px solid var(--border); border-radius: 8px;
+}
+.blk-tablefilter:focus { outline: none; border-color: var(--accent); }
+.blk-tableexport {
+  flex: none; padding: 6px 12px; font: inherit; font-size: 0.8rem; cursor: pointer;
+  background: var(--card); color: var(--fg-2);
+  border: 1px solid var(--border-strong); border-radius: 8px;
+  transition: border-color 150ms var(--ease), color 150ms var(--ease);
+}
+.blk-tableexport:hover { border-color: var(--accent); color: var(--accent); }
+
 /* ---------- chart ---------- */
 /* NO height here: renderChart always sets the inline height, and this class
    also lands on the outer .blk.blk-chart dispatch wrapper — a CSS height
@@ -316,7 +364,7 @@
 /* ---------- mermaid ---------- */
 .blk-mermaid {
   overflow: auto;
-  max-height: 1200px;
+  max-height: 800px;
   text-align: center;
 }
 .blk-mermaid svg {
@@ -392,7 +440,7 @@
 /* ---------- graphviz (offline, vendored Viz.js) ---------- */
 .blk-graphviz {
   overflow: auto;
-  max-height: 1200px;
+  max-height: 800px;
   text-align: center;
   /* graphviz draws on its own white canvas; frame it as a deliberate card so
      it reads intentional in dark mode instead of a stray white rectangle */
@@ -411,7 +459,7 @@
 /* ---------- plantuml (server-rendered image) ---------- */
 .blk-plantuml {
   overflow: auto;
-  max-height: 1200px;
+  max-height: 800px;
   text-align: center;
   background: #fff;
   border: 1px solid var(--border);
@@ -426,7 +474,7 @@
 /* ---------- image ---------- */
 .blk-imagewrap {
   overflow: auto;
-  max-height: 1200px;
+  max-height: 800px;
   border: 1px solid var(--border);
   border-radius: 10px;
   background: var(--bg-sunken);
@@ -483,6 +531,13 @@ body.blk-full-open { overflow: hidden; }
   background: var(--card); border-bottom: 1px solid var(--border);
   z-index: 51;
 }
+/* When the comment rail is docked open (≥980px), inset the full-screen overlay
+   AND its toolbar from the right by the rail width — otherwise the overlay slides
+   under the (higher z-index) rail and its close/comment buttons get hidden. */
+@media (min-width: 980px) {
+  body.ann-rail-open .blk-full { right: 340px; }
+  body.ann-rail-open .blk-full > .blk-tools { right: 340px; }
+}
 .blk-chart.blk-full {
   height: 100vh !important; width: auto !important;
   padding: 44px 16px 16px;
@@ -585,3 +640,108 @@ body.blk-full-open { overflow: hidden; }
 .pal-tag.tone-nature { background: #EAF3DE; color: #3B6D11; }
 .pal-tag.tone-bold { background: #FBEAF0; color: #72243E; }
 .pal-tag.tone-digital { background: #EEEDFE; color: #3C3489; }
+
+/* ---------- kpi (stat cards) ---------- */
+.blk-kpi { margin: 4px 0; }
+.kpi-title { font-weight: 600; color: var(--fg-2); margin-bottom: 10px; }
+.kpi-grid { display: grid; grid-template-columns: repeat(auto-fit, minmax(160px, 1fr)); gap: 12px; }
+.kpi-card {
+  border: 1px solid var(--border); border-radius: 12px;
+  background: var(--card); padding: 14px 16px;
+}
+.kpi-label { color: var(--muted); font-size: 0.82rem; }
+.kpi-value { font-family: var(--serif); font-size: 1.8rem; line-height: 1.1; margin: 4px 0 2px; letter-spacing: -0.02em; }
+.kpi-delta { font-size: 0.85rem; font-weight: 600; color: var(--fg-2); }
+.kpi-delta.kpi-up { color: var(--ok); }
+.kpi-delta.kpi-down { color: var(--danger); }
+.kpi-sub { color: var(--muted); font-size: 0.78rem; margin-top: 2px; }
+
+/* ---------- typography (specimens) ---------- */
+.blk-typography { margin: 4px 0; }
+.typo-title { font-weight: 600; color: var(--fg-2); margin-bottom: 10px; }
+.typo-row { padding: 10px 0; border-bottom: 1px solid var(--border); }
+.typo-row:last-child { border-bottom: 0; }
+.typo-meta { color: var(--muted); font-size: 0.74rem; text-transform: uppercase; letter-spacing: 0.04em; margin-bottom: 4px; }
+.typo-sample { color: var(--fg); font-size: 1.1rem; line-height: 1.3; overflow-wrap: anywhere; }
+
+/* ---------- compare (before/after slider) ---------- */
+.blk-comparewrap { margin: 4px 0; }
+.cmp-frame {
+  position: relative; overflow: hidden; user-select: none; touch-action: none;
+  border: 1px solid var(--border); border-radius: 12px; line-height: 0;
+  cursor: ew-resize;
+}
+.cmp-img { display: block; width: 100%; height: auto; }
+.cmp-before { position: absolute; inset: 0; width: 50%; overflow: hidden; }
+.cmp-before .cmp-img-before { position: absolute; left: 0; top: 0; height: 100%; max-width: none; }
+.cmp-handle {
+  position: absolute; top: 0; bottom: 0; left: 50%; width: 2px;
+  background: #fff; box-shadow: 0 0 0 1px rgba(0,0,0,0.25); transform: translateX(-1px);
+}
+.cmp-handle-grip {
+  position: absolute; top: 50%; left: 50%; transform: translate(-50%, -50%);
+  width: 30px; height: 30px; border-radius: 50%;
+  background: #fff; color: #333; box-shadow: 0 1px 4px rgba(0,0,0,0.35);
+  display: grid; place-items: center; font-size: 13px; cursor: ew-resize;
+}
+.cmp-handle:focus-visible { outline: 2px solid var(--accent); outline-offset: 2px; }
+.cmp-tag {
+  position: absolute; bottom: 10px; padding: 3px 8px; border-radius: 6px;
+  font-size: 0.72rem; line-height: 1.4; color: #fff; background: rgba(0,0,0,0.55);
+  pointer-events: none;
+}
+.cmp-tag-before { left: 10px; }
+.cmp-tag-after { right: 10px; }
+
+/* ---------- reference links (open a visual in a modal) ---------- */
+.rly-reflink {
+  display: inline-flex; align-items: center; gap: 0.3em;
+  color: var(--accent); cursor: pointer; text-decoration: none;
+  border-bottom: 1px solid transparent; border-radius: 4px;
+  transition: border-color 150ms var(--ease);
+}
+.rly-reflink:hover { border-bottom-color: var(--accent); }
+.rly-reflink:focus-visible { outline: 2px solid var(--accent); outline-offset: 2px; }
+.rly-reflink-ico {
+  flex: none; width: 0.85em; height: 0.85em;
+  border: 1.6px solid currentColor; border-radius: 50%;
+  position: relative;
+}
+.rly-reflink-ico::after {
+  content: ''; position: absolute; width: 0.42em; height: 1.6px;
+  background: currentColor; right: -0.28em; bottom: 0.02em;
+  transform: rotate(45deg); transform-origin: left center;
+}
+/* floating "↩ Back" pill shown after a reference jumps to a non-modal block */
+.rly-refback {
+  position: fixed; left: 18px; bottom: 18px; z-index: 60;
+  display: inline-flex; align-items: center; gap: 6px;
+  padding: 8px 14px; font: inherit; font-size: 0.85rem; font-weight: 500;
+  color: var(--accent-fg); background: var(--accent);
+  border: 0; border-radius: 999px; cursor: pointer;
+  box-shadow: var(--shadow-lift);
+  animation: rly-refback-in 180ms var(--ease);
+}
+.rly-refback:hover { filter: brightness(1.06); }
+@keyframes rly-refback-in { from { opacity: 0; transform: translateY(6px); } to { opacity: 1; transform: none; } }
+/* brief highlight when a reference jumps to a non-modal block */
+.rly-refflash { animation: rly-refflash 1.2s var(--ease); }
+@keyframes rly-refflash {
+  0%, 100% { box-shadow: 0 0 0 0 transparent; }
+  20% { box-shadow: 0 0 0 3px var(--accent); }
+}
+
+/* ---------- image coordinate pins (block.pins) ---------- */
+.blk-img-pinnable { cursor: crosshair; }
+.blk-imgpins { position: absolute; inset: 0; pointer-events: none; }
+.blk-imgpin {
+  position: absolute; transform: translate(-50%, -50%);
+  min-width: 22px; height: 22px; padding: 0 6px;
+  border-radius: 11px; border: 2px solid #fff;
+  background: var(--accent); color: #fff;
+  font: inherit; font-size: 0.72rem; font-weight: 600; line-height: 1;
+  cursor: pointer; pointer-events: auto;
+  box-shadow: 0 1px 4px rgba(0,0,0,0.35);
+  display: grid; place-items: center;
+}
+.blk-imgpin:hover { filter: brightness(1.08); }