@1agh/maude 0.28.1 → 0.30.0

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"

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

@@ -213,6 +213,55 @@ capture() {
   fi
 }
 
+# ---------- port-bounce recovery (P2.1 / DDR-094) ----------
+# The dev server can respawn on a DIFFERENT port (the prior port got taken, a
+# Tailscale/mDNS hiccup bounced it, a stale _server.json was cleared). A capture
+# launched against the OLD port then fails with ERR_CONNECTION_REFUSED. The
+# running server keeps _server.json current, so on any capture failure we re-read
+# the LIVE port and, if it changed, rewrite $URL and retry once.
+RELIVE_REPO="${ROOT:-${CLAUDE_PROJECT_DIR:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}}"
+RELIVE_STATE="$RELIVE_REPO/.design/_server.json"
+RELIVED=0
+
+read_state_port() {
+  [ -f "$RELIVE_STATE" ] || return 1
+  if command -v jq >/dev/null 2>&1; then
+    jq -r .port "$RELIVE_STATE" 2>/dev/null
+  else
+    sed -nE 's/.*"port"[[:space:]]*:[[:space:]]*([0-9]+).*/\1/p' "$RELIVE_STATE" 2>/dev/null | head -n1
+  fi
+}
+
+# Re-read the live port; if it differs from the one in $URL, rewrite $URL and
+# return 0 (a retry is warranted). Returns 1 when nothing changed (don't retry).
+# Only fires ONCE per run (RELIVED guard) so a genuinely-down server still fails.
+relive_url() {
+  [ "$RELIVED" -eq 0 ] || return 1
+  local cur new
+  cur=$(printf '%s' "$URL" | sed -nE 's#https?://[^:/]+:([0-9]+).*#\1#p')
+  new=$(read_state_port)
+  [ -n "$new" ] || return 1
+  if [ -n "$cur" ] && [ "$cur" != "$new" ]; then
+    URL=$(printf '%s' "$URL" | sed -E "s#(://[^:/]+:)[0-9]+#\1${new}#")
+    RELIVED=1
+    echo "→ dev-server bounced ports ($cur → $new); re-reading _server.json and retrying at $URL" >&2
+    return 0
+  fi
+  return 1
+}
+
+# capture(), but on failure re-read the live port and retry once if it bounced.
+capture_resilient() {
+  local css="$1"
+  local out="$2"
+  capture "$css" "$out" && return 0
+  if relive_url; then
+    navigate_once
+    capture "$css" "$out" && return 0
+  fi
+  return 1
+}
+
 # ---------- --all-screens loop ----------
 if [ $ALL_SCREENS -eq 1 ]; then
   mkdir -p "$OUT_DIR"
@@ -227,6 +276,17 @@ if [ $ALL_SCREENS -eq 1 ]; then
     # Strip surrounding quotes, then split on comma.
     IDS=$(printf '%s' "$raw" | sed 's/^"//; s/"$//' | tr ',' '\n')
   fi
+  # No screens enumerated may mean the page never loaded (port bounce) — try a
+  # live-port re-read + one re-navigate before giving up.
+  if [ -z "$IDS" ] && relive_url; then
+    navigate_once
+    if [ "$ENGINE" = "agent-browser" ]; then
+      raw=$(agent-browser eval \
+        "Array.from(document.querySelectorAll('[data-dc-screen],[data-dc-slot]')).map(e => e.getAttribute('data-dc-screen') || e.getAttribute('data-dc-slot')).filter(Boolean).join(',')" \
+        2>/dev/null)
+      IDS=$(printf '%s' "$raw" | sed 's/^"//; s/"$//' | tr ',' '\n')
+    fi
+  fi
   if [ -z "$IDS" ]; then
     echo "✗ no [data-dc-screen]/[data-dc-slot] elements found (or eval unavailable on this engine)" >&2
     exit 3
@@ -241,7 +301,7 @@ if [ $ALL_SCREENS -eq 1 ]; then
       agent-browser eval "document.querySelector('[data-dc-screen=\"$ID\"], [data-dc-slot=\"$ID\"]').scrollIntoView({block:'center'})" >/dev/null 2>&1
       sleep 0.6
     fi
-    if capture "[data-dc-screen=\"$ID\"], [data-dc-slot=\"$ID\"]" "$OUT_FILE"; then
+    if capture_resilient "[data-dc-screen=\"$ID\"], [data-dc-slot=\"$ID\"]" "$OUT_FILE"; then
       echo "$OUT_FILE"
     else
       echo "✗ failed: $ID" >&2
