@1agh/maude 0.22.2 → 0.24.0

package/plugins/design/dev-server/client/app.jsx

@@ -64,7 +64,7 @@ function urlOf(p) {
 // canvases keep the legacy "serve the file with inspector + Babel injected"
 // path. Phase 3.6 contract; the path argument is repo-root-relative
 // (e.g. ".design/ui/Foo.tsx").
-function canvasUrl(p, cfg) {
+function canvasUrl(p, cfg, opts) {
   if (!p.endsWith('.tsx')) return urlOf(p);
   const designRel = (cfg?.designRel || '.design').replace(/^\/+|\/+$/g, '');
   // Path under designRoot.
@@ -77,22 +77,36 @@ function canvasUrl(p, cfg) {
   const params = new URLSearchParams();
   params.set('canvas', rel);
   params.set('designRel', designRel);
-  // Resolve tokens path. Prefer the first designSystem's tokensCssRel — that's
-  // the project's authoritative tokens file (e.g. `system/project/colors_and_type.css`).
-  // The top-level cfg.tokensCssRel is the legacy default (`system/colors_and_type.css`)
-  // and points to a file that usually doesn't exist in DS-bootstrapped projects.
+  // Gallery thumbnails suppress the shell-owned comment layer (`?comments=0`)
+  // so previews stay non-interactive; opening the same canvas as a real tab
+  // omits the flag and gets comments. See canvas-comment-mount.tsx.
+  if (opts?.thumbnail) params.set('comments', '0');
   const ds0 = cfg?.designSystems?.[0];
-  const tokens = ds0?.tokensCssRel || cfg?.tokensCssRel;
+  // Specimen detection: anything under `system/<ds>/preview/` belongs to that
+  // specific DS, so it must render with *that* DS's tokens — not always the
+  // first one. In a multi-DS project this is what keeps each design system's
+  // preview distinct (beta previews use beta tokens, not alpha's).
+  const specMatch = rel.match(/^system\/([^/]+)\/preview\//);
+  const specDsEntry = specMatch
+    ? cfg?.designSystems?.find(
+        (d) => d.path === `system/${specMatch[1]}` || d.path.endsWith(`/${specMatch[1]}`)
+      )
+    : null;
+  // Resolve tokens path. For a specimen, prefer the matching DS's tokensCssRel
+  // (fall back to the `system/<ds>/colors_and_type.css` convention). Otherwise
+  // prefer the first designSystem's tokensCssRel — the project's authoritative
+  // tokens file. The top-level cfg.tokensCssRel is the legacy default
+  // (`system/colors_and_type.css`) and usually doesn't exist post-bootstrap.
+  const tokens = specMatch
+    ? (specDsEntry?.tokensCssRel || `system/${specMatch[1]}/colors_and_type.css`)
+    : (ds0?.tokensCssRel || cfg?.tokensCssRel);
   if (tokens) params.set('tokens', tokens);
   if (cfg?.componentsCssRel) params.set('components', cfg.componentsCssRel);
-  // Specimen detection: anything under `system/<ds>/preview/` gets the layout
-  // chrome CSS so its `.specimen-hd` / `_layout.css`-baked treatment renders.
-  const specMatch = rel.match(/^system\/([^/]+)\/preview\//);
   if (specMatch) {
-    const ds = specMatch[1];
-    params.set('layout', `system/${ds}/preview/_layout.css`);
+    const dsName = specMatch[1];
+    params.set('layout', `system/${dsName}/preview/_layout.css`);
     if (!cfg?.componentsCssRel) {
-      params.set('components', `system/${ds}/preview/_components.css`);
+      params.set('components', `system/${dsName}/preview/_components.css`);
     }
   } else if (ds0?.path) {
     // UI canvas — load the project DS's `_components.css` so the dc-canvas /
@@ -102,7 +116,11 @@ function canvasUrl(p, cfg) {
       params.set('components', `${ds0.path}/preview/_components.css`);
     }
   }
-  return `/_canvas-shell.html?${params.toString()}`;
+  // T2 (9.1-A) — load the iframe from the segregated canvas origin when the
+  // server advertises one; fall back to a same-origin relative URL otherwise
+  // (older server, tests). The trailing path + query are identical either way.
+  const origin = cfg?.canvasOrigin || '';
+  return `${origin}/_canvas-shell.html?${params.toString()}`;
 }
 
 function basename(p) {
@@ -418,7 +436,7 @@ function CanvasRow({ primary, sidecars, depth, kind, activePath, onOpen, openCou
   );
 }
 
-function Tree({ node, activePath, onOpen, commentsByFile, depth = 1, kind, showHidden, search, dsFolders, onOpenSystem }) {
+function Tree({ node, activePath, onOpen, commentsByFile, depth = 1, kind, showHidden, search, dsFolders, activeDsName, onOpenSystem }) {
   const dirs = Object.keys(node).filter(k => k !== '_files').sort();
   const files = node._files || [];
   // VS Code-style sidecar grouping. Canvas (`.tsx`/`.html`) becomes the primary
@@ -480,6 +498,7 @@ function Tree({ node, activePath, onOpen, commentsByFile, depth = 1, kind, showH
             kind={kind}
             showHidden={showHidden}
             search={search}
+            activeDsName={activeDsName}
             onOpenSystem={onOpenSystem}
           />
         );
@@ -491,7 +510,7 @@ function Tree({ node, activePath, onOpen, commentsByFile, depth = 1, kind, showH
               dsName={dsMatch.name}
               depth={depth}
               defaultOpen={true}
-              active={activePath === SYSTEM_TAB}
+              active={activePath === SYSTEM_TAB && dsMatch.name === activeDsName}
               onOpenSystem={onOpenSystem}
             >
               {childTree}
@@ -529,7 +548,7 @@ function sectionMetaFor(g) {
   return { title: g.label.toUpperCase(), pillFromCount: true };
 }
 
-function Sidebar({ groups, activePath, onOpen, onOpenSystem, wsConnected, search, setSearch, commentsByFile, showHidden, sectionsExpanded, onToggleSection }) {
+function Sidebar({ groups, activePath, activeDsName, onOpen, onOpenSystem, wsConnected, search, setSearch, commentsByFile, showHidden, sectionsExpanded, onToggleSection }) {
   const filteredGroups = useMemo(() => {
     if (!search) return groups;
     return groups.map(g => ({ ...g, tree: filterTree(g.tree, search), filtered: !!search }));
@@ -624,6 +643,7 @@ function Sidebar({ groups, activePath, onOpen, onOpenSystem, wsConnected, search
                   showHidden={showHidden}
                   search={search}
                   dsFolders={g.dsFolders}
+                  activeDsName={activeDsName}
                   onOpenSystem={isDs ? onOpenSystem : undefined}
                 />
               ) : (
@@ -896,7 +916,9 @@ function ToolsDropdown({ onAction, onClose }) {
     { id: 'pen',     label: 'Pen',     shortcut: 'B' },
     { id: 'rect',    label: 'Rect',    shortcut: 'R' },
     { id: 'ellipse', label: 'Ellipse', shortcut: 'O' },
+    { id: 'sticky',  label: 'Sticky',  shortcut: 'N' },
     { id: 'arrow',   label: 'Arrow',   shortcut: 'A' },
+    { id: 'text',    label: 'Text',    shortcut: 'T' },
     { id: 'eraser',  label: 'Eraser',  shortcut: 'E' },
   ];
   return (
@@ -1084,6 +1106,14 @@ function Viewport({ tabs, activePath, registerIframe, systemData, onOpenFromSyst
             src={canvasUrl(t.path, cfg)}
             className={t.path === activePath ? 'active' : ''}
             data-path={t.path}
+            // T2 (9.1-A) — only sandbox + delegate clipboard when the canvas is
+            // served cross-origin (canvasOrigin present = the split is on). In
+            // the default same-origin mode these attrs are omitted so behavior
+            // is identical to pre-9.1. allow-same-origin gives the cross-origin
+            // frame its OWN origin (own WS/fetch/storage), NOT the parent's.
+            {...(cfg?.canvasOrigin
+              ? { sandbox: 'allow-scripts allow-same-origin', allow: 'clipboard-write' }
+              : {})}
           />
         );
       })}
@@ -1294,7 +1324,7 @@ function Gallery({ title, items, onOpen, kind, cfg }) {
         {items.map(p => (
           <article key={p.path} className="sv-preview-card" onClick={() => onOpen(p.path)}>
             <div className="sv-preview-frame">
-              <iframe src={canvasUrl(p.path, cfg)} title={p.label} scrolling="no" />
+              <iframe src={canvasUrl(p.path, cfg, { thumbnail: true })} title={p.label} scrolling="no" {...(cfg?.canvasOrigin ? { sandbox: 'allow-scripts allow-same-origin' } : {})} />
             </div>
             <div className="sv-preview-foot">
               <strong>{p.label}</strong>
@@ -1336,7 +1366,7 @@ function StatusBarSlot({ label, children, className = '' }) {
   );
 }
 
-function StatusBar({ activePath, selected, wsConnected, openCount, theme, onToggleTheme, onClearSelected }) {
+function StatusBar({ activePath, selected, wsConnected, openCount, theme, onToggleTheme, onClearSelected, syncStatus }) {
   const isSystem = activePath === SYSTEM_TAB;
   const text = selected && selected.selector
     ? selected.selector + (selected.text ? ` — "${selected.text.slice(0, 60)}"` : '')
@@ -1369,6 +1399,18 @@ function StatusBar({ activePath, selected, wsConnected, openCount, theme, onTogg
         <span className="sb-key">{wsConnected ? 'live' : 'reconnecting'}</span>
       </StatusBarSlot>
 
+      {/* DDR-060 / 9.1-D — linked-to-hub-but-nothing-syncs state lives here in the
+          status bar (DS-styled, hover for detail) instead of a floating off-brand
+          pill. Only shown when the project is linked + has 0 syncable canvases. */}
+      {syncStatus?.notSyncable && (
+        <StatusBarSlot label="Hub sync" className="sb-sync">
+          <span className="sb-sync-dot" aria-hidden="true" />
+          <span className="sb-key" title={syncStatus.reason || 'Linked to a hub, but no canvases are syncable.'}>
+            0 syncable{syncStatus.tsxCount > 0 ? ` · ${syncStatus.tsxCount} tsx` : ''}
+          </span>
+        </StatusBarSlot>
+      )}
+
       <span className="sb-spacer" />
 
       <StatusBarSlot label="Theme" className="sb-theme">
@@ -1474,6 +1516,77 @@ function CommentsPanel({ commentsByFile, filter, setFilter, activePath, focusedI
   );
 }
 
+// ---------- Sync banner (Phase 9 Task 8 — hub-down offline mode) ----------
+
+// Renders nothing when online with no flash (the common case). Yellow strip
+// while offline (with queued-edit count), red when offline > 24h, green flash
+// for 3s right after a reconnect. Driven entirely by the 'sync:status' payload
+// the dev-server's linked-mode sync runtime broadcasts.
+function SyncBanner({ status }) {
+  if (!status || status.linked === false) return null;
+  // DDR-060 / 9.1-D — the "linked but 0 syncable" state is surfaced in the
+  // status bar (sb-sync slot), NOT as a floating banner. This component owns
+  // only the transient offline / reconnect-flash banner (Task 8).
+  if (status.notSyncable) return null;
+  const { state, queuedOps, flash, conflicts } = status;
+  const showFlash = flash === 'synced';
+  const offline = state === 'offline' || state === 'offline-long';
+  if (!offline && !showFlash) return null;
+
+  let bg;
+  let fg;
+  let border;
+  let text;
+  if (showFlash) {
+    bg = '#dcfce7';
+    fg = '#166534';
+    border = '#86efac';
+    text = 'Synced with hub';
+  } else if (state === 'offline-long') {
+    bg = '#fee2e2';
+    fg = '#991b1b';
+    border = '#fca5a5';
+    text = `Long offline — ${queuedOps} edit(s) queued. Consider \`git commit && git push\` as backup.`;
+  } else {
+    bg = '#fef9c3';
+    fg = '#854d0e';
+    border = '#fde047';
+    text = `Working offline · ${queuedOps} edit(s) queued · will sync when the hub reconnects.`;
+  }
+  const conflictNote =
+    conflicts && conflicts.length > 0 ? ` (${conflicts.length} conflict notice(s))` : '';
+
+  return (
+    <div
+      role="status"
+      aria-live="polite"
+      style={{
+        position: 'fixed',
+        top: 12,
+        left: '50%',
+        transform: 'translateX(-50%)',
+        zIndex: 10003,
+        display: 'flex',
+        alignItems: 'center',
+        gap: 10,
+        padding: '8px 14px',
+        background: bg,
+        color: fg,
+        border: `1px solid ${border}`,
+        borderRadius: 999,
+        boxShadow: '0 2px 8px rgba(0,0,0,0.12)',
+        font: '500 13px/1.2 system-ui, -apple-system, sans-serif',
+        maxWidth: '80vw',
+      }}
+    >
+      <span>
+        {text}
+        {conflictNote}
+      </span>
+    </div>
+  );
+}
+
 // ---------- App ----------
 
 function App() {
@@ -1487,6 +1600,9 @@ function App() {
   // every dirty Y.Doc to disk by the time this state populates, so accepting
   // the reload is data-loss-safe (DDR-051 §3).
   const [gitLifecycle, setGitLifecycle] = useState(null);
+  // Phase 9 Task 8 — hub-down offline mode banner. Driven by the 'sync:status'
+  // WS message the linked-mode sync runtime emits. null in solo mode.
+  const [syncStatus, setSyncStatus] = useState(null);
   const [search, setSearch] = useState('');
   const [systemData, setSystemData] = useState(null);
   // Loaded once at boot from /_config — informs canvasUrl() so TSX iframes
@@ -1507,11 +1623,31 @@ function App() {
           // legacy default; designSystems[0].tokensCssRel is the project's
           // authoritative value (post DS-bootstrap).
           designSystems: data.designSystems,
+          // T2 (9.1-A) — segregated canvas-content origin. canvasUrl() prepends
+          // it so iframes load cross-origin (hub-pushed JSX is then walled off
+          // from the main origin's /_api). Absent on older servers → relative
+          // URL fallback keeps same-origin behavior.
+          canvasOrigin: data.canvasOrigin,
         });
       })
       .catch(() => {});
     return () => { cancelled = true; };
   }, []);
+  // Backfill the sync banner on mount from /_sync-status. The 'sync:status' WS
+  // broadcast is one-shot for the zero-syncable case (DDR-060 / 9.1-D), so a
+  // tab that connects after boot would otherwise miss it. {linked:false} (solo)
+  // leaves the banner null.
+  useEffect(() => {
+    let cancelled = false;
+    fetch('/_sync-status')
+      .then((r) => r.json())
+      .then((data) => {
+        if (cancelled || !data || data.linked === false) return;
+        setSyncStatus(data);
+      })
+      .catch(() => {});
+    return () => { cancelled = true; };
+  }, []);
   const [commentsByFile, setCommentsByFile] = useState({});      // { file: [Comment] }
   // Phase 6 — the in-iframe composer owns drafting; the shell no longer holds
   // a `draft` state. Mutations route through postMessage → WS instead.
@@ -1555,6 +1691,17 @@ function App() {
       document.documentElement.setAttribute('data-theme', theme);
       localStorage.setItem(THEME_STORE, theme);
     } catch {}
+    // System-review D9 — the canvas-shell chrome (workspace plane, floating
+    // toolbar, minimap, zoom HUD, halos) follows the Maude theme. Broadcast to
+    // EVERY open canvas iframe (not just activePath — several may be open); the
+    // iframe's canvas-shell sets `data-maude-theme` and re-themes its floating
+    // chrome via the --maude-chrome-* family. Artboards keep their DS theme.
+    // Mirrors the git-lifecycle broadcast-to-all loop below. On the initial
+    // mount run iframesRef is empty (no canvas open yet) — a freshly-loaded
+    // iframe instead gets the current theme from the `dgn:'loaded'` handler.
+    for (const el of iframesRef.current.values()) {
+      try { el.contentWindow.postMessage({ dgn: 'theme', theme }, '*'); } catch {}
+    }
   }, [theme]);
 
   // Persist sidebar / hidden-files / DS-body toggles. Mirror theme pattern.
@@ -1669,6 +1816,9 @@ function App() {
             for (const el of iframesRef.current.values()) {
               try { el.contentWindow.postMessage({ dgn: 'ai-activity', file: m.file, entry: m.entry }, '*'); } catch {}
             }
+          } else if (m.type === 'sync:status' && m.payload) {
+            // Phase 9 Task 8 — hub connection state for the offline banner.
+            setSyncStatus(m.payload);
           } else if (m.type === 'git-lifecycle' && m.payload) {
             // Phase 8 Task 7 — branch switch / pull mid-session. Server has
             // already flushed every dirty Y.Doc to JSON; just prompt the user.
@@ -1707,8 +1857,13 @@ function App() {
     setFocusedCommentId(null);
   }, []);
 
-  const openSystem = useCallback(() => {
-    if (!systemData) loadSystemData();
+  const openSystem = useCallback((dsName) => {
+    // DsFolderRow passes the clicked DS name → scope the System view to it so
+    // each folder shows its own tokens + previews. The no-arg callers (menubar,
+    // keyboard reopen) only load default data on first open.
+    const ds = typeof dsName === 'string' ? dsName : undefined;
+    if (ds) loadSystemData(ds);
+    else if (!systemData) loadSystemData();
     openTab(SYSTEM_TAB);
   }, [systemData, loadSystemData, openTab]);
 
@@ -1770,6 +1925,14 @@ function App() {
   // ----- Inbound messages from iframes -----
   useEffect(() => {
     function onMessage(e) {
+      // Cross-origin hardening (DDR-054): only accept dgn control messages from
+      // the canvas-content origin — the split origin when on, else our own origin
+      // for the same-origin iframe. Drops spoofed messages from any other window.
+      // The handlers below relay to inert stores (comments / selection — the
+      // "safe to sync" set), so the blast radius was small, but unchecked inbound
+      // postMessage is a confused-deputy seam the F1 hardening should close.
+      const expectedOrigin = cfg?.canvasOrigin || window.location.origin;
+      if (e.origin !== expectedOrigin) return;
       const m = e.data;
       if (!m || typeof m !== 'object' || !m.dgn) return;
       if (m.dgn === 'select' && m.selection) {
@@ -1841,6 +2004,10 @@ function App() {
         const el = [...iframesRef.current.entries()].find(([k]) => k === m.file)?.[1];
         if (el && el.contentWindow) {
           try { el.contentWindow.postMessage({ dgn: 'comments-set', comments: list }, '*'); } catch {}
+          // System-review D9 — seed the just-loaded canvas with the current
+          // chrome theme so a canvas opened AFTER a theme toggle starts
+          // correct (no flash from the dark default).
+          try { el.contentWindow.postMessage({ dgn: 'theme', theme }, '*'); } catch {}
           if (focusedCommentId && list.some(c => c.id === focusedCommentId)) {
             try { el.contentWindow.postMessage({ dgn: 'comment-focus', id: focusedCommentId }, '*'); } catch {}
           }
@@ -1849,7 +2016,7 @@ function App() {
     }
     window.addEventListener('message', onMessage);
     return () => window.removeEventListener('message', onMessage);
-  }, [commentsByFile, focusedCommentId]);
+  }, [commentsByFile, focusedCommentId, cfg, theme]);
 
   // Tell the active canvas iframe to drop any persistent selection (canvas
   // SelectionSet) — used when the comment composer closes via submit /
@@ -2021,6 +2188,7 @@ function App() {
       className={'app' + (commentsPanelOpen ? ' with-rsidebar' : '') + (sidebarOpen ? '' : ' no-sidebar')}
       onContextMenu={onShellContextMenu}
     >
+      <SyncBanner status={syncStatus} />
       {gitLifecycle && (
         <div
           role="status"
@@ -2075,6 +2243,7 @@ function App() {
       <Sidebar
         groups={groups}
         activePath={activePath}
+        activeDsName={activePath === SYSTEM_TAB ? (systemData?.ds?.name ?? null) : null}
         onOpen={openTab}
         onOpenSystem={openSystem}
         wsConnected={wsConnected}
@@ -2125,6 +2294,7 @@ function App() {
           theme={theme}
           onToggleTheme={toggleTheme}
           onClearSelected={clearSelected}
+          syncStatus={syncStatus}
         />
       </div>
       {commentsPanelOpen && (

package/plugins/design/dev-server/client/styles/3-shell.css

@@ -799,6 +799,16 @@
   background: var(--u-status-error);
 }
 .sb-live .sb-key { color: var(--u-fg-1); }
+/* DDR-060 / 9.1-D — linked-but-0-syncable indicator. Warn dot (heads-up, not
+   error), DS-tokened, hover the label for the full reason via the title attr. */
+.sb-sync { cursor: help; }
+.sb-sync-dot {
+  width: 7px; height: 7px;
+  background: var(--u-status-warn);
+  border-radius: 50%;
+  flex: none;
+}
+.sb-sync .sb-key { color: var(--u-fg-2); }
 .sb-spacer {
   flex: 1 0 auto;
   border-right: 1px solid var(--u-border-subtle);

package/plugins/design/dev-server/collab/awareness-bridge.ts

@@ -0,0 +1,77 @@
+// Bidirectional Awareness relay — Phase 9 Task 5 (awareness over WSS).
+//
+// In linked mode each canvas has TWO Awareness instances in this process:
+//
+//   - the collab Room's Awareness (browser tabs ↔ dev-server, loopback WS)
+//   - the sync provider's Awareness (dev-server ↔ hub, HocuspocusProvider)
+//
+// Hocuspocus relays awareness frames between connected peers on a document out
+// of the box, so the provider's Awareness already reaches cross-continent
+// peers. The only missing link is in-process: this bridge wires the Room's
+// Awareness to the provider's Awareness so a browser cursor published into the
+// Room reaches the hub (and back) without either side knowing about the other.
+//
+// Awareness is EPHEMERAL — it is never persisted to disk. That is why this
+// bridge is decoupled from the file-ownership question (DDR-054 F14): relaying
+// cursors/selections/viewport touches no `.json` / `.svg` / `.html` file, so
+// it neither introduces nor resolves the comments/annotations write race. The
+// doc-content bridge (Room doc ↔ provider doc) is intentionally NOT built here
+// — disk stays the medium between the two docs (Task 4), and F14 remains a
+// documented risk for the doc-content bridge work.
+//
+// Echo prevention: every cross relay applies the update to the far side tagged
+// with a shared BRIDGE origin. Each direction's listener skips updates carrying
+// that origin, so a relayed state never bounces back to where it came from.
+// This is the same pattern y-websocket uses to relay awareness across a fan-out
+// hub. State identity is preserved because awareness updates are keyed by the
+// originating clientID — the random 32-bit ids make local↔remote collisions
+// negligible.
+
+import { applyAwarenessUpdate, encodeAwarenessUpdate } from 'y-protocols/awareness';
+import type { Awareness } from 'y-protocols/awareness';
+
+interface AwarenessChange {
+  added: number[];
+  updated: number[];
+  removed: number[];
+}
+
+/**
+ * Wire `a` ↔ `b` bidirectionally. Existing states on each side are exchanged
+ * immediately so a peer that connected before the bridge existed still shows
+ * up. Returns a detach fn that removes both listeners — call it BEFORE either
+ * Awareness is destroyed, otherwise a late relay would apply to a dead
+ * instance.
+ */
+export function bridgeAwareness(a: Awareness, b: Awareness): () => void {
+  // A single shared origin for both directions. A genuine local change carries
+  // some other origin (a browser conn, the provider's internal token, or null),
+  // so it relays; a change this bridge applied carries BRIDGE, so it stops.
+  const BRIDGE = { awarenessBridge: true };
+
+  function makeRelay(from: Awareness, to: Awareness) {
+    return ({ added, updated, removed }: AwarenessChange, origin: unknown) => {
+      if (origin === BRIDGE) return;
+      const changed = added.concat(updated, removed);
+      if (changed.length === 0) return;
+      applyAwarenessUpdate(to, encodeAwarenessUpdate(from, changed), BRIDGE);
+    };
+  }
+
+  const aToB = makeRelay(a, b);
+  const bToA = makeRelay(b, a);
+
+  // Initial state exchange — push each side's current states to the other.
+  const aClients = Array.from(a.getStates().keys());
+  if (aClients.length > 0) applyAwarenessUpdate(b, encodeAwarenessUpdate(a, aClients), BRIDGE);
+  const bClients = Array.from(b.getStates().keys());
+  if (bClients.length > 0) applyAwarenessUpdate(a, encodeAwarenessUpdate(b, bClients), BRIDGE);
+
+  a.on('update', aToB);
+  b.on('update', bToA);
+
+  return () => {
+    a.off('update', aToB);
+    b.off('update', bToA);
+  };
+}

package/plugins/design/dev-server/collab/index.ts

@@ -1,6 +1,9 @@
 // Public surface of the collab module. Bundles the registry + persistence
 // wiring so ws.ts + server.ts don't need to know about the internal split.
 
+import { readFileSync } from 'node:fs';
+import path from 'node:path';
+
 import type { Api } from '../api.ts';
 import type { Context } from '../context.ts';
 
@@ -14,6 +17,8 @@ export type { CollabConn } from './protocol.ts';
 
 export interface Collab {
   registry: Registry;
+  /** Tear down the fs-driven re-seed subscription (server shutdown). */
+  dispose(): void;
 }
 
 /**
@@ -24,15 +29,21 @@ export interface Collab {
  */
 export function createCollab(ctx: Context, api: Api): Collab {
   // Inverse of api.fileSlug — we have the URL slug, need the canonical
-  // repo-relative path the api expects. The current fileSlug() is destructive
-  // (loses the extension + the designRel prefix), so we round-trip by
-  // scanning loadAllComments — cheap enough at room-open time, and a fresh
-  // canvas with no comments yet just returns null (an empty Y.Doc is correct
-  // in that case).
+  // repo-relative path the api expects.
+  //
+  // Primary: api.fileForSlug scans the ACTUAL canvas files, so it resolves even
+  // when the canvas has no comments yet. This is the fix for the receiving-peer
+  // projection gap — a peer that hasn't yet got a comment for a canvas must
+  // still locate the file to MATERIALIZE the first hub-pushed comment to disk
+  // (DDR-064). The old comments-file scan was chicken-and-egg here: no comments
+  // → null → persistJson bailed → the incoming comment never hit disk.
   //
-  // Task 3 will tighten this to a slug -> file lookup table maintained from
-  // the index/file-tree state so we don't need to read every JSON file.
+  // Fallback: a canvas whose file the scan missed (renamed/moved with an orphan
+  // comments file) still resolves via its existing comments file, preserving
+  // the prior behavior for that edge.
   async function fileForSlug(slug: string): Promise<string | null> {
+    const byCanvas = await api.fileForSlug(slug);
+    if (byCanvas) return byCanvas;
     const all = await api.loadAllComments();
     for (const [file] of Object.entries(all)) {
       if (api.fileSlug(file) === slug) return file;
@@ -40,8 +51,75 @@ export function createCollab(ctx: Context, api: Api): Collab {
     return null;
   }
 
-  const persistence = createPersistence({ ctx, api, fileForSlug });
+  // Phase 9.2 (DDR-064) — under sharedDoc, disable the room's local file-seed
+  // for pinned (provider-attached) slugs so it can't push duplicate Y.Array
+  // items against the hub's canonical items (Risk 1). The registry is created
+  // from the persistence callbacks, so break the cycle with a late-bound ref
+  // (the predicate is only consulted at room-seed time, after `registry` is
+  // assigned). Flag-OFF → predicate returns true → seed unchanged.
+  let registryRef: Registry | null = null;
+  const persistence = createPersistence({
+    ctx,
+    api,
+    fileForSlug,
+    shouldSeed: (slug) => !(ctx.sharedDoc && registryRef?.isPinned(slug)),
+  });
   const registry = createRegistry(persistence);
+  registryRef = registry;
+
+  // File = truth (the file-sync collaboration model + DDR-051): when a synced
+  // file changes on disk from OUTSIDE the API path — the sync agent writing a
+  // hub-pushed diff, or `design:edit` editing a JSON/SVG directly — fan the
+  // change back out to the browser, since none of these go through the API's
+  // onCommentsChanged. Two consumers, two reasons:
+  //   - the live collab room (canvas pins / annotation strokes) — re-seeded so
+  //     its in-memory doc stops clobbering the external change on next persist
+  //     (the cross-machine "comment reverts to []" bug). Only when a room is
+  //     mounted (peek, never create).
+  //   - the shell's comments SIDEBAR — driven solely by the 'comments' WS event
+  //     (app.jsx), which otherwise fires only on API writes. Emit it here too so
+  //     a hub-pushed comment shows up on the peer's sidebar without a reload.
+  // The registry's no-op guards make an identical re-seed free, so this can't
+  // loop against the room's own persist (which also writes the file).
+  const reseedFromDisk = async (rel: string): Promise<void> => {
+    const cm = /^_comments\/(.+)\.json$/.exec(rel);
+    const am = /^(.+)\.annotations\.svg$/.exec(rel);
+    const slug = cm?.[1] ?? am?.[1];
+    if (!slug) return;
+    const abs = path.join(ctx.paths.designRoot, rel);
+    try {
+      if (cm) {
+        // Prefer the canonical loader (validates + default-fills the Comment
+        // shape) keyed by the canvas file; fall back to the raw array when the
+        // slug isn't mapped yet (e.g. a freshly-synced file with no prior load).
+        const file = await fileForSlug(slug);
+        const parsed = file
+          ? await api.loadCommentsForFile(file)
+          : JSON.parse(readFileSync(abs, 'utf8'));
+        if (!Array.isArray(parsed)) return;
+        // Phase 9.2 (DDR-064): under sharedDoc the hub provider is attached to
+        // the single room doc, so a hub-pushed comment is ALREADY in the room —
+        // the wholesale re-seed (last-writer-wins blob copy) is the retired
+        // clobber path. The agent's diff-aware applyFromFs handles external
+        // file→doc imports instead. The sidebar still needs the 'comments' bus
+        // emit, so keep that unconditionally.
+        if (!ctx.sharedDoc && registry.peek(slug)) registry.syncRoomFromComments(slug, parsed);
+        if (file) ctx.bus.emit('comments', { file, comments: parsed });
+      } else if (!ctx.sharedDoc && registry.peek(slug)) {
+        registry.syncRoomFromAnnotations(slug, readFileSync(abs, 'utf8'));
+      }
+    } catch {
+      /* file vanished mid-flight or unreadable — leave state as-is */
+    }
+  };
+  const unsubFs = ctx.bus.on('fs:any', (rel: string) => {
+    void reseedFromDisk(rel);
+  });
 
-  return { registry };
+  return {
+    registry,
+    dispose() {
+      unsubFs?.();
+    },
+  };
 }