start-vibing 4.3.1 → 4.3.3

package/template/.claude/skills/super-design/scripts/extract-tokens.mjs

@@ -1,7 +1,8 @@
 #!/usr/bin/env node
-// Extract + canonicalize + hash design tokens from Tailwind configs and
-// CSS custom properties. Output is deterministic regardless of insertion
-// order (artifact §9.2 line 722: "canonical = JSON.stringify(theme,
+// Extract + canonicalize + hash design tokens from Tailwind configs, CSS custom
+// properties, and DTCG / Tokens Studio JSON (artifact §9.1 lines 707-709, §9.2
+// lines 720-761). Output is deterministic regardless of insertion order
+// (artifact §9.2 line 722: "canonical = JSON.stringify(theme,
 // Object.keys(theme).sort())").
 import fs from "node:fs";
 import path from "node:path";
@@ -9,7 +10,9 @@ import { createHash } from "node:crypto";
 import { pathToFileURL } from "node:url";
 
 const out = {};
+const sources = [];
 const tailwindConfigs = ["tailwind.config.ts", "tailwind.config.js", "tailwind.config.mjs", "tailwind.config.cjs"];
+let tailwindFound = false;
 for (const candidate of tailwindConfigs) {
   if (fs.existsSync(candidate)) {
     try {
@@ -17,10 +20,14 @@ for (const candidate of tailwindConfigs) {
       const cfg = (await import(pathToFileURL(path.resolve(candidate)).href)).default;
       const resolved = resolveConfig(cfg);
       flatten(resolved.theme, "tw", out);
+      tailwindFound = true;
     } catch (e) { out[`_error_${candidate}`] = String(e.message || e); }
     break;
   }
 }
+if (tailwindFound) sources.push("tailwind");
+
+let cssFound = false;
 try {
   const postcss = (await import("postcss")).default;
   const cssCandidates = ["styles/globals.css","src/styles/globals.css","app/globals.css","styles/theme.css","src/app/globals.css"];
@@ -28,21 +35,37 @@ try {
     if (!fs.existsSync(css)) continue;
     const source = fs.readFileSync(css, "utf8");
     const root = postcss.parse(source);
-    root.walkAtRules("theme", at => { at.walkDecls(/^--/, d => { out[`css:${d.prop}`] = d.value.trim(); }); });
-    root.walkRules(":root", rule => { rule.walkDecls(/^--/, d => { out[`css:${d.prop}`] = d.value.trim(); }); });
+    root.walkAtRules("theme", at => { at.walkDecls(/^--/, d => { out[`css:${d.prop}`] = d.value.trim(); cssFound = true; }); });
+    root.walkRules(":root", rule => { rule.walkDecls(/^--/, d => { out[`css:${d.prop}`] = d.value.trim(); cssFound = true; }); });
   }
 } catch (e) { out._postcss_error = String(e.message || e); }
+if (cssFound) sources.push("css-vars");
 
-// TODO(sd-audit-state §9.1 artifact line 707-709): DTCG *.tokens.json and
-// Tokens Studio support — parse JSON, resolve `{alias}` refs per §9.2 line
-// 747 before hashing, then merge into `out` with prefix `dtcg:`.
+// DTCG + Tokens Studio support (artifact §9.1 line 707-709, §9.2 line 747).
+const dtcgFiles = discoverDtcgFiles(".");
+let dtcgFound = false;
+for (const file of dtcgFiles) {
+  try {
+    const raw = fs.readFileSync(file, "utf8");
+    const parsed = JSON.parse(raw);
+    // Tokens Studio $metadata/$themes are not token trees — skip.
+    if (path.basename(file) === "$metadata.json" || path.basename(file) === "$themes.json") continue;
+    const resolved = resolveDtcgAliases(parsed, file);
+    const relFile = path.relative(".", file).replaceAll("\\", "/");
+    flattenDtcg(resolved, `dtcg:${relFile}`, out);
+    dtcgFound = true;
+  } catch (e) {
+    out[`_dtcg_error_${file}`] = String(e.message || e);
+  }
+}
+if (dtcgFound) sources.push("dtcg");
 
 // Deterministic canonical form: keys sorted top-to-bottom.
 const sorted = Object.keys(out).sort().reduce((acc, k) => { acc[k] = out[k]; return acc; }, {});
 const canonical = JSON.stringify(sorted);
 const tokens_hash = "sha256:" + createHash("sha256").update(canonical).digest("hex");
 
-console.log(JSON.stringify({ tokens: sorted, tokens_hash }, null, 2));
+console.log(JSON.stringify({ tokens: sorted, tokens_hash, sources: sources.sort() }, null, 2));
 
 function flatten(obj, prefix, acc) {
   if (obj == null) return;
@@ -56,3 +79,124 @@ function flatten(obj, prefix, acc) {
     else acc[key] = Array.isArray(v) ? v.join(",") : String(v);
   }
 }
+
+// Walk cwd, returning **/*.tokens.json (excluding build/vendor dirs) plus the
+// two conventional Tokens Studio single-file exports.
+function discoverDtcgFiles(rootDir) {
+  const skipDirs = new Set(["node_modules", "dist", ".next", "build", ".git", "coverage", ".turbo", ".cache"]);
+  const found = [];
+  const walk = (dir) => {
+    let entries;
+    try { entries = fs.readdirSync(dir, { withFileTypes: true }); } catch { return; }
+    for (const entry of entries) {
+      if (entry.isDirectory()) {
+        if (skipDirs.has(entry.name) || entry.name.startsWith(".")) {
+          // Allow explicit `.tokens` dir used by some Tokens Studio setups.
+          if (entry.name !== ".tokens") continue;
+        }
+        walk(path.join(dir, entry.name));
+      } else if (entry.isFile()) {
+        const full = path.join(dir, entry.name);
+        if (entry.name.endsWith(".tokens.json")) found.push(full);
+        else if (entry.name === "tokens.json" && (dir === rootDir || path.basename(dir) === ".tokens")) found.push(full);
+      }
+    }
+  };
+  walk(rootDir);
+  return found.sort();
+}
+
+// Resolve DTCG aliases transitively. Supports both `{color.brand.primary}` and
+// Tokens Studio legacy `$color.brand.primary`. Cycle detection throws loudly.
+function resolveDtcgAliases(tree, filename) {
+  const resolving = new Set();
+  const lookup = (pathStr) => {
+    const segs = pathStr.split(".");
+    let node = tree;
+    for (const s of segs) {
+      if (node == null || typeof node !== "object") return undefined;
+      node = node[s];
+    }
+    return node;
+  };
+  const resolveValue = (value, trail) => {
+    if (typeof value !== "string") return value;
+    const braceMatch = value.match(/^\{([^}]+)\}$/);
+    const dollarMatch = value.match(/^\$([A-Za-z_][A-Za-z0-9_.-]*)$/);
+    const aliasPath = braceMatch ? braceMatch[1] : dollarMatch ? dollarMatch[1] : null;
+    if (!aliasPath) return value;
+    if (trail.has(aliasPath)) {
+      throw new Error(`DTCG alias cycle in ${filename}: ${[...trail, aliasPath].join(" -> ")}`);
+    }
+    const target = lookup(aliasPath);
+    if (target == null) return value; // dangling alias: pass through raw
+    const next = typeof target === "object" && target !== null && "$value" in target ? target.$value : target;
+    return resolveValue(next, new Set([...trail, aliasPath]));
+  };
+  const walk = (node) => {
+    if (node == null || typeof node !== "object") return node;
+    if (Array.isArray(node)) return node.map(walk);
+    if ("$value" in node) {
+      const copy = { ...node };
+      try {
+        copy.$value = resolveValue(copy.$value, new Set());
+      } catch (err) {
+        // Cycles must fail loudly per requirements.
+        throw err;
+      }
+      copy.$value = applyTokensStudioTransforms(copy.$value, node.$extensions, filename);
+      return copy;
+    }
+    const result = {};
+    for (const k of Object.keys(node)) result[k] = walk(node[k]);
+    return result;
+  };
+  return walk(tree);
+}
+
+// Apply Tokens Studio `modify` transforms (lighten/darken/alpha). Anything
+// unparseable emits a warning to stderr and passes through the raw $value.
+function applyTokensStudioTransforms(value, extensions, filename) {
+  const modify = extensions?.["studio.tokens"]?.modify;
+  if (!modify || typeof value !== "string") return value;
+  const { type, amount, space } = modify;
+  const num = Number(amount);
+  try {
+    if (type === "alpha" && /^#([0-9a-f]{6})$/i.test(value) && Number.isFinite(num)) {
+      const a = Math.round(Math.max(0, Math.min(1, num)) * 255).toString(16).padStart(2, "0");
+      return value + a;
+    }
+    if ((type === "lighten" || type === "darken") && /^#([0-9a-f]{6})$/i.test(value) && Number.isFinite(num)) {
+      const hex = value.slice(1);
+      const rgb = [0, 2, 4].map(i => parseInt(hex.slice(i, i + 2), 16));
+      const factor = type === "lighten" ? num : -num;
+      const adjusted = rgb.map(c => Math.max(0, Math.min(255, Math.round(c + (factor * 255)))));
+      return "#" + adjusted.map(c => c.toString(16).padStart(2, "0")).join("");
+    }
+    process.stderr.write(`[extract-tokens] warn: unsupported Tokens Studio modify(${type}, space=${space}) in ${filename}; passing through raw value\n`);
+    return value;
+  } catch {
+    process.stderr.write(`[extract-tokens] warn: failed to apply Tokens Studio modify(${type}) in ${filename}; passing through raw value\n`);
+    return value;
+  }
+}
+
+// Flatten a resolved DTCG tree into `prefix.path = stringified $value` leaves.
+function flattenDtcg(node, prefix, acc) {
+  if (node == null) return;
+  if (typeof node !== "object" || Array.isArray(node)) {
+    acc[prefix] = Array.isArray(node) ? node.join(",") : String(node);
+    return;
+  }
+  if ("$value" in node) {
+    const v = node.$value;
+    const t = node.$type;
+    const key = t ? `${prefix}[${t}]` : prefix;
+    acc[key] = typeof v === "object" ? JSON.stringify(v, Object.keys(v).sort()) : String(v);
+    return;
+  }
+  for (const k of Object.keys(node).sort()) {
+    if (k.startsWith("$")) continue; // $description / $extensions / $metadata
+    flattenDtcg(node[k], `${prefix}.${k}`, acc);
+  }
+}

