@1agh/maude 0.28.1 → 0.29.0

package/apps/studio/bin/_motion-sample-playwright.mjs

@@ -0,0 +1,129 @@
+// _motion-sample-playwright.mjs — the live-motion proof sampler (draw-proof --motion).
+//
+// A still screenshot CANNOT prove animation — the studyfi-v3 session burned ~3
+// rounds because a freeze-frame "confirmed" a dead CSS `d:path()` morph (which
+// does not animate live in any shipping browser). This shim closes that gap: it
+// loads the proof URL in a real Chromium, samples the animated element's
+// geometry/paint signature at TWO distinct wall-clock times, and asserts it
+// changed. Freeze-frame pass + over-time NO-CHANGE ⇒ HARD FAIL (DDR-094 M1).
+//
+// Signature = getBBox() (x/y/width/height — catches morph/scale/translate) +
+// computed transform matrix + computed opacity (catches fade-only animation).
+// Any component differing beyond epsilon ⇒ the property is animating.
+//
+// Target selection: an explicit --selector, else auto-detect the parent of the
+// first <animate>/<animateTransform> in the document.
+//
+// Invocation (via draw-proof.sh; never a raw path — DDR-062):
+//   node _motion-sample-playwright.mjs --url <url> [--selector <css>]
+//        [--gap 600] [--timeout 12]
+//
+// Exit: 0 motion proven · 1 element/animation not found · 2 bad args
+//       3 Chromium binary missing (launchChromium) · 4 NO over-time change (HARD FAIL)
+
+/**
+ * Pure signature-delta test (exported for a unit test — no browser needed).
+ * Returns true when any component of two samples differs beyond `eps`.
+ */
+export function signatureChanged(a, b, eps = 0.25) {
+  if (!a || !b) return false;
+  const keys = new Set([...Object.keys(a), ...Object.keys(b)]);
+  for (const k of keys) {
+    if (k.startsWith('__')) continue;
+    const av = a[k];
+    const bv = b[k];
+    if (typeof av === 'number' && typeof bv === 'number') {
+      if (Math.abs(av - bv) > eps) return true;
+    } else if (av !== bv) {
+      return true;
+    }
+  }
+  return false;
+}
+
+// The in-page sampler: bbox + transform matrix + opacity of the target element.
+// Exported so the selector/auto-detect contract is documented + reviewable.
+export const SAMPLE_FN = (sel) => {
+  let el = null;
+  if (sel) {
+    el = document.querySelector(sel);
+  } else {
+    const anim = document.querySelector('animate, animateTransform');
+    el = anim ? anim.parentElement : null;
+  }
+  if (!el) return { __missing: true };
+  const box = typeof el.getBBox === 'function' ? el.getBBox() : { x: 0, y: 0, width: 0, height: 0 };
+  const cs = getComputedStyle(el);
+  return {
+    x: box.x,
+    y: box.y,
+    width: box.width,
+    height: box.height,
+    transform: cs.transform || 'none',
+    opacity: Number(cs.opacity) || 1,
+  };
+};
+
+// Entry-point detection that works under BOTH node and bun across versions
+// (`import.meta.main` is Node-24-only). True only when run directly, so the
+// unit test can `import { signatureChanged }` without launching Chromium.
+const { pathToFileURL } = await import('node:url');
+const isEntry = Boolean(process.argv[1]) && import.meta.url === pathToFileURL(process.argv[1]).href;
+
+// Browser driver — runs ONLY as the entry point, never on import.
+if (isEntry) {
+  const { launchChromium } = await import('./_pw-launch.mjs');
+
+  const args = Object.fromEntries(
+    process.argv.slice(2).reduce((acc, cur, i, all) => {
+      if (cur.startsWith('--')) acc.push([cur.slice(2), all[i + 1] ?? '1']);
+      return acc;
+    }, [])
+  );
+
+  const { url, selector, gap = '600', timeout = '12' } = args;
+  if (!url) {
+    console.error('usage: _motion-sample-playwright.mjs --url <url> [--selector <css>] [--gap ms]');
+    process.exit(2);
+  }
+  const gapMs = Number(gap);
+  const timeoutMs = Number(timeout) * 1000;
+
+  const browser = await launchChromium();
+  try {
+    const ctx = await browser.newContext({ viewport: { width: 1440, height: 900 } });
+    const page = await ctx.newPage();
+    await page.goto(url, { waitUntil: 'networkidle', timeout: timeoutMs });
+    await page.evaluate(() => document.fonts.ready);
+
+    const first = await page.evaluate(SAMPLE_FN, selector ?? null);
+    if (first.__missing) {
+      console.error(
+        selector
+          ? `motion-sample: no element matched "${selector}"`
+          : 'motion-sample: no <animate>/<animateTransform> found in the document'
+      );
+      process.exit(1);
+    }
+
+    await page.waitForTimeout(gapMs); // let the runtime advance real wall-clock
+    const second = await page.evaluate(SAMPLE_FN, selector ?? null);
+
+    if (signatureChanged(first, second)) {
+      console.error(`motion-sample: over-time delta confirmed (gap ${gapMs}ms) — motion proven`);
+      await browser.close();
+      process.exit(0);
+    }
+    console.error(
+      `motion-sample: NO change over ${gapMs}ms — dead mechanism (freeze-frame may look fine). ` +
+        'Check for CSS d:path() or a non-animating property (DDR-094 M1/M2).'
+    );
+    console.error(`  t0=${JSON.stringify(first)}`);
+    console.error(`  t1=${JSON.stringify(second)}`);
+    await browser.close();
+    process.exit(4);
+  } catch (err) {
+    await browser.close();
+    throw err;
+  }
+}

