start-vibing 4.3.1 → 4.3.3

package/template/.claude/skills/super-design/scripts/score-typeui.mjs

@@ -0,0 +1,224 @@
+#!/usr/bin/env node
+// score-typeui.mjs — rank typeui-* skills by fit against a site fingerprint.
+//
+// Usage:
+//   node score-typeui.mjs <fingerprint.json> [--top 3]
+//   node score-typeui.mjs --from-audit <audit-dir>         # derive fingerprint from sd-audit findings + DIS
+//   node score-typeui.mjs --list                            # list available typeui skills with axes
+//
+// Fingerprint input (JSON):
+//   { density: "low|medium|high", contrast: "low|medium|high",
+//     geometry: "round|square|mixed", color: "muted|vibrant|bold",
+//     typography: "neutral|expressive|display", motion: "static|subtle|dynamic",
+//     audience: "enterprise|developer|consumer|creative" }
+//
+// Output (stdout): JSON { ranked: [{ name, fit, reasons, applies_tokens }] }
+
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+
+const AXES = ['density', 'contrast', 'geometry', 'color', 'typography', 'motion', 'audience'];
+
+// Static fingerprint matrix — derived from each typeui SKILL.md style foundations.
+// Keep in sync with skills at ~/.claude/skills/typeui-*/SKILL.md. Expand via harvest-typeui.sh.
+const TYPEUI = {
+  ant: {
+    density: 'high', contrast: 'medium', geometry: 'square',
+    color: 'muted', typography: 'neutral', motion: 'static', audience: 'enterprise',
+    tokens: { primary: '#1677ff', radius: 6, spacing: [4, 8, 12, 16, 24, 32] },
+    summary: 'Structured, enterprise-focused design. Data-dense tables, forms.',
+  },
+  application: {
+    density: 'medium', contrast: 'high', geometry: 'round',
+    color: 'vibrant', typography: 'neutral', motion: 'subtle', audience: 'developer',
+    tokens: { primary: '#9333ea', radius: 8, spacing: [4, 8, 12, 16, 24, 32] },
+    summary: 'Vercel/GitHub purple aesthetic. Top-bar nav, card layouts.',
+  },
+  artistic: {
+    density: 'low', contrast: 'high', geometry: 'mixed',
+    color: 'bold', typography: 'expressive', motion: 'dynamic', audience: 'creative',
+    tokens: { primary: '#000000', radius: 0, spacing: [8, 16, 24, 40, 64, 96] },
+    summary: 'High-contrast, expressive. Creative typography, bold color.',
+  },
+  bento: {
+    density: 'medium', contrast: 'medium', geometry: 'round',
+    color: 'muted', typography: 'neutral', motion: 'subtle', audience: 'consumer',
+    tokens: { primary: '#0ea5e9', radius: 16, spacing: [8, 16, 24, 32, 48, 64] },
+    summary: 'Modular grid of card-blocks. Clear hierarchy, soft spacing.',
+  },
+  bold: {
+    density: 'low', contrast: 'high', geometry: 'square',
+    color: 'bold', typography: 'display', motion: 'dynamic', audience: 'consumer',
+    tokens: { primary: '#111111', radius: 4, spacing: [8, 16, 24, 48, 80, 128] },
+    summary: 'Strong visual presence. Heavyweight type, high-contrast.',
+  },
+  clean: {
+    density: 'low', contrast: 'medium', geometry: 'round',
+    color: 'muted', typography: 'neutral', motion: 'static', audience: 'consumer',
+    tokens: { primary: '#18181b', radius: 8, spacing: [8, 16, 24, 32, 48, 72] },
+    summary: 'Simplicity-focused. Whitespace, legible type, limited palette.',
+  },
+  dashboard: {
+    density: 'high', contrast: 'high', geometry: 'round',
+    color: 'vibrant', typography: 'neutral', motion: 'subtle', audience: 'developer',
+    tokens: { primary: '#3b82f6', radius: 6, spacing: [4, 8, 12, 16, 24, 32] },
+    summary: 'Dark cloud-platform. Modular grids, glass panels, data hierarchy.',
+  },
+  doodle: {
+    density: 'low', contrast: 'medium', geometry: 'mixed',
+    color: 'vibrant', typography: 'expressive', motion: 'dynamic', audience: 'creative',
+    tokens: { primary: '#f59e0b', radius: 12, spacing: [8, 16, 24, 40, 64, 96] },
+    summary: 'Hand-drawn, sketch-like. Doodles, handwritten fonts.',
+  },
+  dramatic: {
+    density: 'low', contrast: 'high', geometry: 'mixed',
+    color: 'bold', typography: 'display', motion: 'dynamic', audience: 'creative',
+    tokens: { primary: '#dc2626', radius: 0, spacing: [16, 32, 48, 80, 128, 200] },
+    summary: 'Theatrical. Bold layouts, immersive visuals, unconventional.',
+  },
+  enterprise: {
+    density: 'high', contrast: 'high', geometry: 'square',
+    color: 'muted', typography: 'neutral', motion: 'static', audience: 'enterprise',
+    tokens: { primary: '#0f172a', radius: 4, spacing: [4, 8, 12, 16, 24, 32] },
+    summary: 'Clean, high-contrast enterprise. Drag-drop, structured layouts.',
+  },
+  neobrutalism: {
+    density: 'medium', contrast: 'high', geometry: 'square',
+    color: 'bold', typography: 'display', motion: 'subtle', audience: 'creative',
+    tokens: { primary: '#ffd700', radius: 0, spacing: [8, 16, 24, 32, 48, 64] },
+    summary: 'Bold borders, vivid accents, raw high-contrast on warm surfaces.',
+  },
+  paper: {
+    density: 'medium', contrast: 'medium', geometry: 'round',
+    color: 'muted', typography: 'expressive', motion: 'static', audience: 'consumer',
+    tokens: { primary: '#78350f', radius: 4, spacing: [8, 16, 24, 32, 48, 64] },
+    summary: 'Paper-textured, print-inspired. Serif/sans, tactile.',
+  },
+};
+
+// Axis weights — density/contrast/geometry dominate; audience is secondary.
+const WEIGHTS = {
+  density: 0.22, contrast: 0.18, geometry: 0.16, color: 0.14,
+  typography: 0.12, motion: 0.10, audience: 0.08,
+};
+
+function matchScore(a, b) {
+  if (a === b) return 1.0;
+  const pairs = {
+    'low|medium': 0.5, 'medium|high': 0.5,
+    'muted|vibrant': 0.5, 'vibrant|bold': 0.5,
+    'neutral|expressive': 0.5, 'expressive|display': 0.5,
+    'static|subtle': 0.5, 'subtle|dynamic': 0.5,
+    'round|mixed': 0.6, 'square|mixed': 0.6,
+  };
+  const key = [a, b].sort().join('|');
+  return pairs[key] ?? 0;
+}
+
+function scoreFor(fp, typeui) {
+  let total = 0;
+  const reasons = [];
+  for (const axis of AXES) {
+    const fpv = fp[axis];
+    const tuv = typeui[axis];
+    if (!fpv || !tuv) continue;
+    const s = matchScore(fpv, tuv);
+    total += s * WEIGHTS[axis];
+    if (s >= 0.5) reasons.push(`${axis}:${tuv}`);
+  }
+  return { fit: Math.round(total * 100) / 100, reasons };
+}
+
+function rank(fp, topN = 3) {
+  const scored = Object.entries(TYPEUI).map(([name, tu]) => ({
+    name: `typeui-${name}`,
+    ...scoreFor(fp, tu),
+    applies_tokens: tu.tokens,
+    summary: tu.summary,
+  }));
+  scored.sort((a, b) => b.fit - a.fit);
+  return scored.slice(0, topN);
+}
+
+// Derive fingerprint from sd-audit findings.json + design-intelligence.json.
+function fingerprintFromAudit(auditDir) {
+  const fp = {};
+  const diPath = path.join(auditDir, 'design-intelligence.json');
+  const fPath = path.join(auditDir, 'findings.json');
+  if (!fs.existsSync(diPath)) {
+    throw new Error(`design-intelligence.json not found in ${auditDir}`);
+  }
+  const di = JSON.parse(fs.readFileSync(diPath, 'utf8'));
+  const findings = fs.existsSync(fPath) ? JSON.parse(fs.readFileSync(fPath, 'utf8')) : [];
+
+  const scores = di.per_page?.[0]?.categories || di.categories || {};
+  const s = (k) => scores[k]?.score ?? scores[k] ?? 5;
+
+  // Density: C1 density + C11 information scent
+  const densityScore = (s('C1') + s('C11')) / 2;
+  fp.density = densityScore >= 7 ? 'high' : densityScore >= 4 ? 'medium' : 'low';
+
+  // Contrast: C6 contrast (inverse — low craft = low contrast detected)
+  fp.contrast = s('C6') >= 7 ? 'high' : s('C6') >= 4 ? 'medium' : 'low';
+
+  // Geometry: C14 border-radius variance (heuristic)
+  const radiusVar = di.summary?.radius_variance ?? 0;
+  fp.geometry = radiusVar > 8 ? 'mixed' : radiusVar > 2 ? 'round' : 'square';
+
+  // Color: C5 palette saturation
+  const satScore = di.summary?.color_saturation ?? 0.5;
+  fp.color = satScore > 0.7 ? 'bold' : satScore > 0.4 ? 'vibrant' : 'muted';
+
+  // Typography: C7 type scale variance
+  const typeVariance = di.summary?.type_variance ?? 0.5;
+  fp.typography = typeVariance > 0.7 ? 'display' : typeVariance > 0.4 ? 'expressive' : 'neutral';
+
+  // Motion: C13 motion/transitions
+  fp.motion = s('C13') >= 7 ? 'dynamic' : s('C13') >= 4 ? 'subtle' : 'static';
+
+  // Audience: inferred from findings categories — best-effort
+  const mobileCount = findings.filter((f) => f.id?.startsWith('M')).length;
+  const dataCount = findings.filter((f) => /table|dense|data/i.test(f.quote || '')).length;
+  fp.audience = dataCount > mobileCount ? 'enterprise' : 'consumer';
+
+  return fp;
+}
+
+function listSkills() {
+  return Object.entries(TYPEUI).map(([name, tu]) => ({
+    name: `typeui-${name}`,
+    axes: AXES.reduce((o, a) => ({ ...o, [a]: tu[a] }), {}),
+    summary: tu.summary,
+  }));
+}
+
+// CLI
+const args = process.argv.slice(2);
+if (args.includes('--list')) {
+  console.log(JSON.stringify(listSkills(), null, 2));
+  process.exit(0);
+}
+
+let fp;
+let topN = 3;
+const topIdx = args.indexOf('--top');
+if (topIdx >= 0) topN = parseInt(args[topIdx + 1], 10) || 3;
+
+const fromAuditIdx = args.indexOf('--from-audit');
+if (fromAuditIdx >= 0) {
+  const dir = args[fromAuditIdx + 1];
+  if (!dir) {
+    console.error('--from-audit requires a directory path');
+    process.exit(2);
+  }
+  fp = fingerprintFromAudit(dir);
+} else if (args[0] && fs.existsSync(args[0])) {
+  fp = JSON.parse(fs.readFileSync(args[0], 'utf8'));
+} else {
+  console.error('Usage: score-typeui.mjs <fingerprint.json> | --from-audit <dir> | --list');
+  process.exit(2);
+}
+
+const ranked = rank(fp, topN);
+console.log(JSON.stringify({ fingerprint: fp, ranked }, null, 2));