package/template/.claude/skills/super-design/scripts/harvest-typeui.sh

@@ -0,0 +1,131 @@
+#!/usr/bin/env bash
+# harvest-typeui.sh — discover + install typeui-* and related design skills.
+#
+# Sources, in order:
+#   1. typeui.sh registry (if reachable) — fetch catalog.json, install missing
+#   2. vercel-labs/agent-skills design skills (composition, web-design-guidelines)
+#   3. anthropics/skills webapp-testing + mcp-builder (already covered, idempotent)
+#
+# Usage:
+#   harvest-typeui.sh              # install everything missing (user-scope ~/.claude/skills/)
+#   harvest-typeui.sh --list       # print catalog without installing
+#   harvest-typeui.sh --refresh    # re-download even if already installed
+#   harvest-typeui.sh --dest <dir> # install to custom dir (default: ~/.claude/skills)
+
+set -euo pipefail
+
+DEST="${HOME}/.claude/skills"
+LIST_ONLY=0
+REFRESH=0
+
+while (( $# )); do
+  case "$1" in
+    --list) LIST_ONLY=1 ;;
+    --refresh) REFRESH=1 ;;
+    --dest) DEST="$2"; shift ;;
+    -h|--help)
+      sed -n '2,18p' "$0"
+      exit 0 ;;
+    *) echo "unknown flag: $1" >&2; exit 2 ;;
+  esac
+  shift
+done
+
+mkdir -p "$DEST"
+
+TYPEUI_CATALOG_URL="${TYPEUI_CATALOG_URL:-https://typeui.sh/catalog.json}"
+TMP=$(mktemp)
+trap 'rm -f "$TMP"' EXIT
+
+log() { echo "[harvest-typeui] $*"; }
+
+fetch_catalog() {
+  if command -v curl >/dev/null 2>&1; then
+    curl -sSfL --max-time 10 "$TYPEUI_CATALOG_URL" -o "$TMP" 2>/dev/null && return 0
+  fi
+  if command -v wget >/dev/null 2>&1; then
+    wget -q --timeout=10 -O "$TMP" "$TYPEUI_CATALOG_URL" 2>/dev/null && return 0
+  fi
+  return 1
+}
+
+# Fallback catalog — built-in list of known typeui skills + companions.
+# Format: name|base_url (raw SKILL.md location)
+DEFAULT_CATALOG=$(cat <<'EOF'
+typeui-ant|https://raw.githubusercontent.com/typeui-sh/skills/main/typeui-ant/SKILL.md
+typeui-application|https://raw.githubusercontent.com/typeui-sh/skills/main/typeui-application/SKILL.md
+typeui-artistic|https://raw.githubusercontent.com/typeui-sh/skills/main/typeui-artistic/SKILL.md
+typeui-bento|https://raw.githubusercontent.com/typeui-sh/skills/main/typeui-bento/SKILL.md
+typeui-bold|https://raw.githubusercontent.com/typeui-sh/skills/main/typeui-bold/SKILL.md
+typeui-clean|https://raw.githubusercontent.com/typeui-sh/skills/main/typeui-clean/SKILL.md
+typeui-dashboard|https://raw.githubusercontent.com/typeui-sh/skills/main/typeui-dashboard/SKILL.md
+typeui-doodle|https://raw.githubusercontent.com/typeui-sh/skills/main/typeui-doodle/SKILL.md
+typeui-dramatic|https://raw.githubusercontent.com/typeui-sh/skills/main/typeui-dramatic/SKILL.md
+typeui-enterprise|https://raw.githubusercontent.com/typeui-sh/skills/main/typeui-enterprise/SKILL.md
+typeui-neobrutalism|https://raw.githubusercontent.com/typeui-sh/skills/main/typeui-neobrutalism/SKILL.md
+typeui-paper|https://raw.githubusercontent.com/typeui-sh/skills/main/typeui-paper/SKILL.md
+composition-patterns|https://raw.githubusercontent.com/vercel-labs/agent-skills/main/skills/composition-patterns/SKILL.md
+web-design-guidelines|https://raw.githubusercontent.com/vercel-labs/agent-skills/main/skills/web-design-guidelines/SKILL.md
+react-best-practices|https://raw.githubusercontent.com/vercel-labs/agent-skills/main/skills/react-best-practices/SKILL.md
+webapp-testing|https://raw.githubusercontent.com/anthropics/skills/main/skills/webapp-testing/SKILL.md
+mcp-builder|https://raw.githubusercontent.com/anthropics/skills/main/skills/mcp-builder/SKILL.md
+EOF
+)
+
+CATALOG=""
+if fetch_catalog; then
+  # typeui.sh returned JSON — extract {name,url} tuples via node
+  if command -v node >/dev/null 2>&1; then
+    CATALOG=$(node -e "
+      const c = JSON.parse(require('fs').readFileSync('$TMP','utf8'));
+      const items = c.skills || c.items || c;
+      for (const it of items) {
+        const n = it.name || it.slug;
+        const u = it.skill_url || it.url || it.raw || it.source;
+        if (n && u) console.log(n + '|' + u);
+      }
+    " 2>/dev/null || echo "")
+  fi
+fi
+
+if [[ -z "$CATALOG" ]]; then
+  log "registry unreachable or empty — using built-in catalog"
+  CATALOG="$DEFAULT_CATALOG"
+fi
+
+if (( LIST_ONLY )); then
+  echo "$CATALOG"
+  exit 0
+fi
+
+INSTALLED=0
+SKIPPED=0
+FAILED=0
+
+while IFS='|' read -r name url; do
+  [[ -z "$name" ]] && continue
+  target_dir="$DEST/$name"
+  target_file="$target_dir/SKILL.md"
+
+  if [[ -f "$target_file" && $REFRESH -eq 0 ]]; then
+    SKIPPED=$((SKIPPED + 1))
+    continue
+  fi
+
+  mkdir -p "$target_dir"
+  if command -v curl >/dev/null 2>&1; then
+    if curl -sSfL --max-time 15 "$url" -o "$target_file" 2>/dev/null; then
+      log "installed $name"
+      INSTALLED=$((INSTALLED + 1))
+    else
+      log "failed $name ($url)"
+      FAILED=$((FAILED + 1))
+      rmdir "$target_dir" 2>/dev/null || true
+    fi
+  else
+    log "curl missing — cannot fetch $name"
+    FAILED=$((FAILED + 1))
+  fi
+done <<< "$CATALOG"
+
+log "done: installed=$INSTALLED skipped=$SKIPPED failed=$FAILED dest=$DEST"

package/template/.claude/skills/super-design/scripts/hash-pages.sh

@@ -1,48 +1,228 @@
 #!/usr/bin/env bash
 # Usage: hash-pages.sh <urls_file>
 #
-# TODO(sd-audit-state artifact §10 line 492, §16 line 1367-1384):
-#   Per-viewport hashes (mobile_375 / tablet_768 / desktop_1280) + pHash
-#   for perceptual similarity, plus mask_selectors passed to
-#   page.screenshot({ mask: [...] }) for deterministic diffs. Current impl
-#   hashes a single desktop viewport only.
+# Captures three viewports per URL (mobile_375, tablet_768, desktop_1280),
+# computes sha256 (exact) + phash (perceptual) for each, and emits a single
+# JSON file with one record per URL (artifact §3.4, §10 line 492, §16 lines
+# 1367-1384).
+#
+# Env vars:
+#   OUT_DIR          — where to write hashes.json and the per-viewport PNGs
+#                      (default: docs/super-design/.cache/hashes).
+#   MASK_SELECTORS   — comma-separated CSS selectors masked on every
+#                      screenshot via Playwright's `mask:` option with
+#                      maskColor "#000". Artifact §3.4 defaults are always
+#                      merged in; user-supplied selectors are additive.
+#   MASK_COLOR       — overrides the mask fill color (default #000).
+#   HASH_URL_TIMEOUT — per-URL navigation timeout ms (default 30000).
+#
+# Output shape (artifact §10 line 492):
+#   {
+#     "url": "...",
+#     "html_hash":          "sha256:...",
+#     "dom_structure_hash": "sha256:...",
+#     "screenshot_hash":    "sha256:...",   (desktop, back-compat)
+#     "viewport_hashes": {
+#       "mobile_375":  { "sha256": "...", "phash": "..." },
+#       "tablet_768":  { "sha256": "...", "phash": "..." },
+#       "desktop_1280":{ "sha256": "...", "phash": "..." }
+#     }
+#   }
+#
+# Perceptual hash (phash):
+#   We prefer `sharp` if installed (true DCT/aHash on a 32x32 greyscale
+#   downsample). If sharp is unavailable we fall back to a deterministic
+#   PNG-structural fingerprint — 64 bits derived from 8 evenly-sliced
+#   sha256 windows over the PNG buffer. This is NOT a true perceptual
+#   hash; it survives identical re-renders but is sensitive to any pixel
+#   change. Compare with Hamming distance only when sharp was used (the
+#   emitted record includes an "engine" field so consumers can pick the
+#   right distance metric).
 set -euo pipefail
+
 URLS="${1:?usage: hash-pages.sh <urls_file>}"
 OUT_DIR="${OUT_DIR:-docs/super-design/.cache/hashes}"
+MASK_SELECTORS="${MASK_SELECTORS:-}"
+MASK_COLOR="${MASK_COLOR:-#000}"
+HASH_URL_TIMEOUT="${HASH_URL_TIMEOUT:-30000}"
 mkdir -p "$OUT_DIR"
 
-URLS="$URLS" OUT_DIR="$OUT_DIR" node --experimental-vm-modules <<'JS'
+URLS="$URLS" OUT_DIR="$OUT_DIR" \
+MASK_SELECTORS="$MASK_SELECTORS" MASK_COLOR="$MASK_COLOR" \
+HASH_URL_TIMEOUT="$HASH_URL_TIMEOUT" node --experimental-vm-modules <<'JS'
 import { chromium } from "playwright";
 import { createHash } from "node:crypto";
-import { readFileSync, writeFileSync } from "node:fs";
+import { readFileSync, writeFileSync, mkdirSync } from "node:fs";
+import { join } from "node:path";
 
 const urlsFile = process.env.URLS;
 const outDir = process.env.OUT_DIR;
-const urls = readFileSync(urlsFile, "utf8").split("\n").map(s => s.trim()).filter(Boolean);
+const maskColor = process.env.MASK_COLOR || "#000";
+const navTimeout = Number(process.env.HASH_URL_TIMEOUT || 30000);
+
+// Artifact §3.4 defaults — always masked.
+const DEFAULT_MASKS = [
+  "[data-timestamp]",
+  ".relative-time",
+  "[data-react-hydration]",
+  "video",
+  "canvas",
+];
+const userMasks = (process.env.MASK_SELECTORS || "")
+  .split(",").map(s => s.trim()).filter(Boolean);
+const maskSelectors = [...new Set([...DEFAULT_MASKS, ...userMasks])];
+
+// Volatile attributes stripped from the DOM structure hash (artifact §3.4
+// — added data-react-hydration to match the mask defaults).
+const VOLATILE_ATTRS = new Set([
+  "nonce",
+  "data-timestamp",
+  "data-reactid",
+  "data-next-hydrate",
+  "data-react-hydration",
+]);
+
+const urls = readFileSync(urlsFile, "utf8")
+  .split("\n").map(s => s.trim()).filter(Boolean);
+
+const VIEWPORTS = [
+  { label: "mobile_375",  width: 375,  height: 667  },
+  { label: "tablet_768",  width: 768,  height: 1024 },
+  { label: "desktop_1280", width: 1280, height: 800  },
+];
+
+const sha = (s) => createHash("sha256").update(s).digest("hex");
+
+// Optional sharp — gives us a real perceptual hash. Falls back to a
+// PNG-structural fingerprint (documented in the header) when absent.
+let sharp = null;
+let phashEngine = "fallback-png-fingerprint";
+try {
+  sharp = (await import("sharp")).default;
+  phashEngine = "sharp-ahash-8x8";
+} catch { /* no sharp installed; use fallback */ }
+
+async function aHash(buf) {
+  if (!sharp) return fallbackFingerprint(buf);
+  // Average-hash: downscale to 8x8 greyscale, threshold at mean.
+  const raw = await sharp(buf)
+    .greyscale()
+    .resize(8, 8, { fit: "fill", kernel: "cubic" })
+    .raw()
+    .toBuffer();
+  let sum = 0;
+  for (let i = 0; i < raw.length; i++) sum += raw[i];
+  const mean = sum / raw.length;
+  let bits = 0n;
+  for (let i = 0; i < 64; i++) {
+    bits = (bits << 1n) | (raw[i] >= mean ? 1n : 0n);
+  }
+  return bits.toString(16).padStart(16, "0");
+}
+
+function fallbackFingerprint(buf) {
+  // Zero-dep deterministic fingerprint: slice PNG into 8 windows, take the
+  // first byte of each window's sha256, concat to 16 hex chars. Order of
+  // magnitude cheaper than a real pHash and only collision-safe for
+  // identical-buffer comparisons, but it gives us a stable 64-bit slot in
+  // viewport_hashes so downstream tooling can still key on it.
+  if (buf.length === 0) return "0".repeat(16);
+  const windows = 8;
+  const step = Math.max(1, Math.floor(buf.length / windows));
+  let out = "";
+  for (let i = 0; i < windows; i++) {
+    const start = i * step;
+    const end = i === windows - 1 ? buf.length : start + step;
+    const slice = buf.subarray(start, end);
+    const h = createHash("sha256").update(slice).digest();
+    out += h.subarray(0, 1).toString("hex");
+  }
+  return out;
+}
+
 const browser = await chromium.launch();
-const ctx = await browser.newContext({
-  viewport: { width: 1280, height: 800 }, reducedMotion: "reduce", deviceScaleFactor: 1,
-});
-const page = await ctx.newPage();
-const sha = s => createHash("sha256").update(s).digest("hex");
 const results = [];
 for (const url of urls) {
+  const entry = { url, viewport_hashes: {} };
   try {
-    await page.goto(url, { waitUntil: "networkidle", timeout: 30000 });
-    const html = (await page.content()).replace(/\s+/g, " ").trim();
-    const dom = await page.evaluate(() => {
-      const V = new Set(["nonce","data-timestamp","data-reactid","data-next-hydrate"]);
-      const walk = n => n.nodeType !== 1 ? "" :
-        `<${n.tagName.toLowerCase()}[${[...n.attributes].filter(a=>!V.has(a.name))
-          .map(a=>`${a.name}=${a.value}`).sort().join(",")}]${[...n.childNodes].map(walk).join("")}>`;
-      return walk(document.documentElement);
-    });
-    const buf = await page.screenshot({ fullPage: true, animations: "disabled", caret: "hide" });
-    results.push({ url, html_hash: "sha256:" + sha(html),
-      dom_structure_hash: "sha256:" + sha(dom), screenshot_hash: "sha256:" + sha(buf) });
-  } catch (e) { results.push({ url, error: String(e.message || e) }); }
+    // Shared context: cache html/dom work on first (desktop) viewport.
+    let capturedHtml = null;
+    let capturedDom = null;
+
+    for (const vp of VIEWPORTS) {
+      const ctx = await browser.newContext({
+        viewport: { width: vp.width, height: vp.height },
+        reducedMotion: "reduce",
+        deviceScaleFactor: 1,
+      });
+      const page = await ctx.newPage();
+      await page.goto(url, { waitUntil: "networkidle", timeout: navTimeout });
+
+      if (capturedHtml === null) {
+        capturedHtml = (await page.content()).replace(/\s+/g, " ").trim();
+        capturedDom = await page.evaluate((volatileList) => {
+          const V = new Set(volatileList);
+          const walk = (n) => n.nodeType !== 1 ? "" :
+            `<${n.tagName.toLowerCase()}[${[...n.attributes]
+              .filter(a => !V.has(a.name))
+              .map(a => `${a.name}=${a.value}`)
+              .sort().join(",")}]${[...n.childNodes].map(walk).join("")}>`;
+          return walk(document.documentElement);
+        }, [...VOLATILE_ATTRS]);
+      }
+
+      // Build mask locator list (skip selectors that error — they're OK
+      // if nothing matches; only invalid syntax throws).
+      const masks = [];
+      for (const sel of maskSelectors) {
+        try { masks.push(page.locator(sel)); } catch { /* bad selector */ }
+      }
+
+      const buf = await page.screenshot({
+        fullPage: true,
+        animations: "disabled",
+        caret: "hide",
+        mask: masks,
+        maskColor,
+      });
+
+      // Persist PNG for visual-regression.sh to consume.
+      const pngDir = join(outDir, "screenshots", encodeURIComponent(url));
+      mkdirSync(pngDir, { recursive: true });
+      const pngPath = join(pngDir, `${vp.label}.png`);
+      writeFileSync(pngPath, buf);
+
+      const ph = await aHash(buf);
+      entry.viewport_hashes[vp.label] = {
+        sha256: "sha256:" + sha(buf),
+        phash: `${phashEngine === "sharp-ahash-8x8" ? "phash" : "fpr"}:${ph}`,
+        png_path: pngPath,
+      };
+
+      if (vp.label === "desktop_1280") {
+        entry.screenshot_hash = entry.viewport_hashes[vp.label].sha256;
+      }
+
+      await ctx.close();
+    }
+
+    entry.html_hash = "sha256:" + sha(capturedHtml);
+    entry.dom_structure_hash = "sha256:" + sha(capturedDom);
+    entry.mask_selectors = maskSelectors;
+    entry.phash_engine = phashEngine;
+  } catch (e) {
+    entry.error = String(e.message || e);
+  }
+  results.push(entry);
 }
-writeFileSync(outDir + "/hashes.json", JSON.stringify(results, null, 2));
+
+writeFileSync(join(outDir, "hashes.json"), JSON.stringify(results, null, 2));
 await browser.close();
-console.log(JSON.stringify({ count: results.length, path: outDir + "/hashes.json" }));
+console.log(JSON.stringify({
+  count: results.length,
+  path: join(outDir, "hashes.json"),
+  phash_engine: phashEngine,
+  viewports: VIEWPORTS.map(v => v.label),
+  mask_selectors: maskSelectors,
+}));
 JS