@1agh/maude 0.20.0 → 0.21.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@1agh/maude",
-  "version": "0.20.0",
+  "version": "0.21.0",
   "description": "Marketplace of Claude Code plugins by Michal Dovrtěl: `design` (canvas-first design iteration) + `flow` (generic agentic workflow loop with .ai second brain). Ships the `maude` CLI (with `mdcc` legacy alias) to scaffold workspace, run the design dev server, and manage configs.",
   "type": "module",
   "engines": {
@@ -41,18 +41,22 @@
     "prepublishOnly": "bash scripts/check-version-parity.sh"
   },
   "optionalDependencies": {
-    "@1agh/maude-darwin-arm64": "0.20.0",
-    "@1agh/maude-darwin-x64": "0.20.0",
-    "@1agh/maude-linux-arm64": "0.20.0",
-    "@1agh/maude-linux-arm64-musl": "0.20.0",
-    "@1agh/maude-linux-x64": "0.20.0",
-    "@1agh/maude-linux-x64-musl": "0.20.0",
-    "@1agh/maude-win32-x64": "0.20.0"
+    "@1agh/maude-darwin-arm64": "0.21.0",
+    "@1agh/maude-darwin-x64": "0.21.0",
+    "@1agh/maude-linux-arm64": "0.21.0",
+    "@1agh/maude-linux-arm64-musl": "0.21.0",
+    "@1agh/maude-linux-x64": "0.21.0",
+    "@1agh/maude-linux-x64-musl": "0.21.0",
+    "@1agh/maude-win32-x64": "0.21.0"
   },
   "files": [
     "cli",
     "plugins/design/dev-server",
+    "plugins/design/dependencies.json",
+    "plugins/design/dependencies.schema.json",
     "plugins/design/templates",
+    "plugins/flow/dependencies.json",
+    "plugins/flow/dependencies.schema.json",
     "plugins/flow/templates",
     "plugins/flow/.claude-plugin/config.schema.json",
     "LICENSE",
@@ -84,5 +88,9 @@
     "@biomejs/biome": "^1.9.4",
     "@changesets/cli": "^2.27.10",
     "@playwright/test": "^1.60.0"
+  },
+  "dependencies": {
+    "ajv": "^8.20.0",
+    "ajv-formats": "^3.0.1"
   }
 }

package/plugins/design/dependencies.json