package/template/.claude/skills/super-design/scripts/validate-state.sh

@@ -1,33 +1,64 @@
 #!/usr/bin/env bash
-# Usage: validate-state.sh [<state_path>]
+# Usage: validate-state.sh [<app_path_or_state_path>]
 #
 # Validates the super-design audit state file. On schema/parse errors,
 # moves the broken file aside (artifact §3 "Graceful corruption handling"
 # line 74) and emits a JSON verdict. Also enforces schema_version major
 # compatibility (artifact §12 line 934).
+#
+# Monorepo support (artifact §11 line 902): the positional arg is the
+# app root (e.g. `apps/web`); state is looked up at
+# `<app_path>/docs/super-design/.audit-state.json`. For single-app
+# repos pass "." or omit (default behavior preserved). Back-compat: if
+# the arg ends in `.audit-state.json` it is used verbatim.
+#
+# Validation strategy:
+#   1. If `ajv` is on PATH, validate against audit-state.schema.json
+#      (draft-07 canonical schema, task #18).
+#   2. Otherwise fall back to the inline jq shape check that existed
+#      pre-schema. Same corrupt-rename behavior in both paths.
 set -euo pipefail
-STATE="${1:-docs/super-design/.audit-state.json}"
+ARG="${1:-.}"
+case "$ARG" in
+  *.audit-state.json) STATE="$ARG" ;;
+  .|"")              STATE="docs/super-design/.audit-state.json" ;;
+  *)                 STATE="${ARG%/}/docs/super-design/.audit-state.json" ;;
+esac
+SKILL_DIR="$(cd "$(dirname "$0")/.." && pwd)"
+SCHEMA="$SKILL_DIR/audit-state.schema.json"
 
 # Current schema major is either read from a sibling .schema-version file
 # (so the number can be bumped without editing shell) or falls back to 1.
