@1agh/maude 0.20.0 → 0.22.0

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

@@ -0,0 +1,215 @@
+// Per-canvas Y.Doc room — registry, connection set, persistence schedule.
+//
+// One Room per canvas slug. Holds the Y.Doc + Awareness + the set of connected
+// peers, broadcasts updates, debounces JSON snapshot writes to disk
+// (DDR-051 — JSON is canonical, `.ydoc.bin` is a cache).
+//
+// The Room is transport-agnostic — it accepts CollabConn objects from the WS
+// layer (ws.ts). Tests construct rooms directly without booting Bun.serve.
+
+import { existsSync, mkdirSync } from 'node:fs';
+import path from 'node:path';
+
+import { Awareness, removeAwarenessStates } from 'y-protocols/awareness';
+import * as Y from 'yjs';
+
+import {
+  type CollabConn,
+  encodeAwarenessFrame,
+  encodeHandshake,
+  encodeSyncUpdate,
+  handleMessage,
+} from './protocol.ts';
+
+export interface RoomConn extends CollabConn {
+  /** Stable id for this connection (UUID from ws.data.id). */
+  id: string;
+}
+
+export interface RoomCallbacks {
+  /**
+   * Persist the JSON projection of `doc` for this slug. Called debounced — the
+   * Room batches Y.Doc updates within 800 ms windows and fires this once at
+   * quiescence. Implementations MUST be idempotent.
+   */
+  persistJson(slug: string, doc: Y.Doc): Promise<void> | void;
+
+  /**
+   * Persist the binary Y.Doc state cache (`.ydoc.bin`). Called on the same
+   * debounce schedule as persistJson. Separate hook so tests can stub one
+   * without the other.
+   */
+  persistBinary(slug: string, state: Uint8Array): Promise<void> | void;
+
+  /**
+   * Seed the Y.Doc from on-disk persistence — `.ydoc.bin` first, JSON
+   * snapshots second. Called once at room construction. MUST be synchronous
+   * with respect to the Y.Doc passed in so the first peer's handshake sees
+   * the seeded state.
+   */
+  seed(slug: string, doc: Y.Doc): Promise<void> | void;
+}
+
+export interface Room {
+  readonly slug: string;
+  readonly doc: Y.Doc;
+  readonly awareness: Awareness;
+  connect(conn: RoomConn): Promise<void>;
+  disconnect(conn: RoomConn): void;
+  receive(conn: RoomConn, payload: Uint8Array): void;
+  /** Force the debounced flush to fire now. DDR-051 §3 (branch-switch). */
+  flush(): Promise<void>;
+  /** Tear down — clears timers + removes awareness. */
+  destroy(): Promise<void>;
+  /** Test/inspection: connection count. */
+  size(): number;
+}
+
+const DEBOUNCE_MS = 800;
+
+export function createRoom(slug: string, callbacks: RoomCallbacks): Room {
+  const doc = new Y.Doc();
+  // Awareness needs a clientID; reuse the Y.Doc's so peers can attribute updates.
+  const awareness = new Awareness(doc);
+
+  const conns = new Map<string, RoomConn>();
+  let dirty = false;
+  let flushTimer: ReturnType<typeof setTimeout> | null = null;
+  let destroyed = false;
+  let seedPromise: Promise<void> | null = null;
+
+  function scheduleFlush() {
+    dirty = true;
+    if (flushTimer) clearTimeout(flushTimer);
+    flushTimer = setTimeout(() => {
+      flushTimer = null;
+      void flush();
+    }, DEBOUNCE_MS);
+  }
+
+  async function flush(): Promise<void> {
+    if (!dirty || destroyed) return;
+    dirty = false;
+    if (flushTimer) {
+      clearTimeout(flushTimer);
+      flushTimer = null;
+    }
+    try {
+      await callbacks.persistJson(slug, doc);
+      await callbacks.persistBinary(slug, Y.encodeStateAsUpdate(doc));
+    } catch (err) {
+      // Re-arm so the next mutation retries. Loud-log; persistence loss is a
+      // user-visible bug if it stays silent.
+      dirty = true;
+      console.error(`[collab/${slug}] flush failed:`, err);
+    }
+  }
+
+  function broadcast(payload: Uint8Array, except?: RoomConn) {
+    for (const c of conns.values()) {
+      if (except && c.id === except.id) continue;
+      try {
+        c.send(payload);
+      } catch {
+        /* close handler will clean up dead sockets */
+      }
+    }
+  }
+
+  // Y.Doc update -> broadcast to all peers + schedule debounced flush.
+  doc.on('update', (update: Uint8Array, origin: unknown) => {
+    if (destroyed) return;
+    // Don't echo back to the origin — they already have it; reduces noise.
+    const except =
+      origin && typeof origin === 'object' && 'id' in origin ? (origin as RoomConn) : undefined;
+    broadcast(encodeSyncUpdate(update), except);
+    scheduleFlush();
+  });
+
+  // Awareness changes -> broadcast (NOT persisted; ephemeral by design).
+  awareness.on(
+    'update',
+    (
+      { added, updated, removed }: { added: number[]; updated: number[]; removed: number[] },
+      origin: unknown
+    ) => {
+      if (destroyed) return;
+      const changed = added.concat(updated, removed);
+      if (changed.length === 0) return;
+      const except =
+        origin && typeof origin === 'object' && 'id' in origin ? (origin as RoomConn) : undefined;
+      broadcast(encodeAwarenessFrame(awareness, changed), except);
+    }
+  );
+
+  function getOrStartSeed(): Promise<void> {
+    if (!seedPromise) {
+      const result = callbacks.seed(slug, doc);
+      seedPromise = Promise.resolve(result).catch((err) => {
+        console.error(`[collab/${slug}] seed failed:`, err);
+      });
+    }
+    return seedPromise;
+  }
+
+  async function connect(conn: RoomConn): Promise<void> {
+    await getOrStartSeed();
+    conns.set(conn.id, conn);
+    const frames = encodeHandshake(doc, awareness);
+    for (const frame of frames) conn.send(frame);
+  }
+
+  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();
+    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);
+    }
+    if (stale.length) removeAwarenessStates(awareness, stale, conn);
+  }
+
+  function receive(conn: RoomConn, payload: Uint8Array): void {
+    const reply = handleMessage(payload, doc, awareness, conn);
+    if (reply) conn.send(reply);
+  }
+
+  async function destroy(): Promise<void> {
+    destroyed = true;
+    if (flushTimer) {
+      clearTimeout(flushTimer);
+      flushTimer = null;
+    }
+    if (dirty) await flush();
+    conns.clear();
+    awareness.destroy();
+    doc.destroy();
+  }
+
+  return {
+    slug,
+    doc,
+    awareness,
+    connect,
+    disconnect,
+    receive,
+    flush,
+    destroy,
+    size: () => conns.size,
+  };
+}
+
+/**
+ * Ensure `<designRoot>/_state/` exists. Idempotent; safe to call on every
+ * room construction (mkdir recursive returns the path or noop).
+ */
+export function ensureStateDir(designRoot: string): string {
+  const dir = path.join(designRoot, '_state');
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+  return dir;
+}

