@1agh/maude 0.40.0 → 0.41.0

package/apps/studio/bin/canvas-rects.sh

@@ -0,0 +1,152 @@
+#!/usr/bin/env bash
+# canvas-rects.sh — the whiteboard AI toolkit's geometry manifest
+# (feature-whiteboard-ai-toolkit). Emits `{ artboards, elements,
+# elementsTruncated }` in WORLD coordinates for a canvas — the file
+# `read-annotations --rects` and `annotate --in/--pin/--board` consume so
+# neither verb ever hand-computes a coordinate. Reached via
+# `maude design canvas-rects` (DDR-062), never a raw bin path.
+#
+# Usage:
+#   canvas-rects.sh <rel-path> [--root <repo>] [--port N] [--timeout 8]
+#                   [--engine auto|agent-browser|playwright]
+#
+# Two lanes:
+#   - LIVE (preferred) — when a dev server is reachable (_server.json or
+#     --port), navigates the canvas-shell URL and reads
+#     `window.__maudeCanvasRects()` (canvas-lib.tsx) so element rects reflect
+#     actual CSS/content. Engine: agent-browser (default, matches
+#     screenshot.sh) or playwright (--engine playwright, or auto-fallback when
+#     agent-browser isn't on PATH).
+#   - STATIC fallback — no server reachable: artboard positions/sizes only
+#     (meta.json + JSX width/height, DDR-027), `elements: []`. No browser
+#     needed. A stderr note explains the degraded result.
+#
+# Unlike screenshot.sh this has no port-bounce retry (accepted v1 simplification
+# — read-annotations/annotate don't have one either); a stale port just falls
+# through to the static lane.
+#
+# Stdout: the manifest JSON (one line). Stderr: diagnostics/engine choice.
+# Exit: 0 on success (either lane) / 2 on bad args.
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+ROOT=""
+PORT=""
+TIMEOUT=8
+ENGINE="auto"
+REL=""
+
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --root)    ROOT="$2"; shift 2 ;;
+    --port)    PORT="$2"; shift 2 ;;
+    --timeout) TIMEOUT="$2"; shift 2 ;;
+    --engine)  ENGINE="$2"; shift 2 ;;
+    --help|-h) sed -n '2,24p' "$0" | sed 's/^# \?//'; exit 0 ;;
+    -*) echo "canvas-rects.sh: unknown arg '$1' (try --help)" >&2; exit 2 ;;
+    *) REL="$1"; shift ;;
+  esac
+done
+
+[ -n "$REL" ] || { echo "canvas-rects.sh: missing <rel-path>" >&2; exit 2; }
+
+REPO="${ROOT:-${CLAUDE_PROJECT_DIR:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}}"
+STATE="$REPO/.design/_server.json"
+
+emit_static() {
+  node "$SCRIPT_DIR/_canvas-rects-static.mjs" --rel "$REL" --root "$REPO"
+}
+
+# ---------- server detection ----------
+if [ -z "$PORT" ] && [ -f "$STATE" ]; then
+  if command -v jq >/dev/null 2>&1; then
+    PORT=$(jq -r .port "$STATE" 2>/dev/null)
+  else
+    PORT=$(sed -nE 's/.*"port"[[:space:]]*:[[:space:]]*([0-9]+).*/\1/p' "$STATE" | head -n1)
+  fi
+fi
+
+if [ -z "$PORT" ] || ! curl -fsS -o /dev/null -m 2 "http://localhost:$PORT/_health" 2>/dev/null; then
+  echo "→ no live dev server reachable — static artboard-only fallback" >&2
+  emit_static
+  exit 0
+fi
+
+# ---------- designRel (for the canvas= query param) ----------
+DESIGN_REL=".design"
+CFG="$REPO/.design/config.json"
+if [ -f "$CFG" ] && command -v jq >/dev/null 2>&1; then
+  CAND=$(jq -r '.designRoot // empty' "$CFG" 2>/dev/null)
+  [ -n "$CAND" ] && DESIGN_REL="$CAND"
+fi
+
+# Canvases mount through the canvas shell; the bare `/<rel>` route 404s when
+# the canvas-origin sandbox is on (default since phase-9.1) — mirrors
+# screenshot.sh's URL construction.
+REL_ENC=$(printf '%s' "$DESIGN_REL/$REL" | sed 's/ /%20/g')
+URL="http://localhost:${PORT}/_canvas-shell.html?canvas=${REL_ENC}"
+
+# ---------- engine resolution (mirrors screenshot.sh) ----------
+AB="${MAUDE_AGENT_BROWSER:-agent-browser}"
+if [ "$ENGINE" = "auto" ]; then
+  if command -v "$AB" >/dev/null 2>&1; then
+    ENGINE="agent-browser"
+  else
+    ENGINE="playwright"
+  fi
+fi
+echo "→ canvas-rects engine: $ENGINE | url: $URL" >&2
+
+# ---------- agent-browser lane ----------
+if [ "$ENGINE" = "agent-browser" ]; then
+  if ! command -v "$AB" >/dev/null 2>&1; then
+    echo "→ agent-browser not on PATH — static artboard-only fallback" >&2
+    emit_static
+    exit 0
+  fi
+  "$AB" open "$URL" >&2
+
+  # Poll for the hook itself (more precise than screenshot.sh's generic
+  # [data-dc-screen] mount check — this is exactly what we're about to call).
+  poll=0
+  ready=0
+  while [ $poll -lt "$TIMEOUT" ]; do
+    sleep 1
+    poll=$((poll + 1))
+    raw=$("$AB" eval "typeof window.__maudeCanvasRects" 2>/dev/null)
+    case "$raw" in
+      *function*) ready=1; break ;;
+    esac
+  done
+  if [ $ready -eq 0 ]; then
+    echo "→ hook never installed after ${TIMEOUT}s (non-canvas page?) — static artboard-only fallback" >&2
+    emit_static
+    exit 0
+  fi
+
+  RAW_JSON=$("$AB" eval "JSON.stringify(window.__maudeCanvasRects())" 2>/dev/null)
+  if [ -z "$RAW_JSON" ]; then
+    echo "→ eval returned nothing — static artboard-only fallback" >&2
+    emit_static
+    exit 0
+  fi
+  if command -v jq >/dev/null 2>&1; then
+    printf '%s\n' "$RAW_JSON" | jq -r .
+  else
+    # No jq — agent-browser's output is a JSON-encoded STRING (quoted,
+    # escaped); node unwraps it the same way `jq -r .` would.
+    printf '%s' "$RAW_JSON" | node -e "let s='';process.stdin.on('data',d=>s+=d).on('end',()=>process.stdout.write(JSON.parse(s)+'\n'))"
+  fi
+  exit 0
+fi
+
+# ---------- playwright lane ----------
+if [ "$ENGINE" = "playwright" ]; then
+  if ! node "$SCRIPT_DIR/_canvas-rects-playwright.mjs" --url "$URL" --timeout "$TIMEOUT"; then
+    echo "→ playwright capture failed — static artboard-only fallback" >&2
+    emit_static
+  fi
+  exit 0
+fi
+
+echo "canvas-rects.sh: unknown --engine '$ENGINE'" >&2
+exit 2