-SCHEMA_VERSION_FILE="$(dirname "$0")/../.schema-version"
-if [[ -f "$SCHEMA_VERSION_FILE" ]]; then
+SCHEMA_VERSION_FILE="$SKILL_DIR/.schema-version"
+if [ -f "$SCHEMA_VERSION_FILE" ]; then
   CURRENT_SCHEMA_MAJOR="$(cut -d. -f1 <"$SCHEMA_VERSION_FILE" | tr -d '[:space:]')"
 else
   CURRENT_SCHEMA_MAJOR=1
 fi
 
-if [[ ! -f "$STATE" ]]; then echo '{"status":"missing"}'; exit 2; fi
+if [ ! -f "$STATE" ]; then echo '{"status":"missing"}'; exit 2; fi
 
 # Parse + shape check. On failure, rename so the user can inspect and we
 # fall through to first-audit (SKILL.md Step 1 treats "corrupt" that way).
-if ! jq -e '
-  (.schema_version | type == "string") and
-  (.last_audit_at  | fromdateiso8601 | . > 0) and
-  (.git_sha_at_audit | test("^[0-9a-f]{7,64}$")) and
-  (.skill_version  | type == "string") and
-  (.tools | type == "object")
-' "$STATE" >/dev/null 2>&1; then
+schema_ok=1
+if command -v ajv >/dev/null 2>&1 && [ -f "$SCHEMA" ]; then
+  if ! ajv validate -s "$SCHEMA" -d "$STATE" --errors=text >/dev/null 2>&1; then
+    schema_ok=0
+  fi
+else
+  # Fallback: inline jq shape check (pre-schema behavior).
+  if ! jq -e '
+    (.schema_version | type == "string") and
+    (.last_audit_at  | fromdateiso8601 | . > 0) and
+    (.git_sha_at_audit | test("^[0-9a-f]{7,64}$")) and
+    (.skill_version  | type == "string") and
+    (.tools | type == "object")
+  ' "$STATE" >/dev/null 2>&1; then
+    schema_ok=0
+  fi
+fi
+
+if [ "$schema_ok" -eq 0 ]; then
   mv "$STATE" "$STATE.corrupt-$(date +%s)" 2>/dev/null || true
   echo '{"status":"corrupt"}'; exit 2
 fi
