@1agh/maude 0.23.0 → 0.25.0

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

@@ -4,12 +4,23 @@
 # per-canvas hooks in /design:edit step 7 / /design:new step 9 — typically
 # dev-server infra changes or bulk multi-canvas migrations. See DDR-021.
 #
+# Beyond "does it render", preview specimens are also gated on "does it render
+# STYLED" (DDR-068): a static import-graph lint (every specimen reaches
+# _layout.css — its single CSS entry, which @imports the tokens + _components.css
+# — and every shared preview/_*.css has >=1 importer) plus a runtime
+# computed-style check (the DS token contract `--bg-0` must resolve on the body,
+# else the canvas's import graph lost the token CSS and every var()-driven rule
+# is dead — the specimen mounts with content but renders unstyled).
+#
 # Usage:
 #   smoke.sh [--root <repo>]
 #            [--out-dir <dir>]
 #            [--include-system 0|1]   (default 1)
 #            [--timeout <secs>]       (default 8)
 #            [--engine auto|agent-browser|playwright]
+#            [--changed-only]         (default off — screenshot only canvases changed
+#                                      since the last smoke run; escalates to the full
+#                                      set when dev-server / canvas-lib / templates changed)
 #
 # Reads:
 #   $DESIGN_ROOT/_server.json   (must exist — caller runs server-up.sh first)
@@ -24,13 +35,14 @@
 # Stdout: one line per canvas, tab-separated:
 #   STATUS \t FILE \t SCREENSHOT \t DETAIL
 # Stderr: diagnostic / progress.
-# Exit:   0 = all green / 3 = at least one blank/error / 1 = missing deps / 2 = bad args.
+# Exit:   0 = all green / 3 = at least one blank/error/unstyled/lint-fail / 1 = missing deps / 2 = bad args.
 
 REPO=""
 OUT_DIR=""
 INCLUDE_SYSTEM=1
 TIMEOUT=8
 ENGINE="auto"
+CHANGED_ONLY=0
 
 while [ $# -gt 0 ]; do
   case "$1" in
@@ -39,8 +51,9 @@ while [ $# -gt 0 ]; do
     --include-system) INCLUDE_SYSTEM="$2"; shift 2 ;;
     --timeout)        TIMEOUT="$2"; shift 2 ;;
     --engine)         ENGINE="$2"; shift 2 ;;
+    --changed-only)   CHANGED_ONLY=1; shift ;;
     --help|-h)
-      sed -n '2,28p' "$0" | sed 's/^# \?//'
+      sed -n '2,30p' "$0" | sed 's/^# \?//'
       exit 0
       ;;
     *)
@@ -73,6 +86,10 @@ if [ -z "$OUT_DIR" ]; then
   OUT_DIR="$DESIGN_ROOT/_history/_smoke/$TS"
 fi
 mkdir -p "$OUT_DIR"
+# agent-browser ignores RELATIVE screenshot paths (writes to ~/.agent-browser/tmp
+# instead), which silently strands every PNG. Canonicalize to absolute so the
+# captured evidence actually lands in OUT_DIR. See DDR-021.
+OUT_DIR="$(cd "$OUT_DIR" && pwd)"
 
 # ---------- engine resolution ----------
 if [ "$ENGINE" = "auto" ]; then
@@ -107,6 +124,57 @@ COUNT=$(printf '%s' "$CANVASES" | grep -c .)
 [ "$COUNT" -gt 0 ] || { echo "smoke.sh: no canvases found (ui/*.tsx or system/*/preview/*.tsx)" >&2; exit 1; }
 echo "→ found $COUNT canvases" >&2
 
