@1agh/maude 0.23.0 → 0.25.0

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,

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

@@ -73,6 +73,14 @@ export function createRoom(slug: string, callbacks: RoomCallbacks): Room {
   const awareness = new Awareness(doc);
 
   const conns = new Map<string, RoomConn>();
+  // clientID → owning conn.id, learned from the origin of each awareness update.
+  // Server-authoritative: we do NOT trust a client-supplied `__connId` (awareness
+  // is attacker-influenceable through a semi-trusted hub — DDR-054). On disconnect
+  // we remove exactly the clientIDs this conn published so other peers drop the
+  // avatar immediately, instead of waiting out the ~30s awareness timeout (which
+  // let phantom peers pile up on rapid reconnects — the cross-origin repro that
+  // surfaced this latent bug).
+  const connByClient = new Map<number, string>();
   let dirty = false;
   let flushTimer: ReturnType<typeof setTimeout> | null = null;
   let destroyed = false;
@@ -138,6 +146,13 @@ export function createRoom(slug: string, callbacks: RoomCallbacks): Room {
       if (changed.length === 0) return;
       const except =
         origin && typeof origin === 'object' && 'id' in origin ? (origin as RoomConn) : undefined;
+      // Learn which clientIDs belong to which conn from the update origin, so
+      // disconnect() can evict them precisely.
+      if (except) {
+        for (const id of added) connByClient.set(id, except.id);
+        for (const id of updated) connByClient.set(id, except.id);
+        for (const id of removed) connByClient.delete(id);
+      }
       broadcast(encodeAwarenessFrame(awareness, changed), except);
     }
   );