package/apps/studio/bin/fetch-asset.sh

@@ -0,0 +1,34 @@
+#!/usr/bin/env bash
+# fetch-asset.sh — hardened download-first image fetch. Thin shim over
+# _fetch-asset.mjs; reached via `maude design fetch-asset` (DDR-062), never a
+# raw bin path. See _fetch-asset.mjs for the full security rationale
+# (DDR-147 § Security follow-up item 1).
+#
+# Usage:
+#   fetch-asset.sh <https-url> --root <repo> [--design-root .design]
+#                  [--max-bytes N] [--max-time S] [--json]
+#
+# stdout on success = the canvas reference path (e.g. /assets/a44d3d60.png).
+# Exit: 0 ok · 2 usage · 3 SSRF/validation reject · 4 download/http error ·
+#       5 unsupported media type · 6 write/containment error · 1 other.
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+
+case "$1" in
+  --help|-h) sed -n '2,17p' "$0" | sed 's/^# \?//'; exit 0 ;;
+esac
+
+if ! command -v curl >/dev/null 2>&1; then
+  echo "fetch-asset.sh: curl is required (hardened download uses fixed curl args)." >&2
+  exit 1
+fi
+
+# Prefer node (always present with a maude install); fall back to bun in a dev
+# tree that has bun but a shimmed node. The module is pure Node ESM — no .ts.
+if command -v node >/dev/null 2>&1; then
+  exec node "$SCRIPT_DIR/_fetch-asset.mjs" "$@"
+elif command -v bun >/dev/null 2>&1; then
+  exec bun run "$SCRIPT_DIR/_fetch-asset.mjs" "$@"
+else
+  echo "fetch-asset.sh: node (or bun) is required." >&2
+  exit 1
+fi

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