@@ -0,0 +1,147 @@
+{
+  "$schema": "./dependencies.schema.json",
+  "version": "1",
+  "plugin": "design",
+  "dependencies": [
+    {
+      "id": "node",
+      "type": "cli",
+      "hardness": "hard",
+      "check": {
+        "command": "node --version",
+        "expectExit": 0,
+        "minVersion": "20.0.0"
+      },
+      "install": {
+        "preferred": "https://nodejs.org/en/download",
+        "darwin": "brew install node@22",
+        "linux": "https://nodejs.org/en/download/package-manager"
+      },
+      "autoInstall": false,
+      "usedBy": ["commands/init.md", "commands/browse.md", "dev-server/server.ts"],
+      "docsUrl": "https://nodejs.org"
+    },
+    {
+      "id": "git",
+      "type": "cli",
+      "hardness": "hard",
+      "check": {
+        "command": "git --version",
+        "expectExit": 0
+      },
+      "install": {
+        "darwin": "brew install git",
+        "linux": "apt-get install -y git || dnf install -y git"
+      },
+      "autoInstall": false,
+      "usedBy": ["commands/init.md", "dev-server/collab/git-lifecycle.ts"],
+      "docsUrl": "https://git-scm.com"
+    },
+    {
+      "id": "bun",
+      "type": "cli",
+      "hardness": "hard",
+      "check": {
+        "command": "bun --version",
+        "expectExit": 0,
+        "minVersion": "1.3.0"
+      },
+      "install": {
+        "preferred": "curl -fsSL https://bun.sh/install | bash",
+        "darwin": "brew install oven-sh/bun/bun",
+        "win32": "powershell -c \"irm bun.sh/install.ps1 | iex\""
+      },
+      "autoInstall": false,
+      "fallbackBehavior": "dev-server is migrating to Bun authoritatively (DDR-009). Some build steps (bun run build.ts, bun test) require Bun and have no Node fallback.",
+      "usedBy": ["dev-server/package.json", "dev-server/build.ts", "dev-server/bin/smoke.sh"],
+      "docsUrl": "https://bun.com"
+    },
+    {
+      "id": "agent-browser",
+      "type": "cli",
+      "hardness": "soft",
+      "check": {
+        "command": "agent-browser --version",
+        "expectExit": 0
+      },
+      "install": {
+        "preferred": "npm i -g @anthropic-ai/agent-browser"
+      },
+      "autoInstall": true,
+      "fallbackBehavior": "Screenshot helpers fall back to `npx playwright` (slower, less reliable). /design:smoke and several critics need agent-browser for full coverage.",
+      "usedBy": [
+        "commands/screenshot.md",
+        "commands/new.md",
+        "commands/edit.md",
+        "commands/smoke.md",
+        "dev-server/bin/screenshot.sh",
+        "dev-server/bin/smoke.sh",
+        "agents/design-critic.md",
+        "agents/graphic-design-critic.md",
+        "agents/a11y-critic.md"
+      ],
+      "docsUrl": "https://github.com/anthropics/agent-browser"
+    },
+    {
+      "id": "playwright",
+      "type": "cli",
+      "hardness": "soft",
+      "check": {
+        "command": "npx --no-install playwright --version",
+        "expectExit": 0
+      },
+      "install": {
+        "preferred": "npm i -g playwright && npx playwright install chromium"
+      },
+      "autoInstall": false,
+      "fallbackBehavior": "Screenshot scripts use playwright as a fallback when agent-browser is missing. Without either, screenshot helpers will fail.",
+      "usedBy": ["dev-server/bin/_screenshot-playwright.mjs", "dev-server/bin/screenshot.sh"],
+      "docsUrl": "https://playwright.dev"
+    },
+    {
+      "id": "maude",
+      "type": "cli",
+      "hardness": "soft",
+      "check": {
+        "command": "maude --version",
+        "expectExit": 0
+      },
+      "install": {
+        "preferred": "npm i -g @1agh/maude"
+      },
+      "autoInstall": false,
+      "fallbackBehavior": "Slash commands still work; `maude` CLI provides faster scaffolding (init / config / design serve) without going through Claude.",
+      "usedBy": ["commands/init.md", "skills/design/SKILL.md"],
+      "docsUrl": "https://github.com/1aGh/maude"
+    },
+    {
+      "id": "jq",
+      "type": "system-tool",
+      "hardness": "soft",
+      "check": {
+        "command": "jq --version",
+        "expectExit": 0
+      },
+      "install": {
+        "darwin": "brew install jq",
+        "linux": "apt-get install -y jq || dnf install -y jq",
+        "win32": "winget install jqlang.jq"
+      },
+      "autoInstall": false,
+      "fallbackBehavior": "Slash commands' bash blocks that read .ai/workflows.config.json via jq degrade to inline node one-liners; harder to read but functional.",
+      "usedBy": ["dev-server/bin/bootstrap-check.sh", "dev-server/bin/server-up.sh"]
+    },
+    {
+      "id": "askuserquestion-mcp",
+      "type": "mcp",
+      "hardness": "soft",
+      "check": {
+        "mcp": "AskUserQuestion",
+        "tool": "ask"
+      },
+      "fallbackBehavior": "Discovery + critic-panel rounds fall back to numbered-prose chat. Slower, fewer options per round, no preview side-pane.",
+      "usedBy": ["skills/design-system/SKILL.md", "commands/setup-ds.md", "commands/new.md"],
+      "docsUrl": "https://docs.claude.com/en/docs/claude-code"
+    }
+  ]
+}

package/plugins/design/dependencies.schema.json

