@khanglvm/relay 0.13.9 → 0.14.0

package/README.md

@@ -43,7 +43,7 @@ step, leaving any boards you have open untouched.
 relay also runs as an **MCP App** ([SEP-1865](https://modelcontextprotocol.io/seps/1865-mcp-apps-interactive-user-interfaces-for-mcp))
 — so the same board renders **inline, right in the conversation**, on Claude
 desktop **and mobile** and in Codex, no browser tab. `rly mcp` is a
-zero-dependency stdio MCP server; register it once and the agent gets two tools,
+stdio MCP server with no npm runtime dependencies; register it once and the agent gets two tools,
 `relay_ask` (collect decisions/feedback with real form controls) and
 `relay_show` (present a plan, diagram, diff, table, or prototype):
 
@@ -81,8 +81,9 @@ unchanged; pick whichever surface fits.
 | Feedback = another wall of text | Click any chart point, diagram node, table cell, or sentence to comment — the agent replies and the thread grows on the board |
 
 Everything autosaves in real time (drafts survive timeouts), multiple boards
-run at once, and the package has **zero runtime dependencies** — plain
-Node ≥ 18; Chart.js / Mermaid / Graphviz are vendored and lazy-loaded offline.
+run at once, and the package has **zero npm runtime dependencies** — plain
+Node ≥ 18. Browser-side Chart.js, Mermaid, and Viz.js assets are vendored in
+the package and lazy-loaded offline when a board actually needs them.
 
 ## Learn more
 
@@ -91,6 +92,7 @@ Node ≥ 18; Chart.js / Mermaid / Graphviz are vendored and lazy-loaded offline.
 | `rly help` | every command at a glance |
 | `rly git pick` / `rly git cherry-pick` | choose commit actions and rank the order directly on a board; add `--code` to cherry-pick with split code review and per-hunk Apply/Skip/Hold |
 | `rly git conflict [files…]` | auto-detect unmerged conflict files, or open specific local paths, and return resolved content in `result.blockEdits` |
+| `rly share <board-id>` | activate/list/revoke same-Wi-Fi reviewer or collaborator links for a running browser board |
 | `rly view <file.md> …` | open a quick read-only board that renders local markdown file(s), data files, or PDFs — library-free; great for plans, READMEs, reports, quotes |
 | `rly install --target <agent>` | write relay's rules into an agent's instruction file — `claude` `codex` `cursor` `copilot` `kiro` `windsurf` `cline` `gemini` `opencode` `droid` `agents`; `--all`, `--scope`, `--print`, `--list` |
 | `rly upgrade` | update the CLI **and** refresh the skill in one step (safe around open boards; `--dry-run`, `--cli-only`, `--skill-only`) |
@@ -102,14 +104,14 @@ Node ≥ 18; Chart.js / Mermaid / Graphviz are vendored and lazy-loaded offline.
 ## Development
 
 ```sh
-npm test     # zero-dep smoke tests (spawns real servers, fake-submits)
+npm test     # smoke tests with no external services (spawns real servers, fake-submits)
 ```
 
 ## Changelog
 
 ### 0.11.0 — render inline inside the Claude & Codex apps (MCP App)
 - **`rly mcp` — relay as an MCP App** ([SEP-1865](https://modelcontextprotocol.io/seps/1865-mcp-apps-interactive-user-interfaces-for-mcp),
-  extension `io.modelcontextprotocol/ui`). A zero-dependency stdio MCP server
+  extension `io.modelcontextprotocol/ui`). A stdio MCP server with no npm runtime dependencies
   that declares a `ui://relay/board` resource (`text/html;profile=mcp-app`) and
   two tools, **`relay_ask`** and **`relay_show`**, linked to it via
   `_meta.ui.resourceUri` (plus `openai/outputTemplate` for ChatGPT/Codex). The
@@ -172,7 +174,8 @@ npm test     # zero-dep smoke tests (spawns real servers, fake-submits)
 - **Durable drafts / rescue** — every autosave mirrors to `localStorage`; a
   board whose connection drops blocks further input instead of losing it, and
   `rly rescue <id>` re-serves on the same port so an open tab reconnects.
-- Still **zero runtime dependencies**, offline, and cross-platform.
+- Still **zero npm runtime dependencies**, offline, and cross-platform. Vendored
+  browser libraries are loaded only for boards that need them.
 
 ### 0.9.1
 - The board **intro renders as markdown** (bold/italic/code/links/lists).

package/docs/AGENT.md

@@ -71,6 +71,28 @@ Answers **autosave in real time** as the user fills the board — a page reload
 restores them, and a draft survives timeouts/cancellation (included in those
 results), so partial input is never lost.
 
+## Same-Wi-Fi sharing
+
+Browser boards are local-owner only by default. A same-Wi-Fi phone/tablet/other
+laptop gets a locked page until sharing is explicitly activated. The owner can
+click **Share** at the bottom of the board, or you can manage the same links for
+the user:
+
+```sh
+rly share b-xxxxx                         # list active share roles
+rly share b-xxxxx --role review           # reviewer: add comments only
+rly share b-xxxxx --role collab           # collaborator: edit/comment/submit
+rly share b-xxxxx --role review --revoke  # revoke one role
+rly share b-xxxxx --revoke --all          # revoke all active links
+```
+
+Use `review` unless the user explicitly wants the other device to submit as the
+owner. Reviewers cannot change answers, submit, edit comments, or delete
+comments; their autosaves merge new comments into the existing draft.
+Collaborators can edit answers, comment, open allowed local file links, and
+submit. Shared viewers refresh from the live draft when another viewer saves,
+deferred while someone is typing/commenting.
+
 ## Inline mode — relay as an MCP App (Claude & Codex apps)
 
 Everything above is the **CLI** surface (you run `rly` in a terminal and read

package/package.json

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

@@ -174,6 +174,28 @@ Exit codes: 0 submitted · 2 timeout · 3 cancelled · 5 not found. On
 timeout/cancel the result still contains the autosaved `draft` of partial
 answers and any annotations written so far.
 
+## Same-Wi-Fi sharing
+
+Browser boards are local-owner only by default. A phone/tablet/other laptop on
+the same Wi-Fi gets a locked page until sharing is explicitly activated. The
+owner can click **Share** at the bottom of the board, or an agent can manage the
+same links with `rly share`:
+
+```sh
+rly share b-xxxxx                         # list active share roles
+rly share b-xxxxx --role review           # activate a reviewer link
+rly share b-xxxxx --role collab           # activate a collaborator link
+rly share b-xxxxx --role review --revoke  # revoke one role
+rly share b-xxxxx --revoke --all          # revoke all active share links
+```
+
+Use `review` when the other device should add comments only. Reviewers cannot
+change answers, submit, edit comments, or delete comments; their autosaves merge
+new comments into the existing draft. Use `collab` only when the user explicitly
+wants that device to act as the owner: collaborators can edit answers, comment,
+open allowed local file links, and submit. Shared viewers refresh from the live
+draft when another viewer saves, deferred while someone is typing/commenting.
+
 ## Minimal spec
 
 ```json
@@ -347,8 +369,9 @@ the option (and stays annotatable); the label row selects. Use per-option
 blocks whenever a question's choices have visual/example context; skip them
 for plainly textual options.
 
-Chart.js, Mermaid, and Graphviz are **vendored and lazy-loaded** — the base board
-stays dependency-free. PlantUML uses the public plantuml.com server by default;
+Chart.js, Mermaid, and Graphviz are **vendored and lazy-loaded** — the package
+has no npm runtime dependencies, but these browser assets are bundled for rich
+blocks. PlantUML uses the public plantuml.com server by default;
 pass `"server"` for a self-hosted instance. Legacy `"html"` / `"htmlFile"` /
 `"htmlHeight"` on root or questions are still accepted and normalised automatically.
 

package/src/cli.js

@@ -33,7 +33,7 @@ const VALUED_FLAGS = new Set([
   'file', 'html', 'html-file', 'title', 'intro', 'timeout', 'port',
   'submit-label', 'height', 'limit', 'target', 'id', 'replies',
   'on-result', 'notify-cmd', 'idle-grace', 'scope', 'range',
-  'host', 'token', 'allow-origin',
+  'host', 'token', 'allow-origin', 'role',
 ]);
 
 function camel(key) {
@@ -779,6 +779,45 @@ async function cmdResult(args) {
   return 5;
 }
 
+async function cmdShare(args) {
+  const record = mustLoad(args._[0]);
+  const running = loadRunning(record.id);
+  if (!running || !isAlive(running.pid)) {
+    throw new CliError(`board "${record.id}" is not running. Use \`rly reopen ${record.id} --detach\` first.`, 5);
+  }
+  const role = args.all ? 'all' : args.role;
+  if (role !== undefined && !['collab', 'review', 'all'].includes(role)) {
+    throw new CliError('--role must be collab or review.', 4);
+  }
+  const shareUrl = new URL('/api/share', running.url);
+  let res;
+  try {
+    if (args.revoke) {
+      res = await fetch(shareUrl, {
+        method: 'DELETE',
+        headers: { 'content-type': 'application/json' },
+        body: JSON.stringify({ role: role || 'all' }),
+      });
+    } else if (role && role !== 'all') {
+      res = await fetch(shareUrl, {
+        method: 'POST',
+        headers: { 'content-type': 'application/json' },
+        body: JSON.stringify({ role }),
+      });
+    } else {
+      res = await fetch(shareUrl, { method: 'GET' });
+    }
+  } catch (err) {
+    throw new CliError(`could not reach board "${record.id}" at ${running.url}: ${String((err && err.message) || err)}`, 5);
+  }
+  const body = await res.json().catch(() => null);
+  if (!res.ok) {
+    throw new CliError((body && body.error) || `share request failed with HTTP ${res.status}`, res.status === 400 ? 4 : 5);
+  }
+  printJson({ status: args.revoke ? 'revoked' : role && role !== 'all' ? 'active' : 'shares', boardId: record.id, ...body });
+  return 0;
+}
+
 function cmdList(args) {
   const running = listRunning();
   if (args.json) {
@@ -1056,6 +1095,10 @@ the user should view — put it in relay instead of printing it.**
 - Point the user at a file with a clickable local path in a markdown block; embed a
   screen recording with a \`video\` block; when answer choices are visual, give each
   option its own visual (\`options[].blocks\`) so the user picks by looking.
+- Same-Wi-Fi sharing is locked by default. When the user wants another device to
+  review or co-fill a running board, manage explicit links with \`rly share <id>\`:
+  \`--role review\` creates a comments-only reviewer link, \`--role collab\` creates
+  an edit/comment/submit link, and \`--revoke\` disables active links.
 - **There's a purpose-built component for most content — use the MOST SPECIFIC one,
   never plain prose when a block fits.** Blocks: \`table\` (sortable/filterable/CSV,
   load from .csv/.json), \`chart\`, \`kpi\` (stat cards), \`mermaid\`/\`graphviz\`/\`plantuml\`,
@@ -1561,6 +1604,11 @@ USAGE
                                       NB: also writes the FULL result to "resultFile" (first field) —
                                         read that file if your shell truncates stdout; never pipe to head/tail
   rly result <id>                     result/status now (includes live autosaved draft + presence while open)
+  rly share <id>                      list active same-Wi-Fi share links for a running board
+  rly share <id> --role review        activate a reviewer link (comments only)
+  rly share <id> --role collab        activate a collaborator link (edit/comment/submit)
+  rly share <id> --role review --revoke
+                                      revoke one share role; use --revoke --all to disable all roles
   rly list [--json]                   running boards
   rly open [id]                       re-open the browser tab of a running board
   rly reopen <id> [--replies f.json]  serve a saved board again, prefilled with saved answers
@@ -1644,6 +1692,8 @@ export async function main(argv) {
         return await cmdWait(parseArgs(rest));
       case 'result':
         return await cmdResult(parseArgs(rest));
+      case 'share':
+        return await cmdShare(parseArgs(rest));
       case 'list':
         return cmdList(parseArgs(rest));
       case 'open':

package/src/mcp.js

@@ -1,8 +1,9 @@
 // mcp.js — relay as an MCP App (SEP-1865, extension "io.modelcontextprotocol/ui").
 //
-// `rly mcp` starts a zero-dependency MCP server over stdio. Register it with a
-// host that supports MCP Apps (Claude desktop/mobile, Codex, …) and relay's
-// boards render INLINE in the conversation instead of opening a browser tab:
+// `rly mcp` starts an MCP server over stdio with no npm runtime dependencies.
+// Register it with a host that supports MCP Apps (Claude desktop/mobile, Codex,
+// …) and relay's boards render INLINE in the conversation instead of opening a
+// browser tab:
 //
 //   • the server declares a UI resource  ui://relay/board  (text/html;profile=mcp-app)
 //   • the tools `relay_ask` / `relay_show` link to it via _meta.ui.resourceUri

package/src/server.js

@@ -96,7 +96,46 @@ function vendorPresent(file) {
   }
 }
 
-function buildPage(record, rev) {
+function cleanShareHost(raw) {
+  const s = String(raw || '').trim();
+  if (!s) return null;
+  let host = s;
+  try {
+    host = s.includes('://') ? new URL(s).hostname : s;
+  } catch {
+    host = s;
+  }
+  host = host.replace(/^https?:\/\//, '').split('/')[0].split(':')[0].trim();
+  if (!host || host === '127.0.0.1' || host === 'localhost') return null;
+  return host;
+}
+
+function isPrivateIpv4(address) {
+  if (!/^(\d{1,3}\.){3}\d{1,3}$/.test(address)) return false;
+  const parts = address.split('.').map((n) => Number(n));
+  if (parts.some((n) => !Number.isInteger(n) || n < 0 || n > 255)) return false;
+  return (
+    parts[0] === 10 ||
+    (parts[0] === 172 && parts[1] >= 16 && parts[1] <= 31) ||
+    (parts[0] === 192 && parts[1] === 168)
+  );
+}
+
+function shareHost() {
+  const forced = cleanShareHost(process.env.RLY_SHARE_HOST);
+  if (forced) return forced;
+  const candidates = [];
+  const nets = os.networkInterfaces();
+  for (const list of Object.values(nets)) {
+    for (const net of list || []) {
+      if (!net || net.internal || net.family !== 'IPv4') continue;
+      candidates.push(net.address);
+    }
+  }
+  return candidates.find(isPrivateIpv4) || candidates[0] || null;
+}
+
+function buildPage(record, rev, { access = null, draftRev = 0 } = {}) {
   const html = fs.readFileSync(path.join(UI_DIR, 'index.html'), 'utf8');
   const css = readUi('style.css');
   const blocksCss = readUi('blocks.css');
@@ -136,7 +175,7 @@ function buildPage(record, rev) {
         updatedAt: record.draft.updatedAt || null,
       }
     : null;
-  const boot = { boardId: record.id, spec: clientSpec, prefill, pref: loadPref(), vendor, rev };
+  const boot = { boardId: record.id, spec: clientSpec, prefill, pref: loadPref(), vendor, rev, draftRev, access };
   const json = JSON.stringify(boot).replace(/</g, '\\u003c');
   return html
     .split('__TITLE__').join(escapeHtml(spec.title))
@@ -149,6 +188,14 @@ function buildPage(record, rev) {
     .split('__BOOT_JSON__').join(json);
 }
 
+function buildLockedPage(title = 'Relay board') {
+  return '<!doctype html><html><head><meta charset="utf-8">' +
+    '<meta name="viewport" content="width=device-width, initial-scale=1">' +
+    '<title>' + escapeHtml(title) + '</title>' +
+    '<style>body{margin:0;font:16px/1.5 -apple-system,BlinkMacSystemFont,"Segoe UI",sans-serif;background:#fcfbf9;color:#1c1b19;display:grid;min-height:100vh;place-items:center}.box{max-width:420px;padding:28px;text-align:center}.title{font-size:22px;font-weight:650;margin-bottom:8px}.sub{color:#57534e}</style>' +
+    '</head><body><div class="box"><div class="title">Share link not active</div><div class="sub">Ask the board owner to use Share and choose a permission before opening this board from another device.</div></div></body></html>';
+}
+
 // Validates + sanitizes one annotation's threaded replies. Keeps only
 // well-formed {author, text, createdAt} entries; caps at 50; coerces author.
 function sanitizeReplies(value) {
@@ -184,6 +231,50 @@ function sanitizeAnnotations(value) {
   return out;
 }
 
+function nextAnnotationId(existing, used) {
+  let max = 0;
+  for (const a of existing) {
+    const m = /^a(\d+)$/.exec(String(a && a.id || ''));
+    if (m) max = Math.max(max, Number.parseInt(m[1], 10) || 0);
+  }
+  let id;
+  do {
+    id = 'a' + (++max);
+  } while (used.has(id));
+  used.add(id);
+  return id;
+}
+
+function sameReply(a, b) {
+  return a && b && a.author === b.author && a.text === b.text && a.createdAt === b.createdAt;
+}
+
+function mergeReviewAnnotations(existingValue, incomingValue) {
+  const existing = sanitizeAnnotations(existingValue);
+  const incoming = sanitizeAnnotations(incomingValue);
+  const out = existing.map((a) => ({ ...a, replies: Array.isArray(a.replies) ? [...a.replies] : [] }));
+  const byId = new Map(out.map((a) => [String(a.id || ''), a]));
+  const used = new Set(out.map((a) => String(a.id || '')).filter(Boolean));
+  for (const ann of incoming) {
+    const id = String(ann.id || '');
+    const current = byId.get(id);
+    if (!current) {
+      const next = { ...ann, id: id && !used.has(id) ? id : nextAnnotationId(out, used) };
+      next.replies = Array.isArray(next.replies) ? next.replies : [];
+      out.push(next);
+      byId.set(next.id, next);
+      used.add(next.id);
+      continue;
+    }
+    const replies = Array.isArray(current.replies) ? current.replies : (current.replies = []);
+    for (const r of Array.isArray(ann.replies) ? ann.replies : []) {
+      if (replies.length >= 50) break;
+      if (!replies.some((x) => sameReply(x, r))) replies.push(r);
+    }
+  }
+  return out.slice(0, 500);
+}
+
 function limitString(v, max) {
   return typeof v === 'string' ? v.slice(0, max) : '';
 }
@@ -390,12 +481,13 @@ function buildOpenAllowlist(spec, baseCwd) {
 // True when an Origin header (if present) belongs to this board's own server.
 // Same-origin fetches send no Origin or our own; a foreign Origin is a
 // cross-site POST and must not be allowed to open a local file.
-function sameOrigin(req, port) {
+function sameOrigin(req, port, extraHosts = []) {
   const origin = req.headers.origin;
   if (!origin) return true;
   try {
-    const h = new URL(origin).host;
-    return h === `127.0.0.1:${port}` || h === `localhost:${port}`;
+    const u = new URL(origin);
+    if (u.port !== String(port)) return false;
+    return new Set(['127.0.0.1', 'localhost', ...extraHosts.filter(Boolean)]).has(u.hostname);
   } catch {
     return false;
   }
@@ -606,7 +698,13 @@ export async function runBoard({ id, port = 0, open = true, timeoutSec = 1800, q
   // Mutation token: only `rly update` (which reads the running-file record)
   // can authenticate to POST /api/update. Never embedded in the page/boot.
   const token = crypto.randomBytes(16).toString('hex');
+  const shareTokens = {
+    collab: crypto.randomBytes(16).toString('hex'),
+    review: crypto.randomBytes(16).toString('hex'),
+  };
+  const activeShares = { collab: false, review: false };
   let rev = 1;
+  let draftRev = Number.isFinite(record.draftRev) ? record.draftRev : 0;
   let status = 'open';
   let finished = false;
   // Soft timeout: the board's time is up and a `timeout` result was handed back
@@ -616,6 +714,58 @@ export async function runBoard({ id, port = 0, open = true, timeoutSec = 1800, q
   let softTimedOut = false;
   // Latest client presence ping (null until the first ping arrives).
   let presence = null;
+  let actualPort = 0;
+  let url = '';
+  const advertisedHost = shareHost();
+  const accessFor = (req, reqUrl = null) => {
+    const host = String(req.headers.host || '').split(':')[0];
+    if (host === '127.0.0.1' || host === 'localhost') {
+      return {
+        role: 'owner',
+        canShare: true,
+        canSubmit: true,
+        canEditAnswers: true,
+        canComment: true,
+        canEditComments: true,
+        canDeleteComments: true,
+      };
+    }
+    const tokenValue = String(req.headers['x-relay-share-token'] || (reqUrl && reqUrl.searchParams.get('token')) || '');
+    if (activeShares.collab && tokenValue === shareTokens.collab) {
+      return {
+        role: 'collab',
+        token: shareTokens.collab,
+        canShare: false,
+        canSubmit: true,
+        canEditAnswers: true,
+        canComment: true,
+        canEditComments: true,
+        canDeleteComments: true,
+      };
+    }
+    if (activeShares.review && tokenValue === shareTokens.review) {
+      return {
+        role: 'review',
+        token: shareTokens.review,
+        canShare: false,
+        canSubmit: false,
+        canEditAnswers: false,
+        canComment: true,
+        canEditComments: false,
+        canDeleteComments: false,
+      };
+    }
+    return {
+      role: 'locked',
+      canShare: false,
+      canSubmit: false,
+      canEditAnswers: false,
+      canComment: false,
+      canEditComments: false,
+      canDeleteComments: false,
+    };
+  };
+  const shareUrlFor = (role) => advertisedHost ? `http://${advertisedHost}:${actualPort}/?share=${role}&token=${shareTokens[role]}` : null;
   let resolveDone;
   const done = new Promise((r) => {
     resolveDone = r;
@@ -627,11 +777,20 @@ export async function runBoard({ id, port = 0, open = true, timeoutSec = 1800, q
     const theme = reqUrl.searchParams.get('theme') === 'dark' ? 'dark' : 'light';
     try {
       if (req.method === 'GET' && pathname === '/') {
-        sendHtml(res, buildPage(record, rev));
+        const access = accessFor(req, reqUrl);
+        if (access.role === 'locked') {
+          sendHtml(res, buildLockedPage(record.spec.title));
+        } else {
+          sendHtml(res, buildPage(record, rev, { access, draftRev }));
+        }
       } else if (req.method === 'GET' && pathname === '/api/board') {
+        if (accessFor(req, reqUrl).role === 'locked') return sendJson(res, 403, { error: 'share link is not active' });
         sendJson(res, 200, { id: record.id, spec: record.spec, draft: record.draft, result: record.result });
       } else if (req.method === 'GET' && pathname === '/api/status') {
-        sendJson(res, 200, { status, rev, softTimedOut });
+        sendJson(res, 200, { status, rev, draftRev, softTimedOut });
+      } else if (req.method === 'GET' && pathname === '/api/draft') {
+        if (accessFor(req, reqUrl).role === 'locked') return sendJson(res, 403, { error: 'share link is not active' });
+        sendJson(res, 200, { draft: record.draft || null, draftRev });
       } else if (req.method === 'POST' && pathname === '/api/ping') {
         const body = JSON.parse((await readBody(req)) || '{}');
         // Validate body shape: visible/focused booleans, idleMs finite >= 0.
@@ -728,7 +887,9 @@ export async function runBoard({ id, port = 0, open = true, timeoutSec = 1800, q
       } else if (req.method === 'POST' && pathname === '/api/open') {
         // Open a board-referenced local file in the OS default app. Guarded by
         // a same-origin check + an allowlist of paths the board actually links.
-        if (!sameOrigin(req, actualPort)) return sendJson(res, 403, { error: 'cross-origin requests cannot open files' });
+        if (!sameOrigin(req, actualPort, [advertisedHost])) return sendJson(res, 403, { error: 'cross-origin requests cannot open files' });
+        const access = accessFor(req, reqUrl);
+        if (access.role !== 'owner' && access.role !== 'collab') return sendJson(res, 403, { error: 'this share cannot open local files' });
         const body = JSON.parse((await readBody(req)) || '{}');
         const raw = typeof body.path === 'string' ? body.path : '';
         if (!raw.trim()) return sendJson(res, 400, { error: 'missing "path"' });
@@ -748,18 +909,36 @@ export async function runBoard({ id, port = 0, open = true, timeoutSec = 1800, q
         if (!openUrl(target)) return sendJson(res, 500, { error: 'could not open the file' });
         sendJson(res, 200, { ok: true, path: target, name: path.basename(target) });
       } else if (req.method === 'POST' && pathname === '/api/draft') {
+        const access = accessFor(req, reqUrl);
+        if (access.role === 'locked') return sendJson(res, 403, { error: 'share link is not active' });
         const body = JSON.parse((await readBody(req)) || '{}');
-        record.draft = {
-          answers: body.answers && typeof body.answers === 'object' ? body.answers : {},
-          comment: typeof body.comment === 'string' ? body.comment : '',
-          notes: body.notes && typeof body.notes === 'object' ? body.notes : {},
-          annotations: sanitizeAnnotations(body.annotations),
-          blockEdits: sanitizeBlockEdits(body.blockEdits),
-          updatedAt: new Date().toISOString(),
-        };
+        if (access.role === 'review') {
+          const current = record.draft && typeof record.draft === 'object' ? record.draft : {};
+          record.draft = {
+            answers: current.answers && typeof current.answers === 'object' ? current.answers : {},
+            comment: typeof current.comment === 'string' ? current.comment : '',
+            notes: current.notes && typeof current.notes === 'object' ? current.notes : {},
+            annotations: mergeReviewAnnotations(current.annotations, body.annotations),
+            blockEdits: current.blockEdits && typeof current.blockEdits === 'object' ? current.blockEdits : {},
+            updatedAt: new Date().toISOString(),
+          };
+        } else {
+          record.draft = {
+            answers: body.answers && typeof body.answers === 'object' ? body.answers : {},
+            comment: typeof body.comment === 'string' ? body.comment : '',
+            notes: body.notes && typeof body.notes === 'object' ? body.notes : {},
+            annotations: sanitizeAnnotations(body.annotations),
+            blockEdits: sanitizeBlockEdits(body.blockEdits),
+            updatedAt: new Date().toISOString(),
+          };
+        }
+        record.draftRev = ++draftRev;
         saveBoard(record);
-        sendJson(res, 200, { ok: true });
+        sendJson(res, 200, { ok: true, draftRev });
       } else if (req.method === 'POST' && pathname === '/api/submit') {
+        const access = accessFor(req, reqUrl);
+        if (access.role === 'locked') return sendJson(res, 403, { error: 'share link is not active' });
+        if (!access.canSubmit) return sendJson(res, 403, { error: 'this share can comment only' });
         if (status !== 'open') return sendJson(res, 409, { error: 'board already finished' });
         const body = JSON.parse((await readBody(req)) || '{}');
         const answers = body.answers && typeof body.answers === 'object' ? body.answers : {};
@@ -774,6 +953,36 @@ export async function runBoard({ id, port = 0, open = true, timeoutSec = 1800, q
           annotations: sanitizeAnnotations(body.annotations),
           blockEdits: sanitizeBlockEdits(body.blockEdits),
         });
+      } else if (req.method === 'GET' && pathname === '/api/share') {
+        if (accessFor(req, reqUrl).role !== 'owner') return sendJson(res, 403, { error: 'only the board owner can manage sharing' });
+        const roles = {};
+        for (const role of ['collab', 'review']) {
+          roles[role] = {
+            active: activeShares[role] === true,
+            url: activeShares[role] === true ? shareUrlFor(role) : null,
+          };
+        }
+        sendJson(res, 200, { ok: true, roles });
+      } else if (req.method === 'POST' && pathname === '/api/share') {
+        if (accessFor(req, reqUrl).role !== 'owner') return sendJson(res, 403, { error: 'only the board owner can activate sharing' });
+        if (!advertisedHost) return sendJson(res, 400, { error: 'no LAN IPv4 address found for sharing' });
+        const body = JSON.parse((await readBody(req)) || '{}');
+        const role = body.role === 'review' ? 'review' : body.role === 'collab' ? 'collab' : null;
+        if (!role) return sendJson(res, 400, { error: 'role must be "collab" or "review"' });
+        activeShares[role] = true;
+        sendJson(res, 200, { ok: true, role, url: shareUrlFor(role) });
+      } else if (req.method === 'DELETE' && pathname === '/api/share') {
+        if (accessFor(req, reqUrl).role !== 'owner') return sendJson(res, 403, { error: 'only the board owner can manage sharing' });
+        const body = JSON.parse((await readBody(req)) || '{}');
+        const role = body.role === 'review' ? 'review' : body.role === 'collab' ? 'collab' : body.role === 'all' ? 'all' : null;
+        if (!role) return sendJson(res, 400, { error: 'role must be "collab", "review", or "all"' });
+        if (role === 'all') {
+          activeShares.collab = false;
+          activeShares.review = false;
+        } else {
+          activeShares[role] = false;
+        }
+        sendJson(res, 200, { ok: true, role, active: false });
       } else {
         sendJson(res, 404, { error: 'not found' });
       }
@@ -804,15 +1013,15 @@ export async function runBoard({ id, port = 0, open = true, timeoutSec = 1800, q
         }
       };
       server.once('error', onErr);
-      server.listen(p, '127.0.0.1', () => {
+      server.listen(p, '0.0.0.0', () => {
         server.removeListener('error', onErr);
         resolve();
       });
     };
     bind(port, true);
   });
-  const actualPort = server.address().port;
-  const url = `http://127.0.0.1:${actualPort}/`;
+  actualPort = server.address().port;
+  url = `http://127.0.0.1:${actualPort}/`;
   // Remember the port this board last bound, so `rly rescue <id>` can re-serve
   // on the SAME port — letting a still-open (but disconnected) browser tab
   // reconnect to its relative /api/* URLs without the user touching anything.

package/src/ui/annotate.js

@@ -114,6 +114,7 @@
   // Frozen by the host (e.g. relay's connection-lost block): suppress every way
   // to START a comment, so the user can't type feedback that won't be saved.
   let disabled = false;
+  let permissions = { add: true, edit: true, delete: true, reply: true };
   let badgeTimer = 0;
   let railOpen = false;
 
@@ -513,6 +514,7 @@
   try { delConfirmSkip = localStorage.getItem(DEL_SKIP_KEY) === '1'; } catch { /* sandbox: no storage */ }
 
   function requestDelete(id, after) {
+    if (!permissions.delete) return;
     const done = () => { removeAnnotation(id); if (after) after(); };
     if (delConfirmSkip) { done(); return; }
     showDeleteConfirm(done);
@@ -655,6 +657,7 @@
 
   // ---------- mutations ----------
   function addAnnotation(info, text) {
+    if (!permissions.add) return;
     annotations.push({
       id: 'a' + (++idCounter),
       questionId: info.questionId !== undefined ? info.questionId : null,
@@ -687,6 +690,7 @@
   // Append a user reply to a top-level annotation's thread (cap 50, like the
   // server). Empty text is ignored by callers.
   function addReply(id, text) {
+    if (!permissions.reply) return;
     const a = annotations.find((x) => x.id === id);
     if (!a) return;
     if (!Array.isArray(a.replies)) a.replies = [];
@@ -701,6 +705,7 @@
 
   // Edit a top-level comment's text in place (author edits their own comment).
   function editAnnotation(id, text) {
+    if (!permissions.edit) return;
     const a = annotations.find((x) => x.id === id);
     if (!a) return;
     const t = String(text).slice(0, 5000).trim();
@@ -710,6 +715,7 @@
   }
 
   function removeAnnotation(id) {
+    if (!permissions.delete) return;
     const i = annotations.findIndex((a) => a.id === id);
     if (i < 0) return;
     const removed = annotations[i];
@@ -844,11 +850,9 @@
   }
 
   // ---------- public API ----------
-  function init(opts = {}) {
-    ensureDom();
-    // Normalize threads: missing author -> 'user', missing replies -> [].
-    annotations = Array.isArray(opts.initial)
-      ? opts.initial.map((a) => ({
+  function normalizeList(value) {
+    return Array.isArray(value)
+      ? value.map((a) => ({
           ...a,
           author: a.author === 'agent' ? 'agent' : 'user',
           replies: Array.isArray(a.replies)
@@ -862,12 +866,28 @@
             : [],
         }))
       : [];
-    onChange = typeof opts.onChange === 'function' ? opts.onChange : null;
+  }
+
+  function resetCounter() {
     idCounter = 0;
     for (const a of annotations) {
       const m = /^a(\d+)$/.exec(String(a.id || ''));
       if (m) idCounter = Math.max(idCounter, parseInt(m[1], 10));
     }
+  }
+
+  function init(opts = {}) {
+    ensureDom();
+    // Normalize threads: missing author -> 'user', missing replies -> [].
+    annotations = normalizeList(opts.initial);
+    onChange = typeof opts.onChange === 'function' ? opts.onChange : null;
+    permissions = {
+      add: !(opts.permissions && opts.permissions.add === false),
+      edit: !(opts.permissions && opts.permissions.edit === false),
+      delete: !(opts.permissions && opts.permissions.delete === false),
+      reply: !(opts.permissions && opts.permissions.reply === false),
+    };
+    resetCounter();
     scheduleBadgeRefresh();
     renderSummaries();
     refreshRailChrome();
@@ -938,6 +958,14 @@
     return annotations.slice();
   }
 
+  function setList(next) {
+    annotations = normalizeList(next);
+    resetCounter();
+    scheduleBadgeRefresh();
+    renderSummaries();
+    refreshRailChrome();
+  }
+
   // True while the user is mid-comment: the popover is open, which hosts both
   // the "Add a comment" box and every thread's reply input. That text lives
   // only in the DOM until Save, so the board must not reload it away.
@@ -968,5 +996,5 @@
     renderSummaryInto(target);
   }
 
-  window.RelayAnnotate = { init, register, enableTextSelection, openExternal, list, renderSummary, onBadgeRefresh, teardown, isComposing, flushOpen, setDisabled };
+  window.RelayAnnotate = { init, register, enableTextSelection, openExternal, list, setList, renderSummary, onBadgeRefresh, teardown, isComposing, flushOpen, setDisabled };
 })();

package/src/ui/app.js

@@ -3,6 +3,16 @@
 
   const boot = JSON.parse(document.getElementById('boot').textContent);
   const spec = boot.spec;
+  const access = boot.access || {
+    role: 'owner',
+    canShare: true,
+    canSubmit: true,
+    canEditAnswers: true,
+    canComment: true,
+    canEditComments: true,
+    canDeleteComments: true,
+  };
+  if (access.role) document.documentElement.dataset.accessRole = access.role;
   const QS = spec.questions || [];
   const app = document.getElementById('app');
   const banner = document.getElementById('banner');
@@ -10,6 +20,11 @@
   // compares /api/status.rev to this and reloads the board when it advances
   // (an agent ran `rly update`).
   const bootRev = typeof boot.rev === 'number' ? boot.rev : null;
+  let seenDraftRev = typeof boot.draftRev === 'number' ? boot.draftRev : 0;
+
+  function authHeaders(extra = {}) {
+    return access.token ? { ...extra, 'x-relay-share-token': access.token } : extra;
+  }
 
   // ---------- helpers ----------
   function el(tag, attrs = {}, ...children) {
@@ -453,10 +468,12 @@
     try {
       const r = await fetch('/api/draft', {
         method: 'POST',
-        headers: { 'content-type': 'application/json' },
+        headers: authHeaders({ 'content-type': 'application/json' }),
         body: JSON.stringify(payload()),
       });
       if (!r.ok) throw new Error('draft rejected');
+      const body = await r.json().catch(() => null);
+      if (body && typeof body.draftRev === 'number') seenDraftRev = body.draftRev;
       saveFailures = 0;
       if (seq === saveSeq && saveEl && !submitted && !persistenceLost) saveEl.textContent = 'draft saved ✓';
     } catch {
@@ -513,6 +530,12 @@
   if (Annotate) {
     Annotate.init({
       initial: state.annotations,
+      permissions: {
+        add: access.canComment !== false,
+        edit: access.canEditComments !== false,
+        delete: access.canDeleteComments !== false,
+        reply: access.canComment !== false,
+      },
       onChange: (list) => {
         state.annotations = list;
         scheduleSave();
@@ -1019,6 +1042,10 @@
       sessionStorage.removeItem('relay-updated');
       showToast('Board updated by the agent');
     }
+    if (sessionStorage.getItem('relay-draft-updated') === '1') {
+      sessionStorage.removeItem('relay-draft-updated');
+      showToast('Board refreshed with shared changes');
+    }
   } catch {
     // sessionStorage may be unavailable (privacy mode) — non-fatal
   }
@@ -1099,8 +1126,112 @@
   saveEl = el('span', { class: 'savestate' }, '');
   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' }, `relay · ${boot.boardId}`));
+  const submitbar = el('div', { class: 'submitbar' }, submitBtn, hint, saveEl);
+  app.append(submitbar);
+
+  function copyText(text, btn) {
+    const done = () => {
+      if (!btn) return;
+      const old = btn.textContent;
+      btn.textContent = 'Copied';
+      setTimeout(() => { btn.textContent = old; }, 1800);
+    };
+    if (navigator.clipboard && navigator.clipboard.writeText) {
+      navigator.clipboard.writeText(text).then(done).catch(() => {});
+      return;
+    }
+    const ta = document.createElement('textarea');
+    ta.value = text;
+    ta.style.position = 'fixed';
+    ta.style.opacity = '0';
+    document.body.append(ta);
+    ta.select();
+    try { document.execCommand('copy'); done(); } catch {}
+    ta.remove();
+  }
+
+  function openSharePanel(host) {
+    const panel = el('div', { class: 'share-panel' },
+      el('div', { class: 'share-title' }, 'Share this board'),
+      el('div', { class: 'share-desc' }, 'Choose a permission. The link starts working only after you confirm.'),
+      el('button', { class: 'share-choice', type: 'button', 'data-role': 'collab' },
+        el('span', { class: 'share-choice-title' }, 'Collaborator'),
+        el('span', { class: 'share-choice-sub' }, 'Can edit answers, comment, and submit as owner.')
+      ),
+      el('button', { class: 'share-choice', type: 'button', 'data-role': 'review' },
+        el('span', { class: 'share-choice-title' }, 'Reviewer'),
+        el('span', { class: 'share-choice-sub' }, 'Can add comments only. No submit, answer edits, edit, or delete.')
+      ),
+      el('div', { class: 'share-result' })
+    );
+    const close = () => panel.remove();
+    const closeBtn = el('button', { class: 'share-close', type: 'button', 'aria-label': 'Close share panel' }, '×');
+    closeBtn.addEventListener('click', close);
+    panel.prepend(closeBtn);
+    const result = panel.querySelector('.share-result');
+    for (const btn of panel.querySelectorAll('.share-choice')) {
+      btn.addEventListener('click', async () => {
+        const role = btn.getAttribute('data-role');
+        const label = role === 'collab' ? 'collaborator' : 'reviewer';
+        if (!window.confirm(`Activate a ${label} link for same-Wi-Fi devices?`)) return;
+        btn.disabled = true;
+        result.textContent = 'Activating...';
+        try {
+          const res = await fetch('/api/share', {
+            method: 'POST',
+            headers: { 'content-type': 'application/json' },
+            body: JSON.stringify({ role }),
+          });
+          const body = await res.json().catch(() => null);
+          if (!res.ok || !body || !body.url) throw new Error(body && body.error ? body.error : 'share failed');
+          const copy = el('button', { class: 'share-copy', type: 'button' }, 'Copy link');
+          copy.addEventListener('click', () => copyText(body.url, copy));
+          result.replaceChildren(
+            el('div', { class: 'share-ready' }, role === 'collab' ? 'Collaborator link active' : 'Reviewer link active'),
+            el('a', { class: 'share-url', href: body.url, target: '_blank', rel: 'noreferrer' }, body.url),
+            copy
+          );
+        } catch (err) {
+          result.textContent = err && err.message ? err.message : 'Could not activate sharing.';
+        } finally {
+          btn.disabled = false;
+        }
+      });
+    }
+    host.append(panel);
+  }
+
+  function buildFooter() {
+    const footer = el('footer', { class: 'qb-footer' }, el('span', {}, `relay · ${boot.boardId}`));
+    if (access.canShare) {
+      const wrap = el('span', { class: 'share-wrap' });
+      const shareBtn = el('button', { class: 'share-btn', type: 'button' }, 'Share');
+      shareBtn.addEventListener('click', () => {
+        const existing = wrap.querySelector('.share-panel');
+        if (existing) existing.remove();
+        else openSharePanel(wrap);
+      });
+      wrap.append(shareBtn);
+      footer.append(wrap);
+    } else if (access.role === 'review') {
+      footer.append(el('span', { class: 'share-mode' }, 'reviewer · comments only'));
+    } else if (access.role === 'collab') {
+      footer.append(el('span', { class: 'share-mode' }, 'collaborator'));
+    }
+    return footer;
+  }
+
+  if (!access.canSubmit) {
+    submitbar.style.display = 'none';
+    app.append(el('div', { class: 'access-note' }, 'Reviewer mode: comments are saved live. Answers and submission are disabled.'));
+  }
+  if (!access.canEditAnswers) {
+    document.documentElement.classList.add('relay-review');
+    for (const node of app.querySelectorAll('.card input, .card textarea, .card button, .card select')) {
+      node.disabled = true;
+    }
+  }
+  app.append(buildFooter());
 
   // ---------- validation & submit ----------
   function validate() {
@@ -1154,7 +1285,7 @@
       try {
         res = await fetch('/api/submit', {
           method: 'POST',
-          headers: { 'content-type': 'application/json' },
+          headers: authHeaders({ 'content-type': 'application/json' }),
           body: JSON.stringify(payload()),
         });
       } catch (netErr) {
@@ -1368,6 +1499,23 @@
           // sessionStorage may be unavailable — the reload still applies the update
         }
         location.reload();
+        return;
+      }
+      if (body && typeof body.draftRev === 'number' && body.draftRev > seenDraftRev && !submitted && !reloading) {
+        if (userIsComposing()) {
+          showNotice('Another viewer updated this board — it’ll refresh as soon as you finish typing.', 'info');
+          return;
+        }
+        reloading = true;
+        stopHeartbeat();
+        clearTimeout(saveTimer);
+        clearLocalDraft();
+        try {
+          sessionStorage.setItem('relay-draft-updated', '1');
+        } catch {
+          // sessionStorage may be unavailable — the reload still applies the update
+        }
+        location.reload();
       }
     } catch {
       // Lost the live connection (the session ended, or the machine slept). Two

package/src/ui/style.css

@@ -341,7 +341,58 @@ textarea { min-height: 90px; resize: vertical; }
 .done h2 { font-family: var(--serif); font-weight: 500; letter-spacing: -0.015em; margin: 0 0 8px; }
 .done p { color: var(--muted); margin: 0; }
 
-.qb-footer { color: var(--muted); font-size: 0.75rem; text-align: center; margin-top: 28px; }
+.qb-footer {
+  color: var(--muted); font-size: 0.75rem; text-align: center; margin-top: 28px;
+  display: flex; justify-content: center; align-items: center; gap: 10px; flex-wrap: wrap;
+}
+.share-wrap { position: relative; display: inline-flex; }
+.share-btn, .share-copy, .share-choice, .share-close {
+  font: inherit;
+}
+.share-btn {
+  border: 1px solid var(--border-strong); border-radius: 999px;
+  background: var(--card); color: var(--fg-2);
+  padding: 5px 12px; cursor: pointer;
+}
+.share-btn:hover { border-color: var(--accent); color: var(--accent); }
+.share-panel {
+  position: absolute; left: 50%; bottom: calc(100% + 10px); transform: translateX(-50%);
+  width: min(360px, calc(100vw - 28px));
+  background: var(--card); color: var(--fg);
+  border: 1px solid var(--border-strong); border-radius: 12px;
+  box-shadow: var(--shadow-lift);
+  padding: 16px; text-align: left; z-index: 45;
+}
+.share-close {
+  position: absolute; top: 8px; right: 8px;
+  border: 0; background: transparent; color: var(--muted);
+  cursor: pointer; font-size: 1.1rem; line-height: 1;
+}
+.share-title { font-weight: 650; font-size: 0.95rem; margin-right: 24px; }
+.share-desc { color: var(--muted); font-size: 0.78rem; margin: 4px 20px 12px 0; }
+.share-choice {
+  width: 100%; display: flex; flex-direction: column; gap: 2px;
+  border: 1px solid var(--border); border-radius: 10px;
+  background: var(--bg-sunken); color: var(--fg);
+  padding: 10px 12px; margin-top: 8px; cursor: pointer; text-align: left;
+}
+.share-choice:hover { border-color: var(--accent); }
+.share-choice-title { font-weight: 650; }
+.share-choice-sub { color: var(--muted); font-size: 0.76rem; }
+.share-result { margin-top: 12px; color: var(--fg-2); font-size: 0.78rem; overflow-wrap: anywhere; }
+.share-ready { color: var(--ok); font-weight: 650; margin-bottom: 4px; }
+.share-url { color: var(--accent); display: block; margin-bottom: 8px; }
+.share-copy {
+  border: 0; border-radius: 8px; background: var(--accent); color: var(--accent-fg);
+  padding: 7px 12px; cursor: pointer; font-weight: 650;
+}
+.share-mode { color: var(--fg-2); }
+.access-note {
+  color: var(--fg-2); background: var(--accent-soft);
+  border-radius: 10px; padding: 10px 14px; font-size: 0.86rem;
+}
+.relay-review .ann-del,
+.relay-review .ann-edit { display: none !important; }
 
 @media (max-width: 480px) {
   .wrap { padding: 18px 12px 18px; }