+# ---------- --changed-only incremental filter (Phase C / DDR-061) ----------
+# Default smoke screenshots every canvas. --changed-only narrows to the canvases
+# touched since the last recorded smoke run, UNLESS the diff touches an
+# "everything could break" shape (dev-server, canvas-lib, canvas templates) — then
+# it escalates back to the full set. Correctness > speed: no baseline, no git, or
+# an escalation trigger all fall back to the full set.
+MARKER="$DESIGN_ROOT/_history/_smoke/.last-smoke.json"
+if [ "$CHANGED_ONLY" = "1" ]; then
+  LAST_SHA=""
+  if [ -f "$MARKER" ] && command -v jq >/dev/null 2>&1; then
+    LAST_SHA=$(jq -r '.sha // empty' "$MARKER" 2>/dev/null)
+  fi
+  if ! command -v git >/dev/null 2>&1 || ! git -C "$REPO" rev-parse HEAD >/dev/null 2>&1; then
+    echo "→ --changed-only: no git in $REPO — running full set" >&2
+  elif [ -z "$LAST_SHA" ]; then
+    echo "→ --changed-only: no prior smoke baseline ($MARKER) — running full set" >&2
+  else
+    # All paths changed between the last smoke and the current working tree
+    # (committed + uncommitted), plus untracked canvases.
+    CHANGED=$(
+      { git -C "$REPO" diff --name-only "$LAST_SHA" -- 2>/dev/null
+        git -C "$REPO" ls-files --others --exclude-standard -- .design/ui .design/system 2>/dev/null
+      } | sort -u
+    )
+    if printf '%s\n' "$CHANGED" | grep -qE 'dev-server/|canvas-lib\.tsx|canvas[^/]*\.tsx\.template'; then
+      echo "→ --changed-only: dev-server / canvas-lib / template changed — escalating to FULL set" >&2
+    else
+      # Keep only canvases whose repo-relative path is in the changed set.
+      FILTERED=""
+      while IFS= read -r CANVAS; do
+        [ -z "$CANVAS" ] && continue
+        REL_REPO="${CANVAS#$REPO/}"
+        if printf '%s\n' "$CHANGED" | grep -qxF "$REL_REPO"; then
+          FILTERED="$FILTERED$CANVAS"$'\n'
+        fi
+      done <<< "$CANVASES"
+      CANVASES=$(printf '%s' "$FILTERED" | sed '/^$/d')
+      COUNT=$(printf '%s' "$CANVASES" | grep -c .)
+      if [ "$COUNT" -eq 0 ]; then
+        echo "→ --changed-only: no canvas .tsx changed since last smoke ($LAST_SHA) — nothing to screenshot" >&2
+        # Refresh the marker so the next run diffs from here, then exit clean.
+        mkdir -p "$(dirname "$MARKER")"
+        printf '{"sha":"%s","ts":"%s","mode":"changed-only-noop"}' \
+          "$(git -C "$REPO" rev-parse HEAD 2>/dev/null)" "$(date -u +%Y-%m-%dT%H:%M:%SZ)" > "$MARKER"
+        exit 0
+      fi
+      echo "→ --changed-only: $COUNT changed canvas(es) since $LAST_SHA" >&2
+    fi
+  fi
+fi
+
 # ---------- helpers ----------
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
 SLUG_HELPER="$SCRIPT_DIR/slug.sh"
@@ -116,6 +184,59 @@ urlencode_path() {
   printf '%s' "$1" | sed 's/ /%20/g'
 }
 
