@1agh/maude 0.23.0 → 0.24.0

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

@@ -103,10 +103,10 @@ function canvasUrl(p, cfg, opts) {
   if (tokens) params.set('tokens', tokens);
   if (cfg?.componentsCssRel) params.set('components', cfg.componentsCssRel);
   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 /
@@ -116,7 +116,11 @@ function canvasUrl(p, cfg, opts) {
       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) {
@@ -912,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 (
@@ -1100,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' }
+              : {})}
           />
         );
       })}
@@ -1310,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, { thumbnail: true })} 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>
@@ -1352,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)}"` : '')
@@ -1385,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">
@@ -1490,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() {
@@ -1503,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
@@ -1523,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.
@@ -1571,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.
@@ -1685,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.
@@ -1791,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) {
@@ -1862,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 {}
           }
@@ -1870,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 /
@@ -2042,6 +2188,7 @@ function App() {
       className={'app' + (commentsPanelOpen ? ' with-rsidebar' : '') + (sidebarOpen ? '' : ' no-sidebar')}
       onContextMenu={onShellContextMenu}
     >
+      <SyncBanner status={syncStatus} />
       {gitLifecycle && (
         <div
           role="status"
@@ -2147,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/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?.();
+    },
+  };
 }

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

@@ -36,6 +36,15 @@ export interface PersistenceDeps {
   fileForSlug: (slug: string) => Promise<string | null>;
   /** Best-effort cache primer — see fileForSlug above. */
   noteFile?: (file: string) => void;
+  /**
+   * Phase 9.2 (DDR-064) — when this returns false for a slug, `seed` is a no-op
+   * for it. The shared-doc path passes a predicate that returns false for
+   * pinned (provider-attached) slugs, so the local file-seed can't push fresh
+   * Y.Array items that would DUPLICATE the hub's canonical items on merge
+   * (Risk 1). The migrate-seed + provider own initial population for those
+   * slugs. Absent → always seed (flag-OFF behavior, unchanged).
+   */
+  shouldSeed?: (slug: string) => boolean;
 }
 
 /**
@@ -50,6 +59,16 @@ export function createPersistence(deps: PersistenceDeps): RoomCallbacks {
   const { ctx, api, fileForSlug } = deps;
   const stateDir = ensureStateDir(ctx.paths.designRoot);
 
+  // Per-slug latch: have we ever projected a NON-empty comments array for this
+  // canvas? We write an empty `[]` to disk only AFTER content has been seen — a
+  // genuine delete-all — never from a doc that was never populated (cold start
+  // before seed/migrate completes), which would clobber a non-empty local file.
+  // This closes the receiving-peer gap where a delete-all on one peer left
+  // stragglers on the other: the old `arr.length > 0` guard skipped the write
+  // when the array emptied, so the deletion never reached the peer's JSON file
+  // (the file the sidebar reads), even though the Y.Doc had converged (DDR-064).
+  const seenComments = new Set<string>();
+
   function ydocBinPath(slug: string): string {
     return path.join(stateDir, `${slug}.ydoc.bin`);
   }
@@ -66,6 +85,13 @@ export function createPersistence(deps: PersistenceDeps): RoomCallbacks {
   }
 
   async function seed(slug: string, doc: Y.Doc): Promise<void> {
+    // Phase 9.2 (DDR-064) — under sharedDoc the migrate-seed + hub provider own
+    // initial population for a pinned slug; a local file-seed here would push
+    // fresh Y.Array items that DUPLICATE the hub's canonical items on merge
+    // (Risk 1). Skip seeding when the predicate says so. Flag-OFF / unpinned →
+    // always seeds (predicate absent or returns true).
+    if (deps.shouldSeed && !deps.shouldSeed(slug)) return;
+
     // Step 1 — try the binary cache.
     const binary = await readBinary(slug);
     if (binary && binary.byteLength > 0) {
@@ -100,10 +126,15 @@ export function createPersistence(deps: PersistenceDeps): RoomCallbacks {
     const file = await fileForSlug(slug);
     if (!file) return;
 
-    // Comments — Y.Array projection back to JSON.
+    // Comments — Y.Array projection back to JSON. Write whenever the doc holds
+    // comments, OR when it just emptied after previously holding some (so a
+    // delete-all materializes on EVERY peer's disk, not just the originator's).
+    // The seenComments latch keeps a never-populated doc (cold start) from
+    // clobbering a non-empty local file with [].
     const arr = doc.getArray(Y_TYPES.comments);
-    if (arr.length > 0) {
-      const list = arr.toArray() as Parameters<Api['saveCommentsForFile']>[1];
+    const list = arr.toArray() as Parameters<Api['saveCommentsForFile']>[1];
+    if (list.length > 0) seenComments.add(slug);
+    if (list.length > 0 || seenComments.has(slug)) {
       await api.saveCommentsForFile(file, list);
     }
 

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

@@ -13,11 +13,32 @@ import { Y_TYPES } from './persistence.ts';
 import type { Room, RoomCallbacks } from './room.ts';
 import { createRoom } from './room.ts';
 
+/** Structural equality via canonical JSON — used by the syncRoomFrom* no-op
+ *  guards. Comment lists are small; stringify is cheap + dependency-free. */
+function jsonEqual(a: unknown, b: unknown): boolean {
+  return JSON.stringify(a) === JSON.stringify(b);
+}
+
 export interface Registry {
   /** Get-or-create. Reuses an existing room for the same slug. */
   get(slug: string): Room;
   /** Existence check — returns the live room if any, else null. NEVER creates. */
   peek(slug: string): Room | null;
+  /**
+   * Phase 9.2 (DDR-064) — the single cached `Y.Doc` for a slug, creating the
+   * owning Room if necessary. This is the seam the shared-doc path attaches its
+   * hub-facing `HocuspocusProvider` to (Phase B): the doc must exist
+   * independent of a live browser connection so the provider can attach at
+   * serve start. Repeated calls return the SAME instance (the room's doc) —
+   * the y-websocket-server `getYDoc(name)` single-cache pattern.
+   *
+   * Phase A: defined but unused (the flag-OFF two-doc path never calls it), so
+   * adding it is behavior-neutral. NOTE: a room created via `getDoc` (no
+   * browser conn) is NOT auto-dropped by the `size()===0` check in `drop` until
+   * Phase B teaches the lifecycle that an attached provider keeps it alive;
+   * for Phase A nothing calls `getDoc`, so no room leaks.
+   */
+  getDoc(slug: string): import('yjs').Doc;
   /**
    * Phase 8 Task 3 bridge — inspector-channel writes (REST `/_api/comments*`
    * or the legacy WS comments-add path) call this so the live Y.Array sees
@@ -47,6 +68,22 @@ export interface Registry {
    * no files (see awareness-bridge.ts on why F14 is untouched).
    */
   attachHubAwareness(slug: string, awareness: Awareness): () => void;
+  /**
+   * Phase 9.2 (DDR-064) — pin a room so `drop` won't destroy it when the last
+   * browser leaves. The shared-doc path pins a slug while a hub
+   * `HocuspocusProvider` is attached to its `getDoc(slug)`: destroying the
+   * room (→ `doc.destroy()`) would pull the doc out from under the live
+   * provider. Self-gating — only the flag-ON sync runtime calls `pin`, so the
+   * flag-OFF `drop` lifecycle is byte-for-byte unchanged. Idempotent.
+   */
+  pin(slug: string): void;
+  /** Release a pin (provider detached on runtime stop). Idempotent. */
+  unpin(slug: string): void;
+  /** True when a slug is pinned (a shared-doc provider is attached). Used to
+   *  disable the room's local file-seed for that slug under sharedDoc — the
+   *  migrate-seed + provider own initial population, so a duplicate file-seed
+   *  can't re-introduce items (DDR-064 Risk 1). */
+  isPinned(slug: string): boolean;
   /** Flush every dirty room synchronously. DDR-051 branch-switch path. */
   flushAll(): Promise<void>;
   /** Tear down everything (e.g. on server shutdown). */
@@ -64,6 +101,11 @@ export function createRegistry(callbacks: RoomCallbacks): Registry {
   // is (re)created for a slug that has an attached hub Awareness.
   const hubAwareness = new Map<string, Awareness>();
   const bridges = new Map<string, () => void>();
+  // Phase 9.2 (DDR-064) — slugs whose room must survive the last-browser-leaves
+  // drop because a shared-doc hub provider is attached to its doc. Only the
+  // flag-ON sync runtime ever adds to this; flag-OFF leaves it empty so `drop`
+  // is unchanged.
+  const pinned = new Set<string>();
 
   function wireBridge(slug: string, room: Room): void {
     if (bridges.has(slug)) return;
@@ -104,11 +146,37 @@ export function createRegistry(callbacks: RoomCallbacks): Registry {
     return rooms.get(slug) ?? null;
   }
 
+  function getDoc(slug: string): import('yjs').Doc {
+    // Reuse get-or-create so the doc, awareness, persistence schedule, and
+    // (idempotent) awareness-bridge wiring are all set up exactly once. The
+    // room's doc IS the single shared doc for this slug.
+    return get(slug).doc;
+  }
+
+  function pin(slug: string): void {
+    pinned.add(slug);
+  }
+
+  function unpin(slug: string): void {
+    pinned.delete(slug);
+  }
+
+  function isPinned(slug: string): boolean {
+    return pinned.has(slug);
+  }
+
   function syncRoomFromComments(slug: string, comments: readonly unknown[]): void {
     const room = rooms.get(slug);
     if (!room) return;
+    const arr = room.doc.getArray<unknown>(Y_TYPES.comments);
+    // No-op guard (load-bearing): skip when the room already holds this exact
+    // list. The wholesale delete+push always emits a doc update, which schedules
+    // a persist → file write → fs event → re-seed … so without this equality
+    // short-circuit, re-seeding the live room from a disk change (sync-agent or
+    // design:edit write — see createCollab's fs hook) would spin an 800ms
+    // persist storm. Equality breaks the loop after a single convergence.
+    if (jsonEqual(arr.toArray(), comments)) return;
     room.doc.transact(() => {
-      const arr = room.doc.getArray<unknown>(Y_TYPES.comments);
       if (arr.length > 0) arr.delete(0, arr.length);
       if (comments.length > 0) arr.push(comments as unknown[]);
     }, 'inspector-write');
@@ -117,8 +185,9 @@ export function createRegistry(callbacks: RoomCallbacks): Registry {
   function syncRoomFromAnnotations(slug: string, svg: string): void {
     const room = rooms.get(slug);
     if (!room) return;
+    const map = room.doc.getMap<string>(Y_TYPES.annotations);
+    if (map.get('svg') === svg) return; // no-op guard — same rationale as comments
     room.doc.transact(() => {
-      const map = room.doc.getMap<string>(Y_TYPES.annotations);
       map.set('svg', svg);
     }, 'inspector-write');
   }
@@ -131,6 +200,11 @@ export function createRegistry(callbacks: RoomCallbacks): Registry {
     const room = rooms.get(slug);
     if (!room) return;
     if (room.size() > 0) return; // still active, leave it
+    // Phase 9.2 (DDR-064) — a pinned room has a shared-doc hub provider attached
+    // to its doc; destroying it would yank the doc out from under the provider.
+    // Leave it (with zero browser conns) until runtime stop / server shutdown.
+    // Empty in the flag-OFF path → no behavior change.
+    if (pinned.has(slug)) return;
     // Tear the bridge down before room.destroy() runs awareness.destroy() —
     // a late relay must not fire against a dead Awareness. The hub Awareness
     // stays registered, so a reconnecting browser re-wires via get().
@@ -150,9 +224,13 @@ export function createRegistry(callbacks: RoomCallbacks): Registry {
   return {
     get,
     peek,
+    getDoc,
     syncRoomFromComments,
     syncRoomFromAnnotations,
     attachHubAwareness,
+    pin,
+    unpin,
+    isPinned,
     flushAll,
     destroyAll,
     drop,