feat(skills): add contrast audit + animation map quality skills (#267)

## Summary Two new quality skills + CLI integration that give agents feedback loops they currently lack — pixel-level contrast auditing and structured animation analysis. ### What this unlocks for agents **Agents can now catch accessibility failures that humans and LLMs consistently miss.** The contrast audit runs automatically on every `hyperframes validate` and reports WCAG AA violations as warnings. In the eval, 4 out of 5 palettes had failing contrast — every baseline composition shipped broken, every treatment composition caught and fixed it. **Agents can now reason about animation choreography.** The animation map produces a structured JSON report with: - Per-tween natural language summaries ("card1 slides 23px up over 0.5s, fades in, ends at (120, 200)") - ASCII timeline showing the full choreography as a Gantt chart - Stagger detection with actual intervals ("3 elements stagger at 120ms" — validates against brief specs) - Dead zone detection (periods >1s with no animation — missing entrance or intentional hold?) - Element lifecycles (first/last animation, final visibility — catches elements that enter but never exit) - Scene snapshots at 5 timestamps (what's on screen at any moment) ### Changes **Skills (new)** - \`skills/hyperframes-contrast/\` — WCAG contrast audit skill + script - \`skills/hyperframes-animation-map/\` — animation analysis skill + script **CLI** - \`hyperframes validate\` now runs contrast audit by default (warnings, not errors) - \`hyperframes validate --no-contrast\` to skip - \`hyperframes render --html-only\` compiles HTML without video encoding - Browser-side WCAG code in \`contrast-audit.browser.js\`, inlined at build time via esbuild text loader **Producer** - Exported \`compileForRender\` for the \`--html-only\` flag ### Eval results 5 prompts x 2 arms = 10 compositions. Arm A = baseline skills. Arm B = +contrast +animation-map. | Prompt | Failing color | Before | After | |--------|--------------|--------|-------| | Halflife | Cement on Ink | 2.98:1 | 5.33:1 | | Meridian | Ash on Midnight | 2.08:1 | 5.44:1 | | Typesmith | Pencil on Paper | 3.19:1 | 5.50:1 | | Lattice | Gray-600 on Terminal | 2.59:1 | 7.50:1 | Animation map correctly enumerated 142 tweens across 5 compositions, detected stagger groups, flagged pacing issues, and produced scene snapshots. ### Pitch video https://itnjfahrnzqvcluhrtif.supabase.co/storage/v1/object/public/assets/uploads/8f043e1c-6882-4fa9-98fd-efb6b3583afa.mp4 ### Dedicated evals https://www.heygenverse.com/a/2cac956b-3d14-47bf-90e8-3c1f50e671f3 ## Test plan - [x] Eval: 10 compositions (5 baseline, 5 treatment), all rendered - [x] Contrast audit caught 4/4 failing palettes, 0 missed - [x] \`hyperframes validate\` shows contrast warnings by default (exit 0) - [x] \`hyperframes validate --no-contrast\` skips audit - [x] \`hyperframes validate --json\` includes contrast data - [x] Animation map tested on 3 compositions (17, 27, 51 tweens) - [x] Stagger detection, dead zones, snapshots, timeline all verified - [x] \`bun run build\` passes - [x] \`bun run lint\` passes (0 errors, 0 warnings, 0 skill lint issues)
2026-09-01 19:42:03 +00:00 · 2026-04-15 03:09:56 +02:00
parent 5b8207730d
commit d3f2295d80
6 changed files with 1252 additions and 56 deletions
@@ -0,0 +1,148 @@
+// Browser-side WCAG contrast audit.
+// Loaded as a raw string and injected via page.addScriptTag to avoid
+// esbuild mangling (page.evaluate serializes functions; __name helpers break).
+//
+// NOTE: WCAG math (relLum, wcagRatio, parseColor, median) is duplicated in
+// skills/hyperframes-contrast/scripts/contrast-report.mjs — keep in sync.
+
+/* eslint-disable */
+window.__contrastAudit = async function (imgBase64, time) {
+  function relLum(r, g, b) {
+    function ch(v) {
+      var s = v / 255;
+      return s <= 0.03928 ? s / 12.92 : Math.pow((s + 0.055) / 1.055, 2.4);
+    }
+    return 0.2126 * ch(r) + 0.7152 * ch(g) + 0.0722 * ch(b);
+  }
+
+  function wcagRatio(r1, g1, b1, r2, g2, b2) {
+    var l1 = relLum(r1, g1, b1),
+      l2 = relLum(r2, g2, b2);
+    var hi = l1 > l2 ? l1 : l2,
+      lo = l1 > l2 ? l2 : l1;
+    return (hi + 0.05) / (lo + 0.05);
+  }
+
+  function parseColor(c) {
+    var m = c.match(/rgba?\(([^)]+)\)/);
+    if (!m) return [0, 0, 0, 1];
+    var p = m[1].split(",").map(function (s) {
+      return parseFloat(s.trim());
+    });
+    return [p[0], p[1], p[2], p[3] != null ? p[3] : 1];
+  }
+
+  function selectorOf(el) {
+    if (el.id) return "#" + el.id;
+    var cls = Array.from(el.classList).slice(0, 2).join(".");
+    return cls ? el.tagName.toLowerCase() + "." + cls : el.tagName.toLowerCase();
+  }
+
+  function median(arr) {
+    var s = arr.slice().sort(function (a, b) {
+      return a - b;
+    });
+    return s[Math.floor(s.length / 2)];
+  }
+
+  // Decode screenshot into canvas pixel data
+  var img = new Image();
+  await new Promise(function (resolve) {
+    img.onload = resolve;
+    img.onerror = function () {
+      resolve();
+    };
+    img.src = "data:image/png;base64," + imgBase64;
+  });
+  if (!img.naturalWidth) return [];
+  var canvas = document.createElement("canvas");
+  canvas.width = img.naturalWidth || 1920;
+  canvas.height = img.naturalHeight || 1080;
+  var ctx = canvas.getContext("2d");
+  if (!ctx) return [];
+  ctx.drawImage(img, 0, 0);
+  var px = ctx.getImageData(0, 0, canvas.width, canvas.height).data;
+  var w = canvas.width;
+  var h = canvas.height;
+
+  // Walk DOM for text elements
+  var out = [];
+  var walker = document.createTreeWalker(document.body, NodeFilter.SHOW_ELEMENT);
+  var node;
+  while ((node = walker.nextNode())) {
+    var el = node;
+
+    // Must have a direct text node child
+    var hasText = false;
+    for (var i = 0; i < el.childNodes.length; i++) {
+      if (
+        el.childNodes[i].nodeType === 3 &&
+        (el.childNodes[i].textContent || "").trim().length > 0
+      ) {
+        hasText = true;
+        break;
+      }
+    }
+    if (!hasText) continue;
+
+    var cs = getComputedStyle(el);
+    if (cs.visibility === "hidden" || cs.display === "none") continue;
+    if (parseFloat(cs.opacity) <= 0.01) continue;
+    var rect = el.getBoundingClientRect();
+    if (rect.width < 8 || rect.height < 8) continue;
+
+    var fg = parseColor(cs.color);
+    if (fg[3] <= 0.01) continue;
+
+    // Sample 4px ring outside bbox for background color
+    var rr = [],
+      gg = [],
+      bb = [];
+    var x0 = Math.max(0, Math.floor(rect.x) - 4);
+    var x1 = Math.min(w - 1, Math.ceil(rect.x + rect.width) + 4);
+    var y0 = Math.max(0, Math.floor(rect.y) - 4);
+    var y1 = Math.min(h - 1, Math.ceil(rect.y + rect.height) + 4);
+    var sample = function (sx, sy) {
+      var idx = (sy * w + sx) * 4;
+      rr.push(px[idx]);
+      gg.push(px[idx + 1]);
+      bb.push(px[idx + 2]);
+    };
+    for (var x = x0; x <= x1; x++) {
+      sample(x, y0);
+      sample(x, y1);
+    }
+    for (var y = y0; y <= y1; y++) {
+      sample(x0, y);
+      sample(x1, y);
+    }
+
+    if (rr.length === 0) continue;
+
+    var bgR = median(rr),
+      bgG = median(gg),
+      bgB = median(bb);
+
+    // Composite foreground alpha over measured background
+    var compR = Math.round(fg[0] * fg[3] + bgR * (1 - fg[3]));
+    var compG = Math.round(fg[1] * fg[3] + bgG * (1 - fg[3]));
+    var compB = Math.round(fg[2] * fg[3] + bgB * (1 - fg[3]));
+
+    var ratio = +wcagRatio(compR, compG, compB, bgR, bgG, bgB).toFixed(2);
+    var fontSize = parseFloat(cs.fontSize);
+    var fontWeight = Number(cs.fontWeight) || 400;
+    var large = fontSize >= 24 || (fontSize >= 19 && fontWeight >= 700);
+
+    out.push({
+      time: time,
+      selector: selectorOf(el),
+      text: (el.textContent || "").trim().slice(0, 50),
+      ratio: ratio,
+      wcagAA: large ? ratio >= 3 : ratio >= 4.5,
+      large: large,
+      fg: "rgb(" + compR + "," + compG + "," + compB + ")",
+      bg: "rgb(" + bgR + "," + bgG + "," + bgB + ")",
+    });
+  }
+  return out;
+};
@@ -16,21 +16,85 @@ interface ConsoleEntry {
  line?: number;
 }

