@khanglvm/relay 0.5.4 → 0.6.0

package/README.md

@@ -92,6 +92,22 @@ Node ≥ 18; Chart.js / Mermaid / Graphviz are vendored and lazy-loaded offline.
 npm test     # zero-dep smoke tests (spawns real servers, fake-submits)
 ```
 
+## Changelog
+
+### 0.6.0 — comment on anything
+- **Comment on any part of a custom-HTML mockup.** Hover any element — a heading,
+  a button, a card, the price — and a pin appears to leave an inline note. No
+  setup needed; the agent writes zero annotation code. Want to scope it? Mark
+  specific elements with `data-relay-annotate="label"`.
+- **Radio questions can carry a note.** Pick an option *and* say why, in one
+  optional field — now shown by default (set `"note": false` to hide it).
+- **Edge-to-edge fullscreen** for charts and HTML mockups, with the toolbar
+  pinned to the top while you scroll.
+- The board **title and intro are commentable** too.
+
+### 0.5.0
+- Visual answer options, image blocks, viewer redesign, adoption rules.
+
 ## Migration from quest-board
 
 relay was formerly `@khanglvm/quest-board` (CLI: `qbd`) — that package is

package/docs/AGENT.md

@@ -6,9 +6,10 @@ then **wait for them to click Submit** and read the answers as JSON from stdout.
 No "type 'done' in the terminal", no hand-rolled HTML+server.
 
 **Tell the user** at the start of your intro text that they can hover chart
-points, diagram nodes, and table cells to leave comments, and select text in
-markdown blocks to annotate — their comments come back in `result.annotations`
-alongside their answers. Treat annotations as first-class feedback.
+points, diagram nodes, table cells, and any element of a custom-HTML block to
+leave comments, and select text in markdown blocks to annotate — their comments
+come back in `result.annotations` alongside their answers. Treat annotations as
+first-class feedback.
 
 Everything machine-relevant is on **stdout as JSON**; human-facing logs go to
 stderr. Exit codes: `0` submitted/acknowledged · `2` timeout · `3` cancelled ·
@@ -137,7 +138,9 @@ boolean/bool/yn→yesno, input→text, longtext→textarea, rating/likert→scal
 
 Unanswered questions are absent from `answers` and listed in `skipped`.
 Questions with `"note": true` show a small optional free-text field; non-empty
-notes come back in `notes` keyed by question id. On `timeout`/`cancelled`, a
+notes come back in `notes` keyed by question id. **`single` (radio) questions
+show this note by default** so the user can qualify their pick — set
+`"note": false` to hide it. On `timeout`/`cancelled`, a
 `draft` field carries the autosaved partial answers and any annotations written
 so far.
 
@@ -295,23 +298,40 @@ Rules of thumb:
   background/text match the user's current theme. **Full documents** are served
   verbatim and receive a `?theme=light|dark` query param on theme toggle.
 
-### kit.js — make iframe elements annotatable
+### Custom HTML is hover-commentable automatically
 
-Load `/kit.js` inside your custom HTML iframe to let users comment on specific
-elements:
+Every custom-HTML block is annotatable out of the box — relay injects a tiny
+runtime that lets the user **hover any meaningful element** (headings,
+paragraphs, list items, buttons, images, cards, table cells…) to get a comment
+pin, exactly like the rest of the board. You don't have to do anything. Comments
+come back in `result.annotations` with `target.kind = "html-element"`, a stable
+`target.ref` (the element), and a `target.label` derived from the element.
+
+Reach for the controls below only when you want to **scope or label** what's
+annotatable — typically for an interactive prototype where blanket hover targets
+would get in the way:
+
+**Declarative signal (preferred)** — mark the elements you want commented. Any
+signal present switches the auto-pick off, so only your marked elements are
+annotatable:
+
+```html
+<button data-relay-annotate="Primary CTA" data-relay-detail="checkout flow">Buy now</button>
+<section data-relay-annotate="Pricing table">…</section>
+```
+
+**Imperative** — same effect from script (needs `/kit.js`, which relay also
+auto-loads):
 
 ```html
 <script src="/kit.js"></script>
 <script>
   relayKit.commentable(document.getElementById('chart'), 'Revenue chart', 'Q1 2026');
