@1agh/maude 0.22.2 → 0.24.0

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

@@ -6,15 +6,39 @@
 // call into (Phase 8 Task 7) to force-snapshot every dirty room before a reload
 // prompt — see DDR-051 §3.
 
+import type { Awareness } from 'y-protocols/awareness';
+
+import { bridgeAwareness } from './awareness-bridge.ts';
 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
@@ -34,6 +58,32 @@ export interface Registry {
    * updated stroke set without waiting for a cold-open re-seed.
    */
   syncRoomFromAnnotations(slug: string, svg: string): void;
+  /**
+   * Phase 9 Task 5 — attach the hub-side Awareness (from a sync provider) for
+   * a slug so the Room's Awareness (browser peers) is bridged bidirectionally
+   * to the hub. While attached, cursors / selections / viewport relay
+   * cross-machine through Hocuspocus. Idempotent per slug; returns a detach
+   * fn. If a room is already live the bridge wires immediately, otherwise it
+   * wires when the room is next created. Awareness is ephemeral — this writes
+   * 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). */
@@ -46,25 +96,87 @@ export interface Registry {
 
 export function createRegistry(callbacks: RoomCallbacks): Registry {
   const rooms = new Map<string, Room>();
+  // Hub-side Awareness per slug (lives as long as the sync provider). Rooms
+  // churn as browser tabs come and go; the bridge is re-wired each time a room
+  // 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;
+    const hub = hubAwareness.get(slug);
+    if (!hub) return;
+    bridges.set(slug, bridgeAwareness(room.awareness, hub));
+  }
+
+  function teardownBridge(slug: string): void {
+    const detach = bridges.get(slug);
+    if (detach) {
+      detach();
+      bridges.delete(slug);
+    }
+  }
 
   function get(slug: string): Room {
     let room = rooms.get(slug);
     if (!room) {
       room = createRoom(slug, callbacks);
       rooms.set(slug, room);
+      wireBridge(slug, room);
     }
     return room;
   }
 
+  function attachHubAwareness(slug: string, awareness: Awareness): () => void {
+    hubAwareness.set(slug, awareness);
+    const room = rooms.get(slug);
+    if (room) wireBridge(slug, room);
+    return () => {
+      teardownBridge(slug);
+      if (hubAwareness.get(slug) === awareness) hubAwareness.delete(slug);
+    };
+  }
+
   function peek(slug: string): Room | null {
     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');
@@ -73,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');
   }
@@ -87,11 +200,22 @@ 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().
+    teardownBridge(slug);
     rooms.delete(slug);
     await room.destroy();
   }
 
   async function destroyAll(): Promise<void> {
+    for (const slug of Array.from(bridges.keys())) teardownBridge(slug);
+    hubAwareness.clear();
     const all = Array.from(rooms.values());
     rooms.clear();
     await Promise.all(all.map((r) => r.destroy()));
@@ -100,8 +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/config.schema.json

@@ -180,6 +180,26 @@
       "type": ["string", "null"],
       "description": "Name of the DS used when a canvas's .meta.json has no 'designSystem' field. For single-DS projects, this is the only DS. For multi-DS, pick the most common.",
       "default": null
+    },
+    "linkedHub": {
+      "type": "object",
+      "description": "Pairs this repo with a Maude hub for cross-machine file sync (Phase 9 Task 3+4). Written by 'maude design link <url> --token <hex>'. Token NEVER lives in this committed config — it's stored per-machine in ~/.config/maude/hubs.json. When present, 'maude design serve' starts the bidirectional Yjs↔fs sync agent (Task 4).",
+      "required": ["url", "linkedAt"],
+      "properties": {
+        "url": {
+          "type": "string",
+          "description": "Hub base URL (normalized — trailing slash trimmed, scheme + host lowercased). The sync agent constructs ws(s)://<host> from this for the HocuspocusProvider connection."
+        },
+        "linkedAt": {
+          "type": "number",
+          "description": "Unix-ms timestamp from when 'maude design link' was first run on this repo."
+        },
+        "adopt": {
+          "type": "boolean",
+          "description": "When true, the first sync after boot pushes local disk state up to the hub unconditionally (use case: bootstrapping the hub from a populated repo, or hub-was-wiped recovery). Cleared after first successful adopt."
+        }
+      },
+      "additionalProperties": false
     }
   }
 }

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

@@ -25,6 +25,12 @@ export interface DesignSystemEntry {
   newComponentDir?: string;
 }
 
+export interface LinkedHub {
+  url: string;
+  linkedAt: number;
+  adopt?: boolean;
+}
+
 export interface DevServerConfig {
   name: string;
   projectLabel: string | null;
@@ -39,6 +45,7 @@ export interface DevServerConfig {
   handoffTargets: unknown[];
   newCanvasDir: string;
   newComponentDir: string;
+  linkedHub?: LinkedHub;
   _source: ConfigSource;
 }
 
@@ -110,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 {

package/plugins/design/dev-server/contextual-toolbar.tsx

@@ -41,14 +41,14 @@ const CTX_TOOLBAR_CSS = `
   align-items: stretch;
   gap: 2px;
   padding: 4px;
-  background: var(--u-bg-0, var(--bg-0, #ffffff));
-  border: 1px solid var(--u-fg-0, #1c1917);
+  background: var(--maude-chrome-bg-0, #ffffff);
+  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);
-  font-family: var(--u-font-mono, ui-monospace, SFMono-Regular, Menlo, monospace);
+  box-shadow: 0 6px 24px var(--maude-chrome-shadow, color-mix(in oklab, #1c1917 10%, transparent));
+  font-family: var(--maude-chrome-font-mono, ui-monospace, SFMono-Regular, Menlo, monospace);
   font-size: 11px;
   letter-spacing: 0.02em;
-  color: var(--u-fg-0, #1a1a1a);
+  color: var(--maude-chrome-fg-0, #1a1a1a);
   user-select: none;
   opacity: 0;
   transition: opacity 100ms cubic-bezier(0.4, 0, 0.2, 1);
@@ -72,8 +72,8 @@ const CTX_TOOLBAR_CSS = `
 }
 .dc-elem-ctx-tb .dc-elem-ctx-count {
   padding: 4px 8px 4px 10px;
-  color: var(--fg-1, rgba(40,30,20,0.7));
-  border-right: 1px solid var(--u-border-subtle, rgba(0,0,0,0.08));
+  color: var(--maude-chrome-fg-1, rgba(40,30,20,0.7));
+  border-right: 1px solid var(--maude-chrome-border, rgba(0,0,0,0.08));
   margin-right: 2px;
   font-variant-numeric: tabular-nums;
 }