@1agh/maude 0.53.1 → 0.54.0

package/apps/studio/client/report-bug.jsx

@@ -14,11 +14,30 @@
 
 import React, { useCallback, useEffect, useRef, useState } from 'react';
 
-import { invoke, isNativeApp, openGitHubUrl } from './github.js';
+import { invoke, isNativeApp, openGitHubUrl, pickMediaFile } from './github.js';
 
-const MAX_SHOTS = 3;
+// Two of these are auto-captured (window + artboard), so the ceiling leaves
+// room for the user to still attach their own.
+const MAX_SHOTS = 4;
 const PUBLIC_ISSUES_URL = 'https://github.com/1aGh/maude/issues/new';
 
+/** How each attached shot got here — shown per tile so the user can tell the
+ * auto-captured artboard (which never contains Maude's own chrome) apart from
+ * one they attached themselves. */
+const SHOT_LABEL = {
+  shell: 'Maude window (auto)',
+  artboard: 'Active artboard (auto)',
+  attached: 'Attached by you',
+};
+
+/** The OS window-capture shortcut, for the "a Maude UI bug needs the chrome"
+ * hint. `platform` is the node `process.platform` string from the bundle. */
+function windowShotHint(platform) {
+  if (platform === 'darwin') return '⇧⌘4 then Space';
+  if (platform === 'win32') return 'Win+Shift+S';
+  return 'your screenshot tool';
+}
+
 function randHex(n) {
   const bytes = new Uint8Array(n / 2);
   crypto.getRandomValues(bytes);
@@ -124,6 +143,7 @@ function ShotTile({ shot, redacting, onRects, onRemove }) {
           />
         ))}
       </div>