package/{plugins/design/dev-server → apps/studio}/bin/canvas-edit.sh

@@ -1,6 +1,6 @@
 #!/usr/bin/env bash
 # canvas-edit.sh — AST-aware single-attribute edit on a canvas .tsx file.
-# Wraps `plugins/design/dev-server/canvas-edit.ts` so /design:edit Step 3a can
+# Wraps `apps/studio/canvas-edit.ts` so /design:edit Step 3a can
 # shell out without booting a Bun module loader inline. Phase 3.6 Task 5.
 #
 # Usage:  canvas-edit.sh <canvas-abs-path> <data-cd-id> <attr> <value>

package/{plugins/design/dev-server → apps/studio}/bin/draw-proof.sh

@@ -13,13 +13,23 @@
 #   draw-proof.sh --asset <mark.svg> --slug <name>
 #                 [--root <repo>] [--out-dir <dir>] [--name <display label>]
 #                 [--engine auto|agent-browser|playwright] [--timeout <secs>]
+#                 [--motion] [--motion-selector <css>] [--motion-gap <ms>]
 #
 # Requires a running dev server (caller runs `maude design server-up` first);
 # reads the port from <designRoot>/_server.json.
 #
+# --motion: after the still ladder, run the LIVE-MOTION proof — sample the
+#   animated element at two wall-clock times and assert it changed. A still
+#   screenshot can't prove animation (DDR-094 M1); a freeze-frame pass + an
+#   over-time NO-CHANGE is a HARD FAIL (dead mechanism, e.g. CSS d:path()).
+#   --motion-selector targets a specific element (default: auto-detect the
+#   parent of the first <animate>/<animateTransform>). --motion-gap sets the
+#   sample interval in ms (default 600).
+#
 # Stdout (last line): the screenshot output directory (capturable in $(...)).
 # Stderr: progress / diagnostics.
-# Exit:   0 success / 1 missing input or server / 2 bad args / 3 capture failed.
+# Exit:   0 success / 1 missing input or server / 2 bad args / 3 capture failed
+#         / 4 motion HARD FAIL (still ladder OK but no over-time change).
 
 ASSET=""
 SLUG=""
@@ -28,6 +38,9 @@ OUT_DIR=""
 NAME=""
 ENGINE="auto"
 TIMEOUT=10
+MOTION=0
+MOTION_SELECTOR=""
+MOTION_GAP=600
 
 while [ $# -gt 0 ]; do
   case "$1" in
@@ -38,8 +51,11 @@ while [ $# -gt 0 ]; do
     --name)    NAME="$2"; shift 2 ;;
     --engine)  ENGINE="$2"; shift 2 ;;
     --timeout) TIMEOUT="$2"; shift 2 ;;
+    --motion)  MOTION=1; shift ;;
+    --motion-selector) MOTION_SELECTOR="$2"; shift 2 ;;
+    --motion-gap)      MOTION_GAP="$2"; shift 2 ;;
     --help|-h)