package/plugins/design/dev-server/comments-overlay.tsx

@@ -34,6 +34,7 @@
 
 import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
 
+import { useCollab } from './use-collab.tsx';
 import { useSelectionSetOptional } from './use-selection-set.tsx';
 
 // ─────────────────────────────────────────────────────────────────────────────
@@ -230,6 +231,34 @@ export function CommentsOverlay(): React.ReactNode {
   const commentsRef = useRef<OverlayComment[]>(comments);
   commentsRef.current = comments;
 
+  // Phase 8 Task 3 — when a collab room is connected, the Y.Array of comments
+  // is the live source of truth. observe() fires on every remote mutation
+  // (added pins from another tab, resolved-from-inspector via the registry
+  // bridge, etc.) and on the local seed. Both paths converge on the same
+  // JSON projection — last-write-wins between Y.Array and postMessage is
+  // safe because they carry identical content; the Y.Array path just
+  // reaches us first (no 800 ms debounce delay).
+  const collab = useCollab();
+  useEffect(() => {
+    if (!collab) return;
+    const arr = collab.doc.getArray<OverlayComment>('comments');
+    const sync = () => {
+      // toArray() snapshot the current Y.Array into a plain JS list.
+      setComments(arr.toArray() as OverlayComment[]);
+    };
+    // Initial fill — covers the case where Y.Doc was already seeded by the
+    // time this overlay mounted.
+    if (arr.length > 0) sync();
+    arr.observe(sync);
+    return () => {
+      try {
+        arr.unobserve(sync);
+      } catch {
+        /* doc destroyed before unmount — observer already gone */
+      }
+    };
+  }, [collab]);
+
   // Listen for the shell's broadcast channels. Schema matches the legacy
   // overlay so the shell-side glue in client/app.jsx (~line 1672) keeps
   // working without modification.

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

@@ -68,7 +68,7 @@ const CTX_TOOLBAR_CSS = `
   transition: background-color 80ms linear;
 }
 .dc-elem-ctx-tb button:hover {
-  background: color-mix(in oklab, var(--accent, #d63b1f) 8%, transparent);
+  background: color-mix(in oklab, var(--maude-hud-accent, #d63b1f) 8%, transparent);
 }
 .dc-elem-ctx-tb .dc-elem-ctx-count {
   padding: 4px 8px 4px 10px;

package/plugins/design/dev-server/cursors-overlay.tsx

@@ -0,0 +1,296 @@
+/**
+ * @file       cursors-overlay.tsx — foreign peer cursors rendered on the canvas
+ * @scope      plugins/design/dev-server/cursors-overlay.tsx
+ * @purpose    Renders one colored SVG arrow + name label per foreign peer at
+ *             their published world coords, transformed through the local
+ *             viewport so the cursor anchors to canvas content (not to my
+ *             screen) — the standard Excalidraw / tldraw multiplayer model.
+ *
+ * Render shape:
+ *   <div position:fixed top:0 left:0 pointer-events:none>
+ *     <Cursor for each foreign peer />
+ *   </div>
+ *
+ * Each cursor is positioned via `transform: translate(screenX px, screenY px)`
+ * where (screenX, screenY) = world * viewport.zoom + viewport.{x,y}. No
+ * react-spring / lerp in this ship (just last-known-position render); the
+ * 30 Hz publish cadence keeps it smooth enough for the multiplayer demo.
+ */
+
+import { memo, useEffect, useState } from 'react';
+
+import { useViewportControllerContext } from './canvas-lib.tsx';
+import { type ForeignAwareness, useCollab, useForeignAwareness } from './use-collab.tsx';
+
+const CURSOR_CSS = `
+.dc-cursor-overlay {
+  position: fixed;
+  top: 0;
+  left: 0;
+  width: 100%;
+  height: 100%;
+  pointer-events: none;
+  z-index: 10000;
+}
+.dc-cursor {
+  position: absolute;
+  top: 0;
+  left: 0;
+  pointer-events: none;
+  will-change: transform;
+  /* The arrow tip is the (0,0) anchor of the SVG; the label hangs to the
+     bottom-right so it never occludes the tip itself. */
+}
+.dc-cursor-arrow {
+  display: block;
+  filter: drop-shadow(0 1px 2px rgba(0, 0, 0, 0.25));
+}
+.dc-cursor-label {
+  position: absolute;
+  top: 18px;
+  left: 14px;
+  padding: 2px 6px;
+  font-family: var(--font-sans, system-ui, -apple-system, sans-serif);
+  font-weight: 500;
+  font-size: 11px;
+  line-height: 1.2;
+  color: var(--maude-hud-accent-fg, #fff);
+  border-radius: var(--radius-sm, 2px);
+  white-space: nowrap;
+  max-width: 180px;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  box-shadow: 0 1px 2px rgba(0, 0, 0, 0.2);
+}
+.dc-peer-selection {
+  position: absolute;
+  top: 0;
+  left: 0;
+  pointer-events: none;
+  border: 2px solid;
+  border-radius: var(--radius-sm, 2px);
+  box-sizing: border-box;
+  will-change: transform, width, height;
+}
+.dc-peer-selection__label {
+  position: absolute;
+  top: -18px;
+  left: -2px;
+  padding: 1px 5px;
+  font-family: var(--font-sans, system-ui, -apple-system, sans-serif);
+  font-weight: 600;
+  font-size: 10px;
+  line-height: 1.3;
+  color: var(--maude-hud-accent-fg, #fff);
+  border-radius: var(--radius-sm, 2px) var(--radius-sm, 2px) 0 0;
+  white-space: nowrap;
+}
+@media (prefers-reduced-motion: reduce) {
+  .dc-cursor { transition: none !important; }
+}
+`.trim();
+
+function ensureCursorStyles(): void {
+  if (typeof document === 'undefined') return;
+  if (document.getElementById('dc-cursor-overlay-css')) return;
+  const s = document.createElement('style');
+  s.id = 'dc-cursor-overlay-css';
+  s.textContent = CURSOR_CSS;
+  document.head.appendChild(s);
+}
+
+interface ViewportSnapshot {
+  x: number;
+  y: number;
+  zoom: number;
+}
+
+interface CursorProps {
+  peer: ForeignAwareness;
+  viewport: ViewportSnapshot;
+}
+
+const Cursor = memo(function Cursor({ peer, viewport }: CursorProps): JSX.Element | null {
+  if (!peer.cursor) return null;
+  // world → screen: screen = world * zoom + viewport.{x,y}
+  const screenX = peer.cursor.x * viewport.zoom + viewport.x;
+  const screenY = peer.cursor.y * viewport.zoom + viewport.y;
+  return (
+    <div className="dc-cursor" style={{ transform: `translate(${screenX}px, ${screenY}px)` }}>
+      <svg
+        className="dc-cursor-arrow"
+        width="20"
+        height="22"
+        viewBox="0 0 20 22"
+        aria-hidden="true"
+      >
+        <path
+          d="M 2 2 L 2 18 L 6 14 L 9 21 L 12 20 L 9 13 L 14 13 Z"
+          fill={peer.color}
+          stroke="#fff"
+          strokeWidth="1.2"
+          strokeLinejoin="round"
+        />
+      </svg>
+      <div className="dc-cursor-label" style={{ background: peer.color }}>
+        {peer.name}
+      </div>
+    </div>
+  );
+});
+
+/**
+ * Foreign-selection halos for stamped annotation strokes. Each peer publishes
+ * `annotationSelection: string[]` — stroke `data-id` values from Phase 5.
+ * We resolve each via `[data-id="<id>"]` and render an outlined rect at the
+ * element's current screen bounds. Re-runs every render so geometry changes
+ * (resize, move) stay in sync without manual re-publish.
+ */
+interface PeerAnnotationSelectionProps {
+  peer: ForeignAwareness;
+}
+
+const PeerAnnotationSelection = memo(function PeerAnnotationSelection({
+  peer,
+}: PeerAnnotationSelectionProps): JSX.Element | null {
+  if (!peer.annotationSelection || peer.annotationSelection.length === 0) return null;
+  if (typeof document === 'undefined') return null;
+  const rects: { id: string; x: number; y: number; w: number; h: number }[] = [];
+  for (const id of peer.annotationSelection) {
+    try {
+      const el = document.querySelector(`[data-id="${CSS.escape(id)}"]`);
+      if (!el) continue;
+      const r = (el as Element).getBoundingClientRect();
+      if (r.width <= 0 || r.height <= 0) continue;
+      // Pad by 3px so the halo sits OUTSIDE the stroke instead of clipping it.
+      rects.push({ id, x: r.left - 3, y: r.top - 3, w: r.width + 6, h: r.height + 6 });
+    } catch {
+      /* invalid id token — skip */
+    }
+  }
+  if (rects.length === 0) return null;
+  return (
+    <>
+      {rects.map((r, i) => (
+        <div
+          key={r.id}
+          className="dc-peer-selection"
+          style={{
+            transform: `translate(${r.x}px, ${r.y}px)`,
+            width: r.w,
+            height: r.h,
+            borderColor: peer.color,
+          }}
+        >
+          {i === 0 && (
+            <div className="dc-peer-selection__label" style={{ background: peer.color }}>
+              {peer.name}
+            </div>
+          )}
+        </div>
+      ))}
+    </>
+  );
+});
+
+/**
+ * Foreign-selection halo for canvas-shell elements (cdId-based selSet).
+ * The peer publishes selection.cssPath; we re-resolve in the local DOM
+ * each render so pan / zoom / hydration changes don't desync. Falls back
+ * to the published `bounds` (screen-px at publish time) when cssPath
+ * can't be resolved locally.
+ */
+interface PeerSelectionProps {
+  peer: ForeignAwareness;
+}
+
+const PeerSelection = memo(function PeerSelection({
+  peer,
+}: PeerSelectionProps): JSX.Element | null {
+  if (!peer.selection) return null;
+  const { cssPath, bounds } = peer.selection;
+
+  let rect: { x: number; y: number; w: number; h: number } | null = bounds ?? null;
+  if (cssPath && typeof document !== 'undefined') {
+    try {
+      const el = document.querySelector(cssPath);
+      if (el && el instanceof Element) {
+        const r = el.getBoundingClientRect();
+        if (r.width > 0 && r.height > 0) {
+          rect = { x: r.left, y: r.top, w: r.width, h: r.height };
+        }
+      }
+    } catch {
+      /* invalid selector — fall through to published bounds */
+    }
+  }
+  if (!rect) return null;
+
+  return (
+    <div
+      className="dc-peer-selection"
+      style={{
+        transform: `translate(${rect.x}px, ${rect.y}px)`,
+        width: rect.w,
+        height: rect.h,
+        borderColor: peer.color,
+      }}
+    >
+      <div className="dc-peer-selection__label" style={{ background: peer.color }}>
+        {peer.name}
+      </div>
+    </div>
+  );
+});
+
+/**
+ * Subscribes to foreign awareness + the local viewport. Renders one Cursor per
+ * peer. Reads viewport from `useViewportControllerContext` — if the canvas
+ * doesn't expose a controller (rare edge case), falls back to identity.
+ */
+export function CursorsOverlay(): JSX.Element {
+  ensureCursorStyles();
+  const peers = useForeignAwareness();
+  const controller = useViewportControllerContext();
+  const liveVp = controller?.viewport ?? { x: 0, y: 0, zoom: 1 };
+  // Take a snapshot per render — controller.viewport already changes on
+  // throttle, so this stays smooth enough at 30 Hz.
+  const [vp, setVp] = useState<ViewportSnapshot>(liveVp);
+  useEffect(() => {
+    setVp({ x: liveVp.x, y: liveVp.y, zoom: liveVp.zoom });
+  }, [liveVp.x, liveVp.y, liveVp.zoom]);
+
+  // Bump a render tick whenever annotations change so PeerAnnotationSelection
+  // re-resolves [data-id] bounds. Without this, a peer resizing a stroke
+  // would propagate via Y.Map → local annotations-layer re-render — but the
+  // sibling CursorsOverlay wouldn't re-render, so the annotation halo would
+  // sit on the OLD bounds until awareness independently changed.
+  const collab = useCollab();
+  const [, bumpAnnotTick] = useState(0);
+  useEffect(() => {
+    if (!collab) return;
+    const map = collab.doc.getMap('annotations');
+    const onChange = () => bumpAnnotTick((n) => n + 1);
+    map.observe(onChange);
+    return () => {
+      try {
+        map.unobserve(onChange);
+      } catch {
+        /* doc destroyed */
+      }
+    };
+  }, [collab]);
+  return (
+    <div className="dc-cursor-overlay" aria-hidden="true">
+      {peers.map((peer) => (
+        <PeerSelection key={`sel-${peer.clientID}`} peer={peer} />
+      ))}
+      {peers.map((peer) => (
+        <PeerAnnotationSelection key={`asel-${peer.clientID}`} peer={peer} />
+      ))}
+      {peers.map((peer) => (
+        <Cursor key={peer.clientID} peer={peer} viewport={vp} />
+      ))}
+    </div>
+  );
+}