-/**
- * Bundle the project HTML with the runtime injected, serve it via a minimal
- * static server, open headless Chrome, and collect console errors.
- */
+interface ContrastEntry {
+  time: number;
+  selector: string;
+  text: string;
+  ratio: number;
+  wcagAA: boolean;
+  large: boolean;
+  fg: string;
+  bg: string;
+}
+
+// esbuild's text loader inlines this at build time — no runtime file read.
+// @ts-expect-error — .browser.js files use esbuild text loader, not TS module resolution
+import CONTRAST_AUDIT_SCRIPT from "./contrast-audit.browser.js";
+
+const CONTRAST_SAMPLES = 5;
+const SEEK_SETTLE_MS = 150;
+
+async function getCompositionDuration(page: import("puppeteer-core").Page): Promise<number> {
+  return page.evaluate(() => {
+    if (window.__hf?.duration && window.__hf.duration > 0) return window.__hf.duration;
+    const root = document.querySelector("[data-composition-id][data-duration]");
+    return root ? parseFloat(root.getAttribute("data-duration") ?? "0") : 0;
+  });
+}
+
+async function seekTo(page: import("puppeteer-core").Page, time: number): Promise<void> {
+  await page.evaluate((t: number) => {
+    if (window.__hf && typeof window.__hf.seek === "function") {
+      window.__hf.seek(t);
+      return;
+    }
+    const timelines = (window as unknown as Record<string, unknown>).__timelines as
+      | Record<string, { seek: (t: number) => void }>
+      | undefined;
+    if (timelines) {
+      for (const tl of Object.values(timelines)) {
+        if (typeof tl.seek === "function") tl.seek(t);
+      }
+    }
+  }, time);
+  await new Promise((r) => setTimeout(r, SEEK_SETTLE_MS));
+}
+
+async function runContrastAudit(page: import("puppeteer-core").Page): Promise<ContrastEntry[]> {
+  const duration = await getCompositionDuration(page);
+  if (duration <= 0) return [];
+
+  await page.addScriptTag({ content: CONTRAST_AUDIT_SCRIPT });
+
+  const results: ContrastEntry[] = [];
+  for (let i = 0; i < CONTRAST_SAMPLES; i++) {
+    const t = +(((i + 0.5) / CONTRAST_SAMPLES) * duration).toFixed(3);
+    await seekTo(page, t);
+
+    const screenshot = (await page.screenshot({ encoding: "base64", type: "png" })) as string;
+    const entries = await page.evaluate(
+      (b64: string, time: number) =>
+        typeof (window as unknown as Record<string, unknown>).__contrastAudit === "function"
+          ? ((window as unknown as Record<string, unknown>).__contrastAudit as Function)(b64, time)
+          : [],
+      screenshot,
+      t,
+    );
+    results.push(...(entries as ContrastEntry[]));
+  }
+
+  return results;
+}
+
 async function validateInBrowser(
  projectDir: string,
-  opts: { timeout?: number },
-): Promise<{ errors: ConsoleEntry[]; warnings: ConsoleEntry[] }> {
+  opts: { timeout?: number; contrast?: boolean },
+): Promise<{ errors: ConsoleEntry[]; warnings: ConsoleEntry[]; contrast?: ContrastEntry[] }> {
  const { bundleToSingleHtml } = await import("@hyperframes/core/compiler");
  const { ensureBrowser } = await import("../browser/manager.js");

-  // 1. Bundle
  let html = await bundleToSingleHtml(projectDir);

-  // Inject local runtime if available
  const runtimePath = resolve(
    __dirname,
    "..",
@@ -48,7 +112,6 @@ async function validateInBrowser(
    );
  }

-  // 2. Start minimal file server for project assets (audio, images, fonts, json)
  const { createServer } = await import("node:http");
  const { getMimeType } = await import("@hyperframes/core/studio-api");

@@ -59,7 +122,6 @@ async function validateInBrowser(
      res.end(html);
      return;
    }
-    // Serve project files
    const filePath = join(projectDir, decodeURIComponent(url));
    if (existsSync(filePath)) {
      res.writeHead(200, { "Content-Type": getMimeType(filePath) });
@@ -79,9 +141,9 @@ async function validateInBrowser(

  const errors: ConsoleEntry[] = [];
  const warnings: ConsoleEntry[] = [];
+  let contrast: ContrastEntry[] | undefined;

  try {
-    // 3. Launch headless Chrome
    const browser = await ensureBrowser();
    const puppeteer = await import("puppeteer-core");
    const chromeBrowser = await puppeteer.default.launch({
@@ -93,14 +155,11 @@ async function validateInBrowser(
    const page = await chromeBrowser.newPage();
    await page.setViewport({ width: 1920, height: 1080 });

-    // 4. Capture console messages
    page.on("console", (msg) => {
      const type = msg.type();
      const loc = msg.location();
      const text = msg.text();
      if (type === "error") {
-        // Network errors show as console errors but with no useful location.
-        // We capture those separately via response/requestfailed events.
        if (text.startsWith("Failed to load resource")) return;
        errors.push({ level: "error", text, url: loc.url, line: loc.lineNumber });
      } else if (type === "warn") {
@@ -108,52 +167,54 @@ async function validateInBrowser(
      }
    });

-    // Capture uncaught exceptions
    page.on("pageerror", (err) => {
-      const message = err instanceof Error ? err.message : String(err);
-      errors.push({ level: "error", text: message });
+      errors.push({ level: "error", text: err instanceof Error ? err.message : String(err) });
    });

-    // Capture failed network requests for project assets (skip favicon, data: URIs)
    page.on("requestfailed", (req) => {
      const url = req.url();
-      if (url.includes("favicon")) return;
-      if (url.startsWith("data:")) return;
-      // Extract the path relative to the server
-      const urlObj = new URL(url);
-      const path = decodeURIComponent(urlObj.pathname).replace(/^\//, "");
-      const failure = req.failure()?.errorText ?? "net::ERR_FAILED";
-      errors.push({ level: "error", text: `Failed to load ${path}: ${failure}`, url });
+      if (url.includes("favicon") || url.startsWith("data:")) return;
+      const path = decodeURIComponent(new URL(url).pathname).replace(/^\//, "");
+      errors.push({
+        level: "error",
+        text: `Failed to load ${path}: ${req.failure()?.errorText ?? "net::ERR_FAILED"}`,
+        url,
+      });
    });

-    // Capture HTTP errors (404, 500, etc.) for project assets
    page.on("response", (res) => {
-      const status = res.status();
-      if (status >= 400) {
+      if (res.status() >= 400) {
        const url = res.url();
        if (url.includes("favicon")) return;
-        const urlObj = new URL(url);
-        const path = decodeURIComponent(urlObj.pathname).replace(/^\//, "");
-        errors.push({ level: "error", text: `${status} loading ${path}`, url });
+        const path = decodeURIComponent(new URL(url).pathname).replace(/^\//, "");
+        errors.push({ level: "error", text: `${res.status()} loading ${path}`, url });
      }
    });

-    // 5. Navigate and wait
-    const timeoutMs = opts.timeout ?? 3000;
-    await page.goto(`http://127.0.0.1:${port}/`, {
-      waitUntil: "domcontentloaded",
-      timeout: 10000,
-    });
+    await page.goto(`http://127.0.0.1:${port}/`, { waitUntil: "domcontentloaded", timeout: 10000 });
+    await new Promise((r) => setTimeout(r, opts.timeout ?? 3000));

-    // Wait for scripts to settle
-    await new Promise((r) => setTimeout(r, timeoutMs));
+    if (opts.contrast) {
+      contrast = await runContrastAudit(page);
+    }

    await chromeBrowser.close();
  } finally {
    server.close();
  }

-  return { errors, warnings };
+  return { errors, warnings, contrast };
+}
+
+function printContrastFailures(failures: ContrastEntry[]) {
+  console.log();
+  console.log(`  ${c.warn("⚠")} WCAG AA contrast warnings (${failures.length}):`);
+  for (const cf of failures) {
+    const threshold = cf.large ? "3" : "4.5";
+    console.log(
+      `    ${c.warn("·")} ${cf.selector} ${c.dim(`"${cf.text}"`)} — ${c.warn(cf.ratio + ":1")} ${c.dim(`(need ${threshold}:1, t=${cf.time}s)`)}`,
+    );
+  }
 }

 export default defineCommand({
@@ -168,15 +229,12 @@ Examples:
  hyperframes validate --timeout 5000`,
  },
  args: {
-    dir: {
-      type: "positional",
-      description: "Project directory",
-      required: false,
-    },
-    json: {
+    dir: { type: "positional", description: "Project directory", required: false },
+    json: { type: "boolean", description: "Output as JSON", default: false },
+    contrast: {
      type: "boolean",
-      description: "Output as JSON",
-      default: false,
+      description: "WCAG contrast audit (enabled by default)",
+      default: true,
    },
    timeout: {
      type: "string",
@@ -187,13 +245,20 @@ Examples:
  async run({ args }) {
    const project = resolveProject(args.dir);
    const timeout = parseInt(args.timeout as string, 10) || 3000;
+    const useContrast = args.contrast ?? true;

    if (!args.json) {
      console.log(`${c.accent("◆")}  Validating ${c.accent(project.name)} in headless Chrome`);
    }

    try {
-      const { errors, warnings } = await validateInBrowser(project.dir, { timeout });
+      const { errors, warnings, contrast } = await validateInBrowser(project.dir, {
+        timeout,
+        contrast: useContrast,
+      });
+
+      const contrastFailures = (contrast ?? []).filter((e) => !e.wcagAA);
+      const contrastPassed = (contrast ?? []).filter((e) => e.wcagAA);

      if (args.json) {
        console.log(
@@ -202,6 +267,8 @@ Examples:
              ok: errors.length === 0,
              errors,
              warnings,
+              contrast,
+              contrastFailures: contrastFailures.length,
            }),
            null,
            2,
@@ -210,22 +277,26 @@ Examples:
        process.exit(errors.length > 0 ? 1 : 0);
      }

-      if (errors.length === 0 && warnings.length === 0) {
-        console.log(`${c.success("◇")}  No console errors`);
+      if (errors.length === 0 && warnings.length === 0 && contrastFailures.length === 0) {
+        const suffix =
+          contrastPassed.length > 0 ? ` · ${contrastPassed.length} text elements pass WCAG AA` : "";
+        console.log(`${c.success("◇")}  No console errors${suffix}`);
        return;
      }

      console.log();
      for (const e of errors) {
-        const loc = e.line ? ` (line ${e.line})` : "";
-        console.log(`  ${c.error("✗")} ${e.text}${c.dim(loc)}`);
+        console.log(`  ${c.error("✗")} ${e.text}${e.line ? c.dim(` (line ${e.line})`) : ""}`);
      }
      for (const w of warnings) {
-        const loc = w.line ? ` (line ${w.line})` : "";
-        console.log(`  ${c.warn("⚠")} ${w.text}${c.dim(loc)}`);
+        console.log(`  ${c.warn("⚠")} ${w.text}${w.line ? c.dim(` (line ${w.line})`) : ""}`);
      }
+      if (contrastFailures.length > 0) printContrastFailures(contrastFailures);
+
      console.log();
-      console.log(`${c.accent("◇")}  ${errors.length} error(s), ${warnings.length} warning(s)`);
+      const parts = [`${errors.length} error(s)`, `${warnings.length} warning(s)`];
+      if (contrastFailures.length > 0) parts.push(`${contrastFailures.length} contrast warning(s)`);
+      console.log(`${c.accent("◇")}  ${parts.join(", ")}`);

      process.exit(errors.length > 0 ? 1 : 0);
    } catch (err: unknown) {
@@ -57,5 +57,6 @@ var __dirname = __hf_dirname(__filename);`,
    options.alias = {
      "@hyperframes/producer": resolve(__dirname, "../producer/src/index.ts"),
    };
+    options.loader = { ...options.loader, ".browser.js": "text" };
  },
 });
@@ -0,0 +1,596 @@
+#!/usr/bin/env node
+// animation-map.mjs — HyperFrames animation map for agents
+//
+// Reads every GSAP timeline registered in window.__timelines, enumerates
+// tweens, samples bboxes at N points per tween, computes flags and
+// human-readable summaries. Outputs a single animation-map.json.
+//
+// Usage:
+//   node skills/hyperframes-animation-map/scripts/animation-map.mjs <composition-dir> \
+//     [--frames N] [--out <dir>] [--min-duration S] [--width W] [--height H] [--fps N]
+
+import { mkdir, writeFile } from "node:fs/promises";
+import { resolve, join } from "node:path";
+
+import {
+  createFileServer,
+  createCaptureSession,
+  initializeSession,
+  closeCaptureSession,
+  getCompositionDuration,
+} from "@hyperframes/producer";
+
+// ─── CLI ─────────────────────────────────────────────────────────────────────
+
+const args = parseArgs(process.argv.slice(2));
+if (!args.composition) die("missing <composition-dir>");
+
+const FRAMES = Number(args.frames ?? 6);
+const OUT_DIR = resolve(args.out ?? ".hyperframes/anim-map");
+const MIN_DUR = Number(args["min-duration"] ?? 0.15);
+const WIDTH = Number(args.width ?? 1920);
+const HEIGHT = Number(args.height ?? 1080);
+const FPS = Number(args.fps ?? 30);
+const COMP_DIR = resolve(args.composition);
+
+await mkdir(OUT_DIR, { recursive: true });
+
+// ─── Main ────────────────────────────────────────────────────────────────────
+
+const server = await createFileServer({ projectDir: COMP_DIR, port: 0 });
+const session = await createCaptureSession(
+  server.url,
+  OUT_DIR,
+  { width: WIDTH, height: HEIGHT, fps: FPS, format: "png" },
+  null,
+);
+await initializeSession(session);
+
+try {
+  const duration = await getCompositionDuration(session);
+  const tweens = await enumerateTweens(session);
+  const kept = tweens.filter((tw) => tw.end - tw.start >= MIN_DUR);
+
+  const report = {
+    composition: COMP_DIR,
+    duration,
+    totalTweens: tweens.length,
+    mappedTweens: kept.length,
+    skippedMicroTweens: tweens.length - kept.length,
+    tweens: [],
+  };
+
+  for (let i = 0; i < kept.length; i++) {
+    const tw = kept[i];
+    const times = Array.from(
+      { length: FRAMES },
+      (_, k) => +(tw.start + ((k + 0.5) / FRAMES) * (tw.end - tw.start)).toFixed(3),
+    );
+
+    const bboxes = [];
+    for (const t of times) {
+      await seekTo(session, t);
+      const bbox = await measureTarget(session, tw.selectorHint);
+      bboxes.push({ t, ...bbox });
+    }
+
+    const animProps = tw.props.filter(
+      (p) => !["parent", "overwrite", "immediateRender", "startAt", "runBackwards"].includes(p),
+    );
+    const flags = computeFlags(tw, bboxes, { width: WIDTH, height: HEIGHT });
+    const summary = describeTween(tw, animProps, bboxes, flags);
+
+    report.tweens.push({
+      index: i + 1,
+      selector: tw.selectorHint,
+      targets: tw.targetCount,
+      props: animProps,
+      start: +tw.start.toFixed(3),
+      end: +tw.end.toFixed(3),
+      duration: +(tw.end - tw.start).toFixed(3),
+      ease: tw.ease,
+      bboxes,
+      flags,
+      summary,
+    });
+  }
+
+  markCollisions(report.tweens);
+
+  for (const tw of report.tweens) {
+    if (tw.flags.includes("collision") && !tw.summary.includes("collision")) {
+      tw.summary += " Overlaps another animated element.";
+    }
+  }
+
+  // ── Composition-level analysis ──
+  report.choreography = buildTimeline(report.tweens, duration);
+  report.density = computeDensity(report.tweens, duration);
+  report.staggers = detectStaggers(report.tweens);
+  report.elements = buildElementLifecycles(report.tweens);
+  report.deadZones = findDeadZones(report.density, duration);
+  report.snapshots = await captureSnapshots(session, report.tweens, duration);
+
+  await writeFile(join(OUT_DIR, "animation-map.json"), JSON.stringify(report, null, 2));
+
+  printSummary(report);
+} finally {
+  await closeCaptureSession(session).catch(() => {});
+  server.close();
+}
+
+// ─── Seek helper ────────────────────────────────────────────────────────────
+
+async function seekTo(session, t) {
+  await session.page.evaluate((time) => {
+    if (window.__hf && typeof window.__hf.seek === "function") {
+      window.__hf.seek(time);
+      return;
+    }
+    const tls = window.__timelines;
+    if (tls) {
+      for (const tl of Object.values(tls)) {
+        if (typeof tl.seek === "function") tl.seek(time);
+      }
+    }
+  }, t);
+  await new Promise((r) => setTimeout(r, 100));
+}
+
+// ─── Timeline introspection ──────────────────────────────────────────────────
+
+async function enumerateTweens(session) {
+  return await session.page.evaluate(() => {
+    const results = [];
+    const registry = window.__timelines || {};
+
+    const selectorOf = (el) => {
+      if (!el || !(el instanceof Element)) return null;
+      if (el.id) return `#${el.id}`;
+      const cls = [...el.classList].slice(0, 2).join(".");
+      return cls ? `${el.tagName.toLowerCase()}.${cls}` : el.tagName.toLowerCase();
+    };
+
+    const walk = (node, parentOffset = 0) => {
+      if (!node) return;
+      if (typeof node.getChildren === "function") {
+        const offset = parentOffset + (node.startTime?.() ?? 0);
+        for (const child of node.getChildren(true, true, true)) {
+          walk(child, offset);
+        }
+        return;
+      }
+      const targets = (node.targets?.() ?? []).filter((t) => t instanceof Element);
+      if (!targets.length) return;
+      const vars = node.vars ?? {};
+      const props = Object.keys(vars).filter(
+        (k) =>
+          ![
+            "duration",
+            "ease",
+            "delay",
+            "repeat",
+            "yoyo",
+            "onStart",
+            "onUpdate",
+            "onComplete",
+            "stagger",
+          ].includes(k),
+      );
+      const start = parentOffset + (node.startTime?.() ?? 0);
+      const end = start + (node.duration?.() ?? 0);
+      results.push({
+        selectorHint: selectorOf(targets[0]) ?? "(unknown)",
+        targetCount: targets.length,
+        props,
+        start,
+        end,
+        ease: typeof vars.ease === "string" ? vars.ease : (vars.ease?.toString?.() ?? "none"),
+      });
+    };
+
+    for (const tl of Object.values(registry)) walk(tl, 0);
+    results.sort((a, b) => a.start - b.start);
+    return results;
+  });
+}
+
+async function measureTarget(session, selector) {
+  return await session.page.evaluate((sel) => {
+    const el = document.querySelector(sel);
+    if (!el) return { x: 0, y: 0, w: 0, h: 0, missing: true };
+    const r = el.getBoundingClientRect();
+    const cs = getComputedStyle(el);
+    return {
+      x: Math.round(r.x),
+      y: Math.round(r.y),
+      w: Math.round(r.width),
+      h: Math.round(r.height),
+      opacity: parseFloat(cs.opacity),
+      visible: cs.visibility !== "hidden" && cs.display !== "none",
+    };
+  }, selector);
+}
+
+// ─── Tween description (the key output for agents) ──────────────────────────
+
+function describeTween(tw, props, bboxes, flags) {
+  const dur = (tw.end - tw.start).toFixed(2);
+  const parts = [];
+
+  parts.push(`${tw.selectorHint} animates ${props.join("+")} over ${dur}s (${tw.ease})`);
+
+  // Movement
+  const first = bboxes[0];
+  const last = bboxes[bboxes.length - 1];
+  if (first && last) {
+    const dx = last.x - first.x;
+    const dy = last.y - first.y;
+    if (Math.abs(dx) > 3 || Math.abs(dy) > 3) {
+      const dirs = [];
+      if (Math.abs(dy) > 3) dirs.push(dy < 0 ? `${Math.abs(dy)}px up` : `${Math.abs(dy)}px down`);
+      if (Math.abs(dx) > 3)
+        dirs.push(dx < 0 ? `${Math.abs(dx)}px left` : `${Math.abs(dx)}px right`);
+      parts.push(`moves ${dirs.join(" and ")}`);
+    }
+  }
+
+  // Opacity
+  if (first && last && first.opacity !== undefined && last.opacity !== undefined) {
+    const o1 = first.opacity;
+    const o2 = last.opacity;
+    if (Math.abs(o2 - o1) > 0.1) {
+      if (o1 < 0.1 && o2 > 0.5) parts.push("fades in");
+      else if (o1 > 0.5 && o2 < 0.1) parts.push("fades out");
+      else parts.push(`opacity ${o1.toFixed(1)}→${o2.toFixed(1)}`);
+    }
+  }
+
+  // Scale (from props)
+  if (props.includes("scale") || props.includes("scaleX") || props.includes("scaleY")) {
+    parts.push("scales");
+  }
+
+  // Size changes
+  if (first && last) {
+    const dw = last.w - first.w;
+    const dh = last.h - first.h;
+    if (Math.abs(dw) > 5) parts.push(`width ${first.w}→${last.w}px`);
+    if (Math.abs(dh) > 5) parts.push(`height ${first.h}→${last.h}px`);
+  }
+
+  // Visibility
+  if (first && last && first.visible !== last.visible) {
+    parts.push(last.visible ? "becomes visible" : "becomes hidden");
+  }
+
+  // Final position
+  if (last && !last.missing) {
+    parts.push(`ends at (${last.x}, ${last.y}) ${last.w}×${last.h}px`);
+  }
+
+  // Flags
+  if (flags.length > 0) {
+    parts.push(`FLAGS: ${flags.join(", ")}`);
+  }
+
+  return parts.join(". ") + ".";
+}
+
+// ─── Flag computation ───────────────────────────────────────────────────────
+
+function computeFlags(tw, bboxes, { width, height }) {
+  const flags = [];
+  const dur = tw.end - tw.start;
+
+  if (bboxes.every((b) => b.w === 0 || b.h === 0)) flags.push("degenerate");
+
+  const anyOffscreen = bboxes.some(
+    (b) =>
+      b.x + b.w <= 0 ||
+      b.y + b.h <= 0 ||
+      b.x >= width ||
+      b.y >= height ||
+      b.x < -b.w * 0.5 ||
+      b.y < -b.h * 0.5 ||
+      b.x + b.w > width + b.w * 0.5 ||
+      b.y + b.h > height + b.h * 0.5,
+  );
+  if (anyOffscreen) flags.push("offscreen");
+
+  if (bboxes.every((b) => b.opacity !== undefined && b.opacity < 0.01 && b.visible)) {
+    flags.push("invisible");
+  }
+
+  if (dur < 0.2 && tw.props.some((p) => ["y", "x", "opacity", "scale"].includes(p))) {
+    flags.push("paced-fast");
+  }
+  if (dur > 2.0) flags.push("paced-slow");
+
+  return flags;
+}
+
+function markCollisions(tweens) {
+  for (let i = 0; i < tweens.length; i++) {
+    for (let j = i + 1; j < tweens.length; j++) {
+      const a = tweens[i];
+      const b = tweens[j];
+      if (a.end <= b.start || b.end <= a.start) continue;
+      for (const ba of a.bboxes) {
+        const bb = b.bboxes.find((x) => Math.abs(x.t - ba.t) < 0.05);
+        if (!bb) continue;
+        const overlap = rectOverlapArea(ba, bb);
+        const aArea = ba.w * ba.h;
+        if (aArea > 0 && overlap / aArea > 0.3) {
+          if (!a.flags.includes("collision")) a.flags.push("collision");
+          if (!b.flags.includes("collision")) b.flags.push("collision");
+          break;
+        }
+      }
+    }
+  }
+}
+
+function rectOverlapArea(a, b) {
+  const x1 = Math.max(a.x, b.x);
+  const y1 = Math.max(a.y, b.y);
+  const x2 = Math.min(a.x + a.w, b.x + b.w);
+  const y2 = Math.min(a.y + a.h, b.y + b.h);
+  return Math.max(0, x2 - x1) * Math.max(0, y2 - y1);
+}
+
+// ─── Composition-level analysis ─────────────────────────────────────────────
+
+function buildTimeline(tweens, duration) {
+  const cols = 60;
+  const lines = [];
+  const secPerCol = duration / cols;
+
+  lines.push("Timeline (" + duration.toFixed(1) + "s, each char ≈ " + secPerCol.toFixed(2) + "s):");
+  lines.push("  " + "0s" + " ".repeat(cols - 8) + duration.toFixed(0) + "s");
+  lines.push("  " + "┼" + "─".repeat(cols - 1) + "┤");
+
+  for (const tw of tweens) {
+    const startCol = Math.floor(tw.start / secPerCol);
+    const endCol = Math.min(cols, Math.ceil(tw.end / secPerCol));
+    const bar =
+      " ".repeat(startCol) +
+      "█".repeat(Math.max(1, endCol - startCol)) +
+      " ".repeat(Math.max(0, cols - endCol));
+    const label = tw.selector + " " + tw.props.join("+");
+    lines.push("  " + bar + "  " + label);
+  }
+
+  return lines.join("\n");
+}
+
+function computeDensity(tweens, duration) {
+  const buckets = [];
+  for (let t = 0; t < duration; t += 0.5) {
+    const active = tweens.filter((tw) => tw.start <= t + 0.5 && tw.end >= t);
+    buckets.push({ t: +t.toFixed(1), activeTweens: active.length });
+  }
+  return buckets;
+}
+
+function findDeadZones(density, duration) {
+  const zones = [];
+  let zoneStart = null;
+  for (const d of density) {
+    if (d.activeTweens === 0) {
+      if (zoneStart === null) zoneStart = d.t;
+    } else {
+      if (zoneStart !== null) {
+        const zoneEnd = d.t;
+        if (zoneEnd - zoneStart >= 1.0) {
+          zones.push({
+            start: zoneStart,
+            end: zoneEnd,
+            duration: +(zoneEnd - zoneStart).toFixed(1),
+            note:
+              "No animation for " +
+              (zoneEnd - zoneStart).toFixed(1) +
+              "s. Intentional hold or missing entrance?",
+          });
+        }
+        zoneStart = null;
+      }
+    }
+  }
+  if (zoneStart !== null && duration - zoneStart >= 1.0) {
+    zones.push({
+      start: zoneStart,
+      end: +duration.toFixed(1),
+      duration: +(duration - zoneStart).toFixed(1),
+      note:
+        "No animation for " +
+        (duration - zoneStart).toFixed(1) +
+        "s at end. Final hold or missing outro?",
+    });
+  }
+  return zones;
+}
+
+function detectStaggers(tweens) {
+  const groups = [];
+  const used = new Set();
+
+  for (let i = 0; i < tweens.length; i++) {
+    if (used.has(i)) continue;
+    const tw = tweens[i];
+    const group = [tw];
+    used.add(i);
+
+    for (let j = i + 1; j < tweens.length; j++) {
+      if (used.has(j)) continue;
+      const other = tweens[j];
+      const sameProps = tw.props.join(",") === other.props.join(",");
+      const sameDuration = Math.abs(tw.duration - other.duration) < 0.05;
+      const closeInTime = other.start - tw.start < tw.duration * 4;
+      if (sameProps && sameDuration && closeInTime) {
+        group.push(other);
+        used.add(j);
+      }
+    }
+
+    if (group.length >= 3) {
+      const intervals = [];
+      for (let k = 1; k < group.length; k++) {
+        intervals.push(+(group[k].start - group[k - 1].start).toFixed(3));
+      }
+      const avgInterval = intervals.reduce((a, b) => a + b, 0) / intervals.length;
+      const maxDrift = Math.max(...intervals.map((iv) => Math.abs(iv - avgInterval)));
+      const consistent = maxDrift < avgInterval * 0.3;
+
+      groups.push({
+        elements: group.map((g) => g.selector),
+        props: tw.props,
+        count: group.length,
+        intervals,
+        avgInterval: +avgInterval.toFixed(3),
+        consistent,
+        note: consistent
+          ? group.length +
+            " elements stagger at " +
+            (avgInterval * 1000).toFixed(0) +
+            "ms intervals"
+          : group.length +
+            " elements stagger with uneven intervals (" +
+            intervals.map((iv) => (iv * 1000).toFixed(0) + "ms").join(", ") +
+            ")",
+      });
+    }
+  }
+
+  return groups;
+}
+
+function buildElementLifecycles(tweens) {
+  const elements = {};
+  for (const tw of tweens) {
+    const sel = tw.selector;
+    if (!elements[sel]) {
+      elements[sel] = { firstTween: tw.start, lastTween: tw.end, tweenCount: 0, props: new Set() };
+    }
+    elements[sel].firstTween = Math.min(elements[sel].firstTween, tw.start);
+    elements[sel].lastTween = Math.max(elements[sel].lastTween, tw.end);
+    elements[sel].tweenCount++;
+    tw.props.forEach((p) => elements[sel].props.add(p));
+  }
+
+  const result = {};
+  for (const [sel, data] of Object.entries(elements)) {
+    const lastBbox = findLastBbox(tweens, sel);
+    result[sel] = {
+      firstAppears: +data.firstTween.toFixed(3),
+      lastAnimates: +data.lastTween.toFixed(3),
+      tweenCount: data.tweenCount,
+      props: [...data.props],
+      endsVisible: lastBbox ? lastBbox.opacity > 0.1 && lastBbox.visible : null,
+      finalPosition: lastBbox
+        ? { x: lastBbox.x, y: lastBbox.y, w: lastBbox.w, h: lastBbox.h }
+        : null,
+    };
+  }
+  return result;
+}
+
+function findLastBbox(tweens, selector) {
+  for (let i = tweens.length - 1; i >= 0; i--) {
+    if (tweens[i].selector === selector && tweens[i].bboxes?.length > 0) {
+      return tweens[i].bboxes[tweens[i].bboxes.length - 1];
+    }
+  }
+  return null;
+}
+
+async function captureSnapshots(session, tweens, duration) {
+  const times = [0, duration * 0.25, duration * 0.5, duration * 0.75, duration - 0.1];
+  const snapshots = [];
+
+  for (const t of times) {
+    await seekTo(session, t);
+    const visible = await session.page.evaluate(() => {
+      const out = [];
+      const els = document.querySelectorAll("[id]");
+      for (const el of els) {
+        const cs = getComputedStyle(el);
+        if (cs.display === "none") continue;
+        const opacity = parseFloat(cs.opacity);
+        if (opacity < 0.01) continue;
+        const rect = el.getBoundingClientRect();
+        if (rect.width < 1 || rect.height < 1) continue;
+        out.push({
+          id: el.id,
+          x: Math.round(rect.x),
+          y: Math.round(rect.y),
+          w: Math.round(rect.width),
+          h: Math.round(rect.height),
+          opacity: +opacity.toFixed(2),
+        });
+      }
+      return out;
+    });
+
+    const activeTweens = tweens
+      .filter((tw) => tw.start <= t && tw.end >= t)
+      .map((tw) => tw.selector);
+
+    snapshots.push({
+      t: +t.toFixed(2),
+      visibleElements: visible.length,
+      animatingNow: activeTweens,
+      elements: visible,
+    });
+  }
+
+  return snapshots;
+}
+
+// ─── Output ─────────────────────────────────────────────────────────────────
+
+function printSummary(report) {
+  console.log(
+    `\nAnimation map: ${report.mappedTweens}/${report.totalTweens} tweens (skipped ${report.skippedMicroTweens} micro-tweens)`,
+  );
+
+  const flagCounts = {};
+  for (const tw of report.tweens) {
+    for (const f of tw.flags) flagCounts[f] = (flagCounts[f] ?? 0) + 1;
+  }
+  if (Object.keys(flagCounts).length > 0) {
+    for (const [f, n] of Object.entries(flagCounts)) console.log(`  ${f}: ${n}`);
+  }
+  if (report.staggers?.length > 0) {
+    console.log(`  staggers: ${report.staggers.map((s) => s.note).join("; ")}`);
+  }
+  if (report.deadZones?.length > 0) {
+    console.log(
+      `  dead zones: ${report.deadZones.map((z) => z.start + "-" + z.end + "s").join(", ")}`,
+    );
+  }
+
+  console.log(report.choreography);
+}
+
+function parseArgs(argv) {
+  const out = {};
+  let positional = 0;
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a.startsWith("--")) {
+      const k = a.slice(2);
+      const v = argv[i + 1]?.startsWith("--") ? true : argv[++i];
+      out[k] = v;
+    } else if (positional === 0) {
+      out.composition = a;
+      positional++;
+    }
+  }
+  return out;
+}
+
+function die(msg) {
+  console.error(`animation-map: ${msg}`);
+  process.exit(2);
+}
@@ -0,0 +1,335 @@
+#!/usr/bin/env node
+// contrast-report.mjs — HyperFrames contrast audit
+//
+// Reads a composition, seeks to N sample timestamps, walks the DOM for text
+// elements, measures the WCAG 2.1 contrast ratio between each element's
+// declared foreground color and the pixels behind it, and emits:
+//
+//   - contrast-report.json  (machine-readable, one entry per text element × sample)
+//   - contrast-overlay.png  (sprite grid; magenta=fail AA, yellow=pass AA only, green=AAA)
+//
+// Usage:
+//   node skills/hyperframes-contrast/scripts/contrast-report.mjs <composition-dir> \
+//     [--samples N] [--out <dir>] [--width W] [--height H] [--fps N]
+//
+// The composition directory must contain an index.html. Raw authoring HTML
+// works — the producer's file server auto-injects the runtime at serve time.
+// Exits 1 if any text element fails WCAG AA.
+
+import { mkdir, writeFile } from "node:fs/promises";
+import { resolve } from "node:path";
+
+import sharp from "sharp";
+
+// Use the producer's file server — it auto-injects the HyperFrames runtime
+// and render-seek bridge, so raw authoring HTML works without a build step.
+import {
+  createFileServer,
+  createCaptureSession,
+  initializeSession,
+  closeCaptureSession,
+  captureFrameToBuffer,
+  getCompositionDuration,
+} from "@hyperframes/producer";
+
+// ─── CLI ─────────────────────────────────────────────────────────────────────
+
+const args = parseArgs(process.argv.slice(2));
+if (!args.composition) die("missing <composition-dir>");
+
+const SAMPLES = Number(args.samples ?? 10);
+const OUT_DIR = resolve(args.out ?? ".hyperframes/contrast");
+const WIDTH = Number(args.width ?? 1920);
+const HEIGHT = Number(args.height ?? 1080);
+const FPS = Number(args.fps ?? 30);
+const COMP_DIR = resolve(args.composition);
+
+// ─── Main ────────────────────────────────────────────────────────────────────
+
+await mkdir(OUT_DIR, { recursive: true });
+
+const server = await createFileServer({ projectDir: COMP_DIR, port: 0 });
+const session = await createCaptureSession(
+  server.url,
+  OUT_DIR,
+  { width: WIDTH, height: HEIGHT, fps: FPS, format: "png" },
+  null,
+);
+await initializeSession(session);
+
+try {
+  const duration = await getCompositionDuration(session);
+  const times = Array.from(
+    { length: SAMPLES },
+    (_, i) => +(((i + 0.5) / SAMPLES) * duration).toFixed(3),
+  );
+
+  const allEntries = [];
+  const overlayFrames = [];
+
+  for (let i = 0; i < times.length; i++) {
+    const t = times[i];
+    const { buffer: pngBuf } = await captureFrameToBuffer(session, i, t);
+    const elements = await probeTextElements(session, t);
+    const annotated = await annotateFrame(pngBuf, elements);
+    overlayFrames.push({ t, png: annotated });
+    for (const el of elements) allEntries.push({ time: t, ...el });
+  }
+
+  const report = {
+    composition: COMP_DIR,
+    width: WIDTH,
+    height: HEIGHT,
+    duration,
+    samples: times,
+    entries: allEntries,
+    summary: summarize(allEntries),
+  };
+
+  await writeFile(resolve(OUT_DIR, "contrast-report.json"), JSON.stringify(report, null, 2));
+  await writeOverlaySprite(overlayFrames, resolve(OUT_DIR, "contrast-overlay.png"));
+
+  printSummary(report);
+  process.exitCode = report.summary.failAA > 0 ? 1 : 0;
+} finally {
+  await closeCaptureSession(session).catch(() => {});
+  server.close();
+}
+
+// ─── DOM probe (runs in the page) ────────────────────────────────────────────
+
+async function probeTextElements(session, _t) {
+  // `session.page` is the Puppeteer Page owned by the capture session.
+  // We pass a pure function to `evaluate`: it walks the DOM and returns
+  // enough info for us to compute a ratio in Node using the frame buffer.
+  return await session.page.evaluate(() => {
+    /** @type {Array<{selector: string, text: string, fg: [number,number,number,number], fontSize: number, fontWeight: number, bbox: {x:number,y:number,w:number,h:number}}>} */
+    const out = [];
+    const walker = document.createTreeWalker(document.body, NodeFilter.SHOW_ELEMENT);
+    const parseColor = (c) => {
+      const m = c.match(/rgba?\(([^)]+)\)/);
+      if (!m) return [0, 0, 0, 1];
+      const parts = m[1].split(",").map((s) => parseFloat(s.trim()));
+      return [parts[0], parts[1], parts[2], parts[3] ?? 1];
+    };
+    const selectorOf = (el) => {
+      if (el.id) return `#${el.id}`;
+      const cls = [...el.classList].slice(0, 2).join(".");
+      return cls ? `${el.tagName.toLowerCase()}.${cls}` : el.tagName.toLowerCase();
+    };
+    let el;
+    while ((el = walker.nextNode())) {
+      // must have direct text
+      const direct = [...el.childNodes].some(
+        (n) => n.nodeType === 3 && n.textContent.trim().length,
+      );
+      if (!direct) continue;
+      const cs = getComputedStyle(el);
+      if (cs.visibility === "hidden" || cs.display === "none") continue;
+      if (parseFloat(cs.opacity) <= 0.01) continue;
+      const rect = el.getBoundingClientRect();
+      if (rect.width < 8 || rect.height < 8) continue;
+      out.push({
+        selector: selectorOf(el),
+        text: el.textContent.trim().slice(0, 60),
+        fg: parseColor(cs.color),
+        fontSize: parseFloat(cs.fontSize),
+        fontWeight: Number(cs.fontWeight) || 400,
+        bbox: { x: rect.x, y: rect.y, w: rect.width, h: rect.height },
+      });
+    }
+    return out;
+  });
+}
+
+// ─── Pixel sampling + WCAG math ──────────────────────────────────────────────
+
+async function annotateFrame(pngBuf, elements) {
+  const img = sharp(pngBuf);
+  const meta = await img.metadata();
+  const { width, height } = meta;
+  const raw = await img.ensureAlpha().raw().toBuffer();
+  const channels = 4;
+
+  const measured = [];
+  for (const el of elements) {
+    const bg = sampleRingMedian(raw, width, height, channels, el.bbox);
+    const fg = compositeOver(el.fg, bg); // flatten any alpha against measured bg
+    const ratio = wcagRatio(fg, bg);
+    const large = isLargeText(el.fontSize, el.fontWeight);
+    el.bg = bg;
+    el.ratio = +ratio.toFixed(2);
+    el.wcagAA = large ? ratio >= 3 : ratio >= 4.5;
+    el.wcagAALarge = ratio >= 3;
+    el.wcagAAA = large ? ratio >= 4.5 : ratio >= 7;
+    measured.push(el);
+  }
+
+  // Draw boxes + ratio labels as an SVG overlay (sharp composite).
+  const svg = buildOverlaySVG(measured, width, height);
+  return await sharp(pngBuf)
+    .composite([{ input: Buffer.from(svg), top: 0, left: 0 }])
+    .png()
+    .toBuffer();
+}
+
+function sampleRingMedian(raw, width, height, channels, bbox) {
+  // 4-px ring immediately outside the element bbox. Median of each channel.
+  const r = [],
+    g = [],
+    b = [];
+  const x0 = Math.max(0, Math.floor(bbox.x) - 4);
+  const x1 = Math.min(width - 1, Math.ceil(bbox.x + bbox.w) + 4);
+  const y0 = Math.max(0, Math.floor(bbox.y) - 4);
+  const y1 = Math.min(height - 1, Math.ceil(bbox.y + bbox.h) + 4);
+  const pushPixel = (x, y) => {
+    const i = (y * width + x) * channels;
+    r.push(raw[i]);
+    g.push(raw[i + 1]);
+    b.push(raw[i + 2]);
+  };
+  for (let x = x0; x <= x1; x++) {
+    pushPixel(x, y0);
+    pushPixel(x, y1);
+  }
+  for (let y = y0; y <= y1; y++) {
+    pushPixel(x0, y);
+    pushPixel(x1, y);
+  }
+  return [median(r), median(g), median(b), 1];
+}
+
+function median(arr) {
+  const s = [...arr].sort((a, b) => a - b);
+  return s[Math.floor(s.length / 2)];
+}
+
+function compositeOver([fr, fg, fb, fa], [br, bg, bb]) {
+  return [
+    Math.round(fr * fa + br * (1 - fa)),
+    Math.round(fg * fa + bg * (1 - fa)),
+    Math.round(fb * fa + bb * (1 - fa)),
+    1,
+  ];
+}
+
+function relLum([r, g, b]) {
+  const ch = (v) => {
+    const s = v / 255;
+    return s <= 0.03928 ? s / 12.92 : ((s + 0.055) / 1.055) ** 2.4;
+  };
+  return 0.2126 * ch(r) + 0.7152 * ch(g) + 0.0722 * ch(b);
+}
+
+function wcagRatio(a, b) {
+  const la = relLum(a);
+  const lb = relLum(b);
+  const [L1, L2] = la > lb ? [la, lb] : [lb, la];
+  return (L1 + 0.05) / (L2 + 0.05);
+}
+
+function isLargeText(fontSize, fontWeight) {
+  return fontSize >= 24 || (fontSize >= 19 && fontWeight >= 700);
+}
+
+// ─── Overlay rendering ───────────────────────────────────────────────────────
+
+function buildOverlaySVG(elements, w, h) {
+  const rects = elements
+    .map((el) => {
+      const color = !el.wcagAA ? "#ff00aa" : !el.wcagAAA ? "#ffcc00" : "#00e08a";
+      const { x, y, w: bw, h: bh } = el.bbox;
+      return `
+        <rect x="${x}" y="${y}" width="${bw}" height="${bh}"
+              fill="none" stroke="${color}" stroke-width="3"/>
+        <rect x="${x}" y="${y - 18}" width="${48}" height="16" fill="${color}"/>
+        <text x="${x + 4}" y="${y - 5}" font-family="monospace" font-size="12" fill="#000">
+          ${el.ratio.toFixed(1)}:1
+        </text>`;
+    })
+    .join("");
+  return `<svg xmlns="http://www.w3.org/2000/svg" width="${w}" height="${h}">${rects}</svg>`;
+}
+
+async function writeOverlaySprite(frames, outPath) {
+  if (!frames.length) return;
+  const cols = Math.min(frames.length, 5);
+  const rows = Math.ceil(frames.length / cols);
+  const { width, height } = await sharp(frames[0].png).metadata();
+  const scale = 0.25;
+  const cellW = Math.round(width * scale);
+  const cellH = Math.round(height * scale);
+
+  const cells = await Promise.all(
+    frames.map(async (f) => ({
+      input: await sharp(f.png).resize(cellW, cellH).png().toBuffer(),
+      time: f.t,
+    })),
+  );
+
+  const composites = cells.map((c, i) => ({
+    input: c.input,
+    top: Math.floor(i / cols) * cellH,
+    left: (i % cols) * cellW,
+  }));
+
+  await sharp({
+    create: {
+      width: cols * cellW,
+      height: rows * cellH,
+      channels: 3,
+      background: { r: 16, g: 16, b: 20 },
+    },
+  })
+    .composite(composites)
+    .png()
+    .toFile(outPath);
+}
+
+// ─── Summary ────────────────────────────────────────────────────────────────
+
+function summarize(entries) {
+  const total = entries.length;
+  const failAA = entries.filter((e) => !e.wcagAA).length;
+  const passAAonly = entries.filter((e) => e.wcagAA && !e.wcagAAA).length;
+  const passAAA = entries.filter((e) => e.wcagAAA).length;
+  return { total, failAA, passAAonly, passAAA };
+}
+
+function printSummary({ summary, entries }) {
+  const { total, failAA, passAAonly, passAAA } = summary;
+  console.log(`\nContrast report: ${total} text-element samples`);
+  console.log(`  fail WCAG AA:     ${failAA}`);
+  console.log(`  pass AA, not AAA: ${passAAonly}`);
+  console.log(`  pass AAA:         ${passAAA}`);
+  if (failAA) {
+    console.log("\nFailures:");
+    for (const e of entries.filter((x) => !x.wcagAA)) {
+      console.log(`  t=${e.time}s  ${e.selector.padEnd(24)}  ${e.ratio.toFixed(2)}:1  "${e.text}"`);
+    }
+  }
+}
+
+// ─── Utilities ──────────────────────────────────────────────────────────────
+
+function parseArgs(argv) {
+  const out = {};
+  let positional = 0;
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a.startsWith("--")) {
+      const k = a.slice(2);
+      const v = argv[i + 1]?.startsWith("--") ? true : argv[++i];
+      out[k] = v;
+    } else if (positional === 0) {
+      out.composition = a;
+      positional++;
+    }
+  }
+  return out;
+}
+
+function die(msg) {
+  console.error(`contrast-report: ${msg}`);
+  process.exit(2);
+}
@@ -257,6 +257,51 @@ When no `visual-style.md` or animation direction is provided, follow [house-styl
 ## Output Checklist

 - [ ] `npx hyperframes lint` and `npx hyperframes validate` both pass
+- [ ] Contrast warnings addressed (see Quality Checks below)
+- [ ] Animation choreography verified (see Quality Checks below)
+
+## Quality Checks
+
+### Contrast
+
+`hyperframes validate` runs a WCAG contrast audit by default. It seeks to 5 timestamps, screenshots the page, samples background pixels behind every text element, and computes contrast ratios. Failures appear as warnings:
+
+```
+⚠ WCAG AA contrast warnings (3):
+  · .subtitle "secondary text" — 2.67:1 (need 4.5:1, t=5.3s)
+```
+
+If warnings appear:
+
+- On dark backgrounds: brighten the failing color until it clears 4.5:1 (normal text) or 3:1 (large text, 24px+ or 19px+ bold)
+- On light backgrounds: darken it
+- Stay within the palette family — don't invent a new color, adjust the existing one
+- Re-run `hyperframes validate` until clean
+
+Use `--no-contrast` to skip if iterating rapidly and you'll check later.
+
+### Animation Map
+
+After authoring animations, run the animation map to verify choreography:
+
+```bash
+node skills/hyperframes-animation-map/scripts/animation-map.mjs <composition-dir> \
+  --out <composition-dir>/.hyperframes/anim-map
+```
+
+Outputs a single `animation-map.json` with:
+
+- **Per-tween summaries**: `"#card1 animates opacity+y over 0.50s. moves 23px up. fades in. ends at (120, 200)"`
+- **ASCII timeline**: Gantt chart of all tweens across the composition duration
+- **Stagger detection**: reports actual intervals (`"3 elements stagger at 120ms"`)
+- **Dead zones**: periods over 1s with no animation — intentional hold or missing entrance?
+- **Element lifecycles**: first/last animation time, final visibility
+- **Scene snapshots**: visible element state at 5 key timestamps
+- **Flags**: `offscreen`, `collision`, `invisible`, `paced-fast` (under 0.2s), `paced-slow` (over 2s)
+
+Read the JSON. Scan summaries for anything unexpected. Check every flag — fix or justify. Verify the timeline shows the intended choreography rhythm. Re-run after fixes.
+
+Skip on small edits (fixing a color, adjusting one duration). Run on new compositions and significant animation changes.

 ---