-      sed -n '2,27p' "$0" | sed 's/^# \?//'
+      sed -n '2,37p' "$0" | sed 's/^# \?//'
       exit 0
       ;;
     *)
@@ -125,5 +141,24 @@ fi
 
 COUNT=$(find "$OUT_DIR" -maxdepth 1 -type f -name '*.png' 2>/dev/null | wc -l | tr -d ' ')
 echo "→ captured $COUNT proof image(s) in $OUT_DIR" >&2
+
+# ---------- live-motion proof (--motion) ----------
+# The still ladder above is the freeze-frame; it cannot prove the mark ANIMATES.
+# Sample the animated element at two wall-clock times and require a delta.
+if [ "$MOTION" -eq 1 ]; then
+  echo "→ live-motion proof (over-time delta) …" >&2
+  MOTION_ARGS=(--url "$URL" --gap "$MOTION_GAP" --timeout "$TIMEOUT")
+  [ -n "$MOTION_SELECTOR" ] && MOTION_ARGS+=(--selector "$MOTION_SELECTOR")
+  node "$SCRIPT_DIR/_motion-sample-playwright.mjs" "${MOTION_ARGS[@]}" >&2
+  MRC=$?
+  case "$MRC" in
+    0) echo "→ motion proven (over-time delta confirmed)" >&2 ;;
+    4) echo "draw-proof.sh: MOTION HARD FAIL — still ladder OK but the mark does NOT animate over time (dead mechanism). See DDR-094 M1/M2." >&2
+       exit 4 ;;
+    *) echo "draw-proof.sh: motion sampler error (rc=$MRC) — could not verify animation" >&2
+       exit 3 ;;
+  esac
+fi
+
 # Last stdout line = the output dir, for $(maude design draw-proof ...) capture.
 printf '%s\n' "$OUT_DIR"

package/{plugins/design/dev-server → apps/studio}/bin/preflight.sh

@@ -27,7 +27,7 @@
 # Exit: 0 if all hard deps pass; 1 otherwise.
 
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
-PLUGIN_ROOT="${CLAUDE_PLUGIN_ROOT:-$(cd "$SCRIPT_DIR/../.." && pwd)}"
+PLUGIN_ROOT="${CLAUDE_PLUGIN_ROOT:-$(cd "$SCRIPT_DIR/.." && pwd)}"
 PKG_ROOT="$(cd "$PLUGIN_ROOT/../.." && pwd)"
 
 if [ -f "$PKG_ROOT/cli/lib/preflight.mjs" ]; then

package/apps/studio/bin/read-annotations.mjs