@@ -161,16 +176,14 @@ export function createRoom(slug: string, callbacks: RoomCallbacks): Room {
 
   function disconnect(conn: RoomConn): void {
     conns.delete(conn.id);
-    // Awareness states keyed by the conn token; clean them up so other peers'
-    // cursor renderers can drop the avatar.
-    const states = awareness.getStates();
+    // Remove the awareness states this conn published (tracked by update origin
+    // in connByClient) so other peers' cursor renderers drop the avatar now,
+    // not after the ~30s awareness timeout.
     const stale: number[] = [];
-    for (const clientId of states.keys()) {
-      // Bridge: our Awareness state setters tag the state with `__connId`
-      // matching conn.id; remove states whose owning conn just left.
-      const state = states.get(clientId) as { __connId?: string } | undefined;
-      if (state && state.__connId === conn.id) stale.push(clientId);
+    for (const [clientId, connId] of connByClient) {
+      if (connId === conn.id) stale.push(clientId);
     }
+    for (const clientId of stale) connByClient.delete(clientId);
     if (stale.length) removeAwarenessStates(awareness, stale, conn);
   }
 

package/plugins/design/dev-server/context-menu.tsx

@@ -55,6 +55,15 @@ export interface MenuItem {
   shortcut?: string;
   destructive?: boolean;
   disabled?: boolean;
+  /**
+   * Optional nested flyout (e.g. `Theme ▸ DS default / Light / Dark / Follow
+   * chrome`). When present the row opens a submenu on hover / ArrowRight /
+   * click and `onSelect` on THIS item is not invoked — only the chosen leaf's
+   * `onSelect` fires. A disabled leaf carries `disabledHint` for its title.
+   */
+  submenu?: MenuItem[];
+  /** Hover/title hint shown when the item is `disabled` (a11y affordance). */
+  disabledHint?: string;
   onSelect: (target: ContextTarget) => void;
 }
 
@@ -158,20 +167,20 @@ const MENU_CSS = `
 .dc-context-menu {
   position: fixed;
   z-index: 7;
-  background: var(--u-bg-0, var(--bg-0, #fff));
-  border: 1px solid var(--u-fg-0, #1c1917);
+  background: var(--maude-chrome-bg-0, #fff);
+  border: 1px solid var(--maude-chrome-fg-0, #1c1917);
   border-radius: 8px;
-  box-shadow: 0 6px 24px color-mix(in oklab, var(--u-fg-0, #1c1917) 10%, transparent);
+  box-shadow: 0 6px 24px var(--maude-chrome-shadow, color-mix(in oklab, #1c1917 10%, transparent));
   padding: 4px;
   min-width: 220px;
-  font-family: var(--u-font-mono, ui-monospace, SFMono-Regular, Menlo, monospace);
+  font-family: var(--maude-chrome-font-mono, ui-monospace, SFMono-Regular, Menlo, monospace);
   font-size: 12px;
-  color: var(--u-fg-0, var(--fg-0, rgba(20,15,10,0.92)));
+  color: var(--maude-chrome-fg-0, rgba(20,15,10,0.92));
   user-select: none;
 }
 .dc-context-menu .dc-menu-sep {
   height: 1px;
-  background: var(--border-subtle, rgba(0,0,0,0.08));
+  background: var(--maude-chrome-border, rgba(0,0,0,0.08));
   margin: 4px -4px;
 }
 .dc-context-menu .dc-menu-item {
@@ -191,7 +200,7 @@ const MENU_CSS = `
 }
 .dc-context-menu .dc-menu-item:hover,
 .dc-context-menu .dc-menu-item:focus-visible {
-  background: var(--u-bg-3, var(--bg-3, rgba(0,0,0,0.05)));
+  background: color-mix(in oklab, var(--maude-chrome-fg-0, #1c1917) 8%, transparent);
   outline: none;
 }
 .dc-context-menu .dc-menu-item[disabled] {
@@ -204,11 +213,28 @@ const MENU_CSS = `
   color: var(--accent-fg, #fff);
 }
 .dc-context-menu .dc-menu-shortcut {
-  color: var(--fg-2, rgba(40,30,20,0.55));
+  color: var(--maude-chrome-fg-1, rgba(40,30,20,0.55));
   font-family: ui-monospace, SFMono-Regular, Menlo, monospace;
   font-size: 10px;
   font-variant-numeric: tabular-nums;
 }
+/* Submenu flyout (Theme ▸ …). Anchored to the right of its parent row; flips
+   left near the viewport edge via .is-flip. Reuses .dc-menu-item styling. */
+.dc-context-menu .dc-menu-sub { position: relative; }
+.dc-context-menu .dc-menu-caret { color: var(--maude-chrome-fg-1, rgba(40,30,20,0.55)); font-size: 11px; }
+.dc-context-menu .dc-menu-flyout {
+  position: absolute;
+  top: -5px;
+  left: calc(100% + 3px);
+  min-width: 196px;
+  padding: 4px;
+  background: var(--maude-chrome-bg-0, #fff);
+  border: 1px solid var(--maude-chrome-fg-0, #1c1917);
+  border-radius: 8px;
+  box-shadow: 0 6px 24px var(--maude-chrome-shadow, color-mix(in oklab, #1c1917 10%, transparent));
+  z-index: 8;
+}
+.dc-context-menu .dc-menu-flyout.is-flip { left: auto; right: calc(100% + 3px); }
 `.trim();
 
 function ensureMenuStyles(): void {
@@ -346,21 +372,7 @@ function ContextMenuView({
           <div key={sectionKey} role="group">
             {si > 0 ? <div className="dc-menu-sep" aria-hidden="true" /> : null}
             {section.map((item) => (
-              <button
-                key={item.id}
-                type="button"
-                role="menuitem"
-                disabled={item.disabled}
-                className={`dc-menu-item${item.destructive ? ' is-destructive' : ''}`}
-                onClick={() => {
-                  if (item.disabled) return;
-                  item.onSelect(target);
-                  onClose();
-                }}
-              >
-                <span>{item.label}</span>
-                {item.shortcut ? <span className="dc-menu-shortcut">{item.shortcut}</span> : null}
-              </button>
+              <MenuItemRow key={item.id} item={item} target={target} onClose={onClose} />
             ))}
           </div>
         );
@@ -368,3 +380,135 @@ function ContextMenuView({
     </div>
   );
 }
+
+// ─────────────────────────────────────────────────────────────────────────────
+// MenuItemRow — a single menu row. Plain rows render a button; rows with a
+// `submenu` render a flyout (opens on hover / ArrowRight / click). Additive:
+// existing flat registries (no `submenu`) take the plain-button path unchanged.
+
+function MenuItemRow({
+  item,
+  target,
+  onClose,
+}: {
+  item: MenuItem;
+  target: ContextTarget;
+  onClose: () => void;
+}) {
+  const [subOpen, setSubOpen] = useState(false);
+  const [flip, setFlip] = useState(false);
+  const btnRef = useRef<HTMLButtonElement>(null);
+  const flyoutRef = useRef<HTMLDivElement>(null);
+  const closeTimer = useRef<ReturnType<typeof setTimeout> | null>(null);
+
+  if (!item.submenu || item.submenu.length === 0) {
+    return (
+      <button
+        type="button"
+        role="menuitem"
+        disabled={item.disabled}
+        title={item.disabled ? item.disabledHint : undefined}
+        className={`dc-menu-item${item.destructive ? ' is-destructive' : ''}`}
+        onClick={() => {
+          if (item.disabled) return;
+          item.onSelect(target);
+          onClose();
+        }}
+      >
+        <span>{item.label}</span>
+        {item.shortcut ? <span className="dc-menu-shortcut">{item.shortcut}</span> : null}
+      </button>
+    );
+  }
+
+  const cancelClose = () => {
+    if (closeTimer.current) {
+      clearTimeout(closeTimer.current);
+      closeTimer.current = null;
+    }
+  };
+  const open = (focusFirst = false) => {
+    cancelClose();
+    const r = btnRef.current?.getBoundingClientRect();
+    if (r && typeof window !== 'undefined') setFlip(r.right + 200 > window.innerWidth);
+    setSubOpen(true);
+    if (focusFirst) {
+      setTimeout(() => {
+        flyoutRef.current
+          ?.querySelector<HTMLButtonElement>('button.dc-menu-item:not([disabled])')
+          ?.focus();
+      }, 0);
+    }
+  };
+  const scheduleClose = () => {
+    cancelClose();
+    closeTimer.current = setTimeout(() => setSubOpen(false), 140);
+  };
+
+  return (
+    <div className="dc-menu-sub" onMouseEnter={() => open()} onMouseLeave={scheduleClose}>
+      <button
+        ref={btnRef}
+        type="button"
+        role="menuitem"
+        aria-haspopup="menu"
+        aria-expanded={subOpen}
+        disabled={item.disabled}
+        className="dc-menu-item"
+        onClick={() => (subOpen ? setSubOpen(false) : open())}
+        onKeyDown={(e) => {
+          if (e.key === 'ArrowRight' || e.key === 'Enter' || e.key === ' ') {
+            e.preventDefault();
+            open(true);
+          } else if (e.key === 'ArrowLeft' || e.key === 'Escape') {
+            if (subOpen) {
+              e.stopPropagation();
+              setSubOpen(false);
+            }
+          }
+        }}
+      >
+        <span>{item.label}</span>
+        <span className="dc-menu-caret" aria-hidden="true">
+          ▸
+        </span>
+      </button>
+      {subOpen ? (
+        <div
+          ref={flyoutRef}
+          className={`dc-menu-flyout${flip ? ' is-flip' : ''}`}
+          role="menu"
+          onMouseEnter={cancelClose}
+          onMouseLeave={scheduleClose}
+        >
+          {item.submenu.map((sub) => (
+            <button
+              key={sub.id}
+              type="button"
+              role="menuitem"
+              disabled={sub.disabled}
+              title={sub.disabled ? sub.disabledHint : undefined}
+              className={`dc-menu-item${sub.destructive ? ' is-destructive' : ''}`}
+              onClick={() => {
+                if (sub.disabled) return;
+                sub.onSelect(target);
+                onClose();
+              }}
+              onKeyDown={(e) => {
+                if (e.key === 'ArrowLeft' || e.key === 'Escape') {
+                  e.preventDefault();
+                  e.stopPropagation();
+                  setSubOpen(false);
+                  btnRef.current?.focus();
+                }
+              }}
+            >
+              <span>{sub.label}</span>
+              {sub.shortcut ? <span className="dc-menu-shortcut">{sub.shortcut}</span> : null}
+            </button>
+          ))}
+        </div>
+      ) : null}
+    </div>
+  );
+}

package/plugins/design/dev-server/context.ts

@@ -117,6 +117,30 @@ export interface Context {
   projectLabel: string;
   paths: Paths;
   bus: Bus;
+  /**
+   * T2 (9.1-A) — origin of the segregated canvas-content server (e.g.
+   * `http://localhost:51234`), set by server.ts once the second listener binds.
+   * The client reads it via /_config to build absolute, cross-origin iframe
+   * URLs. Undefined in tests / before the canvas listener boots.
+   */
+  canvasOrigin?: string;
+  /**
+   * T2 (9.1-A) — origin of the MAIN dev-server listener (e.g.
+   * `http://localhost:4399`), set by server.ts once the primary listener binds.
+   * Used by `cspForCanvasShell` to allowlist the legit embedder in the canvas
+   * origin's `frame-ancestors`. Undefined in tests / before boot.
+   */
+  mainOrigin?: string;
+  /**
+   * Phase 9.2 (DDR-064) — `MAUDE_SHARED_DOC` feature flag. When true, the
+   * collab room's Y.Doc becomes the SINGLE shared doc per canvas: the
+   * hub-facing HocuspocusProvider attaches to it directly (no second doc, no
+   * disk-mediated reconcile). Default `false`/undefined = the proven two-doc
+   * path = zero regression. Set by server.ts from the env; tests set it
+   * directly on the Context they construct. Threaded through Phase A; the flag
+   * gates behavior starting in Phase B.
+   */
+  sharedDoc?: boolean;
 }
 
 function resolveRepoRoot(): string {