@khanglvm/relay 0.12.1 → 0.12.2

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.2",
   "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

@@ -274,11 +274,15 @@
 .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) {
-  .ann-rail-scrim { display: none !important; }
-  body.ann-rail-open { padding-right: 340px; }
+/* The rail always overlays the board (scrim dims, content never moves) — opening
+   it must NOT shift layout, on any width. 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); }
 
 /* ---------- jump-to flash ---------- */
 .ann-flash { animation: ann-flash 1s var(--ease); }

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() {
@@ -601,7 +609,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

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; }