-  relayKit.commentable(document.getElementById('hero-cta'), 'CTA button');
 </script>
 ```
 
-`relayKit.commentable(el, label, detail?)` — outlines `el` on hover; a click
-opens the annotation popover in the parent page anchored to the element.
-Annotations come back in `result.annotations` with `target.kind = "html-element"`,
-`target.label`, and (if provided) `target.detail`.
+**Opt out** of element annotation for a block with `data-relay-annotate="off"`
+on `<html>` or `<body>`.
 
 ## Annotations
 
@@ -349,7 +369,7 @@ intro. Annotations are autosaved with the draft and returned in the final result
 | `graphviz-node` | `nodeId`, `text` | clicking a Graphviz node or edge |
 | `table-cell` | `row` (0-based), `col` (column key), `value` | clicking a table cell |
 | `text` | `quote`, `prefix` (≤30 chars before), `suffix` (≤30 after) | selecting text in a markdown block |
-| `html-element` | `label`, `detail?` | clicking a `relayKit.commentable()` element |
+| `html-element` | `ref`, `label`, `detail?` | hovering any element in a custom-HTML block (auto), or a `data-relay-annotate` / `relayKit.commentable()` element |
 | `image` | `label` | clicking a PlantUML diagram or an image block |
 
 Read annotations as first-class feedback — they often carry the sharpest insight

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@khanglvm/relay",
-  "version": "0.5.4",
+  "version": "0.6.0",
   "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/skills/relay/SKILL.md

@@ -93,7 +93,8 @@ submit with unanswered questions (returned in `skipped`) unless
 
 Set `"note": true` on a question to add a small optional free-text field under
 it — use when the user may want to qualify their choice. Returned as
-`result.notes[questionId]`.
+`result.notes[questionId]`. `single` (radio) questions include this note by
+default (so a pick can carry a comment); set `"note": false` to hide it.
 
 Quick one-liners without a spec file:
 
@@ -153,8 +154,12 @@ pass `"server"` for a self-hosted instance. Legacy `"html"` / `"htmlFile"` /
 
 ## Annotations
 
-Users can hover chart points, diagram nodes (mermaid + graphviz), table cells, or
-select text in markdown to leave inline comments. Always mention this in the board intro.
+Users can hover chart points, diagram nodes (mermaid + graphviz), table cells,
+any element of a custom-HTML block, or select text in markdown to leave inline
+comments. Custom HTML is hover-commentable automatically — to scope/label what's
+annotatable, mark elements with `data-relay-annotate="Label"` (any signal turns
+the auto-pick off); opt a block out with `data-relay-annotate="off"`. Always
+mention annotation in the board intro.
 
 `result.annotations` is an array of:
 

package/src/server.js

@@ -230,16 +230,35 @@ function sendFromDir(res, dir, name, contentType) {
   return true;
 }
 
+// Loaded into every custom-HTML iframe so users can hover any element to leave a
+// comment (relayKit.annotate.auto). Idempotent with an author-added /kit.js, and
+// a no-op when the author opts out via data-relay-annotate="off".
+const ANNOTATE_BOOTSTRAP =
+  '<script>(function(){function go(){try{window.relayKit&&window.relayKit.annotate&&window.relayKit.annotate.auto();}catch(e){}}' +
+  'if(window.relayKit&&window.relayKit.annotate)return go();' +
+  "var s=document.createElement('script');s.src='/kit.js';s.onload=go;s.onerror=go;" +
+  '(document.head||document.documentElement).appendChild(s);})();<\/script>';
+
+// Insert a snippet right before </body> (else </html>, else append).
+function injectBeforeBodyEnd(html, snippet) {
+  const lower = html.toLowerCase();
+  let idx = lower.lastIndexOf('</body>');
+  if (idx === -1) idx = lower.lastIndexOf('</html>');
+  if (idx === -1) return html + snippet;
+  return html.slice(0, idx) + snippet + html.slice(idx);
+}
+
 // Custom-HTML fragments (no <html> tag) get wrapped in a minimal document that
 // matches the user's theme, so e.g. "<b>hi</b>" doesn't paint a stark white
 // block in dark mode. Full documents are served verbatim — their authors can
-// read the ?theme=light|dark query param themselves.
+// read the ?theme=light|dark query param themselves. Either way the annotate
+// bootstrap is injected so every element is hover-commentable.
 function wrapFragment(content, theme) {
-  if (/<html[\s>]/i.test(content)) return content;
+  if (/<html[\s>]/i.test(content)) return injectBeforeBodyEnd(content, ANNOTATE_BOOTSTRAP);
   const dark = theme === 'dark';
   const bg = dark ? '#282624' : '#ffffff';
   const fg = dark ? '#edeae4' : '#1c1b19';
-  return `<!doctype html><html><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1"><style>:root{color-scheme:${dark ? 'dark' : 'light'}}body{margin:12px;font:14px/1.5 -apple-system,BlinkMacSystemFont,"Segoe UI",Roboto,"Helvetica Neue",Arial,sans-serif;background:${bg};color:${fg}}</style></head><body>${content}</body></html>`;
+  return `<!doctype html><html><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1"><style>:root{color-scheme:${dark ? 'dark' : 'light'}}body{margin:12px;font:14px/1.5 -apple-system,BlinkMacSystemFont,"Segoe UI",Roboto,"Helvetica Neue",Arial,sans-serif;background:${bg};color:${fg}}</style></head><body>${content}${ANNOTATE_BOOTSTRAP}</body></html>`;
 }
 
 function readBody(req, limit = 5 * 1024 * 1024) {

package/src/spec.js

@@ -332,7 +332,10 @@ export function normalizeSpec(raw, { cwd = process.cwd() } = {}) {
       label,
       description: asStr(rq.description),
       required: rq.required === true,
-      note: rq.note === true,
+      // Radio (single) questions show the optional per-answer note by default so
+      // the user can qualify their pick; other types stay opt-in. An explicit
+      // note:false turns it off for a single question.
+      note: rq.note === undefined ? type === 'single' : rq.note === true,
       blocks: buildBlocks(rq, cwd, where, `${id}-`),
       placeholder: asStr(rq.placeholder),
     };
@@ -486,7 +489,7 @@ export const SPEC_SCHEMA = {
             },
           },
           other: { type: 'boolean', default: false, description: 'single/multi: add a free-text "Other" option. Its text is returned verbatim as the value.' },