@@ -36,12 +67,12 @@ fi
 # incompatible-older skill, force a full re-audit rather than silently
 # trusting the shape.
 STATE_MAJOR="$(jq -r '.schema_version' "$STATE" | cut -d. -f1)"
-if [[ -z "$STATE_MAJOR" || "$STATE_MAJOR" != "$CURRENT_SCHEMA_MAJOR" ]]; then
+if [ -z "$STATE_MAJOR" ] || [ "$STATE_MAJOR" != "$CURRENT_SCHEMA_MAJOR" ]; then
   echo "{\"status\":\"schema-incompatible\",\"action\":\"force-full\",\"state_major\":\"${STATE_MAJOR:-unknown}\",\"current_major\":\"${CURRENT_SCHEMA_MAJOR}\"}"
   exit 1
 fi
 
 AGE_DAYS=$(( ( $(date -u +%s) - $(jq -r '.last_audit_at | fromdateiso8601' "$STATE") ) / 86400 ))
-if (( AGE_DAYS > 180 )); then echo "{\"status\":\"stale-force-full\",\"age_days\":$AGE_DAYS}"; exit 1
-elif (( AGE_DAYS > 90 )); then echo "{\"status\":\"stale-refresh-research\",\"age_days\":$AGE_DAYS}"; exit 1
+if [ "$AGE_DAYS" -gt 180 ]; then echo "{\"status\":\"stale-force-full\",\"age_days\":$AGE_DAYS}"; exit 1
+elif [ "$AGE_DAYS" -gt 90 ]; then echo "{\"status\":\"stale-refresh-research\",\"age_days\":$AGE_DAYS}"; exit 1
 else echo "{\"status\":\"fresh\",\"age_days\":$AGE_DAYS}"; exit 0; fi

package/template/.claude/skills/super-design/scripts/verify-audit.sh

@@ -1,19 +1,72 @@
 #!/usr/bin/env bash
