@1agh/maude 0.19.1 → 0.21.0

package/plugins/design/dev-server/artboard-marquee.tsx

@@ -18,18 +18,17 @@
 import { useEffect, useRef } from 'react';
 
 import { useArtboardsContext } from './canvas-lib.tsx';
+import { DRAG_THRESHOLD_PX } from './input-router.tsx';
 import { type Selection, useSelectionSet } from './use-selection-set.tsx';
 import { useToolMode } from './use-tool-mode.tsx';
 
-const DRAG_THRESHOLD_PX = 4;
-
 const MARQUEE_CSS = `
 .dc-cv-marquee {
   position: fixed;
   pointer-events: none;
   z-index: 5;
-  border: 1px solid var(--accent, #0d99ff);
-  background: color-mix(in oklab, var(--accent, #0d99ff) 8%, transparent);
+  border: 1px solid var(--maude-hud-accent, #0d99ff);
+  background: color-mix(in oklab, var(--maude-hud-accent, #0d99ff) 8%, transparent);
   display: none;
 }
 `.trim();
@@ -52,7 +51,7 @@ function shouldIgnoreTarget(t: EventTarget | null): boolean {
   // Skip floating chrome and existing overlays (their click handlers run).
   if (
     el.closest(
-      '.dc-mm, .dc-zoom-tb, .dc-tool-palette, .dc-context-menu, .dc-cv-halo, .dc-cv-group-bbox, .cm-composer, .cm-thread, .cm-mention-popup, .cm-pin, .dc-annot-svg, .dc-annot-ctx, .dc-tp-popover, .dc-annot-resize-handle'
+      '.dc-mm, .dc-zoom-tb, .dc-tool-palette, .dc-context-menu, .dc-cv-halo, .dc-cv-group-bbox, .cm-composer, .cm-thread, .cm-mention-popup, .cm-pin, .dc-annot-svg, .dc-annot-ctx, .dc-tp-popover, .dc-annot-resize-handle, .dc-multi-artboard-tb, .dc-elem-ctx-tb, .dc-cv-eq-spacing-layer'
     )
   ) {
     return true;
@@ -125,7 +124,12 @@ export function ArtboardMarqueeOverlay() {
       stateRef.current = null;
       const div = overlayRef.current;
       if (div) div.style.display = 'none';
-      if (!s.crossed) return;
+      if (!s.crossed) {
+        // Bare click on empty world without drag → clear selection
+        // (post-Wave-3 user feedback). Shift-click preserves it.
+        if (!s.shift) selSet.clear();
+        return;
+      }
       if (!artboardsCtx) return;
 
       // Intersect the marquee AABB with each artboard's screen-coord bbox.

package/plugins/design/dev-server/bin/asset-sweep.sh

@@ -0,0 +1,180 @@
+#!/usr/bin/env bash
+# asset-sweep.sh — pre-scaffold real-asset sweep for `/design:setup-ds`.
+# Greps a target repo for production sources of logo/mark/wordmark/mascot/glyph/
+# illustration BEFORE Batch A authors any placeholder. Single hit at a
+# conventional path → copy 1:1. Multiple hits → caller asks user via
+# AskUserQuestion. Zero hits → THEN placeholder authorship is permitted.
+#
+# Closes D-2 in the studyfi imprint-bootstrap retro (placeholder bleed).
+# Spec: `.ai/plans/phase-3.7-setup-ds-hardening-and-motion-subsystem.md` Task 1.
+#
+# Usage:
+#   asset-sweep.sh --root <repo> [--query "logo,mark,wordmark,mascot,glyph,illustration"]
+#                                [--depth 6] [--ext "svg,png"]
+#
+# Defaults:
+#   --query  "logo,mark,wordmark,mascot,glyph,illustration"
+#   --depth  6      (`find -maxdepth`; capped to keep monorepo sweeps < 2s)
+#   --ext    "svg"  (svg-only by default — production marks are vector)
+#
+# Output: one JSON object on stdout, e.g.
+#   { "logo": ["packages/ui/src/components/ui/logo/logo.svg"],
+#     "mark": [],
+#     "wordmark": [],
+#     "mascot": [],
+#     "glyph": ["packages/ui/.../glyphs/sparkle.svg",
+#               "packages/ui/.../glyphs/check.svg"],
+#     "illustration": [] }
+#
+# Paths are relative to --root. Sorted lexicographically. Duplicates removed.
+# Excludes: node_modules/, .git/, .design/_history/, .next/, dist/, build/.
+#
+# Exit: 0 always (zero hits is a valid result, not an error). 2 = bad args.
+
+ROOT=""
+QUERY="logo,mark,wordmark,mascot,glyph,illustration"
+DEPTH=6
+EXT="svg"
+
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --root)  ROOT="$2";  shift 2 ;;
+    --query) QUERY="$2"; shift 2 ;;
+    --depth) DEPTH="$2"; shift 2 ;;
+    --ext)   EXT="$2";   shift 2 ;;
+    --help|-h)
+      sed -n '2,30p' "$0" | sed 's/^# \?//'
+      exit 0
+      ;;
+    *)
+      echo "asset-sweep.sh: unknown arg '$1' (try --help)" >&2
+      exit 2
+      ;;
+  esac
+done
+
+if [ -z "$ROOT" ]; then
+  echo "asset-sweep.sh: --root <repo> required" >&2
+  exit 2
+fi
+if [ ! -d "$ROOT" ]; then
+  echo "asset-sweep.sh: --root '$ROOT' is not a directory" >&2
+  exit 2
+fi
+
+# Resolve --root to an absolute path so the relative-path strip below is stable
+# regardless of caller cwd.
+ROOT_ABS=$(cd "$ROOT" && pwd)
+
+# Build the find -name predicate for the extension list.
+# EXT="svg,png" → \( -name "*.svg" -o -name "*.png" \)
+ext_predicate=()
+IFS=',' read -r -a EXT_ARR <<< "$EXT"
+ext_predicate+=("(")
+first=1
+for e in "${EXT_ARR[@]}"; do
+  e_trim=$(echo "$e" | tr -d '[:space:]')
+  [ -z "$e_trim" ] && continue
+  if [ $first -eq 1 ]; then
+    ext_predicate+=("-name" "*.$e_trim")
+    first=0
+  else
+    ext_predicate+=("-o" "-name" "*.$e_trim")
+  fi
+done
+ext_predicate+=(")")
+
+# Single find pass; bucket by noun in-memory. Earlier per-noun-find walked the
+# tree N times (6× for default query) — ~4s on a 20k-file repo. Single pass
+# pushes us under the 2s/50k budget from the phase plan.
+#
+# Match policy (case-insensitive): a file is bucketed under noun N if N appears
+# as a substring of the basename OR as a path segment in the parent chain
+# (catches `packages/ui/.../logo/logo.svg` AND `assets/glyphs/foo.svg`).
+
+# Normalize nouns once.
+IFS=',' read -r -a NOUNS <<< "$QUERY"
+declare -a NOUNS_LC=()
+for n in "${NOUNS[@]}"; do
+  n_trim=$(echo "$n" | tr -d '[:space:]')
+  [ -z "$n_trim" ] && continue
+  NOUNS_LC+=("$(printf '%s' "$n_trim" | tr '[:upper:]' '[:lower:]')")
+done
+
+# Buckets keyed by noun. Bash 4+ supports declare -A; macOS ships bash 3.2
+# by default — fall back to a per-noun delimiter-joined string in flat vars.
+declare -a BUCKETS=()
+for _ in "${NOUNS_LC[@]}"; do BUCKETS+=(""); done
+
+# Walk once. Prune vendor/build dirs to keep the tree small.
+while IFS= read -r f; do
+  [ -z "$f" ] && continue
+  rel="${f#"$ROOT_ABS"/}"
+  base="${f##*/}"
+  base_lc=$(printf '%s' "$base" | tr '[:upper:]' '[:lower:]')
+  parent="${f%/*}"
+  parent_lc=$(printf '%s' "$parent" | tr '[:upper:]' '[:lower:]')
+  i=0
+  for noun in "${NOUNS_LC[@]}"; do
+    matched=0
+    case "$base_lc" in *"$noun"*) matched=1 ;; esac
+    if [ $matched -eq 0 ]; then
+      case "$parent_lc" in
+        *"/$noun"*|*"/$noun"|*"/${noun}s"*|*"/${noun}s") matched=1 ;;
+      esac
+    fi
+    if [ $matched -eq 1 ]; then
+      if [ -z "${BUCKETS[$i]}" ]; then
+        BUCKETS[$i]="$rel"
+      else
+        BUCKETS[$i]="${BUCKETS[$i]}"$'\n'"$rel"
+      fi
+    fi
+    i=$((i + 1))
+  done
+done < <(
+  find "$ROOT_ABS" \
+      -maxdepth "$DEPTH" \
+      \( \
+        -path "*/node_modules" -o \
+        -path "*/.git" -o \
+        -path "*/.design/_history" -o \
+        -path "*/.next" -o \
+        -path "*/dist" -o \
+        -path "*/build" -o \
+        -path "*/coverage" -o \
+        -path "*/.turbo" -o \
+        -path "*/.cache" \
+      \) -prune -o \
+      -type f \
+      "${ext_predicate[@]}" \
+      -print 2>/dev/null
+)
+
+# JSON emission. Avoid jq as a hard dep (matches server-up.sh's defensive
+# posture) — the JSON shape is small + predictable.
+printf '{'
+first=1
+i=0
+for noun in "${NOUNS_LC[@]}"; do
+  if [ $first -eq 0 ]; then printf ','; fi
+  first=0
+  printf '\n  "%s": [' "$noun"
+  if [ -n "${BUCKETS[$i]}" ]; then
+    # Sort + dedupe, then JSON-emit.
+    printf '\n'
+    ln_first=1
+    while IFS= read -r hit; do
+      [ -z "$hit" ] && continue
+      esc=$(printf '%s' "$hit" | sed -e 's/\\/\\\\/g' -e 's/"/\\"/g')
+      if [ $ln_first -eq 0 ]; then printf ',\n'; fi
+      ln_first=0
+      printf '    "%s"' "$esc"
+    done < <(printf '%s\n' "${BUCKETS[$i]}" | sort -u)
+    printf '\n  ]'
+  else
+    printf ']'
+  fi
+  i=$((i + 1))
+done
+printf '\n}\n'

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

