@1agh/maude 0.22.2 → 0.23.0

package/plugins/design/dev-server/canvas-shell.tsx

@@ -48,7 +48,6 @@ import {
   useViewportControllerContext,
 } from './canvas-lib.tsx';
 import { type AlignMode, alignLabel, equalSpacingLabel } from './commands/equal-spacing-command.ts';
-import { CommentsOverlay } from './comments-overlay.tsx';
 import {
   ContextMenuProvider,
   type ContextRegistry,
@@ -59,6 +58,15 @@ import {
 } from './context-menu.tsx';
 import { ContextualToolbar } from './contextual-toolbar.tsx';
 import { CursorsOverlay } from './cursors-overlay.tsx';
+import {
+  cssEscape,
+  cssPath,
+  deriveFile,
+  domPath,
+  hoverTargetToSelection,
+  realClasses,
+  shortText,
+} from './dom-selection.ts';
 import { EqualSpacingHandles } from './equal-spacing-handles.tsx';
 import { ExportDialogProvider } from './export-dialog.tsx';
 import { type HoverTarget, resolveHoverTarget, useInputRouter } from './input-router.tsx';
@@ -75,7 +83,11 @@ import { AnnotationsVisibilityProvider } from './use-annotations-visibility.tsx'
 import { useCollab } from './use-collab.tsx';
 import { useCursorModifiers } from './use-cursor-modifiers.tsx';
 import { useKeyboardDiscipline } from './use-keyboard-discipline.tsx';
-import { type Selection, SelectionSetProvider, useSelectionSet } from './use-selection-set.tsx';
+import {
+  MaybeSelectionSetProvider,
+  type Selection,
+  useSelectionSet,
+} from './use-selection-set.tsx';
 import { useToolMode } from './use-tool-mode.tsx';
 import { useUndoStack } from './use-undo-stack.tsx';
 
@@ -303,14 +315,17 @@ export function CanvasShell({
   ensureHaloStyles();
   // ToolProvider is mounted by DesignCanvas one level up (so the viewport
   // controller's `isPanDragActive` predicate can read the live tool state).
+  // SelectionSetProvider is mounted via MaybeSelectionSetProvider — the shell-
+  // owned comment mount layer provides one, in which case CanvasShell consumes
+  // that single instance so the comment router + halos share one selection set.
   return (
-    <SelectionSetProvider>
+    <MaybeSelectionSetProvider>
       <AnnotationSelectionProvider>
         <AnnotationsVisibilityProvider>
           <CanvasCore hostRef={hostRef}>{children}</CanvasCore>
         </AnnotationsVisibilityProvider>
       </AnnotationSelectionProvider>
-    </SelectionSetProvider>
+    </MaybeSelectionSetProvider>
   );
 }
 
@@ -1020,103 +1035,18 @@ function CanvasRouter({
         annotSel.clear();
         setHoverEl(null);
       },
-      onDropComment: ({ clientX, clientY }) => {
-        // First try deep mode — preferred when the user clicks exactly on
-        // a stamped element. When the deep hit lands on an element with
-        // `pointer-events: none` (decorative <svg> children, overlay icons),
-        // elementFromPoint propagates past it and `resolveHoverTarget`
-        // returns null because the next-closest hit is `.dc-artboard-body`
-        // itself.
-        let target = resolveHoverTarget(document, clientX, clientY, { deep: true });
-        if (!target) target = resolveHoverTarget(document, clientX, clientY, { deep: false });
-        // Phase 6 fallback — when both resolveHoverTarget passes bail (the
-        // `hit === bodyEl` early-exit triggers on `pointer-events: none`
-        // decorations), enumerate every element under the click point and
-        // climb the first one that has `data-cd-id`. This is how clicks on
-        // SVG logos / icon glyphs land on the actual stamped wrapper.
-        if (!target && typeof document.elementsFromPoint === 'function') {
-          const stack = document.elementsFromPoint(clientX, clientY);
-          for (const candidate of stack) {
-            const stamped = (candidate as Element).closest?.('[data-cd-id]') as HTMLElement | null;
-            if (!stamped) continue;
-            if (!stamped.closest('.dc-artboard-body')) continue;
-            const artboardEl = stamped.closest('[data-dc-screen]');
-            target = {
-              el: stamped,
-              cdId: stamped.getAttribute('data-cd-id'),
-              artboardId: artboardEl?.getAttribute('data-dc-screen') ?? null,
-            };
-            break;
-          }
-        }
-        if (!target) {
-          // Floating comment fallback — no element anchor, just a click
-          // point. The overlay still renders a pin at the stored bounds.
-          if (typeof window === 'undefined' || typeof document === 'undefined') return;
-          const floatingSel: Selection = {
-            file: deriveFile(),
-            id: undefined,
-            selector: '',
-            artboardId: null,
-            tag: '',
-            classes: '',
-            text: '',
-            dom_path: [],
-            bounds: { x: clientX - 12, y: clientY - 12, w: 24, h: 24 },
-            html: '',
-          };
-          try {
-            document.dispatchEvent(
-              new CustomEvent('cm:open-composer', {
-                detail: { selection: floatingSel, clientX, clientY },
-              })
-            );
-          } catch {
-            /* ignore */
-          }
-          try {
-            window.parent.postMessage({ dgn: 'comment-compose', selection: floatingSel }, '*');
-          } catch {
-            /* parent detached */
-          }
-          return;
-        }
-        const sel = hoverTargetToSelection(target);
-        // Commit the target to the selection set so the halo persists while
-        // the composer is open. The user clears by:
-        //   - submit / cancel on the composer (overlay dispatches force-clear)
-        //   - pressing Esc inside the canvas (router's onEscape → clear)
-        //   - clicking another element in comment mode (this handler runs
-        //     again and replaces)
-        selSet.replace(sel);
-        if (typeof window === 'undefined' || typeof document === 'undefined') return;
-        // Phase 6 — open the in-place composer inside the iframe at the click
-        // point. Custom event is iframe-local so the overlay can subscribe
-        // without round-tripping through the parent shell.
-        try {
-          document.dispatchEvent(
-            new CustomEvent('cm:open-composer', {
-              detail: { selection: sel, clientX, clientY },
-            })
-          );
-        } catch {
-          /* CustomEvent absent — fall through to legacy parent path */
-        }
-        // Still post to parent for back-compat with any legacy `.html` mocks
-        // whose inspector script consumes `comment-compose`.
-        try {
-          window.parent.postMessage({ dgn: 'comment-compose', selection: sel }, '*');
-        } catch {
-          /* parent detached */
-        }
-      },
+      // onDropComment is intentionally absent — the comment drop is owned by
+      // the shell-owned comment mount layer's router (canvas-comment-mount.tsx),
+      // which sits as an ancestor capture-listener over this canvas. In comment
+      // mode that ancestor claims `drop-comment` before this router sees it.
     },
   });
 
   return (
     <>
       {children}
-      <CommentsOverlay />
+      {/* CommentsOverlay is mounted ONCE by the shell-owned comment mount layer
+          (canvas-comment-mount.tsx), not here — single instance per surface. */}
       <AnnotationsLayer />
       <ToolPalette />
       <ArtboardMarqueeOverlay />
@@ -1669,137 +1599,6 @@ function classifyContextKind(target: HoverTarget | null): ContextTargetKind {
   return 'world';
 }
 
-function hoverTargetToSelection(target: HoverTarget): Selection {
-  const el = target.el;
-  const rect =
-    el && (el as HTMLElement).getBoundingClientRect
-      ? (el as HTMLElement).getBoundingClientRect()
-      : null;
-  // `cdId` is the hit element's OWN data-cd-id (deep mode); resolver never
-  // climbs to an ancestor. Falls back to cssPath of the hit when no stable
-  // anchor exists.
-  const cdId = target.cdId;
-  // Selector resolution order:
-  //   1. data-cd-id anchor — stable pipeline-stamped id (preferred).
-  //   2. data-dc-screen — chrome click promoted to whole-artboard select
-  //      (T24.5 G8 multi-artboard gesture).
-  //   3. cssPath of the hit — last-resort path string.
-  const selector = cdId
-    ? `[data-cd-id="${cdId}"]`
-    : !cdId && target.artboardId
-      ? `[data-dc-screen="${target.artboardId}"]`
-      : cssPath(el);
-  return {
-    file: typeof window !== 'undefined' ? deriveFile() : undefined,
-    id: cdId ?? undefined,
-    selector,
-    artboardId: target.artboardId,
-    tag: el?.tagName.toLowerCase() ?? '',
-    classes: realClasses(el),
-    text: shortText(el, 240),
-    dom_path: domPath(el),
-    bounds: rect
-      ? {
-          x: Math.round(rect.left),
-          y: Math.round(rect.top),
-          w: Math.round(rect.width),
-          h: Math.round(rect.height),
-        }
-      : null,
-    html: el ? (el.outerHTML ?? '').slice(0, 4000) : '',
-  };
-}
-
-function deriveFile(): string | undefined {
-  try {
-    const p = window.location.pathname;
-    if (p === '/_canvas-shell.html' || p === '/_canvas-shell') {
-      const qs = new URLSearchParams(window.location.search);
-      const canvas = qs.get('canvas') ?? '';
-      const designRel = (qs.get('designRel') ?? '.design').replace(/^\/+|\/+$/g, '');
-      return `${designRel}/${canvas}`;
-    }
-    return decodeURIComponent(p).replace(/^\//, '');
-  } catch {
-    return undefined;
-  }
-}
-
-function realClasses(el: Element | null): string {
-  if (!el) return '';
-  return (el.getAttribute('class') ?? '')
-    .trim()
-    .split(/\s+/)
-    .filter((c) => c && !c.startsWith('dgn-') && !c.startsWith('dc-cv-'))
-    .join(' ');
-}
-
-function shortText(el: Element | null, max: number): string {
-  if (!el) return '';
-  const t = ((el as HTMLElement).innerText || el.textContent || '').replace(/\s+/g, ' ').trim();
-  return t.length > max ? `${t.slice(0, max - 1)}…` : t;
-}
-
-function cssPath(el: Element | null): string {
-  if (!el) return '';
-  const path: string[] = [];
-  let cur: Element | null = el;
-  while (cur && cur.nodeType === 1 && path.length < 8) {
-    const dscEl = cur.getAttribute?.('data-dc-element');
-    if (dscEl) {
-      path.unshift(`[data-dc-element="${dscEl}"]`);
-      break;
-    }
-    const dscSc = cur.getAttribute?.('data-dc-screen');
-    if (dscSc) {
-      path.unshift(`[data-dc-screen="${dscSc}"]`);
-      break;
-    }
-    let sel = cur.nodeName.toLowerCase();
-    if (cur.id) {
-      sel = `#${cur.id}`;
-      path.unshift(sel);
-      break;
-    }
-    const cls = realClasses(cur).split(/\s+/).filter(Boolean).slice(0, 2);
-    if (cls.length) sel += `.${cls.join('.')}`;
-    let sib = 1;
-    let n: Element | null = cur.previousElementSibling;
-    while (n) {
-      sib++;
-      n = n.previousElementSibling;
-    }
-    sel += `:nth-child(${sib})`;
-    path.unshift(sel);
-    cur = cur.parentElement;
-  }
-  return path.join(' > ');
-}
-
-function domPath(el: Element | null): string[] {
-  const hops: string[] = [];
-  let cur = el;
-  while (cur && cur.nodeType === 1 && hops.length < 8) {
-    let label = cur.nodeName.toLowerCase();
-    const dEl = cur.getAttribute?.('data-dc-element');
-    const dSc = cur.getAttribute?.('data-dc-screen');
-    if (dEl) label += `[data-dc-element="${dEl}"]`;
-    else if (dSc) label += `[data-dc-screen="${dSc}"]`;
-    else if (cur.id) label += `#${cur.id}`;
-    const cls = realClasses(cur).split(/\s+/).filter(Boolean).slice(0, 2);
-    if (cls.length && !dEl && !dSc) label += `.${cls.join('.')}`;
-    hops.unshift(label);
-    cur = cur.parentElement;
-  }
-  return hops;
-}
-
-function cssEscape(s: string): string {
-  // Minimal CSS.escape polyfill — only handles chars actually present in
-  // pipeline-stamped IDs (alphanumerics + `-` + `_`).
-  return s.replace(/[^a-zA-Z0-9_-]/g, (c) => `\\${c}`);
-}
-
 function safeQuery(selector: string): Element | null {
   try {
     return document.querySelector(selector);

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,17 +77,31 @@ 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`);
@@ -418,7 +432,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 +494,7 @@ function Tree({ node, activePath, onOpen, commentsByFile, depth = 1, kind, showH
             kind={kind}
             showHidden={showHidden}
             search={search}
+            activeDsName={activeDsName}
             onOpenSystem={onOpenSystem}
           />
         );
@@ -491,7 +506,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 +544,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 +639,7 @@ function Sidebar({ groups, activePath, onOpen, onOpenSystem, wsConnected, search
                   showHidden={showHidden}
                   search={search}
                   dsFolders={g.dsFolders}
+                  activeDsName={activeDsName}
                   onOpenSystem={isDs ? onOpenSystem : undefined}
                 />
               ) : (
@@ -1294,7 +1310,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" />
             </div>
             <div className="sv-preview-foot">
               <strong>{p.label}</strong>
@@ -1707,8 +1723,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]);
 
@@ -2075,6 +2096,7 @@ function App() {
       <Sidebar
         groups={groups}
         activePath={activePath}
+        activeDsName={activePath === SYSTEM_TAB ? (systemData?.ds?.name ?? null) : null}
         onOpen={openTab}
         onOpenSystem={openSystem}
         wsConnected={wsConnected}

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/registry.ts

@@ -6,6 +6,9 @@
 // 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';
@@ -34,6 +37,16 @@ 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;
   /** Flush every dirty room synchronously. DDR-051 branch-switch path. */
   flushAll(): Promise<void>;
   /** Tear down everything (e.g. on server shutdown). */
@@ -46,16 +59,47 @@ 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>();
+
+  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;
   }
@@ -87,11 +131,17 @@ export function createRegistry(callbacks: RoomCallbacks): Registry {
     const room = rooms.get(slug);
     if (!room) return;
     if (room.size() > 0) return; // still active, leave it
+    // 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()));
@@ -102,6 +152,7 @@ export function createRegistry(callbacks: RoomCallbacks): Registry {
     peek,
     syncRoomFromComments,
     syncRoomFromAnnotations,
+    attachHubAwareness,
     flushAll,
     destroyAll,
     drop,

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.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;
 }