@@ -0,0 +1,107 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "maude plugin — runtime dependency manifest",
+  "description": "Declares CLI binaries, MCP servers, and runtime packages the plugin's commands / agents / skills shell out to. Consumed by maude doctor (cli/commands/doctor.mjs) and preflight.sh / preflight.mjs. Schema is shared between plugins — each plugin ships its own dependencies.json + (symlink to) this schema.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["version", "plugin", "dependencies"],
+  "properties": {
+    "version": {
+      "type": "string",
+      "const": "1",
+      "description": "Manifest schema version. Bumped when the dependency entry shape changes incompatibly."
+    },
+    "plugin": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Plugin name (matches plugins/<plugin>/.claude-plugin/plugin.json `name`)."
+    },
+    "dependencies": {
+      "type": "array",
+      "minItems": 0,
+      "items": { "$ref": "#/$defs/Dependency" }
+    }
+  },
+  "$defs": {
+    "Dependency": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["id", "type", "hardness", "check"],
+      "properties": {
+        "id": {
+          "type": "string",
+          "pattern": "^[a-z0-9][a-z0-9._-]*$",
+          "description": "Unique identifier within the manifest. Lowercase, hyphenated."
+        },
+        "type": {
+          "type": "string",
+          "enum": ["cli", "mcp", "node-package", "bun-package", "system-tool"],
+          "description": "What kind of dependency. `cli` = on PATH; `mcp` = MCP server / tool; `node-package` / `bun-package` = installed via npm/bun; `system-tool` = OS-provided (curl, jq)."
+        },
+        "hardness": {
+          "type": "string",
+          "enum": ["hard", "soft"],
+          "description": "`hard` = missing blocks plugin use; `soft` = graceful degradation possible (fallback path, warning only)."
+        },
+        "check": {
+          "type": "object",
+          "additionalProperties": false,
+          "description": "How to detect presence. For CLI/system-tool/package: shell command + expected exit. For MCP: tool name to probe.",
+          "properties": {
+            "command": {
+              "type": "string",
+              "description": "Shell command executed via `bash -c`. Pipes allowed. Defaults to `<id> --version`."
+            },
+            "expectExit": {
+              "type": "integer",
+              "default": 0,
+              "description": "Expected exit code. Anything else = missing/broken."
+            },
+            "minVersion": {
+              "type": "string",
+              "description": "Minimum semver. Comparator extracts `vX.Y.Z` from check.command stdout."
+            },
+            "mcp": {
+              "type": "string",
+              "description": "MCP server name. For type=mcp only."
+            },
+            "tool": {
+              "type": "string",
+              "description": "Specific tool name on the MCP server. For type=mcp only."
+            }
+          }
+        },
+        "install": {
+          "type": "object",
+          "additionalProperties": false,
+          "description": "Install commands per platform. `preferred` is OS-agnostic / fallback; per-platform keys override.",
+          "properties": {
+            "preferred": { "type": "string" },
+            "darwin": { "type": "string" },
+            "linux": { "type": "string" },
+            "win32": { "type": "string" }
+          }
+        },
+        "autoInstall": {
+          "type": "boolean",
+          "default": false,
+          "description": "If true, `maude doctor --fix` may run install.preferred after per-dep confirmation prompt."
+        },
+        "fallbackBehavior": {
+          "type": "string",
+          "description": "What the plugin does when this soft dep is missing. Human-readable; surfaces in maude doctor's report."
+        },
+        "usedBy": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Repo-relative paths (or path globs) of plugin files that reference this dependency. Aids debugging — doctor surfaces this when explaining a miss."
+        },
+        "docsUrl": {
+          "type": "string",
+          "format": "uri",
+          "description": "Where to read more."
+        }
+      }
+    }
+  }
+}

package/plugins/design/dev-server/ai-banner.tsx

