@1agh/maude 0.29.0 → 0.31.0

package/apps/studio/bin/annotate.sh

@@ -0,0 +1,17 @@
+#!/usr/bin/env bash
+# annotate.sh — thin wrapper around annotate.mjs (the AI annotation WRITE
+# verb). Runs under Bun, not node: the verb imports the CANONICAL TypeScript
+# annotation model (annotations-model.ts — serializer + sanitizer) so it can
+# never emit a shape the canvas wouldn't, and node can't import TS.
+# Reached via `maude design annotate` (DDR-062), never a raw bin path.
+#
+# Usage:
+#   annotate.sh <rel-path> [--ops <file|->] [--flow <file|->] [--near <id>]
+#               [--canvas-state <path>] [--root <repo>] [--dry-run]
+#   (see annotate.mjs --help for the full contract)
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+if ! command -v bun >/dev/null 2>&1; then
+  echo "annotate: bun is required (the verb imports the canonical TS annotation model). Install: https://bun.sh" >&2
+  exit 1
+fi
+exec bun "$SCRIPT_DIR/annotate.mjs" "$@"

package/apps/studio/bin/chat-open.sh

@@ -0,0 +1,44 @@
+#!/usr/bin/env bash
+# chat-open.sh — Phase 31 (DDR-123). Backs `/design:chat` (via `maude design
+# chat-open`): asks the running dev-server to surface the native ACP chat
+# sidepanel by POSTing /_api/acp/focus. The server emits a bus event the shell
+# (app.jsx, native-only) turns into "open the Assistant panel".
+#
+# Reads:  $DESIGN_ROOT/_server.json  (port the running server wrote)
+# Usage:  chat-open.sh [--root <repo>]
+# Exits:  0 on success, 1 if no live server / focus request failed.
+set -euo pipefail
+
+REPO="${CLAUDE_PROJECT_DIR:-$(pwd)}"
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --root) REPO="$2"; shift 2 ;;
+    *) shift ;;
+  esac
+done
+
+DESIGN_ROOT="$REPO/.design"
+STATE="$DESIGN_ROOT/_server.json"
+
+if [ ! -f "$STATE" ]; then
+  echo "chat-open: no running dev server ($STATE missing). Open Maude first." >&2
+  exit 1
+fi
+
+if command -v jq >/dev/null 2>&1; then
+  PORT="$(jq -r '.port // empty' "$STATE" 2>/dev/null)"
+else
+  PORT="$(sed -nE 's/.*"port"[[:space:]]*:[[:space:]]*([0-9]+).*/\1/p' "$STATE" 2>/dev/null | head -n1)"
+fi
+
+if [ -z "${PORT:-}" ]; then
+  echo "chat-open: could not read the server port from $STATE." >&2
+  exit 1
+fi
+
+if curl -fsS -X POST "http://127.0.0.1:${PORT}/_api/acp/focus" >/dev/null 2>&1; then
+  echo "→ opened the Assistant panel in Maude (port ${PORT})."
+else
+  echo "chat-open: focus request to the dev server failed (port ${PORT})." >&2
+  exit 1
+fi

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