-          note: { type: 'boolean', default: false, description: 'Add a small optional free-text field under the question (e.g. to qualify a choice). Returned separately as result.notes[questionId].' },
+          note: { type: 'boolean', description: 'Small optional free-text field under the question (to qualify an answer). Returned separately as result.notes[questionId]. Defaults to true for "single" (radio) questions so users can comment on their pick, false for other types; set note:false to hide it on a single question.' },
           placeholder: { type: 'string', description: 'For text/textarea.' },
           default: { description: 'Pre-selected value. Shape matches the answer shape for the type.' },
           min: { type: 'integer', default: 1, description: 'scale only' },
@@ -504,7 +507,7 @@ export const SPEC_SCHEMA = {
       type: 'array',
       readOnly: true,
       description:
-        'Returned in the result (not part of the input spec). Element-level comments the user attached to blocks. Each: {id, questionId|null, blockId|null, target:{kind:"chart-element"|"mermaid-node"|"table-cell"|"text"|"html-element", …}, text, createdAt}.',
+        'Returned in the result (not part of the input spec). Element-level comments the user attached to blocks. Each: {id, questionId|null, blockId|null, target:{kind:"chart-element"|"mermaid-node"|"graphviz-node"|"table-cell"|"text"|"html-element"|"image", …}, text, createdAt}. For html-element, target carries a stable ref + label; users can hover any element of a custom-HTML block (automatic) or ones the author marked with data-relay-annotate.',
     },
     blockEdits: {
       type: 'object',

package/src/ui/app.js

@@ -232,6 +232,9 @@
       onChange: (list) => {
         state.annotations = list;
         scheduleSave();
+        // Refresh per-element comment badges inside custom-HTML iframes (bridge
+        // sets this once the iframe annotate plumbing is wired below).
+        if (window.__relayBroadcastCounts) window.__relayBroadcastCounts();
       },
     });
   }
@@ -516,7 +519,13 @@
     // sessionStorage may be unavailable (privacy mode) — non-fatal
   }
 
-  app.append(el('header', { class: 'qb-header' }, el('h1', {}, spec.title), themeBtn));
+  const titleEl = el('h1', {}, spec.title);
+  app.append(el('header', { class: 'qb-header' }, titleEl, themeBtn));
+  // The board title is commentable too: hovering it shows the pin, like the
+  // intro and every other content element. (themeBtn stays out of it.)
+  if (spec.title) {
+    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);
     app.append(intro);
@@ -581,7 +590,7 @@
   const hint = el('span', { class: 'hint' },
     QS.length && spec.allowPartial ? 'Unanswered questions are returned as skipped.' : '');
   app.append(el('div', { class: 'submitbar' }, submitBtn, hint, saveEl));
-  app.append(el('footer', { class: 'qb-footer' }, `quest-board · ${boot.boardId}`));
+  app.append(el('footer', { class: 'qb-footer' }, `relay · ${boot.boardId}`));
 
   // ---------- validation & submit ----------
   function validate() {
@@ -664,33 +673,66 @@
   }
 
   // ---------- iframe annotate bridge ----------