@@ -0,0 +1,188 @@
+/**
+ * @file       ai-banner.tsx — yellow "Claude is editing this canvas" banner
+ * @scope      plugins/design/dev-server/ai-banner.tsx
+ * @purpose    Mounted by canvas-shell. Subscribes to the inspector WS
+ *             `ai-activity` event for the canvas's own file path; shows a
+ *             non-modal yellow banner while AI work is in progress and clears
+ *             on explicit /end OR 30-second heartbeat-grace expiry.
+ *
+ * The banner is a soft notice, NOT a lock — the user can still type, click,
+ * drag annotations, etc. It exists so the user doesn't unknowingly fight a
+ * `/design:edit` that's about to rewrite their HTML.
+ */
+
+import { useEffect, useState } from 'react';
+
+function deriveFile(): string | null {
+  if (typeof window === 'undefined') return null;
+  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 canvas ? `${designRel}/${canvas}` : null;
+    }
+    return decodeURIComponent(p).replace(/^\//, '');
+  } catch {
+    return null;
+  }
+}
+
+const BANNER_CSS = `
+.dc-ai-banner {
+  position: fixed;
+  top: 14px;
+  left: 50%;
+  transform: translateX(-50%);
+  z-index: 10001;
+  padding: 8px 14px;
+  display: flex;
+  align-items: center;
+  gap: 10px;
+  background: var(--maude-hud-accent-tint, oklch(92% 0.040 55));
+  color: var(--fg-0, #111);
+  border: 1px solid var(--border-default, rgba(0,0,0,0.16));
+  border-radius: var(--radius-md, 4px);
+  box-shadow: 0 2px 8px rgba(0, 0, 0, 0.08);
+  font-family: var(--font-sans, system-ui, -apple-system, sans-serif);
+  font-weight: 500;
+  font-size: 12px;
+  line-height: 1.2;
+  letter-spacing: 0.01em;
+  pointer-events: none;
+  user-select: none;
+}
+.dc-ai-banner__dot {
+  width: 7px;
+  height: 7px;
+  border-radius: 50%;
+  background: var(--maude-hud-accent, oklch(56% 0.170 50));
+  flex: 0 0 auto;
+  animation: dc-ai-banner-pulse 1.4s ease-in-out infinite;
+}
+@keyframes dc-ai-banner-pulse {
+  0%, 100% { opacity: 1; transform: scale(1); }
+  50%      { opacity: 0.5; transform: scale(0.75); }
+}
+@media (prefers-reduced-motion: reduce) {
+  .dc-ai-banner__dot { animation: none; }
+}
+`.trim();
+
+function ensureBannerStyles(): void {
+  if (typeof document === 'undefined') return;
+  if (document.getElementById('dc-ai-banner-css')) return;
+  const s = document.createElement('style');
+  s.id = 'dc-ai-banner-css';
+  s.textContent = BANNER_CSS;
+  document.head.appendChild(s);
+}
+
+interface AiEntry {
+  file: string;
+  author: string;
+  startedAt: number;
+  lastHeartbeat: number;
+}
+
+export function AiBanner(): JSX.Element | null {
+  ensureBannerStyles();
+  const [entry, setEntry] = useState<AiEntry | null>(null);
+  const file = deriveFile();
+
+  // Mount-time backfill — the bus only emits on changes, so a freshly opened
+  // tab needs to GET the snapshot to learn that an edit is already in flight.
+  useEffect(() => {
+    if (!file) return;
+    let cancelled = false;
+    fetch('/_api/ai')
+      .then((r) => r.json())
+      .then((j: { entries?: AiEntry[] }) => {
+        if (cancelled) return;
+        const hit = (j.entries ?? []).find((e) => e.file === file);
+        if (hit) setEntry(hit);
+      })
+      .catch(() => {
+        /* offline / restart — silently no-op */
+      });
+    return () => {
+      cancelled = true;
+    };
+  }, [file]);
+
+  // Subscribe to the parent shell's WS broadcast — when the inspector channel
+  // receives an `ai-activity` event for OUR file path, update local state.
+  // The shell relays via postMessage so we don't need our own WS connection
+  // (the iframe already piggybacks on the parent's inspector session).
+  //
+  // FALLBACK — when the canvas is opened standalone (export iframe, _shell.html
+  // direct URL), no parent WS exists. We open a thin reader-only inspector WS
+  // ourselves and watch for the matching event.
+  useEffect(() => {
+    if (!file) return;
+    if (typeof window === 'undefined') return;
+
+    // postMessage relay path — parent sends `ai-activity` events.
+    const onMessage = (e: MessageEvent) => {
+      const m = e.data as { dgn?: string; file?: string; entry?: AiEntry | null } | null;
+      if (!m || typeof m !== 'object') return;
+      if (m.dgn !== 'ai-activity') return;
+      if (m.file !== file) return;
+      setEntry(m.entry ?? null);
+    };
+    window.addEventListener('message', onMessage);
+
+    // Standalone fallback — if no parent is relaying, dial /_ws directly.
+    let standaloneWs: WebSocket | null = null;
+    let reconnect: ReturnType<typeof setTimeout> | null = null;
+    function connectStandalone() {
+      const proto = location.protocol === 'https:' ? 'wss:' : 'ws:';
+      const ws = new WebSocket(`${proto}//${location.host}/_ws`);
+      standaloneWs = ws;
+      ws.addEventListener('message', (ev) => {
+        try {
+          const data = typeof ev.data === 'string' ? ev.data : '';
+          if (!data) return;
+          const m = JSON.parse(data) as { type?: string; file?: string; entry?: AiEntry | null };
+          if (m.type !== 'ai-activity') return;
+          if (m.file !== file) return;
+          setEntry(m.entry ?? null);
+        } catch {
+          /* not a JSON frame (binary from collab WS) — ignore */
+        }
+      });
+      ws.addEventListener('close', () => {
+        standaloneWs = null;
+        reconnect = setTimeout(connectStandalone, 2000);
+      });
+      ws.addEventListener('error', () => {
+        /* close handler reconnects */
+      });
+    }
+    // Only open the standalone WS when we're not inside an iframe — the parent
+    // already drives the postMessage relay for embedded canvases.
+    if (window.parent === window) connectStandalone();
+
+    return () => {
+      window.removeEventListener('message', onMessage);
+      if (reconnect) clearTimeout(reconnect);
+      if (standaloneWs && standaloneWs.readyState === WebSocket.OPEN) {
+        try {
+          standaloneWs.close();
+        } catch {
+          /* ignore */
+        }
+      }
+    };
+  }, [file]);
+
+  if (!entry) return null;
+  return (
+    // biome-ignore lint/a11y/useSemanticElements: <output> is a form-result element; role="status" on a div is the canonical live-region banner pattern (APG).
+    <div className="dc-ai-banner" role="status" aria-live="polite">
+      <span className="dc-ai-banner__dot" aria-hidden="true" />
+      <span>{entry.author} is editing this canvas — your changes may conflict</span>
+    </div>
+  );
+}