@@ -254,7 +314,7 @@ fi
 
 # ---------- single-shot ----------
 navigate_once
-if capture "$CSS_SEL" "$OUT"; then
+if capture_resilient "$CSS_SEL" "$OUT"; then
   echo "$OUT"
   exit 0
 fi

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

@@ -55,7 +55,12 @@ fi
 #     `bash server-up.sh` falls back to the postinstall side-channel.
 #   bun + server.ts → dev tree / fallback (DDR-020 made bun authoritative for source).
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
-PLUGIN_ROOT="${CLAUDE_PLUGIN_ROOT:-$(cd "$SCRIPT_DIR/../.." && pwd)}"
+# PLUGIN_ROOT is a 2-levels-under-pkgRoot anchor: plugins/design when `maude
+# design <verb>` sets CLAUDE_PLUGIN_ROOT, else apps/studio ($SCRIPT_DIR/.. — the
+# studio root, also 2-deep) for a direct `bash server-up.sh`. Both keep
+# `$PLUGIN_ROOT/../../cli` = <pkgRoot>/cli. The dev-server tree itself is always
+# $SCRIPT_DIR/.. (apps/studio) — DDR-095 moved it out of plugins/design.
+PLUGIN_ROOT="${CLAUDE_PLUGIN_ROOT:-$(cd "$SCRIPT_DIR/.." && pwd)}"
 SERVER_TS="$PLUGIN_ROOT/dev-server/server.ts"
 SERVER_MJS="$PLUGIN_ROOT/dev-server/server.mjs"
 if [ ! -f "$SERVER_TS" ]; then SERVER_TS="$SCRIPT_DIR/../server.ts"; fi
@@ -66,7 +71,8 @@ if [ ! -f "$SERVER_MJS" ]; then SERVER_MJS="$SCRIPT_DIR/../server.mjs"; fi
 # `bash server-up.sh` on a production install). MAUDE_FORCE_SOURCE=1 forces source.
 SERVER_BIN="${MAUDE_DEV_SERVER_BIN:-}"
 if [ -z "$SERVER_BIN" ] && [ "${MAUDE_FORCE_SOURCE:-0}" != "1" ]; then
-  # PLUGIN_ROOT=<pkgRoot>/plugins/design, so the side-channel is ../../cli.
+  # PLUGIN_ROOT is 2-deep under pkgRoot (plugins/design or apps/studio), so the
+  # side-channel is ../../cli either way.
   # `head -n1` (parity with the Node readers' `.trim()`) tolerates a trailing newline.
   SC="$PLUGIN_ROOT/../../cli/.platform-binary-path"
   if [ -f "$SC" ]; then
@@ -154,7 +160,7 @@ fi
 # Step 1.5 — dependency preflight (source `bun server.ts` path ONLY; runs on cold
 # start). The compiled binary embeds its deps, so this is skipped when RUNTIME=binary
 # — it only guards the source fallback. The dev-server's runtime deps live in a
-# NESTED package.json (plugins/design/dev-server/) that a global `@1agh/maude` npm
+# NESTED package.json (apps/studio/) that a global `@1agh/maude` npm
 # install or a fresh `git worktree` does NOT populate; a missing `yjs` (imported at
 # boot by sync/index.ts) crashes `bun server.ts` AFTER spawn → without this guard we
 # poll the full ${TIMEOUT}s and report a generic "start timeout", burying the cause

package/apps/studio/bin/to-lottie-verify.html