+# Static import-graph lint (DDR-068). Runs once before render. The dev-server
+# inlines ONLY the CSS a canvas's import graph produces (canvas-build.ts), so a
+# forgotten import is a silently unstyled specimen that still "has content" and
+# sails past the per-canvas render checks below. Asserts, per DS preview dir:
+#   (1) every specimen reaches `_layout.css` (direct `import`, or its own css
+#       `@import`s it) — _layout.css is the single CSS entry that pulls tokens
+#       (colors_and_type.css) + controls (_components.css);
+#   (2) every shared `preview/_*.css` has >=1 importer (no orphan partial — the
+#       class of bug where `.btn`/`.input` in _components.css loaded NOWHERE).
+# Appends violations to $MD; sets LINT_FAILED. Anchored to real `^import` lines
+# so a specimen that DISPLAYS a css filename in its content isn't a false match.
+LINT_FAILED=0
+lint_specimen_imports() {
+  local SQ Q preview tsx base css imp impfile reached n=0
+  SQ=$(printf '\047'); Q="[\"$SQ]"   # bracket class matching either quote style
+  for preview in "$DESIGN_ROOT"/system/*/preview; do
+    [ -d "$preview" ] || continue
+    # (1) every specimen reaches _layout.css
+    for tsx in "$preview"/*.tsx; do
+      [ -e "$tsx" ] || continue
+      base=$(basename "$tsx"); case "$base" in _*) continue ;; esac
+      grep -qE "^[[:space:]]*import[^;]*${Q}[^\"$SQ]*_layout\.css" "$tsx" && continue
+      reached=0
+      while IFS= read -r imp; do
+        impfile="$preview/$(basename "$imp")"
+        [ -f "$impfile" ] || continue
+        if grep -qE "@import[^;]*_layout\.css" "$impfile"; then reached=1; break; fi
+      done < <(grep -oE "import[[:space:]]+${Q}[^\"$SQ]*\.css" "$tsx" 2>/dev/null | grep -oE "[^\"$SQ]*\.css$")
+      if [ "$reached" -eq 0 ]; then
+        printf 'LINT-FAIL  %s — never reaches _layout.css (no DS tokens/layout/components)\n' "${tsx#$DESIGN_ROOT/}" >&2
+        printf '| ✗ LINT | `%s` | — | never reaches _layout.css |\n' "${tsx#$DESIGN_ROOT/}" >> "$MD"
+        n=$((n + 1))
+      fi
+    done
+    # (2) every shared _*.css partial has an importer
+    for css in "$preview"/_*.css; do
+      [ -e "$css" ] || continue
+      base=$(basename "$css")
+      grep -qsE "^[[:space:]]*import[^;]*${Q}[^\"$SQ]*${base}${Q}" "$preview"/*.tsx && continue
+      grep -qsE "@import[^;]*${base}" "$preview"/*.css "$preview"/../*.css && continue
+      printf 'LINT-FAIL  %s — orphan shared partial (no specimen or css imports it)\n' "${css#$DESIGN_ROOT/}" >&2
+      printf '| ✗ LINT | `%s` | — | orphan shared partial |\n' "${css#$DESIGN_ROOT/}" >> "$MD"
+      n=$((n + 1))
+    done
+  done
+  LINT_FAILED=$n
+  if [ "$n" -eq 0 ]; then
+    echo "→ import-graph lint: clean" >&2
+  else
+    echo "✗ import-graph lint: $n violation(s) — see report" >&2
+  fi
+}
+
 # Probe a canvas via agent-browser. Returns three lines on stdout:
 #   <status>   one of OK / BLANK / ERROR
 #   <detail>   short summary string
@@ -123,6 +244,7 @@ urlencode_path() {
 probe_agent_browser() {
   local url="$1"
   local out_png="$2"
+  local is_specimen="$3"   # 1 → apply the DDR-068 computed-style gate
 
   agent-browser open "$url" >/dev/null 2>&1 || { echo "ERROR"; echo "open-failed"; echo ""; return; }
 
@@ -160,6 +282,8 @@ probe_agent_browser() {
     for (const s of sel) { const el = document.querySelector(s); if (el && el.innerText) return el.innerText.slice(0, 120); }
     const body = document.body && document.body.innerText || '';
     if (body.startsWith('Error:') || body.startsWith('SyntaxError:') || body.startsWith('ReferenceError:')) return body.slice(0, 120);
+    const t = body.trim();
+    if (t === 'Not found' || t.startsWith('Forbidden (canvas origin)')) return 'route-error: ' + t.slice(0, 80);
     return '';
   })()" 2>/dev/null)
   # Strip wrapping quotes that agent-browser eval adds for strings.
@@ -172,16 +296,53 @@ probe_agent_browser() {
     return
   fi
 
+  # The PNG IS the evidence (DDR-021). A missing/empty file means agent-browser
+  # never wrote it (relative path, capture crash, …) — that is a FAILURE, not an
+  # OK. The old code fell straight through to "OK" here, which is exactly how a
+  # broken canvas route ("Not found" 404 + no PNG) masqueraded as 43/43 green.
+  if [ ! -s "$out_png" ]; then
+    echo "ERROR"
+    echo "screenshot-not-written"
+    echo "$out_png"
+    return
+  fi
   # PNG size sanity — < 2 KB usually means blank background only.
-  if [ -s "$out_png" ]; then
-    local size
-    size=$(wc -c < "$out_png" 2>/dev/null | tr -d ' ')
-    if [ -n "$size" ] && [ "$size" -lt 2048 ]; then
-      echo "BLANK"
-      echo "png-${size}B"
-      echo "$out_png"
-      return
-    fi
+  local size
+  size=$(wc -c < "$out_png" 2>/dev/null | tr -d ' ')
+  if [ -n "$size" ] && [ "$size" -lt 2048 ]; then
+    echo "BLANK"
+    echo "png-${size}B"
+    echo "$out_png"
+    return
+  fi
+
+  # Computed-style gate (DDR-068) — "mounts with content" ≠ "rendered styled". A
+  # specimen whose import graph dropped the token CSS passes every check above
+  # (it has text, no error, a >2 KB screenshot) yet every var()-driven rule is
+  # dead. Confirm the DS token contract actually resolved at runtime: --bg-0 is
+  # defined on :root by colors_and_type.css (DDR-043 name contract) and inherits
+  # to <body>, so an empty value means the token CSS never loaded. Scoped to DS
+  # preview specimens — ui/ app canvases may legitimately opt out of the tokens.
+  if [ "$is_specimen" = "1" ]; then
+    local styled
+    styled=$(agent-browser eval "(() => {
+      const b = document.body; if (!b) return 'unstyled:no-body';
+      const cs = getComputedStyle(b);
+      const tok = (cs.getPropertyValue('--bg-0').trim() || cs.getPropertyValue('--fg-0').trim() || cs.getPropertyValue('--accent').trim());
+      if (tok) return 'styled';
+      return 'unstyled:no-tokens(ff=' + ((cs.fontFamily||'').replace(/[\"\\n]/g,'').slice(0,18)) + ')';
+    })()" 2>/dev/null)
+    styled=$(printf '%s' "$styled" | sed 's/^"//; s/"$//')
+    # Only an EXPLICIT unstyled* verdict fails — a blank/garbled eval (browser
+    # hiccup) falls through to OK, since the DOM already mounted without error.
+    case "$styled" in
+      unstyled*)
+        echo "UNSTYLED"
+        echo "$styled"
+        echo "$out_png"
+        return
+        ;;
+    esac
   fi
 
   echo "OK"
@@ -204,6 +365,13 @@ printf 'status\tfile\tscreenshot\tdetail\n' > "$TSV"
   echo "|---|---|---|---|"
 } > "$MD"
 
+# Static import-graph lint before rendering (DDR-068) — only meaningful when
+# system specimens are in scope (they own the shared _layout.css / _components.css
+# chain). Violations are folded into the final exit code alongside render fails.
+if [ "$INCLUDE_SYSTEM" = "1" ] && [ -d "$DESIGN_ROOT/system" ]; then
+  lint_specimen_imports
+fi
+
 FAILED=0
 N=0
 while IFS= read -r CANVAS; do
@@ -211,14 +379,20 @@ while IFS= read -r CANVAS; do
   N=$((N + 1))
   REL="${CANVAS#$DESIGN_ROOT/}"
   REL_ENC=$(urlencode_path "$REL")
-  URL="http://localhost:$PORT/$REL_ENC"
+  # Canvases render through the canvas shell, not the bare path. The bare
+  # `/<rel>` route 404s when the canvas-origin sandbox is on (default since
+  # phase-9.1) — only `/_canvas-shell.html?canvas=<rel>` mounts the canvas
+  # (works in both split-on and legacy same-origin modes).
+  URL="http://localhost:$PORT/_canvas-shell.html?canvas=$REL_ENC"
   SLUG=$(bash "$SLUG_HELPER" "$REL" 2>/dev/null || printf '%s' "$REL" | tr '/ ' '__' | tr '[:upper:]' '[:lower:]')
   OUT_PNG="$OUT_DIR/$SLUG.png"
+  # DS preview specimens get the computed-style gate; ui/ app canvases don't.
+  case "$REL" in system/*/preview/*) IS_SPECIMEN=1 ;; *) IS_SPECIMEN=0 ;; esac
 
   printf '  [%d/%d] %s … ' "$N" "$COUNT" "$REL" >&2
 
   if [ "$ENGINE" = "agent-browser" ]; then
-    RESULT=$(probe_agent_browser "$URL" "$OUT_PNG")
+    RESULT=$(probe_agent_browser "$URL" "$OUT_PNG" "$IS_SPECIMEN")
   else
     # Playwright fallback — coarser: just screenshot, accept any PNG > 2 KB as OK.
     # See _screenshot-playwright.mjs for the underlying tool.
@@ -240,10 +414,11 @@ while IFS= read -r CANVAS; do
   SHOT=$(printf '%s\n' "$RESULT" | sed -n '3p')
 
   case "$STATUS" in
-    OK)    SYM="✓"; echo "$SYM" >&2 ;;
-    BLANK) SYM="✗"; FAILED=$((FAILED + 1)); echo "$SYM blank ($DETAIL)" >&2 ;;
-    ERROR) SYM="⚠"; FAILED=$((FAILED + 1)); echo "$SYM error ($DETAIL)" >&2 ;;
-    *)     SYM="?"; FAILED=$((FAILED + 1)); echo "? unknown ($STATUS)" >&2 ;;
+    OK)       SYM="✓"; echo "$SYM" >&2 ;;
+    BLANK)    SYM="✗"; FAILED=$((FAILED + 1)); echo "$SYM blank ($DETAIL)" >&2 ;;
+    ERROR)    SYM="⚠"; FAILED=$((FAILED + 1)); echo "$SYM error ($DETAIL)" >&2 ;;
+    UNSTYLED) SYM="✗"; FAILED=$((FAILED + 1)); echo "$SYM unstyled ($DETAIL)" >&2 ;;
+    *)        SYM="?"; FAILED=$((FAILED + 1)); echo "? unknown ($STATUS)" >&2 ;;
   esac
 
   printf '%s\t%s\t%s\t%s\n' "$STATUS" "$REL" "$SHOT" "$DETAIL" >> "$TSV"
@@ -252,21 +427,31 @@ while IFS= read -r CANVAS; do
   printf '%s\t%s\t%s\t%s\n' "$STATUS" "$REL" "$SHOT" "$DETAIL"
 done <<< "$CANVASES"
 
+TOTAL_FAIL=$((FAILED + LINT_FAILED))
 {
   echo
-  if [ $FAILED -eq 0 ]; then
-    echo "**Result:** ✓ all $COUNT canvases rendered."
+  if [ $TOTAL_FAIL -eq 0 ]; then
+    echo "**Result:** ✓ all $COUNT canvases rendered styled; import-graph lint clean."
   else
-    echo "**Result:** ✗ $FAILED / $COUNT canvases failed."
+    echo "**Result:** ✗ $FAILED / $COUNT canvases failed render/style; $LINT_FAILED import-graph lint violation(s)."
   fi
 } >> "$MD"
 
 echo "→ report: $MD" >&2
 echo "→ tsv:    $TSV" >&2
 
-if [ $FAILED -gt 0 ]; then
-  echo "✗ smoke: $FAILED / $COUNT canvases failed" >&2
+# Record this run as the baseline for the next --changed-only diff (Phase C / DDR-061).
+if command -v git >/dev/null 2>&1 && git -C "$REPO" rev-parse HEAD >/dev/null 2>&1; then
+  mkdir -p "$DESIGN_ROOT/_history/_smoke"
+  printf '{"sha":"%s","ts":"%s","mode":"%s","count":%d,"failed":%d}' \
+    "$(git -C "$REPO" rev-parse HEAD 2>/dev/null)" "$(date -u +%Y-%m-%dT%H:%M:%SZ)" \
+    "$([ "$CHANGED_ONLY" = "1" ] && echo changed-only || echo full)" "$COUNT" "$FAILED" \
+    > "$DESIGN_ROOT/_history/_smoke/.last-smoke.json"
+fi
+
+if [ $TOTAL_FAIL -gt 0 ]; then
+  echo "✗ smoke: $FAILED / $COUNT canvases failed render/style; $LINT_FAILED lint violation(s)" >&2
   exit 3
 fi
-echo "✓ smoke: all $COUNT canvases rendered" >&2
+echo "✓ smoke: all $COUNT canvases rendered styled; import-graph lint clean" >&2
 exit 0

package/plugins/design/dev-server/canvas-arrowheads.ts

@@ -0,0 +1,220 @@
+/**
+ * @file       canvas-arrowheads.ts — Phase 24 arrow shaft + head geometry
+ * @scope      plugins/design/dev-server/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
+ *             primitive into the persisted `.annotations.svg` string; the live
+ *             `StrokeNode` maps the SAME primitives to JSX — so the on-disk and
+ *             on-canvas forms can never drift.
+ *
+ *             Back-compat invariant (DDR-067): a default arrow (lineType
+ *             'straight', startHead 'none', endHead 'triangle', solid) MUST
+ *             reduce to exactly `[<line>, <polyline fill=color>]` — the
+ *             byte-identical Phase-5.1 form the canary fixtures freeze.
+ *             `arrowHeadPoints` lives here (moved from annotations-layer, which
+ *             re-exports it). This module owns the arrow style enums + a
+ *             structural geometry input and imports NOTHING from
+ *             annotations-layer — keeping the dependency one-way
+ *             (annotations-layer → canvas-arrowheads) so there is no module
+ *             cycle. (A `.ts` root in a re-export cycle with a react `.tsx`
+ *             breaks @types/react's global `JSX` namespace project-wide under
+ *             this tsconfig's `types: ["bun-types"]` — see DDR-067.)
+ */
+
+/**
+ * Phase 24 — full FigJam arrowhead vocabulary, selectable per end. `none` =
+ * bare end; `line` = open chevron; `triangle` = the legacy filled head
+ * (default end); `triangle-outline` = unfilled triangle; `circle` / `diamond`
+ * = filled markers. annotations-layer re-exports this type.
+ */
+export type ArrowHead = 'none' | 'line' | 'triangle' | 'triangle-outline' | 'circle' | 'diamond';
+/** The valid `ArrowHead` vocabulary as a runtime set — `svgToStrokes` clamps a
+ *  parsed `data-*-head` against this so a poisoned/out-of-vocab value can't be
+ *  cast through unchecked (Phase 24 security review, DDR-067). */
+export const ARROW_HEADS: ReadonlySet<string> = new Set<ArrowHead>([
+  'none',
+  'line',
+  'triangle',
+  'triangle-outline',
+  'circle',
+  'diamond',
+]);
+/** Phase 24 — arrow shaft routing. `straight` is the default + legacy form. */
+export type ArrowLineType = 'straight' | 'curved' | 'elbow';
+
+/**
+ * Structural geometry input for {@link arrowPrimitives}. `ArrowStroke` (defined
+ * in annotations-layer) is assignable to this, so we depend on the shape, not
+ * the named type — no import back, no cycle.
+ */
+export interface ArrowGeom {
+  x1: number;
+  y1: number;
+  x2: number;
+  y2: number;
+  width: number;
+  color: string;
+  startHead?: ArrowHead;
+  endHead?: ArrowHead;
+  dashed?: boolean;
+  lineType?: ArrowLineType;
+}
+
+/**
+ * The filled-triangle head outline as an SVG `points` string. Three points —
+ * `wingA, tip, wingB` — drawn as a <polyline> (filled = solid triangle, the
+ * implicit close; unfilled = open chevron) or a <polygon> (closed outline).
+ * Parameterized by the tip + the point the shaft arrives FROM, exactly as in
+ * Phase 5.1, so the legacy serialization is byte-identical.
+ */
+export function arrowHeadPoints(
+  x1: number,
+  y1: number,
+  x2: number,
+  y2: number,
+  width: number
+): string {
+  const angle = Math.atan2(y2 - y1, x2 - x1);
+  const len = 12 + width * 2;
+  const wing = Math.PI / 7;
+  const ax = x2 - Math.cos(angle - wing) * len;
+  const ay = y2 - Math.sin(angle - wing) * len;
+  const bx = x2 - Math.cos(angle + wing) * len;
+  const by = y2 - Math.sin(angle + wing) * len;
+  return `${ax},${ay} ${x2},${y2} ${bx},${by}`;
+}
+
+/** A small diamond head centered on the tip, one axis along the shaft. */
+function diamondHeadPoints(
+  fromX: number,
+  fromY: number,
+  tipX: number,
+  tipY: number,
+  width: number
+): string {
+  const angle = Math.atan2(tipY - fromY, tipX - fromX);
+  const half = 5 + width;
+  const ax = Math.cos(angle);
+  const ay = Math.sin(angle);
+  const px = -ay;
+  const py = ax;
+  const p = (dx: number, dy: number) => `${tipX + dx},${tipY + dy}`;
+  return `${p(ax * half, ay * half)} ${p(px * half, py * half)} ${p(-ax * half, -ay * half)} ${p(
+    -px * half,
+    -py * half
+  )}`;
+}
+
+/** Ordered SVG primitives — the shaft + heads. The renderer/serializer format these. */
+export type SvgPrimitive =
+  | { el: 'line'; x1: number; y1: number; x2: number; y2: number; dash: boolean }
+  | { el: 'path'; d: string; dash: boolean }
+  | { el: 'polyline'; points: string; fill: string }
+  | { el: 'polygon'; points: string; fill: string }
+  | { el: 'circle'; cx: number; cy: number; r: number; fill: string };
+
+/**
+ * Shaft path for a non-straight arrow + the control point each head orients
+ * toward (its tangent source). Straight arrows never call this — they use a
+ * bare <line> so the legacy bytes are preserved.
+ */
+function shaftPath(
+  x1: number,
+  y1: number,
+  x2: number,
+  y2: number,
+  lineType: Exclude<ArrowLineType, 'straight'>
+): { d: string; startFrom: [number, number]; endFrom: [number, number] } {
+  if (lineType === 'curved') {
+    const mx = (x1 + x2) / 2;
+    const my = (y1 + y2) / 2;
+    const dx = x2 - x1;
+    const dy = y2 - y1;
+    const len = Math.hypot(dx, dy) || 1;
+    // Perpendicular bow — 22% of the chord, consistent side so curve is stable.
+    const off = len * 0.22;
+    const cx = mx + (-dy / len) * off;
+    const cy = my + (dx / len) * off;
+    return { d: `M${x1} ${y1} Q${cx} ${cy} ${x2} ${y2}`, startFrom: [cx, cy], endFrom: [cx, cy] };
+  }
+  // elbow — one orthogonal bend, along the dominant axis first.
+  const corner: [number, number] = Math.abs(x2 - x1) >= Math.abs(y2 - y1) ? [x2, y1] : [x1, y2];
+  return {
+    d: `M${x1} ${y1} L${corner[0]} ${corner[1]} L${x2} ${y2}`,
+    startFrom: corner,
+    endFrom: corner,
+  };
+}
+
+function headPrimitives(
+  head: ArrowHead,
+  tipX: number,
+  tipY: number,
+  fromX: number,
+  fromY: number,
+  width: number,
+  color: string
+): SvgPrimitive[] {
+  switch (head) {
+    case 'none':
+      return [];
+    case 'triangle':
+      // Legacy filled head — byte-identical to Phase 5.1.
+      return [
+        { el: 'polyline', points: arrowHeadPoints(fromX, fromY, tipX, tipY, width), 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' },
+      ];
+    case 'triangle-outline':
+      // Closed triangle outline — polygon auto-closes the third edge.
+      return [
+        { el: 'polygon', points: arrowHeadPoints(fromX, fromY, tipX, tipY, width), fill: 'none' },
+      ];
+    case 'diamond':
+      return [
+        { el: 'polygon', points: diamondHeadPoints(fromX, fromY, tipX, tipY, width), fill: color },
+      ];
+    case 'circle':
+      return [{ el: 'circle', cx: tipX, cy: tipY, r: 4 + width, fill: color }];
+    default:
+      // Defensive: an out-of-vocabulary head (e.g. a poisoned hub-pushed value
+      // that slipped past the parse-clamp) renders NOTHING rather than throwing
+      // a TypeError mid-render — no per-stroke render DoS (Phase 24 security
+      // review, DDR-067). Parse-clamp + serialize-esc are the primary controls.
+      return [];
+  }
+}
+
+/**
+ * Reduce an arrow to its ordered SVG primitives: shaft, then start head, then
+ * end head (matching the legacy serialization order). Defaults: start 'none',
+ * end 'triangle', lineType 'straight', solid.
+ */
+export function arrowPrimitives(s: ArrowGeom): SvgPrimitive[] {
+  const startHead = s.startHead ?? 'none';
+  const endHead = s.endHead ?? 'triangle';
+  const dashed = s.dashed ?? false;
+  const lineType = s.lineType ?? 'straight';
+  const out: SvgPrimitive[] = [];
+
+  // Default tangent sources (straight): each head points away from the far end.
+  let startFrom: [number, number] = [s.x2, s.y2];
+  let endFrom: [number, number] = [s.x1, s.y1];
+
+  if (lineType === 'straight') {
+    out.push({ el: 'line', x1: s.x1, y1: s.y1, x2: s.x2, y2: s.y2, dash: dashed });
+  } else {
+    const shaft = shaftPath(s.x1, s.y1, s.x2, s.y2, lineType);
+    out.push({ el: 'path', d: shaft.d, dash: dashed });
+    startFrom = shaft.startFrom;
+    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));
+  return out;
+}

package/plugins/design/dev-server/canvas-comment-mount.tsx

@@ -48,29 +48,14 @@ import {
 import { MaybeToolProvider, useToolMode } from './use-tool-mode.tsx';
 
 // ─────────────────────────────────────────────────────────────────────────────
-// Cursor CSS for the generic mount host. canvas-lib's HALO_CSS keys comment-
-// mode cursors on `.dc-canvas[data-active-tool]`, which is absent in a bare
-// specimen. We mirror the comment-tool cursor keyed on the mount host's
-// `data-active-tool` attribute so the affordance ships even with no canvas-lib
-// CSS present. The host is `display: contents` (so specimen layout is byte-
-// identical) — a `display:contents` box can't paint a cursor, so the rule
-// targets descendants of the host, not the host box itself.
-
-const MC_CURSOR_CSS = `
-[data-mc-host][data-active-tool="comment"] *,
-body[data-active-tool="comment"] * {
-  cursor: url("data:image/svg+xml;utf8,<svg xmlns='http://www.w3.org/2000/svg' width='16' height='16' viewBox='0 0 16 16'><path d='M3 3 L14 3 L14 11 L8 11 L4 14 L4 11 L3 11 Z' fill='white' stroke='%23111' stroke-width='1' stroke-linejoin='round'/></svg>") 4 4, crosshair !important;
-}
-`.trim();
-
-function ensureMountCursorStyles(): void {
-  if (typeof document === 'undefined') return;
-  if (document.getElementById('mc-cursor-css')) return;
-  const s = document.createElement('style');
-  s.id = 'mc-cursor-css';
-  s.textContent = MC_CURSOR_CSS;
-  document.head.appendChild(s);
-}
+// Phase 24 — the comment-mode cursor (and every other tool cursor) is owned
+// SOLELY by use-tool-mode.tsx, whose `* { cursor: <Kenney glyph> !important }`
+// rule is injected by the ToolProvider this layer mounts (MaybeToolProvider) —
+// so it covers bare DS specimens too. The old `[data-mc-host]…`/`body[…]`
+// comment-cursor rule used to live here, but its higher specificity shadowed
+// the unified Kenney cursor on UI canvases (comment-mount stamps
+// `data-active-tool` on <body>, so `body[data-active-tool="comment"] *` matched
+// there as well). Removed so the single source of truth wins. See DDR-067.
 
 // ─────────────────────────────────────────────────────────────────────────────
 // CommentHost — owns the lite comment subsystem: the input router (comment-
@@ -116,7 +101,6 @@ function pickSpecimenEl(clientX: number, clientY: number): HTMLElement | null {
 }
 
 function CommentHost({ children, file }: { children: ReactNode; file: string | undefined }) {
-  ensureMountCursorStyles();
   const { tool, setTool } = useToolMode();
   const selSet = useSelectionSet();
   const hostRef = useRef<HTMLDivElement | null>(null);