package/plugins/design/dev-server/annotations-context-toolbar.tsx

@@ -73,7 +73,7 @@ const TOOLBAR_CSS = `
   appearance: none;
 }
 .dc-annot-ctx-sw[aria-pressed="true"] {
-  box-shadow: 0 0 0 2px var(--accent, #d63b1f);
+  box-shadow: 0 0 0 2px var(--maude-hud-accent, #d63b1f);
   border-color: transparent;
 }
 .dc-annot-ctx-fill--none {
@@ -103,8 +103,8 @@ const TOOLBAR_CSS = `
   cursor: pointer;
 }
 .dc-annot-ctx-btn[aria-pressed="true"] {
-  background: var(--accent, #d63b1f);
-  color: var(--accent-fg, #fff);
+  background: var(--maude-hud-accent, #d63b1f);
+  color: var(--maude-hud-accent-fg, #fff);
   border-color: transparent;
 }
 .dc-annot-ctx-btn:hover { background: rgba(0,0,0,0.04); }
@@ -134,8 +134,8 @@ const TOOLBAR_CSS = `
   line-height: 1;
 }
 .dc-annot-ctx-mode-btn[aria-pressed="true"] {
-  background: color-mix(in oklab, var(--accent, #d63b1f) 14%, transparent);
-  color: var(--accent, #d63b1f);
+  background: color-mix(in oklab, var(--maude-hud-accent, #d63b1f) 14%, transparent);
+  color: var(--maude-hud-accent, #d63b1f);
   font-weight: 600;
 }
 .dc-annot-ctx-mode-btn:not([aria-pressed="true"]):hover {

package/plugins/design/dev-server/annotations-layer.tsx

@@ -40,6 +40,7 @@ import { crossedDragThreshold } from './input-router.tsx';
 import { AnnotationResizeOverlay } from './use-annotation-resize.tsx';
 import { useAnnotationSelectionOptional } from './use-annotation-selection.tsx';
 import { useAnnotationsVisibility } from './use-annotations-visibility.tsx';
+import { useCollab } from './use-collab.tsx';
 import { useSelectionSetOptional } from './use-selection-set.tsx';
 import { useToolMode } from './use-tool-mode.tsx';
 import { useUndoSinks, useUndoStackOptional } from './use-undo-stack.tsx';
@@ -483,11 +484,11 @@ const ANNOT_CSS = `
   appearance: none;
 }
 .dc-annot-chrome .dc-annot-sw[aria-pressed="true"] {
-  box-shadow: 0 0 0 2px var(--accent, #d63b1f);
+  box-shadow: 0 0 0 2px var(--maude-hud-accent, #d63b1f);
   border-color: transparent;
 }
 .dc-annot-chrome .dc-annot-sw:focus-visible {
-  outline: 2px solid var(--accent, #d63b1f);
+  outline: 2px solid var(--maude-hud-accent, #d63b1f);
   outline-offset: 2px;
 }
 .dc-annot-chrome .dc-annot-sep {
@@ -516,7 +517,7 @@ const ANNOT_CSS = `
     linear-gradient(135deg, transparent 47%, #d63b1f 47%, #d63b1f 53%, transparent 53%);
 }
 .dc-annot-chrome .dc-annot-fill[aria-pressed="true"] {
-  box-shadow: 0 0 0 2px var(--accent, #d63b1f);
+  box-shadow: 0 0 0 2px var(--maude-hud-accent, #d63b1f);
   border-color: transparent;
 }
 .dc-annot-chrome .dc-annot-btn {
@@ -532,13 +533,13 @@ const ANNOT_CSS = `
   text-transform: uppercase;
 }
 .dc-annot-chrome .dc-annot-btn[aria-pressed="true"] {
-  background: var(--accent, #d63b1f);
-  color: var(--accent-fg, #fff);
+  background: var(--maude-hud-accent, #d63b1f);
+  color: var(--maude-hud-accent-fg, #fff);
   border-color: transparent;
 }
 .dc-annot-chrome .dc-annot-btn:hover { background: rgba(0,0,0,0.04); }
 .dc-annot-chrome .dc-annot-btn:focus-visible {
-  outline: 2px solid var(--accent, #d63b1f);
+  outline: 2px solid var(--maude-hud-accent, #d63b1f);
   outline-offset: 2px;
 }
 .dc-annot-input {
@@ -567,8 +568,8 @@ const ANNOT_CSS = `
 /* Drag-select marquee — rendered while user is dragging to select strokes. */
 .dc-annot-marquee {
   pointer-events: none;
-  fill: color-mix(in oklab, var(--accent, #d63b1f) 8%, transparent);
-  stroke: var(--accent, #d63b1f);
+  fill: color-mix(in oklab, var(--maude-hud-accent, #d63b1f) 8%, transparent);
+  stroke: var(--maude-hud-accent, #d63b1f);
   stroke-width: 1;
   stroke-dasharray: 4 3;
 }
@@ -689,6 +690,10 @@ export function AnnotationsLayer() {
   const supportsFill = tool === 'rect' || tool === 'ellipse';
 
   // Load existing annotations on mount.
+  // Phase 8 Task 5 — seed lastAppliedSvgRef so the first Y.Map observe (when
+  // collab connects shortly after this fetch lands) doesn't re-apply the
+  // same content we just hydrated from REST.
+  const lastAppliedSvgRef = useRef<string>('');
   useEffect(() => {
     const file = deriveFile();
     fileRef.current = file;
@@ -701,7 +706,10 @@ export function AnnotationsLayer() {
       .then((text) => {
         if (cancelled) return;
         const loaded = svgToStrokes(text);
-        if (loaded.length) setStrokesState(loaded);
+        if (loaded.length) {
+          setStrokesState(loaded);
+          lastAppliedSvgRef.current = text;
+        }
       })
       .catch(() => {
         /* network blip — start with an empty annotation set */
@@ -711,6 +719,34 @@ export function AnnotationsLayer() {
     };
   }, []);
 
+  // Phase 8 Task 5 — observe the Y.Map.annotations for live updates from
+  // other tabs. Bail when the incoming SVG STRING is identical to the one
+  // we last applied (covers the local echo round-trip without missing real
+  // foreign changes). The prior length+first/last-id check was wrong: a
+  // resize / move keeps the same id list, so all three predicates matched
+  // even though geometry changed — foreign edits silently disappeared.
+  const collab = useCollab();
+  useEffect(() => {
+    if (!collab) return;
+    const map = collab.doc.getMap<string>('annotations');
+    const apply = () => {
+      const svg = map.get('svg');
+      if (typeof svg !== 'string' || !svg) return;
+      if (svg === lastAppliedSvgRef.current) return;
+      lastAppliedSvgRef.current = svg;
+      setStrokesState(svgToStrokes(svg));
+    };
+    apply();
+    map.observe(apply);
+    return () => {
+      try {
+        map.unobserve(apply);
+      } catch {
+        /* doc destroyed before unmount */
+      }
+    };
+  }, [collab]);
+
   const undoStack = useUndoStackOptional();
   const undoSinks = useUndoSinks();
   const undoStackRef = useRef(undoStack);
@@ -734,6 +770,10 @@ export function AnnotationsLayer() {
     const file = fileRef.current;
     if (!file) return Promise.resolve();
     const svg = strokesToSvg(next);
+    // Phase 8 Task 5 — record the SVG we just authored locally so the
+    // server-broadcast echo (PUT → onAnnotationsChanged → syncRoom* →
+    // Y.Map.observe) doesn't trigger a redundant setStrokesState.
+    lastAppliedSvgRef.current = svg;
     return fetch('/_api/annotations', {
       method: 'PUT',
       headers: { 'Content-Type': 'application/json' },
@@ -1683,7 +1723,7 @@ function SelectionHalo({
       width={bbox.w + pad * 2}
       height={bbox.h + pad * 2}
       fill="none"
-      stroke="var(--accent, #d63b1f)"
+      stroke="var(--maude-hud-accent, #d63b1f)"
       strokeWidth={multi ? 1.5 : 2}
       vectorEffect="non-scaling-stroke"
       pointerEvents="none"
@@ -1738,7 +1778,7 @@ function AnnotGroupBbox({
         width={w}
         height={h}
         fill="none"
-        stroke="var(--accent, #d63b1f)"
+        stroke="var(--maude-hud-accent, #d63b1f)"
         strokeWidth={1}
         strokeDasharray="4 3"
         vectorEffect="non-scaling-stroke"
@@ -1751,7 +1791,7 @@ function AnnotGroupBbox({
           y={c.y}
           width={handle}
           height={handle}
-          fill="var(--accent, #d63b1f)"
+          fill="var(--maude-hud-accent, #d63b1f)"
           stroke="var(--bg-0, #ffffff)"
           strokeWidth={1}
           vectorEffect="non-scaling-stroke"