@1agh/maude 0.19.1 → 0.21.0

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.
@@ -1143,14 +1172,22 @@ function computeThreadAnchor(comment: OverlayComment): { x: number; y: number }
 }
 
 function computeAnchor(state: ComposerState): { x: number; y: number } {
-  // Try the selected element first — its live screen rect gives the most
-  // natural anchor (composer sits flush under the element the user clicked).
+  // G4 — anchor to the cursor click point first. Earlier versions anchored to
+  // the selected element's bottom-left, which landed the composer flush in
+  // the corner regardless of where the user clicked — surprising for the
+  // common case of "I clicked the middle of an element, expecting the
+  // composer to appear near my cursor". The element-rect path remains as a
+  // fallback for entry points that don't carry a cursor (e.g. opening the
+  // composer from a contextual toolbar button — those should set clientX/Y
+  // to a sensible anchor before dispatching).
+  if (state.clientX || state.clientY) {
+    return { x: state.clientX, y: state.clientY + 8 };
+  }
   if (state.selection.selector) {
     const rect = screenRectFor(state.selection.selector);
     if (rect) {
       return { x: rect.x, y: rect.y + rect.h + 8 };
     }
   }
-  // Fall back to the raw click point — composer drops 8px below the cursor.
-  return { x: state.clientX, y: state.clientY + 8 };
+  return { x: 16, y: 16 };
 }

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