+      <div className="rb-shot-src">{SHOT_LABEL[shot.source] ?? SHOT_LABEL.attached}</div>
       <div className="rb-shot-actions">
         {shot.rects.length > 0 && (
           <button type="button" className="rb-link" onClick={() => onRects([])}>
@@ -138,11 +158,11 @@ function ShotTile({ shot, redacting, onRects, onRemove }) {
   );
 }
 
-export function ReportBugDialog({ open, onClose }) {
+export function ReportBugDialog({ open, onClose, activeCanvas = null }) {
   const [step, setStep] = useState('describe'); // describe | preview | sending | done | fallback
   const [description, setDescription] = useState('');
   const [bundle, setBundle] = useState(null);
-  const [shots, setShots] = useState([]); // {url, blob, rects:[{x,y,w,h} normalized]}
+  const [shots, setShots] = useState([]); // {url, blob, source, rects:[{x,y,w,h} normalized]}
   const [crashLogs, setCrashLogs] = useState([]); // native only: {name, firstLine}
   const [consent, setConsent] = useState({
     logTail: true,
@@ -150,6 +170,7 @@ export function ReportBugDialog({ open, onClose }) {
     projectName: false,
     crashLogs: true,
   });
+  const [shellPending, setShellPending] = useState(false);
   const [redacting, setRedacting] = useState(false);
   const [result, setResult] = useState(null); // {issueUrl, issueNumber} | {fallbackDir}
   const [error, setError] = useState(null);
@@ -161,21 +182,52 @@ export function ReportBugDialog({ open, onClose }) {
     setBundle(null);
     setShots([]);
     setCrashLogs([]);
+    setShellPending(false);
     setRedacting(false);
     setResult(null);
     setError(null);
     // eslint-disable-next-line react-hooks/exhaustive-deps
   }, [shots]);
 
-  const addShotBlob = useCallback((blob) => {
+  const addShotBlob = useCallback((blob, source = 'attached') => {
     if (!blob) return;
     setShots((prev) =>
       prev.length >= MAX_SHOTS
         ? prev
-        : [...prev, { url: URL.createObjectURL(blob), blob, rects: [] }]
+        : [...prev, { url: URL.createObjectURL(blob), blob, source, rects: [] }]
     );
   }, []);
 
+  // Attach a screenshot the user took themselves — the ONLY lane that can carry
+  // Maude's own chrome (menubar, sidebar, dialogs), since the auto-capture
+  // renders the canvas headlessly and the shell is never in frame. Native
+  // WKWebView won't present a panel for an HTML <input type=file> at all, so it
+  // routes through the same Rust open-dialog the AssetPicker uses.
+  const attachScreenshot = useCallback(async () => {
+    if (isNativeApp()) {
+      try {
+        const picked = await pickMediaFile();
+        if (picked?.bytes) addShotBlob(new Blob([new Uint8Array(picked.bytes)]), 'attached');
+      } catch {
+        /* cancelled or dialog failure — paste (⌘V) still works */
+      }
+      return;
+    }
+    // Browser — imperative off-screen <input>, clicked inside the gesture
+    // (mirrors app.jsx's openFilePicker; display:none inputs don't lay out).
+    const input = document.createElement('input');
+    input.type = 'file';
+    input.accept = 'image/*';
+    input.style.cssText = 'position:fixed;left:-9999px;top:0';
+    document.body.appendChild(input);
+    input.addEventListener('change', () => {
+      const file = input.files?.[0];
+      if (file) addShotBlob(file, 'attached');
+      input.remove();
+    });
+    input.click();
+  }, [addShotBlob]);
+
   // On open: pull the scrubbed bundle, capture the active artboard, list
   // native crash logs. Every leg fails soft — a report with fewer attachments
   // beats no dialog.
@@ -186,14 +238,37 @@ export function ReportBugDialog({ open, onClose }) {
       .then((r) => (r.ok ? r.json() : null))
       .then((b) => alive && setBundle(b))
       .catch(() => {});
-    fetch('/_api/export', {
+    // Artboard shot only when THIS window actually has a canvas open. The
+    // export resolves its target from the server's `_active.json`, so with
+    // nothing open it would attach a stale canvas from another session.
+    if (activeCanvas) {
+      fetch('/_api/export', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ format: 'png', scope: 'artboard' }),
+      })
+        .then((r) => (r.ok ? r.blob() : null))
+        .then((blob) => alive && blob && addShotBlob(blob, 'artboard'))
+        .catch(() => {});
+    }
+    // The window shot — Maude's own chrome, which the artboard capture above
+    // structurally cannot see. Slow (boots a headless browser, opens the canvas),
+    // so it lands second and shows a pending row meanwhile. `canvas` is sent
+    // explicitly — including as null, which means "open nothing", so an empty
+    // window is reported as an empty window.
+    setShellPending(true);
+    fetch('/_api/shell-shot', {
       method: 'POST',
       headers: { 'Content-Type': 'application/json' },
-      body: JSON.stringify({ format: 'png', scope: 'artboard' }),
+      body: JSON.stringify({ canvas: activeCanvas }),
     })
       .then((r) => (r.ok ? r.blob() : null))
-      .then((blob) => alive && blob && addShotBlob(blob))
-      .catch(() => {});
+      .then((blob) => {
+        if (!alive) return;
+        if (blob) addShotBlob(blob, 'shell');
+        setShellPending(false);
+      })
+      .catch(() => alive && setShellPending(false));
     if (isNativeApp()) {
       invoke('list_crash_logs')
         .then((logs) => alive && setCrashLogs(Array.isArray(logs) ? logs.slice(0, 3) : []))
@@ -203,7 +278,7 @@ export function ReportBugDialog({ open, onClose }) {
       alive = false;
     };
     // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, [open]);
+  }, [open, activeCanvas]);
 
   // Paste-to-attach — the lane that covers native-shell bugs the canvas
   // capture can't see (user screenshots the window, pastes here).
@@ -238,7 +313,9 @@ export function ReportBugDialog({ open, onClose }) {
       },
       context: {
         projectName: consent.projectName ? (bundle?.context?.projectName ?? null) : null,
-        activeCanvas: consent.activeCanvas ? (bundle?.context?.activeCanvas ?? null) : null,
+        // This window's canvas, never the server's sticky `_active.json` — the
+        // report must not name a file the reporter does not have open.
+        activeCanvas: consent.activeCanvas ? activeCanvas : null,
       },
       description: description.trim(),
       attachments: {
@@ -385,21 +462,42 @@ export function ReportBugDialog({ open, onClose }) {
               <div className="rb-section">
                 <div className="rb-section-hd">
                   <span>Screenshots ({shots.length})</span>
-                  {shots.length > 0 && (
-                    <button
-                      type="button"
-                      className={`rb-link${redacting ? ' is-on' : ''}`}
-                      data-testid="report-bug-redact"
-                      onClick={() => setRedacting((v) => !v)}
-                    >
-                      {redacting ? 'Done redacting' : 'Redact…'}
-                    </button>
-                  )}
+                  <span className="rb-hd-actions">
+                    {shots.length < MAX_SHOTS && (
+                      <button
+                        type="button"
+                        className="rb-link"
+                        data-testid="report-bug-attach"
+                        onClick={attachScreenshot}
+                      >
+                        Attach screenshot…
+                      </button>
+                    )}
+                    {shots.length > 0 && (
+                      <button
+                        type="button"
+                        className={`rb-link${redacting ? ' is-on' : ''}`}
+                        data-testid="report-bug-redact"
+                        onClick={() => setRedacting((v) => !v)}
+                      >
+                        {redacting ? 'Done redacting' : 'Redact…'}
+                      </button>
+                    )}
+                  </span>
                 </div>
-                {shots.length === 0 ? (
-                  <p className="rb-hint">
-                    No screenshot attached. Paste one (⌘V) to add it — up to {MAX_SHOTS}.
+                <p className="rb-hint">
+                  Maude captures its own window and the active artboard for you. The window shot is
+                  a fresh render, so anything mid-flight — an open menu, a stuck spinner — won't be
+                  in it: grab that yourself ({windowShotHint(bundle?.app?.platform)}) and attach or
+                  paste (⌘V) it here.
+                </p>
+                {shellPending && (
+                  <p className="rb-hint" data-testid="report-bug-shell-pending">
+                    Capturing the Maude window…
                   </p>
+                )}
+                {shots.length === 0 && !shellPending ? (
+                  <p className="rb-hint">No screenshot attached yet — up to {MAX_SHOTS}.</p>
                 ) : (
                   <>
                     {redacting && (
@@ -421,9 +519,6 @@ export function ReportBugDialog({ open, onClose }) {
                         />
                       ))}
                     </div>
-                    {shots.length < MAX_SHOTS && (
-                      <p className="rb-hint">Paste (⌘V) to attach another screenshot.</p>
-                    )}
                   </>
                 )}
               </div>
@@ -439,7 +534,7 @@ export function ReportBugDialog({ open, onClose }) {
                     {bundle?.app?.arch ?? ''} · {isNativeApp() ? 'desktop app' : 'browser'}
                   </span>
                 </label>
-                {bundle?.context?.activeCanvas && (
+                {activeCanvas && (
                   <label className="rb-check">
                     <input
                       type="checkbox"
@@ -447,7 +542,7 @@ export function ReportBugDialog({ open, onClose }) {
                       onChange={(e) => setConsent({ ...consent, activeCanvas: e.target.checked })}
                     />
                     <span>
-                      Active canvas path — <code>{bundle.context.activeCanvas}</code>
+                      Active canvas path — <code>{activeCanvas}</code>
                     </span>
                   </label>
                 )}

package/apps/studio/client/styles/4-components-maude.css

@@ -113,6 +113,11 @@
 .rb-dialog .rb-shot-box.is-redacting img { pointer-events: none; }
 .rb-dialog .rb-redact-rect { position: absolute; background: #000; pointer-events: none; }
 .rb-dialog .rb-shot-actions { display: flex; gap: var(--space-3); }
+.rb-dialog .rb-hd-actions { display: flex; gap: var(--space-3); align-items: center; }
+.rb-dialog .rb-shot-src {
+  font-family: var(--font-mono); font-size: var(--type-xs);
+  letter-spacing: var(--tracking-wide); color: var(--fg-2); max-width: 260px;
+}
 .rb-dialog .rb-link {
   appearance: none; background: transparent; border: 0; padding: 0; cursor: pointer;
   font-size: var(--type-xs); font-family: var(--font-body);

package/apps/studio/client/styles/4-components.css

@@ -1876,3 +1876,78 @@
   gap: 6px;
 }
 
+
+/* Cloud Phase 27 C4 — the cloud-only "where am I / how do I leave" affordance.
+   A browser tab has no window title and no app switcher; the desktop gets both
+   from the OS. Sits in the menubar, after the brand, before the menus. */
+.st-cloudback {
+  display: inline-flex;
+  align-items: center;
+  gap: 8px;
+  margin-left: 4px;
+  padding-left: 10px;
+  border-left: 1px solid var(--u-line, rgba(255, 255, 255, 0.1));
+  min-width: 0;
+}
+.st-cloudback-link {
+  color: var(--u-fg-2);
+  text-decoration: none;
+  font-size: 12px;
+  white-space: nowrap;
+  border-radius: 5px;
+  padding: 2px 6px;
+}
+.st-cloudback-link:hover,
+.st-cloudback-link:focus-visible {
+  color: var(--u-fg-0);
+  background: var(--u-bg-2);
+}
+.st-cloudback-project {
+  font-size: 12px;
+  font-weight: 600;
+  color: var(--u-fg-1);
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+  max-width: 22ch;
+}
+
+/* …and its counterpart on the right: WHICH ACCOUNT this tab is, and the way to
+   stop being it. The email is quiet (it is context, not a control); the sign-out
+   only resolves on hover, because the common case is reading it and the rare
+   case is needing it. */
+.st-cloudwho {
+  display: inline-flex;
+  align-items: center;
+  gap: 8px;
+  min-width: 0;
+}
+.st-cloudwho-email {
+  font-size: 12px;
+  color: var(--u-fg-2);
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+  max-width: 24ch;
+}
+.st-cloudwho-form {
+  display: inline-flex;
+  margin: 0;
+}
+.st-cloudwho-out {
+  font: inherit;
+  font-size: 12px;
+  color: var(--u-fg-3);
+  background: none;
+  border: 0;
+  cursor: pointer;
+  text-decoration: none;
+  white-space: nowrap;
+  border-radius: 5px;
+  padding: 2px 6px;
+}
+.st-cloudwho-out:hover,
+.st-cloudwho-out:focus-visible {
+  color: var(--u-fg-0);
+  background: var(--u-bg-2);
+}

package/apps/studio/cloud-build.ts

@@ -0,0 +1,208 @@
+// The cloud build — Cloud Phase 27 D1: ELIMINATE, do not un-route.
+//
+// A cell already refuses every one of these surfaces three times over: the
+// route table is pruned at boot (`workspace-mode.ts`), the hub's manifest denies
+// them, and a running cell 404s all of them. That is operational containment,
+// and it is not the same claim as DDR-123's "claude never runs on our
+// infrastructure" — which is a statement about what is IN the image, not about
+// what answers. Code that is present is code that a future route, a future
+// import, or a future mistake can reach.
+//
+// WHAT MADE THIS POSSIBLE. `--define` plus dead-code elimination does not work
+// here: Bun inlines a dynamically-imported module and keeps the branch, so the
+// bytes stay (verified before writing any of this — the sentinel survived a
+// minified `--define`d build). What DOES work is substitution at build time:
+// `Bun.build({ compile })` accepts plugins, and a plugin that replaces a module
+// with an inert one removes the original from the binary entirely. Verified the
+// same way: the sentinel string is absent from the compiled artifact.
+//
+// WHAT IS NOT ELIMINATED, AND WHY. System git stays — Phase 27 D2 makes it the
+// engine a cell RUNS on, because two git engines over one index is not a race a
+// careful caller can avoid. Its presence is deliberate and is not part of the
+// secret-bearing surface: it carries no credential and spawns nothing the tenant
+// can name.
+//
+// The stubs are GENERATED from each module's own export list rather than
+// hand-written. A hand-written stub is a second copy of an interface, and the
+// day it falls behind is the day the cloud build fails to boot for a reason
+// nobody can see. Reading the real file's exports means a module that grows a
+// function still stubs cleanly.
+
+import { existsSync, readFileSync } from 'node:fs';
+import path from 'node:path';
+
+/**
+ * The modules a cloud build replaces, relative to `apps/studio/`.
+ *
+ * Each line is one of the surfaces DDR-209's D1 names. Grouped by WHY, because
+ * the reason is the thing to check when deciding whether a new module belongs
+ * on this list.
+ */
+export const CLOUD_ELIMINATED = Object.freeze([
+  // The agent, and everything that starts one. DDR-123: the user's own `claude`
+  // subscription, on the user's own machine, never on ours.
+  'acp/index.ts',
+  'acp/bridge.ts',
+  'acp/login-state.ts', // the `bash -c` native installer
+  'acp/probe.ts', // resolves + trusts a `claude` binary path
+  'acp/plugin-bootstrap.ts',
+  // Shell probes — `$SHELL -ilc "command -v …"`. A login shell on a server is
+  // an execution surface with a tenant-shaped input near it.
+  'readiness.ts',
+  'design-setup-readiness.ts',
+  // The exporter's subprocess spine.
+  'exporters/_runtime.ts',
+  // BYOK: provider keys at rest, and the adapters that spend them.
+  'generation/keys.ts',
+  'generation/adapters/gemini.ts',
+  'generation/adapters/elevenlabs.ts',
+  'generation/adapters/groq.ts',
+  // Endpoints that speak to somebody else's account on the user's behalf.
+  'cloud/endpoints.ts',
+  'github/endpoints.ts',
+  // …and the REST client behind it, which `git/endpoints.ts` also reaches for
+  // its "open a pull request" verb. Stubbing only the endpoints left every
+  // GitHub API URL in the image through that second importer — found by the
+  // gate below, which is the entire reason it greps the artifact instead of
+  // trusting the list.
+  'github/service.ts',
+  'sync/hub-link.ts',
+  // The debug bundle scrubs, but it still assembles an environment report.
+  'debug-bundle.ts',
+]);
+
+/**
+ * Strings that must not appear in a cloud binary.
+ *
+ * The gate greps for these because a stub that silently failed to apply is
+ * indistinguishable from one that worked, right up until it is not. Chosen to
+ * be specific to the eliminated code rather than to any word near it.
+ */
+export const CLOUD_FORBIDDEN_STRINGS = Object.freeze([
+  'claude-agent-acp', // the ACP adapter package
+  '-ilc', // the login-shell probe
+  'application/vnd.github+json', // the REST client that speaks for a user's account
+  'generativelanguage.googleapis.com', // BYOK image generation
+  'api.elevenlabs.io', // BYOK audio generation
+]);
+
+// A NOTE ON CHOOSING THESE. They must be strings only OUR code can produce.
+// `api.github.com` looked ideal and is useless: Bun's own runtime carries
+// `GITHUB_API_DOMAIN` and `GITHUB_API_URL`, so it appears in every compiled
+// binary whatever we do. A gate that can never go green teaches people to
+// ignore it. Each string above is verified present in a desktop binary and
+// absent from a cloud one — that pair is the assertion, not the absence alone.
+
+/** Runtime-visible exports of a module — what a stub has to provide. Types and
+ *  interfaces are erased before this matters, so they are deliberately absent. */
+export function exportedNames(source: string): string[] {
+  const names = new Set<string>();
+  // Leading whitespace is allowed on purpose. The two failure directions are
+  // not symmetric: a MISSED export is a boot-time crash in the cloud binary and
+  // nowhere else, while an extra one is a duplicate `const` that fails the
+  // build loudly, at the desk of whoever caused it. So this errs greedy.
+  const patterns = [
+    /^\s*export\s+(?:async\s+)?function\s+([A-Za-z_$][\w$]*)/gm,
+    /^\s*export\s+(?:const|let|var)\s+([A-Za-z_$][\w$]*)/gm,
+    /^\s*export\s+class\s+([A-Za-z_$][\w$]*)/gm,
+  ];
+  for (const re of patterns) {
+    for (const m of source.matchAll(re)) if (m[1]) names.add(m[1]);
+  }
+  // `export { a, b as c }` — the re-export form.
+  for (const m of source.matchAll(/^\s*export\s*\{([^}]*)\}/gm)) {
+    for (const part of (m[1] ?? '').split(',')) {
+      const alias = part
+        .split(/\s+as\s+/i)
+        .pop()
+        ?.trim();
+      if (alias && /^[A-Za-z_$][\w$]*$/.test(alias) && alias !== 'default') names.add(alias);
+    }
+  }
+  return [...names];
+}
+
+/**
+ * The inert value every stubbed export becomes.
+ *
+ * A self-returning proxy rather than `() => {}` or `null`, because the callers
+ * are not all the same shape: one boot path calls `createExportJobQueue(...)`
+ * and hands the result to the route table, another calls `installLogRing()` for
+ * its side effect, a third reads a property off what `createAcp` returned. A
+ * value that answers every one of those with another inert value cannot crash a
+ * boot on a shape nobody remembered.
+ *
+ * It is deliberately NOT thenable: `await inert` must yield the proxy, not hang
+ * forever waiting for a `then` that never resolves.
+ */
+const INERT_SOURCE = `
+const inert = new Proxy(function cloudEliminated() {}, {
+  get(_t, key) {
+    if (key === 'then') return undefined;
+    if (key === Symbol.toPrimitive || key === 'toString') return () => '';
+    if (key === Symbol.iterator) return function* () {};
+    return inert;
+  },
+  apply: () => inert,
+  construct: () => inert,
+});
+`;
+
+/** Build the replacement source for one eliminated module. */
+export function stubSource(original: string): string {
+  const names = exportedNames(original);
+  const decls = names.map((n) => `export const ${n} = inert;`).join('\n');
+  return `${INERT_SOURCE}\n${decls}\nexport default inert;\n`;
+}
+
+/**
+ * The Bun plugin. Pass it to `Bun.build({ plugins: [cloudStubPlugin(root)] })`.
+ *
+ * `onLoad` rather than `onResolve`: the module still resolves to its real path
+ * (so a typo in the list is a build error rather than a silent no-op), and only
+ * its CONTENTS are replaced.
+ */
+export function cloudStubPlugin(studioRoot: string): import('bun').BunPlugin {
+  const targets = new Set(CLOUD_ELIMINATED.map((rel) => path.join(studioRoot, rel)));
+  const applied = new Set<string>();
+
+  // A LISTED PATH THAT DOES NOT EXIST IS A BUILD FAILURE, NOT A LOG LINE.
+  //
+  // The plugin matches by exact resolved path, so a rename, a move to `.tsx` or
+  // a typo silently stops eliminating that module — and the "never imported"
+  // notice below reads as ordinary, because it IS ordinary when a leaf leaves
+  // the graph with its stubbed importer. The two cases are indistinguishable at
+  // the end of a build, so they are distinguished HERE, where one of them is
+  // simply a path that is not on disk.
+  const missing = CLOUD_ELIMINATED.filter((rel) => !existsSync(path.join(studioRoot, rel)));
+  if (missing.length) {
+    throw new Error(
+      `cloud build: ${missing.length} module(s) in CLOUD_ELIMINATED do not exist — ` +
+        `a rename or a typo means they are NOT being eliminated: ${missing.join(', ')}`
+    );
+  }
+  return {
+    name: 'maude-cloud-eliminate',
+    setup(build) {
+      build.onLoad({ filter: /\.ts$/ }, (args) => {
+        if (!targets.has(args.path)) return undefined;
+        applied.add(args.path);
+        return { contents: stubSource(readFileSync(args.path, 'utf8')), loader: 'ts' };
+      });
+      build.onEnd?.(() => {
+        // A module on the list the graph never reached is USUALLY success, not
+        // drift: stubbing `acp/index.ts` takes `acp/bridge.ts` out of the graph
+        // with it, so the leaf is eliminated by the same stroke and never gets
+        // loaded. Reported at info level for exactly that reason — it is worth
+        // seeing (a typo'd path looks identical) and it is not a failure.
+        const unused = [...targets].filter((t) => !applied.has(t));
+        if (unused.length) {
+          console.log(
+            `[cloud-build] ${unused.length} listed module(s) left the graph with their importer ` +
+              `(or are no longer imported at all): ${unused.map((u) => path.basename(u)).join(', ')}`
+          );
+        }
+      });
+    },
+  };
+}

package/apps/studio/collab/room.ts

@@ -41,6 +41,18 @@ export interface RoomConn extends CollabConn {
    * default can't silently swallow a future canvas path.
    */
   realm?: 'main' | 'canvas';
+  /**
+   * Cloud collab lane (RCA issue-cloud-live-collaboration-dead) — true when
+   * this socket was opened under a read-only role (a cell's `viewer`, or a
+   * cell socket the proxy did not vouch). A read-only conn still receives every
+   * broadcast and publishes awareness — presence for viewers is the point of
+   * the channel — but its SYNC writes are gated to the comment lane, mirroring
+   * the role matrix (`viewer.comment === true`) the same way the inspector
+   * channel's `comments-patch`/`comments-delete` gate does. Absent defaults to
+   * writable ON PURPOSE, for the same reason `realm` defaults to trusted:
+   * every pre-existing caller is a loopback desktop peer.
+   */
+  readOnly?: boolean;
 }
 
 export interface RoomCallbacks {
@@ -194,8 +206,30 @@ export function createRoom(slug: string, callbacks: RoomCallbacks): Room {
   }
 
   /**
-   * Canvas-realm frame path. Awareness frames are unchanged (cursors/presence
-   * are ephemeral and already server-attributed). Sync frames are gated.
+   * Which lanes this conn's sync writes may not touch.
+   *
+   * Two independent dimensions, both fail-closed on `<unresolved>`:
+   *   - realm 'canvas' (DDR-122): body lanes are never writable from the
+   *     untrusted canvas origin, whoever is connected.
+   *   - readOnly (cloud collab lane): only the comment lane is writable — the
+   *     WS mirror of the role matrix's viewer capability.
+   */
+  function refusedLanes(conn: RoomConn, roots: ReadonlySet<string>): string[] {
+    const refused: string[] = [];
+    for (const r of roots) {
+      if (conn.realm === 'canvas' && (isBodyLane(r) || r === '<unresolved>')) {
+        refused.push(r);
+        continue;
+      }
+      if (conn.readOnly === true && r !== 'comments') refused.push(r);
+    }
+    return refused;
+  }
+
+  /**
+   * Gated frame path — canvas-realm and/or read-only conns. Awareness frames
+   * are unchanged (cursors/presence are ephemeral and already
+   * server-attributed). Sync frames are gated.
    */
   function receiveGated(conn: RoomConn, payload: Uint8Array): void {
     if (readMessageType(payload) !== MESSAGE_SYNC) {
@@ -216,14 +250,16 @@ export function createRoom(slug: string, callbacks: RoomCallbacks): Room {
     // Fail closed on anything we could not positively classify — a probe that
     // threw, or a root type we could not resolve to a name.
     const roots = probeRoots ?? new Set<string>();
-    const refused = [...roots].filter((r) => isBodyLane(r) || r === '<unresolved>');
+    const refused = refusedLanes(conn, roots);
     if (probeThrew || refused.length > 0) {
       gateRefusalCount += 1;
       discardMirror();
       console.warn(
-        `[collab/${slug}] origin gate REFUSED a canvas-realm sync frame ` +
-          `(lanes: ${refused.join(', ') || 'unclassifiable'}). Untrusted canvas script may ` +
-          `not write canvas source — see DDR-122 follow-up / collab/origins.ts.`
+        `[collab/${slug}] origin gate REFUSED a ${conn.readOnly ? 'read-only' : 'canvas-realm'} ` +
+          `sync frame (lanes: ${refused.join(', ') || 'unclassifiable'}). ` +
+          (conn.readOnly
+            ? 'A viewer-role socket may only write comments — role matrix, cloud collab lane.'
+            : 'Untrusted canvas script may not write canvas source — see DDR-122 follow-up / collab/origins.ts.')
       );
       // Re-assert server truth to that peer so it converges on the authoritative
       // state instead of silently diverging. Their locally-authored body items
@@ -315,7 +351,7 @@ export function createRoom(slug: string, callbacks: RoomCallbacks): Room {
   }
 
   function receive(conn: RoomConn, payload: Uint8Array): void {
-    if (conn.realm === 'canvas') {
+    if (conn.realm === 'canvas' || conn.readOnly === true) {
       receiveGated(conn, payload);
       return;
     }