@@ -0,0 +1,68 @@
+<!doctype html>
+<!-- to-lottie-verify.html — self-verify harness for `maude design to-lottie --verify`.
+     Renders ANY Lottie JSON through the REAL lottie-web runtime (NOT cairo — cairo
+     can't render masks; lottie-web must — DDR-094 rule 5). Generalized from the POC
+     verify.html: the Lottie source + the seek frame are query params.
+
+     Serve this dir (file:// blocks fetch):  python3 -m http.server 8200
+     Usage:  to-lottie-verify.html?src=<file.json>&f=<frame>   (omit ?f to autoplay)
+             &bg=<css color>  — backdrop (default dark)  ·  &w=&h= — stage size px -->
+<html>
+  <head>
+    <meta charset="utf8" />
+    <script src="https://cdnjs.cloudflare.com/ajax/libs/bodymovin/5.12.2/lottie.min.js"></script>
+    <style>
+      html,
+      body {
+        margin: 0;
+      }
+      #stage {
+        margin: 20px auto;
+      }
+    </style>
+  </head>
+  <body>
+    <div id="stage"></div>
+    <script>
+      const p = new URLSearchParams(location.search);
+      const src = p.get('src');
+      const f = p.get('f');
+      const bg = p.get('bg') || '#0a0a14';
+      const w = p.get('w') || '400';
+      const h = p.get('h') || '400';
+      document.body.style.background = bg;
+      const stage = document.getElementById('stage');
+      stage.style.width = `${w}px`;
+      stage.style.height = `${h}px`;
+
+      if (!src) {
+        document.title = 'error-no-src';
+      } else {
+        fetch(`./${src}`)
+          .then((r) => {
+            if (!r.ok) throw new Error(`fetch ${src} → ${r.status}`);
+            return r.json();
+          })
+          .then((data) => {
+            const anim = lottie.loadAnimation({
+              container: stage,
+              renderer: 'svg',
+              loop: true,
+              autoplay: f === null,
+              animationData: data,
+            });
+            anim.addEventListener('DOMLoaded', () => {
+              if (f !== null) anim.goToAndStop(parseInt(f, 10), true);
+              document.title = `ready${f !== null ? `-${f}` : ''}`;
+            });
+            anim.addEventListener('error', () => {
+              document.title = 'error-render';
+            });
+          })
+          .catch((e) => {
+            document.title = `error-${String(e.message || e).slice(0, 40)}`;
+          });
+      }
+    </script>
+  </body>
+</html>

package/apps/studio/bin/to-lottie.sh

@@ -0,0 +1,128 @@
+#!/usr/bin/env bash
+# to-lottie.sh — emit ONE Lottie from CODE (the maude motion handoff, DDR-094).
+#
+# This is the production-delivery counterpart to draw-build.sh: where draw-build
+# runs an agent-authored *engine* script to emit static SVG/JSX, to-lottie runs an
+# agent-authored *python-lottie generator* to emit ONE `.lottie`/`.json` that
+# renders 1:1 on web (lottie-web / dotlottie-react) AND mobile
+# (lottie-react-native) — same renderer family, 1:1 by construction. It is an
+# EMITTER from the keyframe data, NOT a converter of rendered SVG/SMIL (no reliable
+# one exists — DDR-094 research). The generator encodes the 8 conversion rules; see
+# `plugins/design/commands/to-lottie.md` + `_draw-motion-rules.md`.
+#
+# Reached via `maude design to-lottie` (DDR-062), never a raw bin path.
+#
+# Usage:
+#   to-lottie.sh --script <gen.py> --out <mark.json>
+#                [--verify] [--frames "0,33,66"] [--root <repo>] [--timeout 12]
+#
+# The generator (gen.py) builds the Lottie via python-lottie and writes it to the
+# path in $MAUDE_LOTTIE_OUT (= --out). python-lottie owns format correctness
+# (beziers, keyframes, gradients, masks, parenting); the agent encodes the
+# conversion rules (per-segment easing incl. overshoot, arc parsing via
+# parse_svg_file, layers[0]=top + reverse, masks, baked sub-loops, coord offset,
+# gradient opacity stops).
+#
+# --verify renders frames through HEADLESS lottie-web (cairo can't render masks —
+# lottie-web must) using the shipped harness + the screenshot helper, so you can
+# read the PNGs and compare to the web reference.
+#
+# Stdout (last line): the output .json path (capturable in $(...)).
+# Exit: 0 ok / 1 missing input or runtime / 2 bad args / 3 generate failed
+#       / 4 verify render failed.
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+GEN=""
+OUT=""
+VERIFY=0
+FRAMES="0,33,66"
+REPO=""
+TIMEOUT=12
+
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --script)  GEN="$2"; shift 2 ;;
+    --out)     OUT="$2"; shift 2 ;;
+    --verify)  VERIFY=1; shift ;;
+    --frames)  FRAMES="$2"; shift 2 ;;
+    --root)    REPO="$2"; shift 2 ;;
+    --timeout) TIMEOUT="$2"; shift 2 ;;
+    --help|-h) sed -n '2,33p' "$0" | sed 's/^# \?//'; exit 0 ;;
+    *) echo "to-lottie.sh: unknown arg '$1' (try --help)" >&2; exit 2 ;;
+  esac
+done
+
+[ -n "$GEN" ] || { echo "to-lottie.sh: --script <gen.py> required" >&2; exit 2; }
+[ -n "$OUT" ] || { echo "to-lottie.sh: --out <mark.json> required" >&2; exit 2; }
+[ -f "$GEN" ] || { echo "to-lottie.sh: generator not found: $GEN" >&2; exit 1; }
+command -v python3 >/dev/null 2>&1 || { echo "to-lottie.sh: python3 is required." >&2; exit 1; }
+
+# ---------- python-lottie venv (cached, idempotent) ----------
+VENV="${MAUDE_LOTTIE_VENV:-${XDG_CACHE_HOME:-$HOME/.cache}/maude/lottie-venv}"
+PY="$VENV/bin/python"
+if [ ! -x "$PY" ]; then
+  echo "→ bootstrapping python-lottie venv at $VENV (one-off) …" >&2
+  python3 -m venv "$VENV" || { echo "to-lottie.sh: venv create failed" >&2; exit 1; }
+  "$VENV/bin/pip" install --quiet --disable-pip-version-check lottie cairosvg pillow \
+    || { echo "to-lottie.sh: pip install lottie failed (needs network on first run)" >&2; exit 1; }
+fi
+# Sanity: the `lottie` module must import.
+"$PY" -c 'import lottie' 2>/dev/null || {
+  echo "→ (re)installing python-lottie into $VENV …" >&2
+  "$VENV/bin/pip" install --quiet --disable-pip-version-check lottie cairosvg pillow \
+    || { echo "to-lottie.sh: python-lottie unavailable" >&2; exit 1; }
+}
+
+# ---------- generate ----------
+mkdir -p "$(dirname "$OUT")"
+echo "→ generating Lottie: $GEN → $OUT" >&2
+MAUDE_LOTTIE_OUT="$OUT" "$PY" "$GEN" >&2
+GRC=$?
+if [ "$GRC" -ne 0 ] || [ ! -s "$OUT" ]; then
+  echo "to-lottie.sh: generator failed (rc=$GRC) or wrote no output to $OUT" >&2
+  exit 3
+fi
+# Validity gate: the output must be parseable JSON with the Lottie shape keys.
+"$PY" - "$OUT" <<'PYEOF' >&2 || { echo "to-lottie.sh: output is not a valid Lottie JSON" >&2; exit 3; }
+import json, sys
+d = json.load(open(sys.argv[1]))
+assert isinstance(d, dict) and 'layers' in d and 'op' in d, 'missing Lottie keys (layers/op)'
+print(f"  ✓ valid Lottie: {len(d.get('layers', []))} layers, {d.get('op')} frames @ {d.get('fr')}fps")
+PYEOF
+
+# ---------- self-verify through headless lottie-web ----------
+if [ "$VERIFY" -eq 1 ]; then
+  HARNESS="$SCRIPT_DIR/to-lottie-verify.html"
+  [ -f "$HARNESS" ] || { echo "to-lottie.sh: verify harness missing at $HARNESS — reinstall maude." >&2; exit 1; }
+  OUT_DIR_ABS="$(cd "$(dirname "$OUT")" && pwd)"
+  OUT_BASE="$(basename "$OUT")"
+  cp "$HARNESS" "$OUT_DIR_ABS/_to-lottie-verify.html"
+  FRAMES_DIR="$OUT_DIR_ABS/_verify-frames"
+  mkdir -p "$FRAMES_DIR"
+
+  # Serve the dir (file:// blocks fetch of the JSON). Pick a free-ish port.
+  PORT=$(( ( RANDOM % 2000 ) + 8200 ))
+  ( cd "$OUT_DIR_ABS" && "$PY" -m http.server "$PORT" >/dev/null 2>&1 ) &
+  SRV_PID=$!
+  trap 'kill "$SRV_PID" 2>/dev/null; rm -f "$OUT_DIR_ABS/_to-lottie-verify.html"' EXIT
+  sleep 1
+
+  FAIL=0
+  IFS=',' read -r -a FRAME_ARR <<< "$FRAMES"
+  for F in "${FRAME_ARR[@]}"; do
+    F_TRIM="$(printf '%s' "$F" | tr -d '[:space:]')"
+    URL="http://localhost:$PORT/_to-lottie-verify.html?src=$OUT_BASE&f=$F_TRIM"
+    PNG="$FRAMES_DIR/frame-$F_TRIM.png"
+    echo "→ verify frame $F_TRIM ($URL)" >&2
+    bash "$SCRIPT_DIR/screenshot.sh" --url "$URL" --full --out "$PNG" --timeout "$TIMEOUT" >&2 \
+      || { echo "✗ verify frame $F_TRIM failed" >&2; FAIL=$((FAIL + 1)); }
+  done
+  if [ "$FAIL" -gt 0 ]; then
+    echo "to-lottie.sh: $FAIL verify frame(s) failed to render" >&2
+    exit 4
+  fi
+  echo "→ verify frames in $FRAMES_DIR — READ them and compare to the web reference (masks render on lottie-web, NOT cairo)" >&2
+fi
+
+# Last stdout line = the output path, for $(maude design to-lottie ...) capture.
+printf '%s\n' "$OUT"