@@ -31,18 +31,21 @@
 
 import { existsSync, readFileSync } from 'node:fs';
 import { isAbsolute, join, resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
 
 // ─────────────────────────────────────────────────────────────────────────────
 // Argv
 
 function parseArgv(argv) {
-  const out = { positional: [], root: null, canvasState: null, help: false };
+  const out = { positional: [], root: null, canvasState: null, help: false, graph: 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 === '--graph') {
+      out.graph = true;
     } else if (a === '--root') {
       i += 1;
       out.root = argv[i];
@@ -69,10 +72,20 @@ 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.
+                      each annotation is tagged with the artboard it overlaps,
+                      plus artboard-relative coords (rel) and a W3C-style
+                      target block { source, selector, geometry }.
+  --graph             Emit { annotations, graph } instead of the bare array:
+                      graph.edges = bound arrows (from/to host ids), graph.nodes
+                      = the strokes those arrows connect (with labels) — a
+                      bound flow diagram reads back as a graph.
   --json              No-op (JSON is the only output form).
 
-Emits a JSON array to stdout. A missing annotation file emits [] (exit 0).`;
+FigJam v3 additive fields per annotation: z (render order), groupIds (deepest →
+shallowest), author ("ai" for annotate-verb strokes), and from/to host ids on
+bound arrows.
+
+Emits JSON to stdout. A missing annotation file emits [] (exit 0).`;
 
 // ─────────────────────────────────────────────────────────────────────────────
 // Path + slug resolution — mirror the dev-server (api.ts fileSlug, context.ts
@@ -172,6 +185,22 @@ function readText(attrs, inner) {
   return o;
 }
 
+// FigJam v3 — section container: geometry off the inner <rect>, label off
+// data-label (the inner <text> is presentational chrome).
+function readSection(attrs, inner) {
+  const rectAttrs = inner.match(/<rect\b([^>]*?)\/?>/)?.[1] ?? '';
+  return {
+    tool: 'section',
+    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(attr(attrs, 'data-label') || ''),
+    color: attr(attrs, 'fill') || null,
+  };
+}
+
 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.)
@@ -189,6 +218,20 @@ function readSticky(attrs, inner) {
   };
 }
 
+// FigJam v3 — a bound endpoint persists as `data-(start|end)-bind="<hostId>
+// <nx> <ny>"`. Malformed / out-of-range values are rejected (mirror of the
+// canonical parser's clamp).
+function parseBind(raw) {
+  if (!raw) return null;
+  const parts = String(raw).trim().split(/\s+/);
+  if (parts.length !== 3) return null;
+  const nx = Number.parseFloat(parts[1]);
+  const ny = Number.parseFloat(parts[2]);
+  if (!parts[0] || !Number.isFinite(nx) || !Number.isFinite(ny)) return null;
+  if (nx < 0 || nx > 1 || ny < 0 || ny > 1) return null;
+  return { hostId: parts[0], nx, ny };
+}
+
 function readArrow(attrs, inner) {
   const id = attr(attrs, 'data-id') || '';
   const color = attr(attrs, 'stroke') || null;
@@ -325,34 +368,92 @@ function readUnknown(tool, attrs, inner) {
 // 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.)
+// FigJam v3 — shared root attrs every tool can carry: group membership,
+// provenance, render order (z = document position). Applied uniformly after
+// the per-tool extraction; arrows additionally surface bound endpoints as
+// `from`/`to` host ids so a bound diagram reads back as a GRAPH.
+function withShared(o, attrs, z) {
+  o.z = z;
+  const g = attr(attrs, 'data-group-ids');
+  if (g) {
+    const ids = g.split(/\s+/).filter(Boolean);
+    if (ids.length) o.groupIds = ids;
+  }
+  if (attr(attrs, 'data-author') === 'ai') o.author = 'ai';
+  if (o.tool === 'arrow') {
+    const sb = parseBind(attr(attrs, 'data-start-bind'));
+    if (sb) o.from = sb.hostId;
+    const eb = parseBind(attr(attrs, 'data-end-bind'));
+    if (eb) o.to = eb.hostId;
+  }
+  return o;
+}
+
 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;
+  const re =
+    /<(g|text)\b([^>]*)>([\s\S]*?)<\/\1>|<(path|rect|ellipse|polygon|image)\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));
+      if (tool === 'sticky') out.push(withShared(readSticky(attrs, inner), attrs, out.length));
+      else if (tool === 'section')
+        out.push(withShared(readSection(attrs, inner), attrs, out.length));
+      else if (tool === 'arrow') out.push(withShared(readArrow(attrs, inner), attrs, out.length));
+      else if (tool === 'text') out.push(withShared(readText(attrs, inner), attrs, out.length));
+      else if (tool) out.push(withShared(readUnknown(tool, attrs, inner), attrs, out.length));
     } 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, ''));