@@ -0,0 +1,32 @@
+#!/usr/bin/env bash
+# preflight.sh — design plugin dependency health check.
+# Thin shell wrapper over `node cli/lib/preflight.mjs --plugin design`.
+# Keeps the detection logic in one place (the .mjs lib) while exposing the
+# bash-friendly modes (--shell-export, --warn-only) that init.md and the
+# SessionStart hook need.
+#
+# Usage:
+#   preflight.sh                    # text table (humans)
+#   preflight.sh --json             # machine-readable envelope
+#   preflight.sh --shell-export     # `export DEPS_OK=... DEPS_MISSING=...`
+#   preflight.sh --quiet            # silent on success, one-liner on miss
+#   preflight.sh --warn-only        # same as --quiet (SessionStart hook)
+#
+# Resolution (DDR-045): never compute paths from `dirname $0` inside a
+# `bun --compile` standalone binary — that maps to /$bunfs/root. The CLI
+# entry stays Node, so we resolve via $CLAUDE_PLUGIN_ROOT first, with the
+# script-dir fallback only used when running uncompiled from the repo.
+#
+# Exit: 0 if all hard deps pass; 1 otherwise.
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+PLUGIN_ROOT="${CLAUDE_PLUGIN_ROOT:-$(cd "$SCRIPT_DIR/../.." && pwd)}"
+PKG_ROOT="$(cd "$PLUGIN_ROOT/../.." && pwd)"
+
+# The Node lib needs cwd to be the package root (it resolves dependencies.json
+# via `plugins/<plugin>/dependencies.json`). Subshell so we don't mutate the
+# caller's cwd.
+(
+  cd "$PKG_ROOT" || exit 1
+  exec node "$PKG_ROOT/cli/lib/preflight.mjs" --plugin design "$@"
+)