package/{plugins/design/dev-server → 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';
@@ -66,8 +66,8 @@ function ensureDist() {
 }
 
 async function readPluginVersion(): Promise<{ version: string }> {
-  // plugins/design/dev-server/ → plugins/design/.claude-plugin/plugin.json
-  const manifest = join(ROOT, '..', '.claude-plugin', 'plugin.json');
+  // apps/studio/ → ../../plugins/design/.claude-plugin/plugin.json (DDR-095)
+  const manifest = join(ROOT, '..', '..', 'plugins', 'design', '.claude-plugin', 'plugin.json');
   try {
     const parsed = JSON.parse(await Bun.file(manifest).text()) as { version?: unknown };
     if (typeof parsed.version === 'string') return { version: parsed.version };
@@ -257,7 +257,9 @@ async function ensureBindingForTarget(oxcSlug: string): Promise<void> {
   let oxcVersion = '0.131.0';
   const candidates = [
     join(ROOT, 'node_modules', 'oxc-parser', 'package.json'),
-    join(ROOT, '..', '..', '..', 'node_modules', 'oxc-parser', 'package.json'),
+    // apps/studio → ../../ = repo root → node_modules (DDR-095: was ../../../ at
+    // the old plugins/design/dev-server depth).
+    join(ROOT, '..', '..', 'node_modules', 'oxc-parser', 'package.json'),
   ];
   for (const c of candidates) {
     if (existsSync(c)) {

package/{plugins/design/dev-server → apps/studio}/canvas-arrowheads.ts

@@ -1,6 +1,6 @@
 /**
  * @file       canvas-arrowheads.ts — Phase 24 arrow shaft + head geometry
- * @scope      plugins/design/dev-server/canvas-arrowheads.ts
+ * @scope      apps/studio/canvas-arrowheads.ts
  * @purpose    Single source of truth for arrow rendering. An ArrowStroke is
  *             reduced to an ordered list of `SvgPrimitive`s (the shaft, then
  *             the start head, then the end head). The serializer formats each
@@ -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/{plugins/design/dev-server → apps/studio}/canvas-comment-mount.tsx

@@ -1,6 +1,6 @@
 /**
  * @file       canvas-comment-mount.tsx — shell-owned comment layer + mountCanvas
- * @scope      plugins/design/dev-server/canvas-comment-mount.tsx
+ * @scope      apps/studio/canvas-comment-mount.tsx
  * @purpose    The canvas mount harness (`_shell.html`) calls `mountCanvas`
  *             instead of rendering the canvas default-export raw. mountCanvas
  *             wraps ANY default export — a `DesignCanvas` UI canvas OR a bare

package/apps/studio/canvas-create.ts

@@ -0,0 +1,104 @@
+// canvas-create.ts — Phase 22 UI add-on. Pure helpers behind POST /_api/canvas
+// (api.ts createCanvas), which lets the browser file-tree create a blank brief
+// board directly — no slash command, no model cost. Generation (ingesting a
+// board's notes into artboards) stays with Claude via `/design:new`; this only
+// stamps out the empty annotation surface.
+//
+// SINGLE SOURCE — the board envelope is the SAME `brief-board.tsx.template`
+// `/design:new --blank` substitutes. We text-import it so Bun.build inlines the
+// content into the `bun --compile` standalone binary (verified: works at dev
+// runtime AND embeds at build time), sidestepping DDR-045 — no runtime disk read
+// of a file that lives outside `apps/studio/`. The template stayed under the
+// design plugin (plugins/design/templates) when the studio moved (DDR-095).
+
+import briefBoardTemplate from '../../plugins/design/templates/brief-board.tsx.template' with {
+  type: 'text',
+};
+
+export const BRIEF_BOARD_TEMPLATE: string = briefBoardTemplate;
+
+/**
+ * The ONE security boundary for the create endpoint. A canvas name is the only
+ * user-controlled value, and it is interpolated into BOTH a real nested
+ * filesystem path (`<group>/<name>.tsx`) AND the generated `.tsx` (JSX text) +
+ * `.meta.json` (JSON string). This strict allowlist does triple duty:
+ *   • path safety   — no `/`, `\`, `..`, or leading dot ⇒ no traversal;
+ *   • template safety — no `<`, `>`, `{`, `}` ⇒ can't break out of JSX text;
+ *   • JSON safety    — no `"` or `\` ⇒ can't break out of a meta string.
+ * Unicode letters/numbers are allowed (so "Onboarding Brief" / accented names
+ * work); the first char must be a letter/number (excludes leading space/dash/dot).
+ */
+const NAME_RE = /^[\p{L}\p{N}][\p{L}\p{N} _-]{0,59}$/u;
+
+export interface NameValidation {
+  ok: boolean;
+  name?: string;
+  componentName?: string;
+  error?: string;
+}
+
+export function validateCanvasName(raw: unknown): NameValidation {
+  if (typeof raw !== 'string') return { ok: false, error: 'name must be a string' };
+  // NFC-normalize so a decomposed (NFD) name and its composed sibling can't hash
+  // to two JS strings that collide to ONE on-disk path on a normalizing filesystem
+  // (APFS/HFS+) — which would let the 409 existence guard be bypassed and an
+  // existing board silently overwritten (Phase 22 security review, low). Collapse
+  // runs of SPACES (the one allowed whitespace) to a single space so the JS slug
+  // (`/\s+/→_`) and slug.sh (`tr ' ' '_'`) can't diverge on a double-spaced name
+  // (review #4); tabs/newlines stay un-collapsed and are rejected by NAME_RE.
+  const name = raw.normalize('NFC').trim().replace(/ +/g, ' ');
+  if (!name) return { ok: false, error: 'name is required' };
+  if (name.length > 60) return { ok: false, error: 'name must be 60 characters or fewer' };
+  if (!NAME_RE.test(name)) {
+    return {
+      ok: false,
+      error: 'name may contain only letters, numbers, spaces, hyphens and underscores',
+    };
+  }
+  // Defense in depth — the regex already forbids these, but assert no path bits
+  // survive (a regex edit must never silently re-open traversal).
+  if (name.includes('..') || name.includes('/') || name.includes('\\') || name.startsWith('.')) {
+    return { ok: false, error: 'name may not contain path separators or leading dots' };
+  }
+  return { ok: true, name, componentName: componentNameFrom(name) };
+}
+
+/** PascalCase a name into a valid JS identifier for the component default export.
+ *  Non-identifier characters split words; an empty / digit-leading result gets a
+ *  `Board` prefix so the emitted `export default function <id>()` always parses. */
+export function componentNameFrom(name: string): string {
+  // Split on NON-(letter|number) so Unicode letters survive (the validator
+  // accepts them) — `Přihlášení` → `Přihlášení`, a valid JS identifier (verified
+  // it parses), not the ASCII-mangled `PIhlEn` (review #1). Empty (all-symbol) →
+  // `BriefBoard`; a digit-leading result (incl. Unicode digits) → `Board…` so the
+  // emitted `export default function <id>()` always parses.
+  const pascal = name
+    .split(/[^\p{L}\p{N}]+/u)
+    .filter(Boolean)
+    .map((w) => w[0].toUpperCase() + w.slice(1))
+    .join('');
+  if (!pascal) return 'BriefBoard';
+  if (/^\p{Nd}/u.test(pascal)) return `Board${pascal}`;
+  return pascal;
+}
+
+export interface BriefBoardOpts {
+  name: string;
+  componentName: string;
+  dsName: string;
+  platform: string;
+  seedHint: string;
+  historyDir: string;
+}
+
+/** Substitute the brief-board template placeholders. Safe because `name`
+ *  (the only user value reaching here) is validated by `validateCanvasName`,
+ *  and every other field is server-derived (config / fixed strings). */
+export function renderBriefBoard(opts: BriefBoardOpts): string {
+  return BRIEF_BOARD_TEMPLATE.replaceAll('{{NAME}}', opts.name)
+    .replaceAll('{{COMPONENT_NAME}}', opts.componentName)
+    .replaceAll('{{DS_NAME}}', opts.dsName)
+    .replaceAll('{{PLATFORM}}', opts.platform)
+    .replaceAll('{{SEED_HINT}}', opts.seedHint)
+    .replaceAll('{{HISTORY_DIR}}', opts.historyDir);
+}