@@ -37,7 +37,14 @@ import { pathToFileURL } from 'node:url';
 // Argv
 
 function parseArgv(argv) {
-  const out = { positional: [], root: null, canvasState: null, help: false, graph: false };
+  const out = {
+    positional: [],
+    root: null,
+    canvasState: null,
+    rects: null,
+    help: false,
+    graph: false,
+  };
   for (let i = 0; i < argv.length; i += 1) {
     const a = argv[i];
     if (a === '--help' || a === '-h') {
@@ -56,6 +63,11 @@ function parseArgv(argv) {
       out.canvasState = argv[i];
     } else if (a.startsWith('--canvas-state=')) {
       out.canvasState = a.slice('--canvas-state='.length);
+    } else if (a === '--rects') {
+      i += 1;
+      out.rects = argv[i];
+    } else if (a.startsWith('--rects=')) {
+      out.rects = a.slice('--rects='.length);
     } else {
       out.positional.push(a);
     }
@@ -67,6 +79,7 @@ const HELP = `read-annotations.mjs — headless SVG → JSON annotation reader (
 
 Usage:
   maude design read-annotations <rel-path> [--root <repo>] [--canvas-state <path>]
+                                 [--rects <path>]
 
 Args:
   <rel-path>          Canvas path relative to the design root (e.g. "ui/Foo.tsx").
@@ -75,6 +88,16 @@ Args:
                       each annotation is tagged with the artboard it overlaps,
                       plus artboard-relative coords (rel) and a W3C-style
                       target block { source, selector, geometry }.
+  --rects <p>         A \`maude design canvas-rects\` geometry manifest
+                      ({ artboards, elements }) — feature-whiteboard-ai-toolkit.
+                      Adds ELEMENT-level context: an annotation whose center
+                      falls inside an element's world rect gets
+                      element: { cdId, selector, index, artboard, rect, tag,
+                      text } (or element: null). Also supplies artboard
+                      tagging (as --canvas-state does) when --canvas-state is
+                      not separately given. When an element resolves, the W3C
+                      target.selector upgrades from AnnotationIdSelector to
+                      { type: "CssSelector", value: <element.selector> }.
   --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
@@ -495,23 +518,103 @@ function tagArtboard(ann, artboards) {
  * 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).
+ * geometry as the refinement/fallback). feature-whiteboard-ai-toolkit — when
+ * `anchorToElement` (below) already resolved `ann.element`, the target
+ * selector upgrades to a CssSelector naming that element instead of the bare
+ * AnnotationIdSelector.
  */
 function anchorToArtboard(ann, artboards) {
   const r = findArtboard(ann, artboards);
   if (!r) return { ...ann, artboard: null };
+  const selector = ann.element
+    ? { type: 'CssSelector', value: ann.element.selector }
+    : { type: 'AnnotationIdSelector', value: ann.id };
   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 },
+      selector,
       geometry: ann.x != null ? { x: ann.x, y: ann.y, w: ann.w ?? 0, h: ann.h ?? 0 } : null,
     },
   };
 }
 
+// ─────────────────────────────────────────────────────────────────────────────
+// --rects element-level context (feature-whiteboard-ai-toolkit). Reads a
+// `maude design canvas-rects` geometry manifest ({ artboards, elements }) —
+// `loadArtboards` above already understands `raw.artboards`, so only the
+// elements side needs a dedicated loader.
+
+function loadElements(p) {
+  try {
+    const raw = JSON.parse(readFileSync(p, 'utf8'));
+    const arr = Array.isArray(raw?.elements) ? raw.elements : [];
+    return arr.filter(
+      (e) =>
+        e &&
+        typeof e.selector === 'string' &&
+        e.selector &&
+        [e.x, e.y, e.w, e.h].every((n) => Number.isFinite(n))
+    );
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Deepest-element approximation over a FLAT rect list (no live DOM to walk,
+ * unlike `resolveHoverTarget` in the browser): the smallest-area element whose
+ * world rect contains the annotation's CENTER point. Smallest-containing-rect
+ * is the standard proxy for "innermost" when only bounding boxes are known —
+ * a wrapping card and the button inside it both contain the point, but the
+ * button's rect is smaller.
+ */
+function findElement(ann, elements) {
+  if (ann.x == null || ann.y == null) return null;
+  const cx = ann.x + (ann.w || 0) / 2;
+  const cy = ann.y + (ann.h || 0) / 2;
+  let best = null;
+  let bestArea = Number.POSITIVE_INFINITY;
+  for (const el of elements) {
+    if (cx < el.x || cx > el.x + el.w || cy < el.y || cy > el.y + el.h) continue;
+    const area = Math.max(0, el.w) * Math.max(0, el.h);
+    if (area < bestArea) {
+      bestArea = area;
+      best = el;
+    }
+  }
+  return best;
+}
+
+/**
+ * Look up a manifest element BY IDENTITY (its `cdId` or its full `selector`
+ * string) rather than by point — what `annotate --pin <cdId|selector>` needs
+ * to resolve a placement target. First match in manifest order.
+ */
+function findElementById(elements, query) {
+  if (!query) return null;
+  return elements.find((el) => el.cdId === query || el.selector === query) ?? null;
+}
+
+function anchorToElement(ann, elements) {
+  const el = findElement(ann, elements);
+  if (!el) return { ...ann, element: null };
+  return {
+    ...ann,
+    element: {
+      cdId: el.cdId ?? null,
+      selector: el.selector,
+      index: el.index ?? 0,
+      artboard: el.artboard ?? null,
+      rect: { x: el.x, y: el.y, w: el.w, h: el.h },
+      tag: el.tag ?? '',
+      text: el.text ?? '',
+    },
+  };
+}
+
 // ─────────────────────────────────────────────────────────────────────────────
 // Main
 
@@ -548,14 +651,28 @@ function main() {
 
   let annotations = parseAnnotations(svg);
 
+  // feature-whiteboard-ai-toolkit — --rects supplies element-level context
+  // (and, absent a separate --canvas-state, artboards too: loadArtboards
+  // already understands a canvas-rects manifest's `{ artboards, elements }`
+  // shape). Elements are resolved BEFORE artboards so anchorToArtboard can see
+  // the already-attached `element` and upgrade its W3C target.selector.
+  let artboards = [];
   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) => anchorToArtboard(a, artboards));
+    artboards = loadArtboards(csPath);
+  }
+  if (args.rects) {
+    const rectsPath = isAbsolute(args.rects) ? args.rects : resolve(process.cwd(), args.rects);
+    const elements = loadElements(rectsPath);
+    if (elements.length) {
+      annotations = annotations.map((a) => anchorToElement(a, elements));
     }
+    if (!artboards.length) artboards = loadArtboards(rectsPath);
+  }
+  if (artboards.length) {
+    annotations = annotations.map((a) => anchorToArtboard(a, artboards));
   }
 
   if (args.graph) {
@@ -567,7 +684,21 @@ function 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 };
+// feature-whiteboard-ai-toolkit — findElement/loadElements are exported too so
+// `annotate --pin` (Task 4) can resolve an element's rect from the same
+// canvas-rects manifest without a second implementation.
+export {
+  anchorToElement,
+  buildGraph,
+  fileSlug,
+  findElement,
+  findElementById,
+  loadArtboards,
+  loadElements,
+  parseAnnotations,
+  resolveDesignRoot,
+  tagArtboard,
+};
 
 const isMain = process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href;
 if (isMain) main();

package/apps/studio/bin/smoke.sh

@@ -40,7 +40,11 @@
 # 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/unstyled/lint-fail / 1 = missing deps / 2 = bad args.
+# Exit:   0 = all green / 3 = at least one blank/error/unstyled/broken-img/lint-fail / 1 = missing deps / 2 = bad args.
+#
+# BROKEN-IMG (agent-browser engine only) flags a VISIBLE <img> that finished
+# loading with naturalWidth 0 — a CSP-blocked hotlink or a 404'd local asset the
+# user sees as an empty thumbnail. onError-hidden scrap fallbacks are excluded.
 
 REPO=""
 OUT_DIR=""
@@ -356,6 +360,37 @@ probe_agent_browser() {
     return
   fi
 
+  # Broken-image gate (DDR-147 / 2026-07-06 RCA) — the moodboard + DS specimens
+  # fill photo slots with web imagery; a hotlink blocked by the canvas CSP
+  # (`img-src 'self'`, default-on split origin) or a 404'd local path renders as
+  # an empty "broken image" thumbnail the user sees but every check above sails
+  # past (it has text, no error, a >2 KB screenshot). Flag any <img> that
+  # FINISHED loading with naturalWidth 0 AND is actually VISIBLE — a slot whose
+  # `onError` hid the img and swapped in a scrap (display:none / hidden / opacity
+  # 0) is a graceful degrade, NOT a failure, so it's excluded. Catches the class
+  # of regression where download-first silently stopped working.
+  local broken
+  broken=$(agent-browser eval "(() => {
+    const bad = [...document.querySelectorAll('img')].filter((im) => {
+      if (!im.complete || im.naturalWidth > 0) return false;
+      const src = (im.getAttribute('src') || '').trim();
+      if (!src || src.startsWith('data:')) return false;
+      const cs = getComputedStyle(im);
+      if (cs.display === 'none' || cs.visibility === 'hidden' || cs.opacity === '0') return false;
+      return true;
+    });
+    if (!bad.length) return '';
+    const sample = bad.slice(0, 2).map((im) => (im.currentSrc || im.getAttribute('src') || '').slice(0, 60)).join(', ');
+    return bad.length + ' broken img(s): ' + sample;
+  })()" 2>/dev/null)
+  broken=$(printf '%s' "$broken" | sed 's/^\"//; s/\"$//')
+  if [ -n "$broken" ] && [ "$broken" != "null" ] && [ "$broken" != "undefined" ]; then
+    echo "BROKEN-IMG"
+    echo "$broken"
+    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
@@ -456,11 +491,12 @@ 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 ;;
-    UNSTYLED) SYM="✗"; FAILED=$((FAILED + 1)); echo "$SYM unstyled ($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 ;;
+    BROKEN-IMG) SYM="✗"; FAILED=$((FAILED + 1)); echo "$SYM broken-img ($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"

package/apps/studio/build.ts

@@ -197,6 +197,19 @@ async function buildCss(): Promise<{ outBytes: number; outPath: string }> {
 // Pre-building all 6 sub-bundles at release time + shipping in dist/runtime/
 // eliminates the runtime dependency on disk node_modules entirely.
 
+// Dev builds skip the runtime-bundle regen whenever every bundle is already
+// on disk: the committed dist/runtime/*.js are authoritative for releases
+// (CI builds with MAUDE_SKIP_RUNTIME_BUILD=1), and a dev-mode regen writes
+// UNMINIFIED output that dirties the tree at ~2× the shipped size. Runtime
+// bundles depend only on dependency versions, never on client/server source,
+// so after a dep bump regen deliberately:
+//   MAUDE_FORCE_RUNTIME_BUILD=1 bun run build.ts --release
+async function runtimeBundlesComplete(): Promise<boolean> {
+  const { RUNTIME_PACKAGES, slugFor } = await import('./runtime-bundle.ts');
+  const outDir = join(DIST, 'runtime');
+  return RUNTIME_PACKAGES.every((pkg) => existsSync(join(outDir, `${slugFor(pkg)}.js`)));
+}
+
 async function buildRuntimeBundles(): Promise<{ outDir: string; count: number; bytes: number }> {
   // Defer import so build.ts can run in --dry-run without pulling react.
   const { RUNTIME_PACKAGES, getRuntimeBundle, slugFor } = await import('./runtime-bundle.ts');
@@ -478,6 +491,14 @@ async function main() {
     console.log(
       '[build] dist/runtime/*.js SKIPPED (MAUDE_SKIP_RUNTIME_BUILD=1 — using committed pre-built)'
     );
+  } else if (
+    MODE === 'dev' &&
+    process.env.MAUDE_FORCE_RUNTIME_BUILD !== '1' &&
+    (await runtimeBundlesComplete())
+  ) {
+    console.log(
+      '[build] dist/runtime/*.js SKIPPED (all present; committed bundles are authoritative — MAUDE_FORCE_RUNTIME_BUILD=1 to regen after a dep bump)'
+    );
   } else {
     const runtime = await buildRuntimeBundles();
     const t2b = performance.now();