@@ -0,0 +1,241 @@
+/**
+ * @file       contextual-toolbar.tsx — T30 (Wave 3)
+ * @scope      plugins/design/dev-server/contextual-toolbar.tsx
+ * @purpose    Selection-anchored floating chrome for ELEMENT selections
+ *             (cd-id entries in the selection set). Mirrors the
+ *             MultiArtboardToolbar pattern but scopes to user content inside
+ *             artboards. Actions surface the existing right-click handlers
+ *             one click closer:
+ *
+ *               • Copy CSS path
+ *               • Copy data-cd-id
+ *               • Add comment
+ *
+ *             Hides when:
+ *               - no selection,
+ *               - selection contains only artboards (MultiArtboardToolbar
+ *                 covers that),
+ *               - selection contains only annotations (their own toolbar
+ *                 fires from `annotations-context-toolbar.tsx`).
+ *
+ *             Anchored 14 px above the element selection union bbox; flips
+ *             below when bbox top is < 60 px from the viewport edge — same
+ *             contract as MultiArtboardToolbar so the two never collide.
+ *
+ *             Selection-change tweens are NOT animated here in v1; the
+ *             instant reposition is acceptable given the toolbar fades in
+ *             only when stickily relevant. A future polish wave can add
+ *             the 180 ms position tween per the plan note.
+ */
+
+import { useEffect, useRef } from 'react';
+
+import { useSelectionSet } from './use-selection-set.tsx';
+
+const CTX_TOOLBAR_CSS = `
+.dc-elem-ctx-tb {
+  position: fixed;
+  pointer-events: auto;
+  z-index: 6;
+  display: none;
+  align-items: stretch;
+  gap: 2px;
+  padding: 4px;
+  background: var(--u-bg-0, var(--bg-0, #ffffff));
+  border: 1px solid var(--u-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);
+  font-size: 11px;
+  letter-spacing: 0.02em;
+  color: var(--u-fg-0, #1a1a1a);
+  user-select: none;
+  opacity: 0;
+  transition: opacity 100ms cubic-bezier(0.4, 0, 0.2, 1);
+}
+.dc-elem-ctx-tb[data-on="true"] {
+  opacity: 1;
+}
+.dc-elem-ctx-tb button {
+  appearance: none;
+  background: transparent;
+  border: 0;
+  border-radius: 6px;
+  padding: 4px 10px;
+  font: inherit;
+  cursor: pointer;
+  color: inherit;
+  transition: background-color 80ms linear;
+}
+.dc-elem-ctx-tb button:hover {
+  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;
+  color: var(--fg-1, rgba(40,30,20,0.7));
+  border-right: 1px solid var(--u-border-subtle, rgba(0,0,0,0.08));
+  margin-right: 2px;
+  font-variant-numeric: tabular-nums;
+}
+@media (prefers-reduced-motion: reduce) {
+  .dc-elem-ctx-tb, .dc-elem-ctx-tb button { transition: none; }
+}
+`.trim();
+
+function ensureStyles(): void {
+  if (typeof document === 'undefined') return;
+  if (document.getElementById('dc-elem-ctx-tb-css')) return;
+  const s = document.createElement('style');
+  s.id = 'dc-elem-ctx-tb-css';
+  s.textContent = CTX_TOOLBAR_CSS;
+  document.head.appendChild(s);
+}
+
+function copyText(text: string): void {
+  if (typeof navigator === 'undefined' || !navigator.clipboard) return;
+  void navigator.clipboard.writeText(text).catch(() => {
+    /* clipboard blocked */
+  });
+}
+
+function openComposerForSelection(
+  sel: { id?: string; selector: string },
+  anchorEl: Element | null
+): void {
+  if (typeof document === 'undefined') return;
+  // Anchor near the top-right of the targeted element so the composer drops
+  // into a clear area next to it. Matches the comment-tool click affordance
+  // post-G4 (cursor-anchored composer).
+  let clientX = 0;
+  let clientY = 0;
+  if (anchorEl) {
+    const r = (anchorEl as HTMLElement).getBoundingClientRect();
+    clientX = r.right - 8;
+    clientY = r.top + r.height / 2;
+  }
+  try {
+    document.dispatchEvent(
+      new CustomEvent('cm:open-composer', {
+        detail: { selection: sel, clientX, clientY },
+      })
+    );
+  } catch {
+    /* CustomEvent unsupported — fall through */
+  }
+  // Back-compat parent post for legacy mocks.
+  if (typeof window !== 'undefined') {
+    try {
+      window.parent.postMessage({ dgn: 'comment-compose', selection: sel }, '*');
+    } catch {
+      /* parent detached */
+    }
+  }
+}
+
+export function ContextualToolbar() {
+  ensureStyles();
+  const { selected } = useSelectionSet();
+  const ref = useRef<HTMLDivElement | null>(null);
+  const rafRef = useRef<number | null>(null);
+
+  // Element selections = entries with `id` (data-cd-id) set. Pure artboard
+  // selections (artboardId-only, no id) and empty sets fall through.
+  const elementSelections = selected.filter((s) => !!s.id);
+  const visible = elementSelections.length > 0;
+
+  useEffect(() => {
+    const div = ref.current;
+    if (!div) return;
+    if (!visible) {
+      div.style.display = 'none';
+      div.setAttribute('data-on', 'false');
+      return;
+    }
+    const tick = () => {
+      rafRef.current = null;
+      let xMin = Number.POSITIVE_INFINITY;
+      let yMin = Number.POSITIVE_INFINITY;
+      let xMax = Number.NEGATIVE_INFINITY;
+      let yMax = Number.NEGATIVE_INFINITY;
+      let any = false;
+      for (const sel of elementSelections) {
+        const node = sel.id
+          ? document.querySelector(`[data-cd-id="${sel.id}"]`)
+          : document.querySelector(sel.selector);
+        if (!node) continue;
+        const r = (node as HTMLElement).getBoundingClientRect();
+        if (r.width === 0 && r.height === 0) continue;
+        any = true;
+        if (r.left < xMin) xMin = r.left;
+        if (r.top < yMin) yMin = r.top;
+        if (r.right > xMax) xMax = r.right;
+        if (r.bottom > yMax) yMax = r.bottom;
+      }
+      if (!any) {
+        div.style.display = 'none';
+        div.setAttribute('data-on', 'false');
+        rafRef.current = requestAnimationFrame(tick);
+        return;
+      }
+      div.style.display = 'flex';
+      const tw = div.offsetWidth || 0;
+      const centerX = (xMin + xMax) / 2;
+      const top = yMin;
+      const gap = 14;
+      let anchorY = top - div.offsetHeight - gap;
+      if (anchorY < 60) anchorY = yMax + gap;
+      div.style.left = `${Math.round(centerX - tw / 2)}px`;
+      div.style.top = `${Math.round(anchorY)}px`;
+      div.setAttribute('data-on', 'true');
+      rafRef.current = requestAnimationFrame(tick);
+    };
+    rafRef.current = requestAnimationFrame(tick);
+    return () => {
+      if (rafRef.current != null) cancelAnimationFrame(rafRef.current);
+    };
+  }, [visible, elementSelections]);
+
+  if (!visible) {
+    return <div ref={ref} className="dc-elem-ctx-tb" aria-hidden="true" />;
+  }
+
+  // For multi-selection, Copy actions operate on the FIRST element — same
+  // convention as the right-click menu (single-target). Future polish: a
+  // mini-menu that lets the user pick which selection's CSS to copy.
+  const primary = elementSelections[0];
+  const count = elementSelections.length;
+
+  return (
+    <div ref={ref} className="dc-elem-ctx-tb" role="toolbar" aria-label="Element actions">
+      <span className="dc-elem-ctx-count">{count === 1 ? '1 element' : `${count} elements`}</span>
+      <button
+        type="button"
+        title="Copy CSS selector"
+        onClick={() => primary && copyText(primary.selector)}
+      >
+        Copy CSS
+      </button>
+      <button
+        type="button"
+        title="Copy data-cd-id"
+        disabled={!primary?.id}
+        onClick={() => primary?.id && copyText(primary.id)}
+      >
+        Copy ID
+      </button>
+      <button
+        type="button"
+        title="Add comment on this element"
+        onClick={() => {
+          if (!primary) return;
+          const node = primary.id
+            ? document.querySelector(`[data-cd-id="${primary.id}"]`)
+            : document.querySelector(primary.selector);
+          openComposerForSelection(primary, node);
+        }}
+      >
+        Comment
+      </button>
+    </div>
+  );
+}

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>
+  );
+}