@khanglvm/relay 0.12.1 → 0.12.3

package/docs/AGENT.md

@@ -154,7 +154,7 @@ rly show --html-file prototype.html --title "Dashboard concept" --height 600
         { "value": "a", "label": "Approach A", "description": "fast, less flexible" },
         "Approach B"                                    // plain strings work too
       ],
-      "other": true },                                  // adds a free-text "Other" option
+      "other": false },                                 // single: "Other" (free-text textarea) is ON by default — set false to remove it
     { "id": "scope", "type": "multi", "label": "Include which parts?", "options": ["api", "ui", "docs"],
       "note": true },                                   // optional free-text under the question
                                                         //   → returned as result.notes.scope

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@khanglvm/relay",
-  "version": "0.12.1",
+  "version": "0.12.3",
   "description": "Question boards with rich blocks (markdown, charts, mermaid, tables, code, diffs, video, sandboxed HTML), clickable local file-links, and element-level annotations for AI coding agents (Claude Code, Codex, …): ask users structured questions, present interactive visuals, collect inline comments, read answers as JSON — in a local browser board OR rendered INLINE inside the Claude & Codex apps as an MCP App (SEP-1865).",
   "keywords": [
     "ai-agents",

package/src/mcp-ui/board.js

@@ -159,6 +159,25 @@
     }
   }
 
+  // Platform awareness: reflect the host's surface so the board (and CSS) can
+  // adapt — a data-platform hint, a touch flag, and the host's safe-area insets
+  // applied as padding so content clears notches / home indicators on mobile.
+  function applyHostEnv() {
+    const root = document.documentElement;
+    if (host.platform === 'web' || host.platform === 'desktop' || host.platform === 'mobile') {
+      root.dataset.platform = host.platform;
+    }
+    root.classList.toggle('mcp-touch', Boolean(host.deviceCapabilities && host.deviceCapabilities.touch));
+    const sai = host.safeAreaInsets;
+    if (sai && typeof sai === 'object') {
+      const px = (n) => (Number.isFinite(n) ? n : 0) + 'px';
+      root.style.setProperty('--mcp-safe-top', px(sai.top));
+      root.style.setProperty('--mcp-safe-right', px(sai.right));
+      root.style.setProperty('--mcp-safe-bottom', px(sai.bottom));
+      root.style.setProperty('--mcp-safe-left', px(sai.left));
+    }
+  }
+
   let sizeTimer = null;
   function measureHeight() {
     return Math.max(document.documentElement.scrollHeight, document.body ? document.body.scrollHeight : 0);
@@ -230,7 +249,7 @@
           }
           return { value: String(o), label: String(o) };
         });
-        q.other = rq.other === true;
+        q.other = type === 'single' ? rq.other !== false : rq.other === true;
       }
       if (type === 'scale') {
         q.min = Number.isFinite(rq.min) ? rq.min : 1;
@@ -496,7 +515,7 @@
     }
     if (q.other) {
       otherRadio = el('input', { type: 'radio', name: q.id });
-      const text = el('input', { type: 'text', placeholder: 'your own answer…' });
+      const text = el('textarea', { class: 'otherinput', rows: '2', placeholder: 'your own answer…' });
       text.value = (state.other[q.id] && state.other[q.id].text) || '';
       otherRadio.checked = otherOn();
       const ensureOther = () => state.other[q.id] || (state.other[q.id] = { on: false, text: text.value });
@@ -529,7 +548,7 @@
     if (q.other) {
       const oth = state.other[q.id];
       const box = el('input', { type: 'checkbox' });
-      const text = el('input', { type: 'text', placeholder: 'your own answer…' });
+      const text = el('textarea', { class: 'otherinput', rows: '2', placeholder: 'your own answer…' });
       box.checked = Boolean(oth && oth.on);
       text.value = (oth && oth.text) || '';
       const sync = () => { state.other[q.id] = { on: box.checked, text: text.value }; syncOptSel(group); clearErr(q.id); };
@@ -841,11 +860,15 @@
     if (p && typeof p === 'object') {
       if ('theme' in p) host.theme = p.theme;
       if ('styles' in p) host.styles = p.styles;
+      if ('platform' in p) host.platform = p.platform;
+      if ('safeAreaInsets' in p) host.safeAreaInsets = p.safeAreaInsets;
+      if ('deviceCapabilities' in p) host.deviceCapabilities = p.deviceCapabilities;
       if (p.displayMode === 'inline' || p.displayMode === 'fullscreen' || p.displayMode === 'pip') {
         displayMode = p.displayMode;
         applyDisplayMode();
       }
       adoptHostStyles();
+      applyHostEnv();
       applyTheme();
     }
   });