+# Usage: verify-audit.sh [--strict] <session_dir>
+#
+# Verifies the artifacts produced by an sd-audit session:
+#   1. .audit-state.json exists and passes validate-state.sh
+#      (so the schema task #18 schema is actually enforced end-to-end).
+#   2. findings.json exists and parses as a JSON array.
+#   3. Every finding has a SHOT (screenshot_path) + SNAP (snapshot_path)
+#      that resolves to a non-empty file on disk.
+#   4. Every finding's snapshot_quote appears verbatim in its snapshot.
+#
+# Exit codes:
+#   0  OK (no errors, no warnings — or warnings present without --strict)
+#   1  non-fatal warning in --strict mode, or verification failure
+#   2  missing prerequisites (session dir / findings.json)
 set -euo pipefail
-SESSION_DIR="${1:?usage: verify-audit.sh <session_dir>}"
+
+STRICT=0
+if [ "${1:-}" = "--strict" ]; then STRICT=1; shift; fi
+
+SESSION_DIR="${1:?usage: verify-audit.sh [--strict] <session_dir>}"
 FINDINGS="$SESSION_DIR/findings.json"
-if [[ ! -f "$FINDINGS" ]]; then echo "FATAL: no findings.json at $FINDINGS" >&2; exit 2; fi
+SKILL_DIR="$(cd "$(dirname "$0")/.." && pwd)"
+VALIDATE="$SKILL_DIR/scripts/validate-state.sh"
+STATE="${AUDIT_STATE:-docs/super-design/.audit-state.json}"
+
+WARNINGS=0
+warn() { echo "WARN: $*" >&2; WARNINGS=$((WARNINGS + 1)); }
 
-jq -r '.[] | [.id, .screenshot_path, .snapshot_path] | @tsv' "$FINDINGS" | while IFS=$'\t' read -r id shot snap; do
-  if [[ ! -s "$shot" ]]; then echo "FAIL $id: missing/empty screenshot $shot" >&2; exit 1; fi
-  if [[ ! -s "$snap" ]]; then echo "FAIL $id: missing/empty snapshot $snap" >&2; exit 1; fi
+# 1. State file schema check — non-fatal (state may live outside session
+#    dir, or may legitimately be absent on first run). In --strict mode
+#    any anomaly counts as a warning.
+if [ ! -f "$STATE" ]; then
+  warn "no audit state at $STATE (first audit? expected on CI)"
+else
+  if ! bash "$VALIDATE" "$STATE" >/dev/null 2>&1; then
+    warn "validate-state.sh rejected $STATE (schema drift or stale)"
+  fi
+fi
+
+# 2. findings.json must exist and parse.
+if [ ! -f "$FINDINGS" ]; then
+  echo "FATAL: no findings.json at $FINDINGS" >&2; exit 2
+fi
+if ! jq -e 'type == "array"' "$FINDINGS" >/dev/null 2>&1; then
+  echo "FATAL: $FINDINGS is not a JSON array" >&2; exit 1
+fi
+
+# 3. Every referenced screenshot/snapshot resolves to a non-empty file.
+jq -r '.[] | [.id, .screenshot_path, .snapshot_path] | @tsv' "$FINDINGS" | \
+while IFS=$'\t' read -r id shot snap; do
+  if [ ! -s "$shot" ]; then echo "FAIL $id: missing/empty screenshot $shot" >&2; exit 1; fi
+  if [ ! -s "$snap" ]; then echo "FAIL $id: missing/empty snapshot $snap" >&2; exit 1; fi
 done
 
+# 4. snapshot_quote must appear verbatim in the snapshot.
 jq -c '.[]' "$FINDINGS" | while read -r f; do
   id=$(echo "$f" | jq -r .id)
-  q=$(echo "$f" | jq -r .snapshot_quote)
-  s=$(echo "$f" | jq -r .snapshot_path)
-  if ! grep -qF "$q" "$s"; then echo "FAIL $id: quote not found verbatim in $s" >&2; exit 1; fi
+  q=$(echo "$f"  | jq -r .snapshot_quote)
+  s=$(echo "$f"  | jq -r .snapshot_path)
+  if ! grep -qF "$q" "$s"; then
+    echo "FAIL $id: quote not found verbatim in $s" >&2; exit 1
+  fi
 done
 
-echo "OK: $(jq 'length' "$FINDINGS") findings verified"
+COUNT=$(jq 'length' "$FINDINGS")
+if [ "$STRICT" -eq 1 ] && [ "$WARNINGS" -gt 0 ]; then
+  echo "STRICT: $COUNT findings verified, $WARNINGS warning(s)" >&2
+  exit 1
+fi
+
+echo "OK: $COUNT findings verified${WARNINGS:+ ($WARNINGS warning(s))}"