package/plugins/design/dev-server/bin/runtime-health.sh

@@ -0,0 +1,169 @@
+#!/usr/bin/env bash
+# runtime-health.sh — verify the dev-server is serving the on-disk pre-built
+# runtime bundles, not a defective dynamic Bun.build output.
+#
+# Why: a stale dev-server process can cache a broken dynamic build of
+# /_canvas-runtime/<slug>.js (e.g. a 409-line motion_react.js with a hoisting
+# bug instead of the 10056-line pre-built). The canvas TSX parses cleanly,
+# server returns HTTP 200, but the iframe throws at module-eval time with
+# `ReferenceError: AcceleratedAnimation is not defined` (or similar).
+#
+# Parse-clean ≠ run-clean. This helper closes that gap: probe every URL the
+# canvas-lib pulls in, compare byte-count to the disk pre-built, fail loud
+# when the served body is suspiciously small.
+#
+# Usage:
+#   runtime-health.sh [--port N] [--root <repo>] [--threshold 0.5]
+#                     [--restart] [--quiet]
+#
+# Behavior:
+#   --restart  → on detected defect, kill the server PID from _server.json
+#                and respawn via server-up.sh. Exit 0 if the restart heals.
+#   --quiet    → silence per-bundle PASS lines; only print failures + summary.
+#
+# Exit codes:
+#   0 all bundles healthy (or --restart healed the defect)
+#   1 server unreachable / no _server.json
+#   2 bad args
+#   3 defective bundle detected (and either no --restart, or restart did not heal)
+
+PORT=""
+REPO=""
+THRESHOLD="0.5"
+RESTART=0
+QUIET=0
+
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --port)      PORT="$2"; shift 2 ;;
+    --root)      REPO="$2"; shift 2 ;;
+    --threshold) THRESHOLD="$2"; shift 2 ;;
+    --restart)   RESTART=1; shift ;;
+    --quiet)     QUIET=1; shift ;;
+    --help|-h)
+      sed -n '2,30p' "$0" | sed 's/^# \?//'
+      exit 0
+      ;;
+    *)
+      echo "runtime-health.sh: unknown arg '$1' (try --help)" >&2
+      exit 2
+      ;;
+  esac
+done
+
+# ---------- repo + plugin root resolution ----------
+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)}"
+PREBUILT_DIR="$PLUGIN_ROOT/dev-server/dist/runtime"
+if [ ! -d "$PREBUILT_DIR" ]; then
+  PREBUILT_DIR="$SCRIPT_DIR/../dist/runtime"
+fi
+if [ ! -d "$PREBUILT_DIR" ]; then
+  echo "runtime-health.sh: pre-built runtime dir not found at $PREBUILT_DIR" >&2
+  echo "  (canvas runtime bundles ship in <plugin>/dev-server/dist/runtime/)" >&2
+  exit 1
+fi
+
+# ---------- resolve port from _server.json if not given ----------
+DESIGN_ROOT="$REPO/.design"
+STATE="$DESIGN_ROOT/_server.json"
+if [ -z "$PORT" ]; then
+  if [ ! -f "$STATE" ]; then
+    echo "runtime-health.sh: no --port given and $STATE not found (run server-up.sh first)" >&2
+    exit 1
+  fi
+  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
+[ -z "$PORT" ] && { echo "runtime-health.sh: could not resolve port" >&2; exit 1; }
+
+BASE="http://localhost:$PORT"
+
+# Confirm server alive before probing individual bundles.
+if ! curl -fs "$BASE/_health" >/dev/null 2>&1; then
+  echo "runtime-health.sh: server not responding at $BASE/_health" >&2
+  exit 1
+fi
+
+# ---------- per-bundle probe ----------
+probe_one() {
+  local slug="$1"
+  local disk_size="$2"
+  local url="$BASE/_canvas-runtime/$slug"
+  local served
+  served=$(curl -fs -o /dev/null -w '%{size_download}' "$url" 2>/dev/null) || {
+    echo "✗ $slug — served HTTP error (curl failed for $url)" >&2
+    return 1
+  }
+  # Floor at 256 bytes — any working ESM bundle is bigger than that.
+  if [ "$served" -lt 256 ]; then
+    echo "✗ $slug — served body $served B < 256 B floor (server returned empty)" >&2
+    return 1
+  fi
+  # Threshold ratio: served must be ≥ threshold × disk.
+  # awk handles the fractional math without bc dependency.
+  local ratio
+  ratio=$(awk -v s="$served" -v d="$disk_size" 'BEGIN{ if(d==0){print 0}else{printf "%.3f", s/d} }')
+  local ok
+  ok=$(awk -v r="$ratio" -v t="$THRESHOLD" 'BEGIN{print (r >= t) ? 1 : 0}')
+  if [ "$ok" = "1" ]; then
+    [ $QUIET -eq 0 ] && echo "✓ $slug — $served B / $disk_size B disk (ratio $ratio)" >&2
+    return 0
+  fi
+  echo "✗ $slug — served $served B / $disk_size B disk (ratio $ratio < $THRESHOLD) — defective dynamic build" >&2
+  return 1
+}
+
+FAIL_COUNT=0
+FAIL_LIST=""
+for f in "$PREBUILT_DIR"/*.js; do
+  [ -f "$f" ] || continue
+  SLUG=$(basename "$f")
+  DISK_SIZE=$(wc -c < "$f" | tr -d ' ')
+  if ! probe_one "$SLUG" "$DISK_SIZE"; then
+    FAIL_COUNT=$((FAIL_COUNT + 1))
+    FAIL_LIST="$FAIL_LIST $SLUG"
+  fi
+done
+
+if [ "$FAIL_COUNT" -eq 0 ]; then
+  [ $QUIET -eq 0 ] && echo "✓ runtime-health OK — all bundles match disk pre-built (threshold $THRESHOLD)" >&2
+  exit 0
+fi
+
+echo "" >&2
+echo "✗ runtime-health FAIL — $FAIL_COUNT bundle(s) below threshold:$FAIL_LIST" >&2
+echo "  These bundles look like defective dynamic Bun.build output." >&2
+echo "  The canvas TSX will parse + serve cleanly, but the iframe will throw at runtime." >&2
+
+if [ "$RESTART" -eq 1 ]; then
+  echo "→ --restart given; killing server and respawning via server-up.sh" >&2
+  if [ -f "$STATE" ]; then
+    if command -v jq >/dev/null 2>&1; then
+      PID=$(jq -r .pid "$STATE" 2>/dev/null)
+    else
+      PID=$(sed -nE 's/.*"pid"[[:space:]]*:[[:space:]]*([0-9]+).*/\1/p' "$STATE" | head -n1)
+    fi
+    if [ -n "$PID" ] && kill -0 "$PID" 2>/dev/null; then
+      kill "$PID" 2>/dev/null
+      sleep 1
+      kill -0 "$PID" 2>/dev/null && kill -9 "$PID" 2>/dev/null
+    fi
+    rm -f "$STATE"
+  fi
+  NEW_PORT=$(bash "$SCRIPT_DIR/server-up.sh" --root "$REPO")
+  [ -z "$NEW_PORT" ] && { echo "✗ server-up.sh did not return a port after restart" >&2; exit 3; }
+  echo "→ server restarted port=$NEW_PORT; re-probing once" >&2
+  # Re-probe via tail-recursive invocation with no --restart (avoid infinite loop).
+  bash "$0" --port "$NEW_PORT" --root "$REPO" --threshold "$THRESHOLD" $( [ $QUIET -eq 1 ] && echo --quiet )
+  exit $?
+fi
+
+echo "  Remediation: rerun with --restart, OR manually 'kill $(cat $STATE 2>/dev/null | sed -nE 's/.*pid.*:.*([0-9]+).*/\1/p') && bash $SCRIPT_DIR/server-up.sh'" >&2
+exit 3