+      if (tool === 'pen') out.push(withShared(readPen(attrs), attrs, out.length));
+      else if (tool === 'rect') out.push(withShared(readRect(attrs), attrs, out.length));
+      else if (tool === 'ellipse') out.push(withShared(readEllipse(attrs), attrs, out.length));
+      else if (tool === 'polygon') out.push(withShared(readPolygon(attrs), attrs, out.length));
+      else if (tool) out.push(withShared(readUnknown(tool, attrs, ''), attrs, out.length));
     }
     m = re.exec(svg);
   }
   return out;
 }
 
+// FigJam v3 — derive the node/edge view of a bound diagram. Edges are arrows
+// with at least one bound end; nodes are the strokes those arrows reference,
+// labelled by their own text or by anchored text targeting them.
+function buildGraph(annotations) {
+  const edges = [];
+  for (const a of annotations) {
+    if (a.tool === 'arrow' && (a.from || a.to)) {
+      edges.push({ id: a.id, from: a.from ?? null, to: a.to ?? null });
+    }
+  }
+  const refIds = new Set();
+  for (const e of edges) {
+    if (e.from) refIds.add(e.from);
+    if (e.to) refIds.add(e.to);
+  }
+  const labelByAnchor = new Map();
+  for (const a of annotations) {
+    if (a.tool === 'text' && a.anchorId && a.text) labelByAnchor.set(a.anchorId, a.text);
+  }
+  const nodes = annotations
+    .filter((a) => refIds.has(a.id))
+    .map((a) => ({
+      id: a.id,
+      tool: a.tool,
+      label: a.text || labelByAnchor.get(a.id) || null,
+      x: a.x,
+      y: a.y,
+      w: a.w,
+      h: a.h,
+      artboard: a.artboard ?? null,
+    }));
+  return { nodes, edges };
+}
+
 // ─────────────────────────────────────────────────────────────────────────────
 // --canvas-state artboard overlap tagging.
 
@@ -374,18 +475,43 @@ function loadArtboards(p) {
   }
 }
 
-function tagArtboard(ann, artboards) {
+function findArtboard(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;
+    if (ann.x <= rx2 && ax2 >= r.x && ann.y <= ry2 && ay2 >= r.y) return r;
   }
   return null;
 }
 
+function tagArtboard(ann, artboards) {
+  return findArtboard(ann, artboards)?.id ?? null;
+}
+
+/**
+ * FigJam v3 — anchor an annotation to its artboard for AI consumers: the
+ * overlapping artboard id, artboard-RELATIVE coords (what survives an artboard
+ * move), and a W3C Web-Annotation-style target (anchor by stable id first,
+ * geometry as the refinement/fallback).
+ */
+function anchorToArtboard(ann, artboards) {
+  const r = findArtboard(ann, artboards);
+  if (!r) return { ...ann, artboard: null };
+  return {
+    ...ann,
+    artboard: r.id,
+    rel: ann.x != null ? { x: ann.x - r.x, y: ann.y - r.y } : null,
+    target: {
+      source: r.id,
+      selector: { type: 'AnnotationIdSelector', value: ann.id },
+      geometry: ann.x != null ? { x: ann.x, y: ann.y, w: ann.w ?? 0, h: ann.h ?? 0 } : null,
+    },
+  };
+}
+
 // ─────────────────────────────────────────────────────────────────────────────
 // Main
 
@@ -428,11 +554,20 @@ function main() {
       : resolve(process.cwd(), args.canvasState);
     const artboards = loadArtboards(csPath);
     if (artboards.length) {
-      annotations = annotations.map((a) => ({ ...a, artboard: tagArtboard(a, artboards) }));
+      annotations = annotations.map((a) => anchorToArtboard(a, artboards));
     }
   }
 
+  if (args.graph) {
+    process.stdout.write(`${JSON.stringify({ annotations, graph: buildGraph(annotations) })}\n`);
+    return;
+  }
   process.stdout.write(`${JSON.stringify(annotations)}\n`);
 }
 
