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-03 12:54:29 +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) {