-  // Custom-HTML iframes (via /kit.js relayKit.commentable) post
-  // {relay:'annotate-request', label, detail?}. Match the source to the
-  // iframe, read its block/question ids, and open the annotate popover anchored
-  // to that iframe.
+  // Custom-HTML iframes (via /kit.js relayKit.annotate, auto-injected by the
+  // server) talk to the parent over postMessage:
+  //   iframe → {relay:'annotate-ready'}                      we send it counts
+  //   iframe → {relay:'annotate-request', ref, label, detail?, rect}
+  //   parent → {relay:'annotate-counts', counts:{ref:n}}     it draws badges
+  // We own the annotation state, popover, and the submitted result; the iframe
+  // owns hover/pin/badges over its own (cross-origin) DOM.
   if (Annotate) {
-    window.addEventListener('message', (e) => {
-      const msg = e.data;
-      if (!msg || typeof msg !== 'object' || msg.relay !== 'annotate-request') return;
-      let frame = null;
+    const frameOf = (source) => {
       for (const f of document.querySelectorAll('iframe.viz')) {
-        if (f.contentWindow === e.source) { frame = f; break; }
+        if (f.contentWindow === source) return f;
       }
+      return null;
+    };
+    // Per-element comment counts for one iframe, keyed by target.ref.
+    const postCountsTo = (frame) => {
+      if (!frame || !frame.contentWindow) return;
+      const blockId = frame.getAttribute('data-block-id') || null;
+      const counts = {};
+      for (const a of Annotate.list()) {
+        if ((a.blockId ?? null) !== (blockId ?? null)) continue;
+        const t = a.target || {};
+        if (t.kind !== 'html-element' || !t.ref) continue;
+        counts[t.ref] = (counts[t.ref] || 0) + 1;
+      }
+      try { frame.contentWindow.postMessage({ relay: 'annotate-counts', counts }, '*'); } catch {}
+    };
+    // Refresh badges in every html iframe (called whenever annotations change).
+    window.__relayBroadcastCounts = () => {
+      for (const f of document.querySelectorAll('iframe.viz')) postCountsTo(f);
+    };
+
+    window.addEventListener('message', (e) => {
+      const msg = e.data;
+      if (!msg || typeof msg !== 'object' || typeof msg.relay !== 'string') return;
+      const frame = frameOf(e.source);
       if (!frame) return;
+      if (msg.relay === 'annotate-ready') { postCountsTo(frame); return; }
+      if (msg.relay !== 'annotate-request') return;
+
       const blockId = frame.getAttribute('data-block-id') || null;
       const questionId = frame.getAttribute('data-question-id') || null;
-      Annotate.openExternal(
-        {
-          blockId,
-          questionId: questionId || null,
-          target: {
-            kind: 'html-element',
-            label: typeof msg.label === 'string' ? msg.label : 'Element',
-            detail: typeof msg.detail === 'string' ? msg.detail : undefined,
-          },
-        },
-        frame
-      );
+      const target = { kind: 'html-element', label: typeof msg.label === 'string' ? msg.label : 'Element' };
+      if (typeof msg.ref === 'string') target.ref = msg.ref;
+      if (typeof msg.detail === 'string') target.detail = msg.detail;
+
+      // Anchor the popover to the actual element: translate the iframe-local
+      // viewport rect the iframe sent into page coords. Fall back to the iframe.
+      let anchor = frame;
+      if (msg.rect && typeof msg.rect === 'object') {
+        const fr = frame.getBoundingClientRect();
+        const r = msg.rect;
+        const left = fr.left + (r.left || 0);
+        const top = fr.top + (r.top || 0);
+        const width = r.width || 0;
+        const height = r.height || 0;
+        const pageRect = { left, top, width, height, right: left + width, bottom: top + height };
+        anchor = { getBoundingClientRect: () => pageRect };
+      }
+      Annotate.openExternal({ blockId, questionId: questionId || null, target }, anchor);
     });
   }
 

package/src/ui/blocks.css

@@ -307,14 +307,28 @@
 .blk-tools .tool-pct { color: var(--muted); font-size: 0.72rem; min-width: 30px; text-align: center; }
 
 /* full-screen = fixed overlay (NOT native fullscreen: annotation pins/badges/
-   popover live on <body> and must stay visible above the expanded block) */
+   popover live on <body> and must stay visible above the expanded block).
+   Edge-to-edge (no modal gap); the toolbar pins to the top as a fixed bar so
+   the close button stays on screen while the content scrolls. */
 .blk-full {
-  position: fixed !important; inset: 12px; z-index: 49;
-  background: var(--card); border: 1px solid var(--border);
-  border-radius: 12px; box-shadow: var(--shadow-lift);
+  position: fixed !important; inset: 0; z-index: 49;
+  background: var(--card); border: 0; border-radius: 0; box-shadow: none;
   overflow: auto; max-height: none !important; margin: 0 !important;
-  padding: 48px 16px 16px;
+  padding: 44px 0 0;
 }
 body.blk-full-open { overflow: hidden; }
-.blk-chart.blk-full { height: calc(100vh - 24px) !important; width: auto !important; }
-.blk-htmlwrap.blk-full iframe.viz { height: calc(100vh - 90px) !important; width: 100%; }
+/* detach the toolbar from the scrolling content and fix it to the viewport top */
+.blk-full > .blk-tools {
+  position: fixed; top: 0; left: 0; right: 0; height: 44px;
+  margin: 0; padding: 0 12px;
+  background: var(--card); border-bottom: 1px solid var(--border);
+  z-index: 51;
+}
+.blk-chart.blk-full {
+  height: 100vh !important; width: auto !important;
+  padding: 44px 16px 16px;
+}
+.blk-htmlwrap.blk-full iframe.viz {
+  height: calc(100vh - 44px) !important; width: 100%;
+  margin: 0; border: 0; border-radius: 0;
+}

package/src/ui/kit.js

@@ -32,13 +32,26 @@
  *     sortable: click column header to sort ascending/descending.
  *
  *   relayKit.commentable(el, label, detail?)
- *     Hover: 1px dashed accent outline + cursor pointer + title "add a comment".
- *     Click: parent.postMessage({relay:'annotate-request', label, detail}, '*').
+ *     Make one element commentable: hover shows a comment pin, a per-element
+ *     badge counts comments, click opens the board's annotation popover anchored
+ *     to the element. Thin shim over relayKit.annotate.register().
+ *
+ *   relayKit.annotate.auto()
+ *     Injected automatically by the server into every custom-HTML iframe. With no
+ *     explicit signals it makes a sensible set of content/interactive elements
+ *     hover-commentable so the user can annotate ANY meaningful part of the HTML.
+ *     If the author marks elements with data-relay-annotate[="Label"] (+ optional
+ *     data-relay-detail) or calls commentable(), auto-mode backs off to just those.
+ *     Opt out with data-relay-annotate="off" on <html> or <body>.
  */
 
 (function () {
   'use strict';
 
+  // Idempotent: the server may inject a /kit.js load on top of one the author
+  // already added. First load wins; a second execution no-ops.
+  if (window.relayKit) return;
+
   // ---------------------------------------------------------------------------
   // Theme
   // ---------------------------------------------------------------------------
@@ -357,39 +370,333 @@
   }
 
   // ---------------------------------------------------------------------------
-  // commentable()
+  // annotate — element-level commenting inside the sandboxed iframe
   // ---------------------------------------------------------------------------
+  // The board's annotation engine lives in the PARENT page and can't reach into
+  // this cross-origin iframe (sandbox without allow-same-origin), so everything
+  // here runs iframe-side and talks to the parent over postMessage:
+  //   iframe → parent  {relay:'annotate-ready'}                     request counts
+  //   iframe → parent  {relay:'annotate-request', ref, label, detail?, rect}
+  //   parent → iframe  {relay:'annotate-counts', counts:{ref:n}}    draw badges
+  //
+  // `ref` is a compact, reload-stable CSS path used as the element's identity so
+  // comments re-bind and badges count per element.
+
+  const annotate = (() => {
+    // Auto-mode picks anything the user would plausibly point at: every element
+    // with its OWN direct text (so div/span-based mockups work, not just
+    // semantic tags), plus meaningful leaves (icons, buttons, media) and a few
+    // semantic containers worth commenting whole. closest() resolves overlaps to
+    // the innermost target on hover.
+    const LEAF_TAGS = /^(IMG|BUTTON|A|INPUT|SELECT|TEXTAREA|svg|VIDEO|CANVAS|SUMMARY)$/;
+    const SKIP_TAGS = /^(SCRIPT|STYLE|HEAD|META|LINK|TITLE|BASE|NOSCRIPT|TEMPLATE)$/;
+    const CONTAINER_SELECTOR =
+      'li,td,th,figure,blockquote,article,.card,[role="button"],[role="listitem"],[role="option"]';
+    const MAX_AUTO = 400;
+    // Replaced elements that can't host a badge child — overlay the badge instead.
+    const NO_CHILD = /^(IMG|INPUT|HR|BR|EMBED|CANVAS|VIDEO|svg)$/;
+
+    const byRef = new Map(); // ref -> element
+    let mode = null;         // 'auto' | 'explicit' (decided on first scan)
+    let started = false;
+    let hot = null;          // currently outlined element
+    let pin = null;          // floating pin button
+    let hideTimer = 0;
+    let lastCounts = {};
+    let overlayBadges = [];  // [{el, badge}] for replaced elements
+    let repoTimer = 0;
+
+    const accent = () => theme.colors.accent;
+
+    // Compact, reload-stable CSS path — the element's identity.
+    function refOf(el) {
+      if (el.__relayRef) return el.__relayRef;
+      const parts = [];
+      let n = el;
+      while (n && n.nodeType === 1 && n !== document.body && parts.length < 10) {
+        let seg = n.tagName.toLowerCase();
+        const p = n.parentNode;
+        if (p && p.children) {
+          const sibs = Array.prototype.filter.call(p.children, (c) => c.tagName === n.tagName);
+          if (sibs.length > 1) seg += ':nth-of-type(' + (sibs.indexOf(n) + 1) + ')';
+        }
+        parts.unshift(seg);
+        n = p;
+      }
+      const ref = parts.join('>') || el.tagName.toLowerCase();
+      el.__relayRef = ref;
+      return ref;
+    }
 
-  function commentable(el, label, detail) {
-    try {
-      const lStr = String(label || '').slice(0, 200);
-      const dStr = detail != null ? String(detail).slice(0, 500) : undefined;
-      const accent = theme.colors.accent;
+    // Human label when the author didn't supply one.
+    function labelOf(el) {
+      const aria = el.getAttribute && el.getAttribute('aria-label');
+      if (aria) return aria.trim().slice(0, 80) || el.tagName.toLowerCase();
+      if (el.tagName === 'IMG') return (el.getAttribute('alt') || 'Image').trim().slice(0, 80) || 'Image';
+      const txt = (el.textContent || '').replace(/\s+/g, ' ').trim();
+      return txt ? txt.slice(0, 80) : el.tagName.toLowerCase();
+    }
 
-      el.style.cursor = 'pointer';
-      el.title = 'add a comment';
+    function injectStyle() {
+      if (document.getElementById('relay-ann-style')) return;
+      const s = document.createElement('style');
+      s.id = 'relay-ann-style';
+      s.textContent = [
+        '.relay-ann-hot{outline:2px solid ' + accent() + ' !important;outline-offset:1px !important;}',
+        '.relay-ann-badge{position:absolute;top:-7px;right:-7px;min-width:16px;height:16px;padding:0 4px;' +
+          'box-sizing:border-box;border-radius:9px;background:' + accent() + ';color:#fff;font:600 10px/16px ' + SANS + ';' +
+          'text-align:center;z-index:2147483646;cursor:pointer;box-shadow:0 1px 2px rgba(0,0,0,.25);}',
+      ].join('\n');
+      (document.head || document.documentElement).appendChild(s);
+    }
 
-      el.addEventListener('mouseenter', () => {
-        el.style.outline = `1px dashed ${accent}`;
-        el.style.outlineOffset = '2px';
-      });
-      el.addEventListener('mouseleave', () => {
-        el.style.outline = '';
-        el.style.outlineOffset = '';
-      });
-      el.addEventListener('click', (e) => {
+    function ensurePin() {
+      if (pin || !document.body) return pin;
+      pin = document.createElement('button');
+      pin.type = 'button';
+      pin.setAttribute('aria-label', 'Add a comment');
+      pin.title = 'Add a comment';
+      pin.style.cssText = [
+        'position:fixed', 'z-index:2147483647', 'display:none', 'width:22px', 'height:22px',
+        'padding:0', 'border:none', 'border-radius:50%', 'cursor:pointer', 'background:' + accent(),
+        'color:#fff', 'align-items:center', 'justify-content:center', 'line-height:0',
+        'box-shadow:0 1px 4px rgba(0,0,0,.3)',
+      ].join(';');
+      pin.innerHTML =
+        '<svg viewBox="0 0 16 16" width="11" height="11" aria-hidden="true">' +
+        '<path d="M3 2.5h10A1.5 1.5 0 0 1 14.5 4v5a1.5 1.5 0 0 1-1.5 1.5H8.4L5 13.4v-2.9H3A1.5 1.5 0 0 1 1.5 9V4A1.5 1.5 0 0 1 3 2.5Z" fill="currentColor"/></svg>';
+      pin.addEventListener('mouseenter', () => clearTimeout(hideTimer));
+      pin.addEventListener('mouseleave', scheduleHide);
+      pin.addEventListener('click', (e) => {
+        e.preventDefault();
         e.stopPropagation();
-        const msg = { relay: 'annotate-request', label: lStr };
-        if (dStr !== undefined) msg.detail = dStr;
-        try {
-          parent.postMessage(msg, '*');
-        } catch (postErr) {
-          console.warn('[relayKit] commentable postMessage error:', postErr);
+        if (hot) request(hot);
+        hidePin();
+      });
+      document.body.appendChild(pin);
+      return pin;
+    }
+
+    function showPinFor(el) {
+      if (!ensurePin()) return;
+      clearTimeout(hideTimer);
+      if (hot && hot !== el) hot.classList.remove('relay-ann-hot');
+      hot = el;
+      el.classList.add('relay-ann-hot');
+      const r = el.getBoundingClientRect();
+      const w = 22;
+      pin.style.display = 'flex';
+      pin.style.left = Math.max(2, Math.min(r.right - w / 2, window.innerWidth - w - 2)) + 'px';
+      pin.style.top = Math.max(2, Math.min(r.top - w / 2, window.innerHeight - w - 2)) + 'px';
+    }
+
+    function scheduleHide() {
+      clearTimeout(hideTimer);
+      hideTimer = setTimeout(hidePin, 220); // grace so the pin itself stays clickable
+    }
+
+    function hidePin() {
+      clearTimeout(hideTimer);
+      if (hot) hot.classList.remove('relay-ann-hot');
+      hot = null;
+      if (pin) pin.style.display = 'none';
+    }
+
+    // Ask the parent to open its annotation popover for this element.
+    function request(el) {
+      const r = el.getBoundingClientRect();
+      const msg = {
+        relay: 'annotate-request',
+        ref: refOf(el),
+        label: String(el.__relayLabel || labelOf(el)).slice(0, 200),
+        rect: { left: r.left, top: r.top, width: r.width, height: r.height },
+      };
+      if (el.__relayDetail != null) msg.detail = String(el.__relayDetail).slice(0, 500);
+      try { parent.postMessage(msg, '*'); } catch (_) {}
+    }
+
+    function positionOverlay(el, badge) {
+      const r = el.getBoundingClientRect();
+      badge.style.left = (r.right + window.scrollX - 9) + 'px';
+      badge.style.top = (r.top + window.scrollY - 7) + 'px';
+      badge.style.right = 'auto';
+    }
+
+    function repositionOverlays() {
+      for (const o of overlayBadges) if (o.el.isConnected) positionOverlay(o.el, o.badge);
+    }
+
+    function renderBadges(counts) {
+      lastCounts = counts || {};
+      for (const b of document.querySelectorAll('.relay-ann-badge')) b.remove();
+      overlayBadges = [];
+      for (const ref of Object.keys(lastCounts)) {
+        const n = lastCounts[ref];
+        if (!n) continue;
+        const el = byRef.get(ref);
+        if (!el || !el.isConnected) continue;
+        const badge = document.createElement('span');
+        badge.className = 'relay-ann-badge';
+        badge.textContent = String(n);
+        badge.title = n + (n === 1 ? ' comment' : ' comments');
+        badge.addEventListener('click', (e) => { e.preventDefault(); e.stopPropagation(); request(el); });
+        if (NO_CHILD.test(el.tagName)) {
+          badge.style.position = 'absolute';
+          document.body.appendChild(badge);
+          overlayBadges.push({ el, badge });
+          positionOverlay(el, badge);
+        } else {
+          if (getComputedStyle(el).position === 'static') el.style.position = 'relative';
+          el.appendChild(badge);
         }
+      }
+    }
+
+    function add(el, label, detail) {
+      if (!el || el.nodeType !== 1) return;
+      byRef.set(refOf(el), el);
+      el.classList.add('relay-annotatable');
+      if (label != null && label !== '') el.__relayLabel = String(label);
+      if (detail != null) el.__relayDetail = detail;
+    }
+
+    // True when the element holds non-whitespace text of its OWN (a direct text
+    // node), not just text inherited from descendants.
+    function hasDirectText(el) {
+      for (const n of el.childNodes) {
+        if (n.nodeType === 3 && n.nodeValue && n.nodeValue.trim()) return true;
+      }
+      return false;
+    }
+
+    function autoPick() {
+      let all;
+      try { all = document.body.querySelectorAll('*'); } catch (_) { return []; }
+      let containers;
+      try { containers = new Set(document.querySelectorAll(CONTAINER_SELECTOR)); } catch (_) { containers = new Set(); }
+      const out = [];
+      for (const el of all) {
+        if (out.length >= MAX_AUTO) break;
+        if (SKIP_TAGS.test(el.tagName)) continue;
+        if (pin && pin.contains(el)) continue;             // our own pin
+        if (el.classList && el.classList.contains('relay-ann-badge')) continue;
+        if (LEAF_TAGS.test(el.tagName) || containers.has(el) || hasDirectText(el)) out.push(el);
+      }
+      return out;
+    }
+
+    function scan() {
+      const signalled = Array.prototype.filter.call(
+        document.querySelectorAll('[data-relay-annotate]'),
+        (el) => el.getAttribute('data-relay-annotate') !== 'off'
+      );
+      // ANY explicit signal (attribute or a prior commentable() call) → the
+      // author scopes what's annotatable; auto-mode stays off.
+      if (mode === null) mode = signalled.length > 0 || byRef.size > 0 ? 'explicit' : 'auto';
+      if (mode === 'explicit') {
+        for (const el of signalled) add(el, el.getAttribute('data-relay-annotate') || null, el.getAttribute('data-relay-detail'));
+        return;
+      }
+      for (const el of autoPick()) add(el, null, undefined);
+    }
+
+    function optedOut() {
+      const v = (document.body && document.body.getAttribute('data-relay-annotate')) ||
+        document.documentElement.getAttribute('data-relay-annotate');
+      return v === 'off';
+    }
+
+    function announce() {
+      try { parent.postMessage({ relay: 'annotate-ready' }, '*'); } catch (_) {}
+    }
+
+    function start() {
+      if (started) return;
+      if (!document.body) { document.addEventListener('DOMContentLoaded', start, { once: true }); return; }
+      started = true;
+      injectStyle();
+      ensurePin();
+      // Delegated hover — closest() resolves nested targets to the innermost.
+      document.addEventListener('mouseover', (e) => {
+        const t = e.target && e.target.closest && e.target.closest('.relay-annotatable');
+        if (t) showPinFor(t);
+      }, true);
+      document.addEventListener('mouseout', (e) => {
+        const t = e.target && e.target.closest && e.target.closest('.relay-annotatable');
+        if (t) scheduleHide();
+      }, true);
+      window.addEventListener('scroll', () => {
+        hidePin();
+        if (overlayBadges.length) { cancelAnimationFrame(repoTimer); repoTimer = requestAnimationFrame(repositionOverlays); }
+      }, true);
+      window.addEventListener('resize', () => { hidePin(); repositionOverlays(); });
+      window.addEventListener('message', (e) => {
+        const m = e.data;
+        if (m && typeof m === 'object' && m.relay === 'annotate-counts') renderBadges(m.counts || {});
       });
-    } catch (err) {
-      console.warn('[relayKit] commentable error:', err);
+      // Re-pick up DOM that author JS builds after load. We observe childList
+      // only (not attributes, so our own hover-class toggles don't fire it) and
+      // ignore mutations that only touch our own pin/badge nodes — otherwise
+      // rendering a badge would re-trigger the observer in a tight loop.
+      try {
+        const ours = (n) =>
+          n.nodeType === 1 &&
+          (n === pin || (pin && pin.contains(n)) || n.id === 'relay-ann-style' ||
+            (n.classList && n.classList.contains('relay-ann-badge')));
+        const mo = new MutationObserver((muts) => {
+          let relevant = false;
+          for (const m of muts) {
+            for (const n of m.addedNodes) if (!ours(n)) { relevant = true; break; }
+            if (relevant) break;
+            for (const n of m.removedNodes) if (!ours(n)) { relevant = true; break; }
+            if (relevant) break;
+          }
+          if (!relevant) return;
+          clearTimeout(mo._t);
+          mo._t = setTimeout(() => { scan(); renderBadges(lastCounts); announce(); }, 250);
+        });
+        mo.observe(document.body, { childList: true, subtree: true });
+      } catch (_) {}
+      announce();
+    }
+
+    // Server-injected entrypoint. Idempotent.
+    function auto() {
+      try {
+        if (optedOut()) return;
+        if (!document.body) { document.addEventListener('DOMContentLoaded', auto, { once: true }); return; }
+        scan();
+        start();
+      } catch (err) {
+        console.warn('[relayKit] annotate.auto error:', err);
+      }
+    }
+
+    // Explicit per-element registration (also used by commentable()).
+    function register(el, label, detail) {
+      try {
+        add(el, label, detail);
+        if (started) renderBadges(lastCounts);
+        else start();
+      } catch (err) {
+        console.warn('[relayKit] annotate.register error:', err);
+      }
     }
+
+    return { auto, register };
+  })();
+
+  // ---------------------------------------------------------------------------
+  // commentable() — back-compat shim over annotate.register()
+  // ---------------------------------------------------------------------------
+
+  function commentable(el, label, detail) {
+    if (!el) return;
+    annotate.register(
+      el,
+      label != null ? String(label).slice(0, 200) : null,
+      detail != null ? String(detail).slice(0, 500) : undefined
+    );
   }
 
   // ---------------------------------------------------------------------------
@@ -403,6 +710,7 @@
     mermaid,
     table,
     commentable,
+    annotate,
   };
 
   window.relayKit = relayKit;