package/plugins/design/dev-server/bin/visual-sanity.sh

@@ -0,0 +1,221 @@
+#!/usr/bin/env bash
+# visual-sanity.sh — mandatory post-scaffold visual sanity gate for
+# `/design:setup-ds`. Boots the dev-server (via server-up.sh), screenshots
+# N specimens (via screenshot.sh) into `_history/_system/<ds>-visual-sanity-
+# <ISO>/`, and exits non-zero on any failure so the caller can surface an
+# `AskUserQuestion` ("dev-server boot failed: <reason> — skip visual sanity
+# or fix and retry?"). Never silently elides the gate.
+#
+# Closes D-3 + D-4 in the imprint-bootstrap retro (sparkle overflow + broken
+# relative-URL asset path — both would have been caught by one screenshot read).
+# Spec: `.ai/plans/phase-3.7-setup-ds-hardening-and-motion-subsystem.md` Task 2.
+#
+# Usage:
+#   visual-sanity.sh --ds <ds-name>
+#                    [--specimens "colors-accent,motion,logo"]
+#                    [--root <repo>] [--out-dir <dir>]
+#                    [--boot-timeout 15] [--shot-timeout 5]
+#                    [--engine auto|agent-browser|playwright]
+#
+# Defaults:
+#   --root         "$CLAUDE_PROJECT_DIR" → "$(git rev-parse --show-toplevel)" → cwd
+#   --specimens    "colors-accent,motion,ui_kits-desktop-showcase"
+#                  (signature trio — accent / motion / DS-in-use)
+#                  caller may override with the roster-derived list of actually-
+#                  written specimens to avoid screenshotting files that don't
+#                  exist on the disk yet.
+#   --out-dir      "<root>/.design/_history/_system/<ds>-visual-sanity-<ISO>"
+#   --boot-timeout 15 (server-up.sh polling window, in seconds)
+#   --shot-timeout 5  (screenshot.sh DC-mount poll window per specimen; bare
+#                      DS-preview specimens have no [data-dc-screen] so the
+#                      poll always exhausts — 5s is plenty for the page-load
+#                      settle without burning 15s × N on every gate run)
+#
+# Output: one PNG path per line on stdout (composable in for-loops); the caller
+#         is expected to `Read` each PNG into context so the agent ACTUALLY SEES
+#         what shipped. JSON manifest written alongside as `_manifest.json`.
+# Stderr: diagnostic, engine choice, timing, failure reasons.
+# Exit:
+#   0  success — all specimens screenshot successfully
+#   1  dev-server boot failed   (caller MUST surface AskUserQuestion)
+#   2  bad args
+#   3  one or more specimen screenshots failed
+#   4  no specimens existed on disk (DS not scaffolded? typo?)
+
+DS=""
+SPECIMENS=""
+ROOT=""
+OUT_DIR=""
+BOOT_TIMEOUT=15
+SHOT_TIMEOUT=5
+ENGINE="auto"
+
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --ds)           DS="$2"; shift 2 ;;
+    --specimens)    SPECIMENS="$2"; shift 2 ;;
+    --root)         ROOT="$2"; shift 2 ;;
+    --out-dir)      OUT_DIR="$2"; shift 2 ;;
+    --boot-timeout) BOOT_TIMEOUT="$2"; shift 2 ;;
+    --shot-timeout) SHOT_TIMEOUT="$2"; shift 2 ;;
+    --timeout)      BOOT_TIMEOUT="$2"; SHOT_TIMEOUT="$2"; shift 2 ;;  # legacy
+    --engine)       ENGINE="$2"; shift 2 ;;
+    --help|-h)
+      sed -n '2,33p' "$0" | sed 's/^# \?//'
+      exit 0
+      ;;
+    *)
+      echo "visual-sanity.sh: unknown arg '$1' (try --help)" >&2
+      exit 2
+      ;;
+  esac
+done
+
+if [ -z "$DS" ]; then
+  echo "visual-sanity.sh: --ds <ds-name> required" >&2
+  exit 2
+fi
+
+# Resolve repo root.
+if [ -z "$ROOT" ]; then
+  ROOT="${CLAUDE_PROJECT_DIR:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}"
+fi
+if [ ! -d "$ROOT" ]; then
+  echo "visual-sanity.sh: --root '$ROOT' is not a directory" >&2
+  exit 2
+fi
+ROOT_ABS=$(cd "$ROOT" && pwd)
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+
+DESIGN_ROOT="$ROOT_ABS/.design"
+DS_PREVIEW="$DESIGN_ROOT/system/$DS/preview"
+if [ ! -d "$DS_PREVIEW" ]; then
+  echo "visual-sanity.sh: preview directory not found at $DS_PREVIEW" >&2
+  echo "  (is the DS scaffolded? did you mean a different --ds value?)" >&2
+  exit 4
+fi
+
+# Default specimen list: the signature trio (accent, motion, DS-in-use).
+# Caller can pass a roster-derived list to override.
+if [ -z "$SPECIMENS" ]; then
+  SPECIMENS="colors-accent,motion,ui_kits-desktop-showcase"
+fi
+
+# Filter specimens to those that actually exist on disk — the trio is a
+# default that not every DS will have written (e.g. an early scaffold may
+# not have ui_kits-* yet). Silently skipping a non-existent specimen is OK;
+# the caller logs which ones we attempted vs. captured.
+declare -a EXISTING=()
+declare -a MISSING=()
+IFS=',' read -r -a SPEC_ARR <<< "$SPECIMENS"
+for s in "${SPEC_ARR[@]}"; do
+  s_trim=$(echo "$s" | tr -d '[:space:]')
+  [ -z "$s_trim" ] && continue
+  if [ -f "$DS_PREVIEW/${s_trim}.tsx" ]; then
+    EXISTING+=("$s_trim")
+  else
+    MISSING+=("$s_trim")
+  fi
+done
+if [ ${#EXISTING[@]} -eq 0 ]; then
+  echo "visual-sanity.sh: none of the requested specimens exist on disk under $DS_PREVIEW" >&2
+  printf '  missing: %s\n' "${MISSING[@]}" >&2
+  exit 4
+fi
+if [ ${#MISSING[@]} -gt 0 ]; then
+  echo "visual-sanity.sh: skipping ${#MISSING[@]} non-existent specimen(s): ${MISSING[*]}" >&2
+fi
+
+# ISO-like timestamp safe for filenames (no colons / spaces).
+TS=$(date -u +"%Y%m%dT%H%M%SZ")
+
+if [ -z "$OUT_DIR" ]; then
+  OUT_DIR="$DESIGN_ROOT/_history/_system/${DS}-visual-sanity-${TS}"
+fi
+mkdir -p "$OUT_DIR"
+
+# Step 1 — boot the dev-server. Failure here is fatal: the caller MUST surface
+# AskUserQuestion ("dev-server boot failed: <reason>; skip visual sanity or
+# fix and retry?") rather than silently skipping the gate.
+echo "→ booting dev-server (timeout ${BOOT_TIMEOUT}s)" >&2
+PORT=$(bash "$SCRIPT_DIR/server-up.sh" --root "$ROOT_ABS" --timeout "$BOOT_TIMEOUT")
+SERVER_RC=$?
+if [ $SERVER_RC -ne 0 ] || [ -z "$PORT" ]; then
+  echo "✗ dev-server boot failed (server-up.sh exit $SERVER_RC); see $DESIGN_ROOT/_server.log" >&2
+  cat > "$OUT_DIR/_manifest.json" <<EOF
+{
+  "ds": "$DS",
+  "ts": "$TS",
+  "status": "server-boot-failed",
+  "server_up_rc": $SERVER_RC,
+  "specimens_requested": $(printf '%s\n' "${SPEC_ARR[@]}" | sed 's/^[[:space:]]*//;s/[[:space:]]*$//' | sed '/^$/d' | sed 's/.*/"&"/' | paste -sd, -),
+  "specimens_captured": []
+}
+EOF
+  exit 1
+fi
+echo "✓ dev-server on port $PORT" >&2
+
+# Step 2 — screenshot each existing specimen. Track captures vs failures.
+declare -a CAPTURED=()
+declare -a FAILED=()
+for s in "${EXISTING[@]}"; do
+  REL="system/$DS/preview/${s}.tsx"
+  REL_ENC=$(printf '%s' "$REL" | sed 's/ /%20/g')
+  URL="http://localhost:${PORT}/_canvas-shell.html?canvas=${REL_ENC}"
+  OUT_PNG="$OUT_DIR/${s}.png"
+  echo "→ screenshot: $s" >&2
+  if bash "$SCRIPT_DIR/screenshot.sh" \
+        --url "$URL" \
+        --full \
+        --out "$OUT_PNG" \
+        --engine "$ENGINE" \
+        --timeout "$SHOT_TIMEOUT" >&2; then
+    echo "$OUT_PNG"
+    CAPTURED+=("$s")
+  else
+    echo "✗ screenshot failed: $s" >&2
+    FAILED+=("$s")
+  fi
+done
+
+# Step 3 — write manifest. Caller can parse this to know what was captured
+# without re-listing the directory.
+json_arr() {
+  # Print a JSON array literal from positional args. Empty → "[]".
+  if [ $# -eq 0 ]; then printf '[]'; return; fi
+  printf '['
+  i=0
+  for a in "$@"; do
+    if [ $i -gt 0 ]; then printf ', '; fi
+    printf '"%s"' "$a"
+    i=$((i + 1))
+  done
+  printf ']'
+}
+
+STATUS="ok"
+[ ${#FAILED[@]} -gt 0 ] && STATUS="partial-failure"
+
+{
+  printf '{\n'
+  printf '  "ds": "%s",\n' "$DS"
+  printf '  "ts": "%s",\n' "$TS"
+  printf '  "status": "%s",\n' "$STATUS"
+  printf '  "port": %s,\n' "$PORT"
+  printf '  "out_dir": "%s",\n' "$OUT_DIR"
+  printf '  "specimens_requested": %s,\n' "$(json_arr "${SPEC_ARR[@]}")"
+  printf '  "specimens_captured":  %s,\n' "$(json_arr "${CAPTURED[@]}")"
+  printf '  "specimens_missing":   %s,\n' "$(json_arr "${MISSING[@]}")"
+  printf '  "specimens_failed":    %s\n' "$(json_arr "${FAILED[@]}")"
+  printf '}\n'
+} > "$OUT_DIR/_manifest.json"
+
+echo "→ manifest: $OUT_DIR/_manifest.json" >&2
+
+if [ ${#FAILED[@]} -gt 0 ]; then
+  echo "✗ ${#FAILED[@]}/${#EXISTING[@]} specimen(s) failed to capture: ${FAILED[*]}" >&2
+  exit 3
+fi
+exit 0