@@ -870,6 +893,7 @@
     if (host.displayMode === 'fullscreen' || host.displayMode === 'pip') displayMode = host.displayMode;
     notify('ui/notifications/initialized', {});
     adoptHostStyles();
+    applyHostEnv();
     applyTheme();
     setStatus('Waiting for the board…');
     reportSize();

package/src/mcp-ui/index.html

@@ -13,7 +13,12 @@
 :root{ color-scheme: light dark; }
 html,body{ background:transparent; }
 body{ margin:0; }
-.wrap{ max-width:none; margin:0; padding:14px 16px 18px; }
+.wrap{ max-width:none; margin:0;
+  padding:
+    calc(14px + var(--mcp-safe-top, 0px))
+    calc(16px + var(--mcp-safe-right, 0px))
+    calc(18px + var(--mcp-safe-bottom, 0px))
+    calc(16px + var(--mcp-safe-left, 0px)); }
 .mcp-status{ font:13px/1.5 var(--sans, -apple-system,BlinkMacSystemFont,"Segoe UI",Roboto,sans-serif); color:var(--muted,#8a8580); padding:18px 16px; }
 /* post-submit: a slim one-line confirmation so the iframe collapses small */
 .mcp-done{ display:flex; align-items:center; gap:8px; padding:11px 16px; font:14px/1.4 var(--sans, -apple-system,BlinkMacSystemFont,"Segoe UI",Roboto,sans-serif); color:var(--fg,#1c1b19); }

package/src/mcp.js

@@ -214,17 +214,42 @@ function callTool(params) {
     const msg = err instanceof CliError ? err.message : String((err && err.message) || err);
     return { content: [{ type: 'text', text: 'relay: invalid board spec — ' + msg }], isError: true };
   }
-  const nQ = spec.questions.length;
-  const summary = nQ
-    ? `Relay board "${spec.title}" is now displayed to the user (${nQ} question${nQ === 1 ? '' : 's'}). They will fill it in and submit; their answers will be delivered back to you. Do NOT re-ask these questions in plain text — wait for the submission.`
-    : `Relay board "${spec.title}" is now displayed to the user. They can review it and acknowledge; any feedback will be delivered back to you.`;
   return {
-    content: [{ type: 'text', text: summary }],
+    content: [{ type: 'text', text: boardText(spec) }],
     structuredContent: { spec, mode: name === 'relay_show' ? 'show' : 'ask' },
     _meta: { ui: { resourceUri: BOARD_URI }, [UI_EXT]: { resourceUri: BOARD_URI } },
   };
 }
 
+// The tool-result text. Beyond announcing the board, it carries a readable
+// rendering of the questions as a GRACEFUL FALLBACK: on a surface that can't show
+// the interactive board (some mobile/remote-control views), the user can still
+// answer in chat and the model has the questions to work from. The model should
+// PREFER the rendered board (wait for the submission) and only fall back to chat
+// when the board clearly didn't render for the user.
+function boardText(spec) {
+  const nQ = spec.questions.length;
+  if (!nQ) {
+    return `Relay board "${spec.title}" is now displayed to the user. They can review it and acknowledge; any feedback will be delivered back to you.`;
+  }
+  const lines = [];
+  lines.push(`Relay board "${spec.title}" is now displayed to the user (${nQ} question${nQ === 1 ? '' : 's'}). Prefer the interactive board — wait for their submission; do NOT re-ask in plain text.`);
+  lines.push('');
+  lines.push('If the board does NOT render on the user\'s surface (e.g. some mobile / remote views) they can answer in chat — the questions are:');
+  spec.questions.forEach((q, i) => {
+    let line = `${i + 1}. [${q.id}] ${q.label} (${q.type}`;
+    if (q.required || spec.allowPartial === false) line += ', required';
+    line += ')';
+    if (Array.isArray(q.options) && q.options.length) {
+      line += ' — options: ' + q.options.map((o) => o.label || o.value).join(' | ') + (q.other ? ' | Other (free text)' : '');
+    } else if (q.type === 'scale') {
+      line += ` — ${q.min}…${q.max}`;
+    }
+    lines.push(line);
+  });
+  return lines.join('\n');
+}
+
 // ---------- stdio loop ----------
 export function runMcp() {
   // The peer closing stdout (EPIPE) is the only reason to stop writing — NOT a

package/src/spec.js

@@ -510,7 +510,10 @@ export function normalizeSpec(raw, { cwd = process.cwd() } = {}) {
       if (q.options.length < 1) {
         throw new CliError(`${where}: type "${type}" needs at least 1 option.`);
       }
-      q.other = rq.other === true;
+      // Radio (single) questions include an "Other" free-text option by default so
+      // the user is never boxed into the listed choices; opt out with other:false.
+      // Multi stays opt-in (checkbox lists are usually exhaustive on purpose).
+      q.other = type === 'single' ? rq.other !== false : rq.other === true;
     }
 
     if (type === 'scale') {
@@ -667,7 +670,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.' },
+          other: { type: 'boolean', description: 'Add a free-text "Other" option (a multi-line textarea); its text is returned verbatim as the value. Defaults ON for "single" (radio) questions so the user is never boxed in — set other:false to remove it; "multi" stays opt-in (other:true).' },
           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.' },

package/src/ui/annotate.css

@@ -48,12 +48,22 @@
   padding: 12px 14px;
   font: 14px/1.5 var(--sans);
 }
+.ann-pop-head { display: flex; align-items: flex-start; gap: 8px; margin-bottom: 8px; }
 .ann-pop-label {
+  flex: 1; min-width: 0;
   color: var(--muted);
   font-size: 0.78rem;
-  margin-bottom: 8px;
   overflow-wrap: anywhere;
 }
+.ann-pop-close {
+  flex: none; margin: -4px -4px 0 0;
+  background: transparent; color: var(--muted);
+  border: none; border-radius: 7px;
+  width: 26px; height: 26px;
+  font-size: 1.25rem; line-height: 1; cursor: pointer;
+  transition: color 150ms var(--ease), background 150ms var(--ease);
+}
+.ann-pop-close:hover { color: var(--fg); background: var(--bg-sunken); }
 .ann-pop-existing { margin-bottom: 8px; max-height: min(50vh, 420px); overflow-y: auto; }
 .ann-pop-existing:empty { display: none; margin: 0; }
 
@@ -146,16 +156,49 @@
 .ann-cancel:hover { border-color: var(--accent); color: var(--accent); }
 
 /* delete button (popover items + summary rows): muted, danger on hover */
+/* Delete = a trash icon button, visually distinct from the close ×. */
 .ann-del {
   flex: none;
+  display: inline-flex; align-items: center; justify-content: center;
   background: transparent; color: var(--muted);
-  border: none; border-radius: 6px;
-  padding: 2px 6px;
-  font-size: 1.05rem; line-height: 1;
+  border: none; border-radius: 7px;
+  width: 26px; height: 26px;
   cursor: pointer;
-  transition: color 150ms var(--ease);
+  transition: color 150ms var(--ease), background 150ms var(--ease);
 }
-.ann-del:hover { color: var(--danger); }
+.ann-del:hover { color: var(--danger); background: var(--accent-soft); }
+
+/* ---------- delete confirmation modal ---------- */
+.ann-confirm-scrim {
+  position: fixed; inset: 0; z-index: 80;
+  background: rgba(28, 27, 25, 0.4);
+  display: flex; align-items: center; justify-content: center;
+  padding: 20px;
+}
+.ann-confirm {
+  width: min(360px, 92vw);
+  background: var(--card); color: var(--fg);
+  border: 1px solid var(--border); border-radius: 14px;
+  box-shadow: var(--shadow-lift);
+  padding: 20px;
+  font: 14px/1.5 var(--sans);
+}
+.ann-confirm-title { font: 600 1.05rem var(--sans); margin-bottom: 6px; }
+.ann-confirm-msg { color: var(--fg-2); font-size: 0.9rem; }
+.ann-confirm-skip {
+  display: flex; align-items: center; gap: 8px;
+  margin: 14px 0 4px; color: var(--fg-2); font-size: 0.85rem; cursor: pointer;
+}
+.ann-confirm-skip input { width: 15px; height: 15px; accent-color: var(--accent); cursor: pointer; }
+.ann-confirm-actions { display: flex; justify-content: flex-end; gap: 8px; margin-top: 16px; }
+.ann-confirm-cancel, .ann-confirm-del {
+  border-radius: 9px; padding: 8px 16px; font: 600 0.88rem var(--sans); cursor: pointer;
+  border: 1px solid var(--border-strong); transition: all 150ms var(--ease);
+}
+.ann-confirm-cancel { background: var(--card); color: var(--fg-2); }
+.ann-confirm-cancel:hover { background: var(--bg-sunken); color: var(--fg); }
+.ann-confirm-del { background: var(--danger); color: var(--danger-fg); border-color: var(--danger); }
+.ann-confirm-del:hover { filter: brightness(1.06); }
 
 /* ---------- floating selection button ---------- */
 .ann-selbtn {
@@ -274,8 +317,20 @@
 .ann-rail-list .ann-sum-row + .ann-sum-row { border-top: 1px solid var(--border); }
 .ann-rail-list .ann-sum-row:hover { border-color: var(--accent); box-shadow: var(--shadow-card); }
 
-/* Wide screens: dock the rail beside the content instead of overlaying it. */
-@media (min-width: 1180px) {
+/* The rail NEVER auto-opens (that shifted the board unexpectedly) — it's reached
+   only via the floating Comments button, which flashes when a new comment lands. */
+@keyframes ann-toggle-pulse {
+  0% { transform: scale(1); }
+  35% { transform: scale(1.12); box-shadow: 0 0 0 4px var(--accent-soft); }
+  100% { transform: scale(1); }
+}
+.ann-rail-toggle.pulse { animation: ann-toggle-pulse 600ms var(--ease); border-color: var(--accent); color: var(--accent); }
+
+/* When opened on a roomy screen, the rail DOCKS and consumes page space (pushes
+   content) instead of covering it — so the board stays visible beside it and
+   clicking a comment reveals the highlighted item in the page. No scrim while
+   docked. Narrow screens fall back to an overlay + scrim (no room to dock). */
+@media (min-width: 980px) {
   .ann-rail-scrim { display: none !important; }
   body.ann-rail-open { padding-right: 340px; }
 }

package/src/ui/annotate.js

@@ -367,6 +367,14 @@
     if (railOpen) closeRail();
     else openRail();
   }
+  // Briefly flash the floating Comments button (used when a comment is added so
+  // the user sees it landed, without auto-opening the rail / shifting layout).
+  function pulseToggle() {
+    if (!dom || !dom.railToggle) return;
+    dom.railToggle.classList.remove('pulse');
+    void dom.railToggle.offsetWidth; // reflow so the animation restarts
+    dom.railToggle.classList.add('pulse');
+  }
   // Sync the toggle badge + rail count with the live list; hide the whole rail
   // affordance when there are no comments.
   function refreshRailChrome() {
@@ -486,13 +494,57 @@
     dom.pop.replaceChildren();
   }
 
+  // ---------- delete a comment (with confirm) ----------
+  // The × that used to delete a comment read as "close the popup". Delete is now
+  // a distinct trash button that opens a confirm modal; "Don't ask again"
+  // (default OFF) suppresses future confirms for the session (persisted best-effort).
+  const ICON_TRASH =
+    '<svg viewBox="0 0 16 16" width="13" height="13" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true">' +
+    '<path d="M2.5 4h11M6 4V2.5h4V4M5 4l.5 9h5l.5-9"/></svg>';
+  const DEL_SKIP_KEY = 'relay-ann-del-skip';
+  let delConfirmSkip = false;
+  try { delConfirmSkip = localStorage.getItem(DEL_SKIP_KEY) === '1'; } catch { /* sandbox: no storage */ }
+
+  function requestDelete(id, after) {
+    const done = () => { removeAnnotation(id); if (after) after(); };
+    if (delConfirmSkip) { done(); return; }
+    showDeleteConfirm(done);
+  }
+  function showDeleteConfirm(onConfirm) {
+    const scrim = el('div', { class: 'ann-confirm-scrim' });
+    const skip = el('input', { type: 'checkbox' });
+    const cancel = el('button', { class: 'ann-confirm-cancel', type: 'button' }, 'Cancel');
+    const del = el('button', { class: 'ann-confirm-del', type: 'button' }, 'Delete');
+    const close = () => { scrim.remove(); document.removeEventListener('keydown', onKey, true); };
+    const onKey = (e) => { if (e.key === 'Escape') { e.preventDefault(); close(); } };
+    cancel.addEventListener('click', close);
+    scrim.addEventListener('mousedown', (e) => { if (e.target === scrim) close(); });
+    del.addEventListener('click', () => {
+      if (skip.checked) { delConfirmSkip = true; try { localStorage.setItem(DEL_SKIP_KEY, '1'); } catch { /* sandbox */ } }
+      close();
+      onConfirm();
+    });
+    scrim.append(el('div', { class: 'ann-confirm', role: 'alertdialog', 'aria-label': 'Delete comment' },
+      el('div', { class: 'ann-confirm-title' }, 'Delete this comment?'),
+      el('div', { class: 'ann-confirm-msg' }, 'This removes the comment and its replies. It can’t be undone.'),
+      el('label', { class: 'ann-confirm-skip' }, skip, el('span', {}, 'Don’t ask again')),
+      el('div', { class: 'ann-confirm-actions' }, cancel, del)
+    ));
+    document.body.append(scrim);
+    document.addEventListener('keydown', onKey, true);
+    setTimeout(() => { try { cancel.focus(); } catch { /* ignore */ } }, 0);
+  }
+
   function openPopover(info, anchorEl) {
     if (disabled) return;
     ensureDom();
     closePopover();
     hidePin();
     const pop = dom.pop;
-    pop.replaceChildren(el('div', { class: 'ann-pop-label' }, humanize(info.target)));
+    // Header: target label + an explicit CLOSE button, so × always means "close".
+    const popClose = el('button', { class: 'ann-pop-close', type: 'button', title: 'Close', 'aria-label': 'Close' }, '×');
+    popClose.addEventListener('click', closePopover);
+    pop.replaceChildren(el('div', { class: 'ann-pop-head' }, el('div', { class: 'ann-pop-label' }, humanize(info.target)), popClose));
 
     // Existing comments on this exact target, rendered as threads: author
     // chip + time + delete, the comment text, its replies indented below,
@@ -502,11 +554,9 @@
     const renderExisting = () => {
       existingWrap.replaceChildren();
       for (const a of matching(info)) {
-        const del = el('button', { class: 'ann-del', type: 'button', title: 'Delete comment', 'aria-label': 'Delete comment' }, '×');
-        del.addEventListener('click', () => {
-          removeAnnotation(a.id);
-          renderExisting();
-        });
+        const del = el('button', { class: 'ann-del', type: 'button', title: 'Delete comment', 'aria-label': 'Delete comment' });
+        del.innerHTML = ICON_TRASH;
+        del.addEventListener('click', () => requestDelete(a.id, renderExisting));
         const thread = el('div', { class: 'ann-thread' },
           el('div', { class: 'ann-thread-head' }, chip(a.author), timeEl(a.createdAt), del),
           el('div', { class: 'ann-pop-text' }, a.text)
@@ -601,7 +651,9 @@
       }
     }
     changed();
-    openRail(); // surface the new comment in the sidebar, Outline-style
+    // Don't auto-open the rail — that shifts the board layout. Just flash the
+    // floating Comments button so the user notices, and opens it when they want.
+    pulseToggle();
   }
 
   // Append a user reply to a top-level annotation's thread (cap 50, like the
@@ -709,11 +761,9 @@
     // The rail has its own header chrome; standalone summaries get a heading.
     if (!isRail) target.append(el('h3', { class: 'ann-sum-head' }, `Comments (${annotations.length})`));
     for (const a of annotations) {
-      const del = el('button', { class: 'ann-del', type: 'button', title: 'Delete comment', 'aria-label': 'Delete comment' }, '×');
-      del.addEventListener('click', (e) => {
-        e.stopPropagation();
-        removeAnnotation(a.id);
-      });
+      const del = el('button', { class: 'ann-del', type: 'button', title: 'Delete comment', 'aria-label': 'Delete comment' });
+      del.innerHTML = ICON_TRASH;
+      del.addEventListener('click', (e) => { e.stopPropagation(); requestDelete(a.id); });
       // Thread meta: reply count, plus an "agent" chip when the latest entry
       // in the thread (last reply, or the comment itself) is agent-authored.
       const replyCount = Array.isArray(a.replies) ? a.replies.length : 0;

package/src/ui/app.js

@@ -597,7 +597,7 @@
     }
     if (q.other) {
       otherRadio = el('input', { type: 'radio', name: q.id });
-      const text = el('input', { type: 'text', placeholder: 'your own answer…' });
+      const text = el('textarea', { class: 'otherinput', rows: '2', placeholder: 'your own answer…' });
       text.value = (state.other[q.id] && state.other[q.id].text) || '';
       otherRadio.checked = otherOn();
       const ensureOther = () => state.other[q.id] || (state.other[q.id] = { on: false, text: text.value });
@@ -666,7 +666,7 @@
     if (q.other) {
       const oth = state.other[q.id];
       const box = el('input', { type: 'checkbox' });
-      const text = el('input', { type: 'text', placeholder: 'your own answer…' });
+      const text = el('textarea', { class: 'otherinput', rows: '2', placeholder: 'your own answer…' });
       box.checked = Boolean(oth && oth.on);
       text.value = (oth && oth.text) || '';
       const sync = () => {

package/src/ui/style.css

@@ -211,6 +211,8 @@ input[type="text"]:focus, textarea:focus {
   box-shadow: 0 0 0 3px var(--accent-soft);
 }
 textarea { min-height: 90px; resize: vertical; }
+/* the inline "Other" free-text is a compact 2-row textarea, not a tall one */
+.otherbox .otherinput { min-height: 2.6em; padding: 8px 12px; }
 
 .qnotewrap { margin-top: 10px; }
 .qnotewrap .qnote { font-size: 0.88rem; padding: 8px 12px; min-height: 52px; resize: vertical; }