package/template/.claude/skills/super-design/scripts/visual-regression.sh

@@ -0,0 +1,275 @@
+#!/usr/bin/env bash
+# Usage: visual-regression.sh [--update-baselines] [<state_file>]
+#
+# Expected `.audit-state.json` `visual_regression` block (artifact §16
+# lines 1367-1384). Kept inline here so the script self-documents the
+# schema shape when audit-state.schema.json is not yet present.
+#
+#   "visual_regression": {
+#     "enabled": true,
+#     "engine": "pixelmatch",            // pixelmatch | odiff | sha256-fallback
+#     "threshold": 0.1,                  // per-pixel YIQ (pixelmatch/odiff)
+#     "max_diff_pixel_ratio": 0.01,      // 1% pixels allowed
+#     "antialiasing": true,
+#     "viewports": [
+#       { "label": "mobile_375",  "width": 375,  "height": 667  },
+#       { "label": "tablet_768",  "width": 768,  "height": 1024 },
+#       { "label": "desktop_1280","width": 1280, "height": 800  }
+#     ],
+#     "mask_selectors": [
+#       "[data-timestamp]", ".relative-time",
+#       "[data-react-hydration]", "video", "canvas"
+#     ],
+#     "baseline_dir": ".super-design/baselines",
+#     "current_dir":  "docs/super-design/.cache/hashes/screenshots",
+#     "diff_dir":     "docs/super-design/.cache/hashes/diffs"
+#   }
+#
+# Runner behaviour:
+# - Reads the block from .audit-state.json (default path overridable via
+#   positional arg).
+# - For every (page, viewport) it finds a current screenshot for, locates
+#   the matching baseline PNG, runs the configured diff engine, emits
+#   {page, viewport, diff_ratio, threshold, pass, diff_image_path} into
+#   <diff_dir>/results.json.
+# - Engine fallback chain: pixelmatch (npx) → odiff (npx) → sha256
+#   equality (logs warning on stderr).
+# - --update-baselines replaces every baseline with the current capture
+#   and exits without diffing.
+#
+# POSIX sh + node; runs under Windows git-bash.
+set -euo pipefail
+
+UPDATE_BASELINES=0
+STATE="docs/super-design/.audit-state.json"
+while (( $# )); do
+  case "$1" in
+    --update-baselines) UPDATE_BASELINES=1 ;;
+    -h|--help)
+      grep '^#' "$0" | sed 's/^# \{0,1\}//'
+      exit 0
+      ;;
+    *) STATE="$1" ;;
+  esac
+  shift
+done
+
+if [[ ! -f "$STATE" ]]; then
+  echo '{"status":"missing-state","hint":"run audit first"}' >&2
+  exit 2
+fi
+
+# Defaults match artifact §16. jq pulls the override from state, if any.
+CFG="$(jq -c '.visual_regression // {}' "$STATE")"
+ENABLED="$(jq -r '.enabled // false' <<<"$CFG")"
+if [[ "$ENABLED" != "true" && "$UPDATE_BASELINES" -ne 1 ]]; then
+  echo '{"status":"disabled","hint":"set visual_regression.enabled=true"}'
+  exit 0
+fi
+
+BASELINE_DIR="$(jq -r '.baseline_dir // ".super-design/baselines"' <<<"$CFG")"
+CURRENT_DIR="$(jq -r '.current_dir  // "docs/super-design/.cache/hashes/screenshots"' <<<"$CFG")"
+DIFF_DIR="$(jq -r    '.diff_dir     // "docs/super-design/.cache/hashes/diffs"' <<<"$CFG")"
+ENGINE="$(jq -r      '.engine       // "pixelmatch"' <<<"$CFG")"
+THRESHOLD="$(jq -r   '.threshold    // 0.1' <<<"$CFG")"
+MAX_RATIO="$(jq -r   '.max_diff_pixel_ratio // 0.01' <<<"$CFG")"
+ANTIALIAS="$(jq -r   '.antialiasing // true' <<<"$CFG")"
+
+mkdir -p "$BASELINE_DIR" "$DIFF_DIR"
+
+# Enumerate current screenshots the hash-pages.sh pass wrote under
+# <current_dir>/<url-encoded-url>/<viewport>.png.
+if [[ ! -d "$CURRENT_DIR" ]]; then
+  echo "{\"status\":\"no-screenshots\",\"hint\":\"run hash-pages.sh first\",\"looked_in\":\"$CURRENT_DIR\"}" >&2
+  exit 2
+fi
+
+# --update-baselines: mirror current -> baseline and exit.
+if [[ "$UPDATE_BASELINES" -eq 1 ]]; then
+  copied=0
+  while IFS= read -r -d '' png; do
+    rel="${png#$CURRENT_DIR/}"
+    dst="$BASELINE_DIR/$rel"
+    mkdir -p "$(dirname "$dst")"
+    cp -f "$png" "$dst"
+    copied=$((copied + 1))
+  done < <(find "$CURRENT_DIR" -type f -name '*.png' -print0)
+  echo "{\"status\":\"baselines-updated\",\"count\":$copied,\"baseline_dir\":\"$BASELINE_DIR\"}"
+  exit 0
+fi
+
+# Resolve engine availability up-front so we warn once rather than per page.
+resolve_engine() {
+  local want="$1"
+  case "$want" in
+    pixelmatch)
+      if command -v npx >/dev/null 2>&1; then
+        if npx --yes pixelmatch --help >/dev/null 2>&1; then echo pixelmatch; return; fi
+      fi
+      ;;
+    odiff)
+      if command -v npx >/dev/null 2>&1; then
+        if npx --yes odiff-bin --help >/dev/null 2>&1; then echo odiff; return; fi
+      fi
+      ;;
+  esac
+  # Chain: pixelmatch > odiff > sha256.
+  if command -v npx >/dev/null 2>&1; then
+    if npx --yes pixelmatch --help >/dev/null 2>&1; then echo pixelmatch; return; fi
+    if npx --yes odiff-bin --help  >/dev/null 2>&1; then echo odiff;      return; fi
+  fi
+  echo sha256-fallback
+}
+
+RESOLVED_ENGINE="$(resolve_engine "$ENGINE")"
+if [[ "$RESOLVED_ENGINE" == "sha256-fallback" ]]; then
+  echo "warning: pixelmatch/odiff unavailable; falling back to sha256 equality (binary pass/fail, diff_ratio will be 0 or 1)" >&2
+fi
+
+# Per-comparison worker. Runs in a node one-shot because pixelmatch /
+# odiff are both invoked there; sha256 fallback is pure node too.
+compare_pair() {
+  local baseline="$1"
+  local current="$2"
+  local diff_out="$3"
+
+  BASE="$baseline" CURR="$current" DIFF="$diff_out" \
+  ENGINE="$RESOLVED_ENGINE" THRESHOLD="$THRESHOLD" \
+  ANTIALIAS="$ANTIALIAS" \
+  node --experimental-vm-modules <<'JS'
+import { createHash } from "node:crypto";
+import { readFileSync, existsSync, writeFileSync, mkdirSync } from "node:fs";
+import { dirname } from "node:path";
+import { spawnSync } from "node:child_process";
+
+const base = process.env.BASE;
+const curr = process.env.CURR;
+const diffPath = process.env.DIFF;
+const engine = process.env.ENGINE;
+const threshold = Number(process.env.THRESHOLD);
+const antialias = process.env.ANTIALIAS === "true";
+
+mkdirSync(dirname(diffPath), { recursive: true });
+
+function sha(buf) { return createHash("sha256").update(buf).digest("hex"); }
+
+if (!existsSync(base)) {
+  console.log(JSON.stringify({
+    pass: false, diff_ratio: 1, reason: "baseline-missing",
+    engine, diff_image_path: null,
+  }));
+  process.exit(0);
+}
+
+if (engine === "sha256-fallback") {
+  const bHash = sha(readFileSync(base));
+  const cHash = sha(readFileSync(curr));
+  const ratio = bHash === cHash ? 0 : 1;
+  console.log(JSON.stringify({
+    pass: ratio === 0, diff_ratio: ratio, engine,
+    diff_image_path: null,
+  }));
+  process.exit(0);
+}
+
+if (engine === "pixelmatch") {
+  // npx pixelmatch <baseline> <current> <diff> [threshold]
+  const r = spawnSync("npx", [
+    "--yes", "pixelmatch", base, curr, diffPath, String(threshold),
+  ], { encoding: "utf8", shell: process.platform === "win32" });
+  // pixelmatch prints e.g. "error: 123 different pixels\n" to stdout.
+  // total-pixels isn't emitted, so we read PNG dimensions from the diff
+  // header (the diff PNG is always produced even on zero-diff).
+  const diffPixels = Number((r.stdout.match(/(\d+)\s+different/) || [0, 0])[1]);
+  let total = 1;
+  if (existsSync(diffPath)) {
+    const buf = readFileSync(diffPath);
+    // PNG width/height live at bytes 16..23 big-endian.
+    if (buf.length >= 24 && buf[0] === 0x89 && buf[1] === 0x50) {
+      const w = buf.readUInt32BE(16);
+      const h = buf.readUInt32BE(20);
+      total = Math.max(1, w * h);
+    }
+  }
+  const ratio = diffPixels / total;
+  console.log(JSON.stringify({
+    pass: null, // decided by caller against max_diff_pixel_ratio
+    diff_ratio: ratio, diff_pixels: diffPixels, total_pixels: total,
+    engine, diff_image_path: diffPath,
+    exit: r.status, stderr: (r.stderr || "").trim().slice(0, 500),
+  }));
+  process.exit(0);
+}
+
+if (engine === "odiff") {
+  // odiff-bin <baseline> <current> <diff> --threshold=<t>
+  const args = [
+    "--yes", "odiff-bin", base, curr, diffPath,
+    `--threshold=${threshold}`,
+  ];
+  if (!antialias) args.push("--antialiasing");
+  const r = spawnSync("npx", args, {
+    encoding: "utf8", shell: process.platform === "win32",
+  });
+  const matchRatio = (r.stdout + r.stderr).match(/(\d+(?:\.\d+)?)\s*%/);
+  const pctDiff = matchRatio ? Number(matchRatio[1]) / 100 : (r.status === 0 ? 0 : 1);
+  console.log(JSON.stringify({
+    pass: null,
+    diff_ratio: pctDiff,
+    engine, diff_image_path: diffPath,
+    exit: r.status, stderr: (r.stderr || "").trim().slice(0, 500),
+  }));
+  process.exit(0);
+}
+
+// Unknown engine — surface as a hard failure rather than silent pass.
+console.log(JSON.stringify({
+  pass: false, diff_ratio: 1,
+  reason: `unknown-engine:${engine}`, engine, diff_image_path: null,
+}));
+JS
+}
+
+results="[]"
+any_fail=0
+while IFS= read -r -d '' curr_png; do
+  rel="${curr_png#$CURRENT_DIR/}"             # e.g. https%3A%2F%2F.../mobile_375.png
+  page_dir="$(dirname "$rel")"
+  viewport="$(basename "$rel" .png)"
+  page_url="$(printf '%s' "$page_dir" | node -e 'process.stdin.on("data",d=>process.stdout.write(decodeURIComponent(d.toString())))')"
+  base_png="$BASELINE_DIR/$rel"
+  diff_png="$DIFF_DIR/$rel"
+
+  raw="$(compare_pair "$base_png" "$curr_png" "$diff_png" || echo '{"pass":false,"diff_ratio":1,"reason":"compare-error"}')"
+
+  # Decide pass/fail against max_diff_pixel_ratio when engine left it null.
+  merged="$(jq -c \
+    --arg page "$page_url" \
+    --arg viewport "$viewport" \
+    --argjson threshold "$THRESHOLD" \
+    --argjson max_ratio "$MAX_RATIO" \
+    '. as $r
+     | .pass = (if .pass == null then (.diff_ratio <= $max_ratio) else .pass end)
+     | .page = $page
+     | .viewport = $viewport
+     | .threshold = $threshold
+     | .max_diff_pixel_ratio = $max_ratio' <<<"$raw")"
+
+  if [[ "$(jq -r '.pass' <<<"$merged")" != "true" ]]; then any_fail=1; fi
+  results="$(jq -c --argjson m "$merged" '. + [$m]' <<<"$results")"
+done < <(find "$CURRENT_DIR" -type f -name '*.png' -print0)
+
+out_file="$DIFF_DIR/results.json"
+mkdir -p "$DIFF_DIR"
+jq -n --argjson r "$results" \
+  --arg engine "$RESOLVED_ENGINE" \
+  --argjson threshold "$THRESHOLD" \
+  --argjson max_ratio "$MAX_RATIO" \
+  '{engine:$engine, threshold:$threshold, max_diff_pixel_ratio:$max_ratio,
+    results:$r, count: ($r|length),
+    passed: ([$r[] | select(.pass==true)] | length),
+    failed: ([$r[] | select(.pass!=true)] | length)}' \
+  >"$out_file"
+
+cat "$out_file"
+exit $any_fail