@1agh/maude 0.20.0 → 0.21.0

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

@@ -140,6 +140,12 @@ export interface Api {
   commentsDelete(id: string): Promise<boolean>;
   commentsAddReply(id: string, payload: { body: string; author?: string }): Promise<Comment | null>;
   gitCommitters(): Promise<GitCommitter[]>;
+  /**
+   * Phase 8 — local `git config user.name`, cached for the process lifetime.
+   * Used by the collab client to derive a stable color hash per peer.
+   * Empty string when git is unset; the client falls back to `anonymous-<pid>`.
+   */
+  gitCurrentUser(): Promise<string>;
   parseMentions(text: string): string[];
   // Canvas state
   loadCanvasState(file: string): Promise<Record<string, unknown> | null>;
@@ -161,7 +167,15 @@ export interface Api {
   appendExportHistory(entry: ExportHistoryEntry): Promise<void>;
 }
 
-export function createApi(ctx: Context, onCommentsChanged: (file: string) => void): Api {
+export interface ApiHooks {
+  onCommentsChanged: (file: string) => void;
+  /** Phase 8 Task 5 — fires after a successful PUT /_api/annotations write. */
+  onAnnotationsChanged?: (file: string, svg: string) => void;
+}
+
+export function createApi(ctx: Context, hooks: ApiHooks): Api {
+  const onCommentsChanged = hooks.onCommentsChanged;
+  const onAnnotationsChanged = hooks.onAnnotationsChanged;
   const { paths, cfg } = ctx;
 
   function fileSlug(file: string): string {
@@ -576,6 +590,7 @@ export function createApi(ctx: Context, onCommentsChanged: (file: string) => voi
     // content fully, so we don't try to sanitize beyond a tag check.
     if (!/^\s*<svg[\s>]/i.test(svg)) return false;
     await Bun.write(annotationsPath(file), svg);
+    onAnnotationsChanged?.(file, svg);
     return true;
   }
 
@@ -936,6 +951,7 @@ export function createApi(ctx: Context, onCommentsChanged: (file: string) => voi
     commentsDelete,
     commentsAddReply,
     gitCommitters,
+    gitCurrentUser,
     parseMentions,
     loadCanvasState,
     saveCanvasState,

package/plugins/design/dev-server/artboard-marquee.tsx

@@ -27,8 +27,8 @@ const MARQUEE_CSS = `
   position: fixed;
   pointer-events: none;
   z-index: 5;
-  border: 1px solid var(--accent, #0d99ff);
-  background: color-mix(in oklab, var(--accent, #0d99ff) 8%, transparent);
+  border: 1px solid var(--maude-hud-accent, #0d99ff);
+  background: color-mix(in oklab, var(--maude-hud-accent, #0d99ff) 8%, transparent);
   display: none;
 }
 `.trim();

package/plugins/design/dev-server/bin/preflight.sh

@@ -0,0 +1,32 @@
+#!/usr/bin/env bash
+# preflight.sh — design plugin dependency health check.
+# Thin shell wrapper over `node cli/lib/preflight.mjs --plugin design`.
+# Keeps the detection logic in one place (the .mjs lib) while exposing the
+# bash-friendly modes (--shell-export, --warn-only) that init.md and the
+# SessionStart hook need.
+#
+# Usage:
+#   preflight.sh                    # text table (humans)
+#   preflight.sh --json             # machine-readable envelope
+#   preflight.sh --shell-export     # `export DEPS_OK=... DEPS_MISSING=...`
+#   preflight.sh --quiet            # silent on success, one-liner on miss
+#   preflight.sh --warn-only        # same as --quiet (SessionStart hook)
+#
+# Resolution (DDR-045): never compute paths from `dirname $0` inside a
+# `bun --compile` standalone binary — that maps to /$bunfs/root. The CLI
+# entry stays Node, so we resolve via $CLAUDE_PLUGIN_ROOT first, with the
+# script-dir fallback only used when running uncompiled from the repo.
+#
+# Exit: 0 if all hard deps pass; 1 otherwise.
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+PLUGIN_ROOT="${CLAUDE_PLUGIN_ROOT:-$(cd "$SCRIPT_DIR/../.." && pwd)}"
+PKG_ROOT="$(cd "$PLUGIN_ROOT/../.." && pwd)"
+
+# The Node lib needs cwd to be the package root (it resolves dependencies.json
+# via `plugins/<plugin>/dependencies.json`). Subshell so we don't mutate the
+# caller's cwd.
+(
+  cd "$PKG_ROOT" || exit 1
+  exec node "$PKG_ROOT/cli/lib/preflight.mjs" --plugin design "$@"
+)

package/plugins/design/dev-server/bin/runtime-health.sh

@@ -0,0 +1,169 @@
+#!/usr/bin/env bash
+# runtime-health.sh — verify the dev-server is serving the on-disk pre-built
+# runtime bundles, not a defective dynamic Bun.build output.
+#
+# Why: a stale dev-server process can cache a broken dynamic build of
+# /_canvas-runtime/<slug>.js (e.g. a 409-line motion_react.js with a hoisting
+# bug instead of the 10056-line pre-built). The canvas TSX parses cleanly,
+# server returns HTTP 200, but the iframe throws at module-eval time with
+# `ReferenceError: AcceleratedAnimation is not defined` (or similar).
+#
+# Parse-clean ≠ run-clean. This helper closes that gap: probe every URL the
+# canvas-lib pulls in, compare byte-count to the disk pre-built, fail loud
+# when the served body is suspiciously small.
+#
+# Usage:
+#   runtime-health.sh [--port N] [--root <repo>] [--threshold 0.5]
+#                     [--restart] [--quiet]
+#
+# Behavior:
+#   --restart  → on detected defect, kill the server PID from _server.json
+#                and respawn via server-up.sh. Exit 0 if the restart heals.
+#   --quiet    → silence per-bundle PASS lines; only print failures + summary.
+#
+# Exit codes:
+#   0 all bundles healthy (or --restart healed the defect)
+#   1 server unreachable / no _server.json
+#   2 bad args
+#   3 defective bundle detected (and either no --restart, or restart did not heal)
+
+PORT=""
+REPO=""
+THRESHOLD="0.5"
+RESTART=0
+QUIET=0
+
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --port)      PORT="$2"; shift 2 ;;
+    --root)      REPO="$2"; shift 2 ;;
+    --threshold) THRESHOLD="$2"; shift 2 ;;
+    --restart)   RESTART=1; shift ;;
+    --quiet)     QUIET=1; shift ;;
+    --help|-h)
+      sed -n '2,30p' "$0" | sed 's/^# \?//'
+      exit 0
+      ;;
+    *)
+      echo "runtime-health.sh: unknown arg '$1' (try --help)" >&2
+      exit 2
+      ;;
+  esac
+done
+
+# ---------- repo + plugin root resolution ----------
+if [ -z "$REPO" ]; then
+  REPO="${CLAUDE_PROJECT_DIR:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}"
+fi
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+PLUGIN_ROOT="${CLAUDE_PLUGIN_ROOT:-$(cd "$SCRIPT_DIR/../.." && pwd)}"
+PREBUILT_DIR="$PLUGIN_ROOT/dev-server/dist/runtime"
+if [ ! -d "$PREBUILT_DIR" ]; then
+  PREBUILT_DIR="$SCRIPT_DIR/../dist/runtime"
+fi
+if [ ! -d "$PREBUILT_DIR" ]; then
+  echo "runtime-health.sh: pre-built runtime dir not found at $PREBUILT_DIR" >&2
+  echo "  (canvas runtime bundles ship in <plugin>/dev-server/dist/runtime/)" >&2
+  exit 1
+fi
+
+# ---------- resolve port from _server.json if not given ----------
+DESIGN_ROOT="$REPO/.design"
+STATE="$DESIGN_ROOT/_server.json"
+if [ -z "$PORT" ]; then
+  if [ ! -f "$STATE" ]; then
+    echo "runtime-health.sh: no --port given and $STATE not found (run server-up.sh first)" >&2
+    exit 1
+  fi
+  if command -v jq >/dev/null 2>&1; then
+    PORT=$(jq -r .port "$STATE" 2>/dev/null)
+  else
+    PORT=$(sed -nE 's/.*"port"[[:space:]]*:[[:space:]]*([0-9]+).*/\1/p' "$STATE" | head -n1)
+  fi
+fi
+[ -z "$PORT" ] && { echo "runtime-health.sh: could not resolve port" >&2; exit 1; }
+
+BASE="http://localhost:$PORT"
+
+# Confirm server alive before probing individual bundles.
+if ! curl -fs "$BASE/_health" >/dev/null 2>&1; then
+  echo "runtime-health.sh: server not responding at $BASE/_health" >&2
+  exit 1
+fi
+
+# ---------- per-bundle probe ----------
+probe_one() {
+  local slug="$1"
+  local disk_size="$2"
+  local url="$BASE/_canvas-runtime/$slug"
+  local served
+  served=$(curl -fs -o /dev/null -w '%{size_download}' "$url" 2>/dev/null) || {
+    echo "✗ $slug — served HTTP error (curl failed for $url)" >&2
+    return 1
+  }
+  # Floor at 256 bytes — any working ESM bundle is bigger than that.
+  if [ "$served" -lt 256 ]; then
+    echo "✗ $slug — served body $served B < 256 B floor (server returned empty)" >&2
+    return 1
+  fi
+  # Threshold ratio: served must be ≥ threshold × disk.
+  # awk handles the fractional math without bc dependency.
+  local ratio
+  ratio=$(awk -v s="$served" -v d="$disk_size" 'BEGIN{ if(d==0){print 0}else{printf "%.3f", s/d} }')
+  local ok
+  ok=$(awk -v r="$ratio" -v t="$THRESHOLD" 'BEGIN{print (r >= t) ? 1 : 0}')
+  if [ "$ok" = "1" ]; then
+    [ $QUIET -eq 0 ] && echo "✓ $slug — $served B / $disk_size B disk (ratio $ratio)" >&2
+    return 0
+  fi
+  echo "✗ $slug — served $served B / $disk_size B disk (ratio $ratio < $THRESHOLD) — defective dynamic build" >&2
+  return 1
+}
+
+FAIL_COUNT=0
+FAIL_LIST=""
+for f in "$PREBUILT_DIR"/*.js; do
+  [ -f "$f" ] || continue
+  SLUG=$(basename "$f")
+  DISK_SIZE=$(wc -c < "$f" | tr -d ' ')
+  if ! probe_one "$SLUG" "$DISK_SIZE"; then
+    FAIL_COUNT=$((FAIL_COUNT + 1))
+    FAIL_LIST="$FAIL_LIST $SLUG"
+  fi
+done
+
+if [ "$FAIL_COUNT" -eq 0 ]; then
+  [ $QUIET -eq 0 ] && echo "✓ runtime-health OK — all bundles match disk pre-built (threshold $THRESHOLD)" >&2
+  exit 0
+fi
+
+echo "" >&2
+echo "✗ runtime-health FAIL — $FAIL_COUNT bundle(s) below threshold:$FAIL_LIST" >&2
+echo "  These bundles look like defective dynamic Bun.build output." >&2
+echo "  The canvas TSX will parse + serve cleanly, but the iframe will throw at runtime." >&2
+
+if [ "$RESTART" -eq 1 ]; then
+  echo "→ --restart given; killing server and respawning via server-up.sh" >&2
+  if [ -f "$STATE" ]; then
+    if command -v jq >/dev/null 2>&1; then
+      PID=$(jq -r .pid "$STATE" 2>/dev/null)
+    else
+      PID=$(sed -nE 's/.*"pid"[[:space:]]*:[[:space:]]*([0-9]+).*/\1/p' "$STATE" | head -n1)
+    fi
+    if [ -n "$PID" ] && kill -0 "$PID" 2>/dev/null; then
+      kill "$PID" 2>/dev/null
+      sleep 1
+      kill -0 "$PID" 2>/dev/null && kill -9 "$PID" 2>/dev/null
+    fi
+    rm -f "$STATE"
+  fi
+  NEW_PORT=$(bash "$SCRIPT_DIR/server-up.sh" --root "$REPO")
+  [ -z "$NEW_PORT" ] && { echo "✗ server-up.sh did not return a port after restart" >&2; exit 3; }
+  echo "→ server restarted port=$NEW_PORT; re-probing once" >&2
+  # Re-probe via tail-recursive invocation with no --restart (avoid infinite loop).
+  bash "$0" --port "$NEW_PORT" --root "$REPO" --threshold "$THRESHOLD" $( [ $QUIET -eq 1 ] && echo --quiet )
+  exit $?
+fi
+
+echo "  Remediation: rerun with --restart, OR manually 'kill $(cat $STATE 2>/dev/null | sed -nE 's/.*pid.*:.*([0-9]+).*/\1/p') && bash $SCRIPT_DIR/server-up.sh'" >&2
+exit 3

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