-main();
+// FigJam v3 — the parsing core is importable (the `annotate` write verb reuses
+// it for host-geometry lookups); main() runs only when invoked as a script.
+export { buildGraph, fileSlug, loadArtboards, parseAnnotations, resolveDesignRoot, tagArtboard };
+
+const isMain = process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href;
+if (isMain) main();

package/apps/studio/build.ts

@@ -16,7 +16,7 @@
 // Per DDR-009 (Bun runtime authoritative) + DDR-012 (React 19 unified) + DDR-014 (Lightning CSS).
 
 import { existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync } from 'node:fs';
-import { dirname, join, relative, resolve } from 'node:path';
+import { dirname, join, relative } from 'node:path';
 import { fileURLToPath } from 'node:url';
 
 import { browserslistToTargets, bundle as lcssBundle } from 'lightningcss';

package/apps/studio/canvas-arrowheads.ts

@@ -59,6 +59,28 @@ export interface ArrowGeom {
   endHead?: ArrowHead;
   dashed?: boolean;
   lineType?: ArrowLineType;
+  /**
+   * FigJam v3 — magnetic binding anchors (normalized over the host bbox;
+   * `ArrowBind` is structurally assignable). A BOUND curved arrow exits its
+   * host perpendicular to the bound side (cubic with exit normals — the
+   * FigJam connector look) and takes the sleeker connector head; unbound
+   * arrows keep the legacy byte-identical geometry.
+   */
+  startBind?: { nx: number; ny: number };
+  endBind?: { nx: number; ny: number };
+}
+
+/**
+ * Exit direction OUT of a bound side — the normalized vector from the host's
+ * center toward the anchor magnet. A center anchor (0.5, 0.5) has no exit
+ * direction (null → the curve falls back to chord-based control points).
+ */
+function bindNormal(b: { nx: number; ny: number }): [number, number] | null {
+  const dx = b.nx - 0.5;
+  const dy = b.ny - 0.5;
+  const len = Math.hypot(dx, dy);
+  if (len < 0.05) return null;
+  return [dx / len, dy / len];
 }
 
 /**
@@ -73,10 +95,13 @@ export function arrowHeadPoints(
   y1: number,
   x2: number,
   y2: number,
-  width: number
+  width: number,
+  // FigJam v3 — optional head length override (sleeker connector heads on
+  // BOUND arrows). Default = the legacy byte-frozen formula.
+  lenOverride?: number
 ): string {
   const angle = Math.atan2(y2 - y1, x2 - x1);
-  const len = 12 + width * 2;
+  const len = lenOverride ?? 12 + width * 2;
   const wing = Math.PI / 7;
   const ax = x2 - Math.cos(angle - wing) * len;
   const ay = y2 - Math.sin(angle - wing) * len;
@@ -154,25 +179,39 @@ function headPrimitives(
   fromX: number,
   fromY: number,
   width: number,
-  color: string
+  color: string,
+  lenOverride?: number
 ): SvgPrimitive[] {
   switch (head) {
     case 'none':
       return [];
     case 'triangle':
-      // Legacy filled head — byte-identical to Phase 5.1.
+      // Legacy filled head — byte-identical to Phase 5.1 (unless a bound
+      // arrow passes the sleeker connector length).
       return [
-        { el: 'polyline', points: arrowHeadPoints(fromX, fromY, tipX, tipY, width), fill: color },
+        {
+          el: 'polyline',
+          points: arrowHeadPoints(fromX, fromY, tipX, tipY, width, lenOverride),
+          fill: color,
+        },
       ];
     case 'line':
       // Open chevron — same 3 points, unfilled (no implicit close).
       return [
-        { el: 'polyline', points: arrowHeadPoints(fromX, fromY, tipX, tipY, width), fill: 'none' },
+        {
+          el: 'polyline',
+          points: arrowHeadPoints(fromX, fromY, tipX, tipY, width, lenOverride),
+          fill: 'none',
+        },
       ];
     case 'triangle-outline':
       // Closed triangle outline — polygon auto-closes the third edge.
       return [
-        { el: 'polygon', points: arrowHeadPoints(fromX, fromY, tipX, tipY, width), fill: 'none' },
+        {
+          el: 'polygon',
+          points: arrowHeadPoints(fromX, fromY, tipX, tipY, width, lenOverride),
+          fill: 'none',
+        },
       ];
     case 'diamond':
       return [
@@ -199,6 +238,7 @@ export function arrowPrimitives(s: ArrowGeom): SvgPrimitive[] {
   const endHead = s.endHead ?? 'triangle';
   const dashed = s.dashed ?? false;
   const lineType = s.lineType ?? 'straight';
+  const bound = Boolean(s.startBind || s.endBind);
   const out: SvgPrimitive[] = [];
 
   // Default tangent sources (straight): each head points away from the far end.
@@ -207,6 +247,28 @@ export function arrowPrimitives(s: ArrowGeom): SvgPrimitive[] {
 
   if (lineType === 'straight') {
     out.push({ el: 'line', x1: s.x1, y1: s.y1, x2: s.x2, y2: s.y2, dash: dashed });
+  } else if (lineType === 'curved' && bound) {
+    // FigJam v3 — connector curve: a cubic whose control points extend along
+    // each bound side's EXIT NORMAL (perpendicular out of the side, then
+    // toward the target) — the smooth "leaves the box sideways" look. A free
+    // / center-anchored end falls back to a chord-aligned control point.
+    const dx = s.x2 - s.x1;
+    const dy = s.y2 - s.y1;
+    const chord = Math.hypot(dx, dy) || 1;
+    const reach = Math.min(160, Math.max(24, chord * 0.4));
+    const n1 = s.startBind ? bindNormal(s.startBind) : null;
+    const n2 = s.endBind ? bindNormal(s.endBind) : null;
+    const c1x = s.x1 + (n1 ? n1[0] : dx / chord) * reach;
+    const c1y = s.y1 + (n1 ? n1[1] : dy / chord) * reach;
+    const c2x = s.x2 + (n2 ? n2[0] : -dx / chord) * reach;
+    const c2y = s.y2 + (n2 ? n2[1] : -dy / chord) * reach;
+    out.push({
+      el: 'path',
+      d: `M${s.x1} ${s.y1} C${c1x} ${c1y} ${c2x} ${c2y} ${s.x2} ${s.y2}`,
+      dash: dashed,
+    });
+    startFrom = [c1x, c1y];
+    endFrom = [c2x, c2y];
   } else {
     const shaft = shaftPath(s.x1, s.y1, s.x2, s.y2, lineType);
     out.push({ el: 'path', d: shaft.d, dash: dashed });
@@ -214,7 +276,14 @@ export function arrowPrimitives(s: ArrowGeom): SvgPrimitive[] {
     endFrom = shaft.endFrom;
   }
 
-  out.push(...headPrimitives(startHead, s.x1, s.y1, startFrom[0], startFrom[1], s.width, s.color));
-  out.push(...headPrimitives(endHead, s.x2, s.y2, endFrom[0], endFrom[1], s.width, s.color));
+  // Bound arrows take the sleeker connector head; unbound keep the legacy
+  // byte-frozen proportions.
+  const headLen = bound ? 9 + s.width * 1.4 : undefined;
+  out.push(
+    ...headPrimitives(startHead, s.x1, s.y1, startFrom[0], startFrom[1], s.width, s.color, headLen)
+  );
+  out.push(
+    ...headPrimitives(endHead, s.x2, s.y2, endFrom[0], endFrom[1], s.width, s.color, headLen)
+  );
   return out;
 }

package/apps/studio/canvas-cursors.ts

@@ -171,6 +171,8 @@ export const TOOL_CURSORS: Record<Tool, string> = Object.freeze({
   hand: HAND,
   comment: COMMENT,
   pen: PEN,
+  // FigJam v3 — the section container draws like a shape (crosshair glyph).
+  section: CROSSHAIR,
   // Highlighter = Kenney `drawing_pencil` rot180; pen = `drawing_pen` rot180 —
   // distinct glyphs, both from the Kenney pack (user steer 2026-06-04).
   highlighter: HIGHLIGHTER,