@@ -0,0 +1,438 @@
+#!/usr/bin/env node
+// read-annotations.mjs — headless, zero-dep SVG → JSON annotation reader.
+//
+// Phase 22. The browser-side parser `svgToStrokes` (annotations-layer.tsx) needs
+// a DOMParser, which plain Node does not expose. This is its headless cousin: it
+// reads a canvas's `<slug>.annotations.svg` and extracts every sticky / text /
+// shape as structured JSON the `/design:new` ingest path folds into a generation
+// brief. It is a SEPARATE implementation (not an import) of the same fixed
+// vocabulary `strokesToSvg` serializes — `read-annotations.test.ts` rebuilds
+// strokes through the CANONICAL serializer and asserts this reader recovers them,
+// so any drift in the SVG shape (Phase 21 / 23 / 24 …) fails that test loud.
+//
+// Regex-over-known-vocabulary, mirroring the discipline of `sanitizeAnnotationSvg`
+// (api.ts) and the defensive defaults of `svgToStrokes`. We never DOM-parse.
+//
+// Output: a JSON array of `{ tool, id, x, y, w, h, text, color }`. Strokes that
+// carry words (sticky, text) populate `text`; position-only strokes (pen, rect,
+// ellipse, polygon, arrow) emit `text: null` with their bounding box. With
+// `--canvas-state <path>` each annotation also gets `artboard: <id|null>` by bbox
+// overlap. Forward-compat: an unknown `data-tool` (Phase 23 image/link) passes
+// through with any `href`/`url`/`title` it carries, so a later ingest picks up
+// dropped reference media without a reader change.
+//
+// Reached via `maude design read-annotations "<rel-path>"` (DDR-062), never a raw
+// bin path. A missing annotation file is NOT an error — a board with no notes is
+// valid; the reader emits `[]` and exits 0.
+//
+// Usage:
+//   read-annotations.mjs <rel-path-relative-to-designRoot> [--root <repo>]
+//                        [--canvas-state <path>] [--json]
+
+import { existsSync, readFileSync } from 'node:fs';
+import { isAbsolute, join, resolve } from 'node:path';
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Argv
+
+function parseArgv(argv) {
+  const out = { positional: [], root: null, canvasState: null, help: false };
+  for (let i = 0; i < argv.length; i += 1) {
+    const a = argv[i];
+    if (a === '--help' || a === '-h') {
+      out.help = true;
+    } else if (a === '--json') {
+      /* default — accepted for symmetry with other verbs */
+    } else if (a === '--root') {
+      i += 1;
+      out.root = argv[i];
+    } else if (a.startsWith('--root=')) {
+      out.root = a.slice('--root='.length);
+    } else if (a === '--canvas-state') {
+      i += 1;
+      out.canvasState = argv[i];
+    } else if (a.startsWith('--canvas-state=')) {
+      out.canvasState = a.slice('--canvas-state='.length);
+    } else {
+      out.positional.push(a);
+    }
+  }
+  return out;
+}
+
+const HELP = `read-annotations.mjs — headless SVG → JSON annotation reader (DDR-062 via \`maude design read-annotations\`)
+
+Usage:
+  maude design read-annotations <rel-path> [--root <repo>] [--canvas-state <path>]
+
+Args:
+  <rel-path>          Canvas path relative to the design root (e.g. "ui/Foo.tsx").
+  --root <repo>       Repo root. Default: $CLAUDE_PROJECT_DIR, then cwd.
+  --canvas-state <p>  JSON of artboard rects ([{id,x,y,w,h}] or {artboards:[…]});
+                      each annotation is tagged with the artboard it overlaps.
+  --json              No-op (JSON is the only output form).
+
+Emits a JSON array to stdout. A missing annotation file emits [] (exit 0).`;
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Path + slug resolution — mirror the dev-server (api.ts fileSlug, context.ts
+// designRoot). The annotation file is named by fileSlug(), so we recompute the
+// SAME slug to find it.
+
+function resolveDesignRoot(repoRoot) {
+  // config.json is ALWAYS at <repoRoot>/.design/config.json; its optional
+  // `designRoot` field (default ".design") is where canvases + annotation SVGs
+  // actually live. (context.ts:64,226 — designRoot defaults to ".design".)
+  let designRel = '.design';
+  try {
+    const cfg = JSON.parse(readFileSync(join(repoRoot, '.design', 'config.json'), 'utf8'));
+    if (typeof cfg.designRoot === 'string' && cfg.designRoot.trim()) {
+      designRel = cfg.designRoot.replace(/^\/+|\/+$/g, '');
+    }
+  } catch {
+    /* no config — default .design */
+  }
+  return { designRel, designRoot: join(repoRoot, designRel) };
+}
+
+// Byte-for-byte the producer's rule (api.ts:266 fileSlug). The reader's input is
+// design-root-relative, but we still strip a leading designRel/ prefix so a
+// repo-root-relative path ("./design/ui/Foo.tsx") resolves to the same slug.
+function fileSlug(file, designRel) {
+  let p = String(file).replace(/^\/+|\/+$/g, '');
+  try {
+    p = decodeURIComponent(p);
+  } catch {
+    /* leave as-is */
+  }
+  const prefix = `${designRel.replace(/^\/+|\/+$/g, '')}/`;
+  if (p.startsWith(prefix)) p = p.slice(prefix.length);
+  return p
+    .replace(/\//g, '-')
+    .replace(/\s+/g, '_')
+    .replace(/\.(tsx|html)$/i, '')
+    .replace(/^\.+/, '')
+    .toLowerCase();
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Tiny SVG helpers — attribute pluck, entity-decode, number coerce.
+
+function attr(s, name) {
+  const re = new RegExp(
+    `(?:^|\\s)${name.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}\\s*=\\s*"([^"]*)"`
+  );
+  const m = s.match(re);
+  return m ? m[1] : null;
+}
+
+function hasAttr(s, name) {
+  return attr(s, name) !== null;
+}
+
+// Reverse esc() (annotations-layer.tsx): &amp; / &quot; / &lt; are the only
+// entities the serializer writes, but we decode the common set defensively.
+// Named entities first, &amp; LAST so "&amp;lt;" (a literal "&lt;") survives.
+function decodeEntities(s) {
+  return String(s)
+    .replace(/&lt;/g, '<')
+    .replace(/&gt;/g, '>')
+    .replace(/&quot;/g, '"')
+    .replace(/&#39;/g, "'")
+    .replace(/&apos;/g, "'")
+    .replace(/&amp;/g, '&');
+}
+
+function num(v, d = 0) {
+  const n = Number.parseFloat(v);
+  return Number.isFinite(n) ? n : d;
+}
+
+function stripTags(s) {
+  return String(s).replace(/<[^>]*>/g, '');
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Per-tool extraction.
+
+function readText(attrs, inner) {
+  const anchorId = attr(attrs, 'data-anchor-id');
+  const standalone = !anchorId;
+  const o = {
+    tool: 'text',
+    id: attr(attrs, 'data-id') || '',
+    x: standalone ? num(attr(attrs, 'x')) : null,
+    y: standalone ? num(attr(attrs, 'y')) : null,
+    w: null,
+    h: null,
+    text: decodeEntities(inner).trim(),
+    color: attr(attrs, 'fill') || attr(attrs, 'stroke') || null,
+  };
+  if (anchorId) o.anchorId = anchorId;
+  return o;
+}
+
+function readSticky(attrs, inner) {
+  // Geometry off the inner <rect>; paper tint off the group fill; body off the
+  // inner <text>. (annotations-layer.tsx strokeToSvgEl 'sticky' branch.)
+  const rectAttrs = inner.match(/<rect\b([^>]*?)\/?>/)?.[1] ?? '';
+  const body = inner.match(/<text\b[^>]*>([\s\S]*?)<\/text>/)?.[1] ?? '';
+  return {
+    tool: 'sticky',
+    id: attr(attrs, 'data-id') || '',
+    x: num(attr(rectAttrs, 'x')),
+    y: num(attr(rectAttrs, 'y')),
+    w: num(attr(rectAttrs, 'width')),
+    h: num(attr(rectAttrs, 'height')),
+    text: decodeEntities(body).trim(),
+    color: attr(attrs, 'fill') || null,
+  };
+}
+
+function readArrow(attrs, inner) {
+  const id = attr(attrs, 'data-id') || '';
+  const color = attr(attrs, 'stroke') || null;
+  let ends = null;
+  const lineAttrs = inner.match(/<line\b([^>]*?)\/?>/)?.[1];
+  if (lineAttrs) {
+    ends = {
+      x1: num(attr(lineAttrs, 'x1')),
+      y1: num(attr(lineAttrs, 'y1')),
+      x2: num(attr(lineAttrs, 'x2')),
+      y2: num(attr(lineAttrs, 'y2')),
+    };
+  } else {
+    // Curved / elbow arrow persists a <path>; first + last coordinate pairs are
+    // the endpoints (arrowEndpoints in annotations-layer.tsx).
+    const d = inner.match(/<path\b([^>]*?)\/?>/)?.[1];
+    const nums = d ? (attr(d, 'd') || '').match(/-?\d+(?:\.\d+)?/g) : null;
+    if (nums && nums.length >= 4) {
+      ends = {
+        x1: num(nums[0]),
+        y1: num(nums[1]),
+        x2: num(nums[nums.length - 2]),
+        y2: num(nums[nums.length - 1]),
+      };
+    }
+  }
+  if (!ends) return { tool: 'arrow', id, x: null, y: null, w: null, h: null, text: null, color };
+  return {
+    tool: 'arrow',
+    id,
+    x: Math.min(ends.x1, ends.x2),
+    y: Math.min(ends.y1, ends.y2),
+    w: Math.abs(ends.x2 - ends.x1),
+    h: Math.abs(ends.y2 - ends.y1),
+    text: null,
+    color,
+  };
+}
+
+function bboxFromNums(nums) {
+  let xMin = Number.POSITIVE_INFINITY;
+  let yMin = Number.POSITIVE_INFINITY;
+  let xMax = Number.NEGATIVE_INFINITY;
+  let yMax = Number.NEGATIVE_INFINITY;
+  for (let i = 0; i + 1 < nums.length; i += 2) {
+    const px = num(nums[i]);
+    const py = num(nums[i + 1]);
+    if (px < xMin) xMin = px;
+    if (px > xMax) xMax = px;
+    if (py < yMin) yMin = py;
+    if (py > yMax) yMax = py;
+  }
+  if (!Number.isFinite(xMin)) return null;
+  return { x: xMin, y: yMin, w: xMax - xMin, h: yMax - yMin };
+}
+
+function readPen(attrs) {
+  const id = attr(attrs, 'data-id') || '';
+  const color = attr(attrs, 'stroke') || null;
+  const bb = bboxFromNums((attr(attrs, 'd') || '').match(/-?\d+(?:\.\d+)?/g) || []);
+  if (!bb) return { tool: 'pen', id, x: null, y: null, w: null, h: null, text: null, color };
+  return { tool: 'pen', id, ...bb, text: null, color };
+}
+
+function readRect(attrs) {
+  return {
+    tool: 'rect',
+    id: attr(attrs, 'data-id') || '',
+    x: num(attr(attrs, 'x')),
+    y: num(attr(attrs, 'y')),
+    w: num(attr(attrs, 'width')),
+    h: num(attr(attrs, 'height')),
+    text: null,
+    color: attr(attrs, 'stroke') || null,
+  };
+}
+
+function readEllipse(attrs) {
+  const cx = num(attr(attrs, 'cx'));
+  const cy = num(attr(attrs, 'cy'));
+  const rx = num(attr(attrs, 'rx'));
+  const ry = num(attr(attrs, 'ry'));
+  return {
+    tool: 'ellipse',
+    id: attr(attrs, 'data-id') || '',
+    x: cx - rx,
+    y: cy - ry,
+    w: rx * 2,
+    h: ry * 2,
+    text: null,
+    color: attr(attrs, 'stroke') || null,
+  };
+}
+
+function readPolygon(attrs) {
+  const id = attr(attrs, 'data-id') || '';
+  const color = attr(attrs, 'stroke') || null;
+  const nums = (attr(attrs, 'points') || '').match(/-?\d+(?:\.\d+)?/g) || [];
+  const bb = bboxFromNums(nums);
+  if (!bb) return { tool: 'polygon', id, x: null, y: null, w: null, h: null, text: null, color };
+  return { tool: 'polygon', id, ...bb, text: null, color };
+}
+
+// Forward-compat (Phase 23) — an unknown data-tool (image / link chip) passes
+// through with whatever geometry + media attrs it carries.
+function readUnknown(tool, attrs, inner) {
+  const text = inner
+    ? decodeEntities(stripTags(inner)).trim() || null
+    : attr(attrs, 'data-text')
+      ? decodeEntities(attr(attrs, 'data-text'))
+      : null;
+  const o = {
+    tool,
+    id: attr(attrs, 'data-id') || '',
+    x: hasAttr(attrs, 'x') ? num(attr(attrs, 'x')) : null,
+    y: hasAttr(attrs, 'y') ? num(attr(attrs, 'y')) : null,
+    w: hasAttr(attrs, 'width') ? num(attr(attrs, 'width')) : null,
+    h: hasAttr(attrs, 'height') ? num(attr(attrs, 'height')) : null,
+    text,
+    color: attr(attrs, 'fill') || attr(attrs, 'stroke') || null,
+  };
+  const href = attr(attrs, 'href') || attr(attrs, 'xlink:href');
+  const url = attr(attrs, 'data-url');
+  const title = attr(attrs, 'data-title');
+  if (href) o.href = href;
+  if (url) o.url = url;
+  if (title) o.title = decodeEntities(title);
+  return o;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Top-level element walk. The annotation vocabulary nests at most one level —
+// sticky/arrow are <g> wrapping leaf primitives, text wraps only character data,
+// and NO container nests inside the same container — so a non-greedy backref
+// match recovers each top-level element in document order. (Task-2 drift guard
+// keeps this invariant honest against the canonical serializer.)
+function parseAnnotations(svg) {
+  const out = [];
+  if (!svg || !/<svg[\s>]/i.test(svg)) return out;
+  const re = /<(g|text)\b([^>]*)>([\s\S]*?)<\/\1>|<(path|rect|ellipse|polygon)\b([^>]*?)\/?>/g;
+  let m = re.exec(svg);
+  while (m !== null) {
+    if (m[1]) {
+      const attrs = m[2];
+      const inner = m[3];
+      const tool = attr(attrs, 'data-tool');
+      if (tool === 'sticky') out.push(readSticky(attrs, inner));
+      else if (tool === 'arrow') out.push(readArrow(attrs, inner));
+      else if (tool === 'text') out.push(readText(attrs, inner));
+      else if (tool) out.push(readUnknown(tool, attrs, inner));
+    } else {
+      const attrs = m[5];
+      const tool = attr(attrs, 'data-tool');
+      if (tool === 'pen') out.push(readPen(attrs));
+      else if (tool === 'rect') out.push(readRect(attrs));
+      else if (tool === 'ellipse') out.push(readEllipse(attrs));
+      else if (tool === 'polygon') out.push(readPolygon(attrs));
+      else if (tool) out.push(readUnknown(tool, attrs, ''));
+    }
+    m = re.exec(svg);
+  }
+  return out;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// --canvas-state artboard overlap tagging.
+
+function loadArtboards(p) {
+  try {
+    const raw = JSON.parse(readFileSync(p, 'utf8'));
+    const arr = Array.isArray(raw)
+      ? raw
+      : Array.isArray(raw.artboards)
+        ? raw.artboards
+        : Array.isArray(raw.layout?.artboards)
+          ? raw.layout.artboards
+          : [];
+    return arr.filter(
+      (r) => r && typeof r.id === 'string' && [r.x, r.y, r.w, r.h].every((n) => Number.isFinite(n))
+    );
+  } catch {
+    return [];
+  }
+}
+
+function tagArtboard(ann, artboards) {
+  if (ann.x == null || ann.y == null) return null;
+  const ax2 = ann.x + (ann.w || 0);
+  const ay2 = ann.y + (ann.h || 0);
+  for (const r of artboards) {
+    const rx2 = r.x + r.w;
+    const ry2 = r.y + r.h;
+    if (ann.x <= rx2 && ax2 >= r.x && ann.y <= ry2 && ay2 >= r.y) return r.id;
+  }
+  return null;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Main
+
+function main() {
+  const args = parseArgv(process.argv.slice(2));
+  if (args.help) {
+    process.stdout.write(`${HELP}\n`);
+    return;
+  }
+  const relPath = args.positional[0];
+  if (!relPath) {
+    process.stderr.write(`read-annotations: missing <rel-path>.\n\n${HELP}\n`);
+    process.exit(2);
+  }
+
+  const repoRoot = args.root
+    ? resolve(args.root)
+    : process.env.CLAUDE_PROJECT_DIR
+      ? resolve(process.env.CLAUDE_PROJECT_DIR)
+      : process.cwd();
+
+  const { designRel, designRoot } = resolveDesignRoot(repoRoot);
+  const slug = fileSlug(relPath, designRel);
+  const svgPath = join(designRoot, `${slug}.annotations.svg`);
+
+  let svg = '';
+  if (existsSync(svgPath)) {
+    try {
+      svg = readFileSync(svgPath, 'utf8');
+    } catch {
+      svg = '';
+    }
+  }
+
+  let annotations = parseAnnotations(svg);
+
+  if (args.canvasState) {
+    const csPath = isAbsolute(args.canvasState)
+      ? args.canvasState
+      : resolve(process.cwd(), args.canvasState);
+    const artboards = loadArtboards(csPath);
+    if (artboards.length) {
+      annotations = annotations.map((a) => ({ ...a, artboard: tagArtboard(a, artboards) }));
+    }
+  }
+
+  process.stdout.write(`${JSON.stringify(annotations)}\n`);
+}
+
+main();

package/apps/studio/bin/read-annotations.sh

@@ -0,0 +1,11 @@
+#!/usr/bin/env bash
+# read-annotations.sh — thin wrapper around read-annotations.mjs (the headless
+# SVG → JSON annotation reader). Reached via `maude design read-annotations`
+# (DDR-062), never a raw bin path. The reader is zero-dep Node, so we exec under
+# `node` (always present — maude itself runs on Node), not Bun.
+#
+# Usage:
+#   read-annotations.sh <rel-path> [--root <repo>] [--canvas-state <path>]
+#   (see read-annotations.mjs --help for the full contract)
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+exec node "$SCRIPT_DIR/read-annotations.mjs" "$@"

package/{plugins/design/dev-server → apps/studio}/bin/runtime-health.sh

@@ -61,7 +61,7 @@ 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)}"
+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"