@@ -93,6 +93,7 @@ import {
   diffLayoutPositions,
 } from './commands/move-artboards-command.ts';
 import { type DragState, useArtboardDrag } from './use-artboard-drag.tsx';
+import { CollabProvider, canvasSlugFromPath } from './use-collab.tsx';
 import { useSelectionSetOptional } from './use-selection-set.tsx';
 import { ToolProvider, useToolModeOptional } from './use-tool-mode.tsx';
 import { UndoStackProvider, useUndoSinks, useUndoStackOptional } from './use-undo-stack.tsx';
@@ -227,7 +228,7 @@ button.dc-artboard-label {
   display: block;
   width: 100%;
 }
-button.dc-artboard-label:focus-visible { outline: 2px solid var(--accent, #d63b1f); outline-offset: -2px; }
+button.dc-artboard-label:focus-visible { outline: 2px solid var(--maude-hud-accent, #d63b1f); outline-offset: -2px; }
 /* Active-artboard ring is in canvas-shell HALO_CSS (subtle 1 px tint). */
 /* Phase 4.2 — drag chrome. */
 .dc-canvas[data-active-tool="move"] .dc-artboard-label { cursor: grab; }
@@ -1170,11 +1171,20 @@ export function DesignCanvas(props: DesignCanvasProps) {
   // `window.top.__maude_undo_stacks` so it survives canvas switches —
   // close Foo.tsx, open Bar.tsx, come back to Foo.tsx → history intact.
   const canvasFile = readCanvasMetaFile() ?? undefined;
+  // Phase 8 / DDR-051 — open a Yjs collab session for this canvas iff we can
+  // derive a stable slug. The slug must match `api.fileSlug` server-side so
+  // both ends agree on the room key. When the canvas was opened via a URL
+  // that doesn't yield a slug (e.g. preview iframes without `canvas=`),
+  // CollabProvider is omitted; useCollab() falls back gracefully to null.
+  const collabSlug = canvasSlugFromPath(canvasFile);
+  const inner = (
+    <ToolProvider>
+      <DesignCanvasInner {...props} />
+    </ToolProvider>
+  );
   return (
     <UndoStackProvider canvasFile={canvasFile}>
-      <ToolProvider>
-        <DesignCanvasInner {...props} />
-      </ToolProvider>
+      {collabSlug ? <CollabProvider slug={collabSlug}>{inner}</CollabProvider> : inner}
     </UndoStackProvider>
   );
 }
@@ -1228,6 +1238,22 @@ function DesignCanvasInner({ children, controls }: DesignCanvasProps) {
     setArtboards(initialArtboards());
   }, [initialArtboards]);
 
+  // Phase 8 — foreign canvas-meta change. The shell-level HMR client
+  // re-fetches `<canvas>.meta.json` and dispatches `maude:meta-refreshed`
+  // when *another* tab PATCHed the layout (drag, distribute, align). We
+  // re-apply positions in-place — no full reload — so the user's tool mode,
+  // undo stack, scroll, and selection state survive. Self-writes are
+  // suppressed at the dispatch site via the `__maude_last_meta_self_write_at`
+  // echo timestamp.
+  useEffect(() => {
+    if (typeof document === 'undefined') return;
+    const onRefresh = () => {
+      setArtboards(initialArtboards());
+    };
+    document.addEventListener('maude:meta-refreshed', onRefresh);
+    return () => document.removeEventListener('maude:meta-refreshed', onRefresh);
+  }, [initialArtboards]);
+
   // Stable refs so the controller's callbacks always see the latest values.
   const artboardsRef = useRef(artboards);
   artboardsRef.current = artboards;
@@ -1736,8 +1762,8 @@ const OVERLAY_CSS = `
    outline-only. Reads from a glance as "what slice of the world you're on". */
 .dc-mm-vp {
   position: absolute;
-  background: color-mix(in oklab, var(--accent, #d63b1f) 12%, transparent);
-  border: 1.5px solid var(--accent, #d63b1f);
+  background: color-mix(in oklab, var(--maude-hud-accent, #d63b1f) 12%, transparent);
+  border: 1.5px solid var(--maude-hud-accent, #d63b1f);
   border-radius: 1px;
   pointer-events: none;
 }
@@ -1773,7 +1799,7 @@ const OVERLAY_CSS = `
 }
 .dc-zoom-tb button:last-child { border-right: 0; }
 .dc-zoom-tb button:hover { background: color-mix(in oklab, var(--fg-0, #1c1917) 5%, transparent); }
-.dc-zoom-tb button:focus-visible { outline: 2px solid var(--accent, #d63b1f); outline-offset: -2px; }
+.dc-zoom-tb button:focus-visible { outline: 2px solid var(--maude-hud-accent, #d63b1f); outline-offset: -2px; }
 .dc-zoom-tb-pct { font-variant-numeric: tabular-nums; min-width: 52px; }
 `.trim();
 

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

@@ -36,6 +36,7 @@ import {
   useState,
 } from 'react';
 
+import { AiBanner } from './ai-banner.tsx';
 import { AnnotationsLayer } from './annotations-layer.tsx';
 import { ArtboardMarqueeOverlay } from './artboard-marquee.tsx';
 import {
@@ -57,17 +58,21 @@ import {
   useContextMenu,
 } from './context-menu.tsx';
 import { ContextualToolbar } from './contextual-toolbar.tsx';
+import { CursorsOverlay } from './cursors-overlay.tsx';
 import { EqualSpacingHandles } from './equal-spacing-handles.tsx';
 import { ExportDialogProvider } from './export-dialog.tsx';
 import { type HoverTarget, resolveHoverTarget, useInputRouter } from './input-router.tsx';
 import { ElementMarqueeOverlay } from './marquee-overlay.tsx';
+import { ParticipantsChrome } from './participants-chrome.tsx';
 import { ToolPalette } from './tool-palette.tsx';
 import { UndoHud } from './undo-hud.tsx';
 import {
   AnnotationSelectionProvider,
   useAnnotationSelection,
+  useAnnotationSelectionOptional,
 } from './use-annotation-selection.tsx';
 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';
@@ -81,6 +86,28 @@ import { useUndoStack } from './use-undo-stack.tsx';
 // plane would otherwise scale a 2 px outline to 0.84 px at 42 % zoom (subpixel
 // = invisible). No per-element class stamping is used.
 
+// HUD-namespace token block. System-review 2026-05-27 (D-4) flagged that the
+// dev-server chrome (toolbar + minimap + halos + marquee + AI banner) used
+// `var(--accent, …)` which inherited the canvas DS palette — a violet StudyFi
+// canvas turned the floating cursor toolbar violet. The HUD owns its own
+// `--maude-hud-*` token family, set on `:root` of the canvas iframe document
+// here. Canvas DSs do NOT define `--maude-hud-*`, so HUD CSS resolves against
+// this block regardless of what the imported `:root { --accent: … }` looks like.
+//
+// Defaults match the existing inline fallback color (`#d63b1f`, Maude brand
+// orange-rust) so no visual change to the default theme. Users who want to
+// re-theme the HUD can set `--maude-hud-accent` etc. via a `<style>` block
+// AFTER this one (CSS cascade — later wins).
+const HUD_TOKENS_CSS = `
+:root {
+  --maude-hud-accent:        #d63b1f;
+  --maude-hud-accent-hover:  #b8331b;
+  --maude-hud-accent-active: #962a16;
+  --maude-hud-accent-fg:     #ffffff;
+  --maude-hud-accent-tint:   color-mix(in oklab, #d63b1f 14%, transparent);
+}
+`;
+
 // DDR-046 — Three-state halo language. Each state has its own border weight,
 // color treatment, and geometric idiom so 8+ semantic states (hover / selected
 // / member-of-multi / group / snap-sibling / snap-grid / marquee / annotation
@@ -98,20 +125,20 @@ const HALO_CSS = `
 /* Hover — lighter 1.5px tinted line + white inner ring for contrast on dark
    elements. NO ring, NO ticks. Synchronous paint (no debounce). */
 .dc-cv-halo--hover {
-  border: 1.5px solid color-mix(in oklab, var(--accent, #0d99ff) 60%, transparent);
+  border: 1.5px solid color-mix(in oklab, var(--maude-hud-accent, #0d99ff) 60%, transparent);
   box-shadow: inset 0 0 0 1px var(--bg-0, #ffffff);
 }
 /* Selected (single) — 2px solid + 18% ring halo + 4 filled corner ticks.
    Ticks are <i class="tick tick-*"> children at inset:-3px, 8x8, accent fill. */
 .dc-cv-halo--selected {
-  border: 2px solid var(--accent, #0d99ff);
-  box-shadow: 0 0 0 4px color-mix(in oklab, var(--accent, #0d99ff) 18%, transparent);
+  border: 2px solid var(--maude-hud-accent, #0d99ff);
+  box-shadow: 0 0 0 4px color-mix(in oklab, var(--maude-hud-accent, #0d99ff) 18%, transparent);
 }
 .dc-cv-halo--selected .tick {
   position: absolute;
   width: 8px;
   height: 8px;
-  background: var(--accent, #0d99ff);
+  background: var(--maude-hud-accent, #0d99ff);
   border-radius: 1px;
   box-shadow: 0 0 0 1px var(--bg-0, #ffffff);
 }
@@ -125,7 +152,7 @@ const HALO_CSS = `
    as "draft / placeholder" and members would melt away inside artboards once
    the artboard border itself is 22%-tinted (T15). */
 .dc-cv-halo--selected-member {
-  border: 1.5px solid var(--accent, #0d99ff);
+  border: 1.5px solid var(--maude-hud-accent, #0d99ff);
 }
 /* Group bbox — 1 px DASHED full accent + four 6 × 6 square corner handles.
    T16 / DDR-046 rev 2 — dashed is the canonical group-container affordance
@@ -138,14 +165,14 @@ const HALO_CSS = `
   position: fixed;
   pointer-events: none;
   z-index: 5;
-  border: 1px dashed var(--accent, #0d99ff);
+  border: 1px dashed var(--maude-hud-accent, #0d99ff);
   border-radius: 2px;
 }
 .dc-cv-group-bbox .tick {
   position: absolute;
   width: 6px;
   height: 6px;
-  background: var(--accent, #0d99ff);
+  background: var(--maude-hud-accent, #0d99ff);
   border-radius: 1px;
   box-shadow: 0 0 0 1px var(--bg-0, #ffffff);
 }
@@ -165,7 +192,7 @@ const HALO_CSS = `
      (3 px ring + hard 6×6×0 offset) was readable but visually expensive once
      the frame itself lost its brutalist treatment. A 2 px ring on a 22 %
      tinted hairline reads unambiguous without claiming subject-ness. */
-  box-shadow: 0 0 0 2px var(--accent, #0d99ff);
+  box-shadow: 0 0 0 2px var(--maude-hud-accent, #0d99ff);
   transition: box-shadow 120ms cubic-bezier(0.4, 0, 0.2, 1);
 }
 /* Respect prefers-reduced-motion across all chrome transitions. */
@@ -247,6 +274,15 @@ const HALO_CSS = `
 
 function ensureHaloStyles(): void {
   if (typeof document === 'undefined') return;
+  // HUD tokens MUST be injected before HALO_CSS so the cascade resolves
+  // `var(--maude-hud-accent, …)` against the dev-server's brand defaults
+  // even when the canvas DS's tokens.css later sets `:root { --accent: … }`.
+  if (!document.getElementById('dc-cv-hud-tokens-css')) {
+    const t = document.createElement('style');
+    t.id = 'dc-cv-hud-tokens-css';
+    t.textContent = HUD_TOKENS_CSS;
+    document.head.appendChild(t);
+  }
   if (document.getElementById('dc-cv-halo-css')) return;
   const s = document.createElement('style');
   s.id = 'dc-cv-halo-css';
@@ -364,6 +400,85 @@ function CanvasCore({
     return () => host.removeAttribute('data-cv-zoom-lod');
   }, [hostRef, publishedZoom]);
 
+  // Phase 8 — publish local cursor (world coords) + viewport to Awareness
+  // so foreign peers can render our cursor on their CursorsOverlay. The
+  // collab.publishAwareness call is already throttled to ~30 Hz internally
+  // (use-collab.tsx) — we just need to compute screen → world per move.
+  const collab = useCollab();
+  useEffect(() => {
+    const host = hostRef.current;
+    if (!host || !collab || !controller) return;
+    const onMove = (e: MouseEvent) => {
+      const v = controller.viewport;
+      // screen → world: world = (screen - viewport.{x,y}) / zoom.
+      const worldX = (e.clientX - v.x) / Math.max(v.zoom, 0.0001);
+      const worldY = (e.clientY - v.y) / Math.max(v.zoom, 0.0001);
+      collab.publishAwareness({ cursor: { x: worldX, y: worldY } });
+    };
+    const onLeave = () => {
+      collab.publishAwareness({ cursor: null });
+    };
+    host.addEventListener('mousemove', onMove);
+    host.addEventListener('mouseleave', onLeave);
+    return () => {
+      host.removeEventListener('mousemove', onMove);
+      host.removeEventListener('mouseleave', onLeave);
+    };
+  }, [hostRef, collab, controller]);
+
+  // Phase 8 — publish viewport when it settles. The CursorsOverlay only
+  // needs the LOCAL viewport (to transform foreign world coords back to
+  // screen), but exposing ours over Awareness sets up Task 6's follow-mode.
+  // biome-ignore lint/correctness/useExhaustiveDependencies: deliberate settle-cadence — re-publish only when x/y/zoom change, not on every viewport field.
+  useEffect(() => {
+    if (!collab || !controller) return;
+    collab.publishAwareness({ viewport: controller.viewport });
+  }, [
+    collab,
+    controller,
+    controller?.viewport.x,
+    controller?.viewport.y,
+    controller?.viewport.zoom,
+  ]);
+
+  // Phase 8 — publish local selection so foreign PeerSelection halos can
+  // render around what *I* selected. Convert the first entry's selector
+  // (CSS path the peer resolves in their own DOM) + current bounds. The
+  // bounds are screen-px from publish time — peers re-resolve cssPath
+  // when possible and fall back to bounds otherwise.
+  useEffect(() => {
+    if (!collab) return;
+    const first = selSet.selected[0];
+    if (!first || !first.selector) {
+      collab.publishAwareness({ selection: null });
+      return;
+    }
+    const b = first.bounds;
+    const bounds =
+      b && typeof b === 'object'
+        ? {
+            x: Number(b.x) || 0,
+            y: Number(b.y) || 0,
+            w: Number(b.w) || 0,
+            h: Number(b.h) || 0,
+          }
+        : { x: 0, y: 0, w: 0, h: 0 };
+    collab.publishAwareness({ selection: { cssPath: first.selector, bounds } });
+  }, [collab, selSet.selected]);
+
+  // Phase 8 — publish annotation selection (Phase 5 strokes). Separate from
+  // selSet because annotations have their own selection registry. Peers
+  // render halos by querying `[data-id="<id>"]` so the same halo follows
+  // resize / move (SVG re-emits with the same data-id). `Optional` flavor
+  // because CanvasCore is mounted INSIDE the AnnotationSelectionProvider
+  // tree but TypeScript / a defensive boot path can't always prove it.
+  const annotSelForPublish = useAnnotationSelectionOptional();
+  const annotSelectedIds = annotSelForPublish?.selectedIds;
+  useEffect(() => {
+    if (!collab) return;
+    collab.publishAwareness({ annotationSelection: annotSelectedIds ?? [] });
+  }, [collab, annotSelectedIds]);
+
   /**
    * T24 — distribute the currently-selected artboards evenly on the given
    * axis. Requires ≥ 3 selected artboards. Sort by leading edge, hold the
@@ -1017,6 +1132,9 @@ function CanvasRouter({
       />
       <SnapGuideOverlay />
       <UndoHud />
+      <CursorsOverlay />
+      <AiBanner />
+      <ParticipantsChrome />
     </>
   );
 }
@@ -1062,7 +1180,7 @@ const MULTI_TOOLBAR_CSS = `
   transition: background-color 80ms linear;
 }
 .dc-multi-artboard-tb button:hover:not(:disabled) {
-  background: color-mix(in oklab, var(--accent, #d63b1f) 8%, transparent);
+  background: color-mix(in oklab, var(--maude-hud-accent, #d63b1f) 8%, transparent);
 }
 .dc-multi-artboard-tb button:disabled {
   cursor: default;

package/plugins/design/dev-server/client/app.jsx

@@ -1483,6 +1483,10 @@ function App() {
   const [activePath, setActivePath] = useState(null);
   const [selected, setSelected] = useState(null);
   const [wsConnected, setWsConnected] = useState(false);
+  // Phase 8 Task 7 — git lifecycle reload prompt. Server has already flushed
+  // every dirty Y.Doc to disk by the time this state populates, so accepting
+  // the reload is data-loss-safe (DDR-051 §3).
+  const [gitLifecycle, setGitLifecycle] = useState(null);
   const [search, setSearch] = useState('');
   const [systemData, setSystemData] = useState(null);
   // Loaded once at boot from /_config — informs canvasUrl() so TSX iframes
@@ -1658,6 +1662,23 @@ function App() {
             setSelected(m.selected);
           } else if (m.type === 'comments' && typeof m.file === 'string') {
             setCommentsByFile(prev => ({ ...prev, [m.file]: m.comments || [] }));
+          } else if (m.type === 'ai-activity' && typeof m.file === 'string') {
+            // Phase 8 Task 4 — relay to every open iframe; each canvas's
+            // AiBanner filters by its own file path. Lightweight broadcast
+            // (one envelope per change, not per iframe count).
+            for (const el of iframesRef.current.values()) {
+              try { el.contentWindow.postMessage({ dgn: 'ai-activity', file: m.file, entry: m.entry }, '*'); } catch {}
+            }
+          } else if (m.type === 'git-lifecycle' && m.payload) {
+            // Phase 8 Task 7 — branch switch / pull mid-session. Server has
+            // already flushed every dirty Y.Doc to JSON; just prompt the user.
+            // Single confirm covers all open iframes — reload reseeds them all.
+            setGitLifecycle(m.payload);
+            // Also relay to iframes so canvas-level "Reload?" UI (if any)
+            // can react. Outer banner is the primary prompt.
+            for (const el of iframesRef.current.values()) {
+              try { el.contentWindow.postMessage({ dgn: 'git-lifecycle', payload: m.payload }, '*'); } catch {}
+            }
           }
         } catch {}
       });
@@ -2000,6 +2021,57 @@ function App() {
       className={'app' + (commentsPanelOpen ? ' with-rsidebar' : '') + (sidebarOpen ? '' : ' no-sidebar')}
       onContextMenu={onShellContextMenu}
     >
+      {gitLifecycle && (
+        <div
+          role="status"
+          aria-live="polite"
+          style={{
+            position: 'fixed',
+            top: 12,
+            left: '50%',
+            transform: 'translateX(-50%)',
+            zIndex: 10002,
+            display: 'flex',
+            alignItems: 'center',
+            gap: 12,
+            padding: '8px 14px',
+            background: '#dbeafe',
+            color: '#1e40af',
+            border: '1px solid #93c5fd',
+            borderRadius: 999,
+            boxShadow: '0 2px 8px rgba(0,0,0,0.12)',
+            font: '500 13px/1.2 system-ui, -apple-system, sans-serif',
+          }}
+        >
+          <span>Repo state changed — reload to sync?</span>
+          <button
+            type="button"
+            onClick={() => { try { window.location.reload(); } catch {} }}
+            style={{
+              padding: '3px 10px',
+              background: '#2563eb',
+              color: '#fff',
+              border: 'none',
+              borderRadius: 4,
+              font: '500 11px/1.2 system-ui',
+              cursor: 'pointer',
+            }}
+          >Reload</button>
+          <button
+            type="button"
+            onClick={() => setGitLifecycle(null)}
+            style={{
+              padding: '3px 10px',
+              background: 'transparent',
+              color: '#1e40af',
+              border: '1px solid #93c5fd',
+              borderRadius: 4,
+              font: '500 11px/1.2 system-ui',
+              cursor: 'pointer',
+            }}
+          >Dismiss</button>
+        </div>
+      )}
       <Sidebar
         groups={groups}
         activePath={activePath}