diff --git a/.fallowrc.jsonc b/.fallowrc.jsonc
index 480ef20940..df303ad2d1 100644
--- a/.fallowrc.jsonc
+++ b/.fallowrc.jsonc
@@ -26,8 +26,9 @@
     // page.addScriptTag (see layout.ts / validate.ts) — referenced by file
     // path, never imported, so they have no import-graph referrer.
     "packages/cli/src/commands/layout-audit.browser.js",
-    "packages/cli/src/commands/contrast-audit.browser.js",
     "packages/cli/src/commands/motion-sample.browser.js",
+    // @hyperframes/validate contrast audit injects it via page.addScriptTag (raw string, no import referrer).
+    "packages/validate/src/contrast-audit.browser.js",
     // Worker entry points loaded dynamically by their *Pool.ts companions.
     "packages/producer/src/services/pngDecodeBlitWorker.ts",
     "packages/producer/src/services/shaderTransitionWorker.ts",
@@ -305,6 +306,13 @@
       // new package makes fallow see it as a fresh finding; the underlying clone
       // predates this refactor.
       "packages/parsers/src/hfIds.ts",
+      // @hyperframes/validate vendors these from cli/src/utils/* so it needn't import @hyperframes/cli (which depends on it); a shared low-level package is a follow-up.
+      "packages/validate/src/staticProjectServer.ts",
+      "packages/validate/src/compositionViewport.ts",
+      "packages/validate/src/dom.ts",
+      "packages/validate/src/errorMessage.ts",
+      // browserValidate.ts: raceMediaReady vs auditClipDurations' in-page closure share the race wiring; intentional — the closure is Puppeteer-serialized into a separate realm (see raceMediaReady doc).
+      "packages/validate/src/browserValidate.ts",
       // Parser test files: parallel arrange/act/assert test cases — pre-existing
       // duplication moved from packages/core/src/parsers/.
       "packages/parsers/src/gsapParser.test.ts",
@@ -573,6 +581,8 @@
       "packages/studio/src/player/components/TimelineCanvas.tsx",
       "packages/studio/src/player/components/TimelineClip.tsx",
       "packages/studio/src/player/components/TimelineClipDiamonds.tsx",
+      // WCAG contrast sampler ported wholesale into @hyperframes/validate; high cyclomatic is inherent to the pixel scan (no new logic).
+      "packages/validate/src/contrast-audit.browser.js",
     ],
   },
 }
diff --git a/bun.lock b/bun.lock
index cac1f849d6..c95cdb9c9d 100644
--- a/bun.lock
+++ b/bun.lock
@@ -22,7 +22,7 @@
     },
     "packages/aws-lambda": {
       "name": "@hyperframes/aws-lambda",
-      "version": "0.7.22",
+      "version": "0.7.38",
       "dependencies": {
         "@aws-sdk/client-s3": "^3.700.0",
         "@aws-sdk/client-sfn": "^3.700.0",
@@ -54,7 +54,7 @@
     },
     "packages/cli": {
       "name": "@hyperframes/cli",
-      "version": "0.7.22",
+      "version": "0.7.38",
       "bin": {
         "hyperframes": "./dist/cli.js",
       },
@@ -86,6 +86,7 @@
         "@hyperframes/producer": "workspace:*",
         "@hyperframes/studio": "workspace:*",
         "@hyperframes/studio-server": "workspace:*",
+        "@hyperframes/validate": "workspace:*",
         "@types/adm-zip": "^0.5.7",
         "@types/fontkit": "^2.0.9",
         "@types/mime-types": "^3.0.1",
@@ -103,7 +104,7 @@
     },
     "packages/core": {
       "name": "@hyperframes/core",
-      "version": "0.7.22",
+      "version": "0.7.38",
       "dependencies": {
         "@chenglou/pretext": "^0.0.5",
         "@hyperframes/lint": "workspace:*",
@@ -128,7 +129,7 @@
     },
     "packages/engine": {
       "name": "@hyperframes/engine",
-      "version": "0.7.22",
+      "version": "0.7.38",
       "dependencies": {
         "@hono/node-server": "^1.13.0",
         "@hyperframes/core": "workspace:^",
@@ -146,7 +147,7 @@
     },
     "packages/gcp-cloud-run": {
       "name": "@hyperframes/gcp-cloud-run",
-      "version": "0.7.22",
+      "version": "0.7.38",
       "dependencies": {
         "@google-cloud/storage": "^7.14.0",
         "@google-cloud/workflows": "^4.2.0",
@@ -166,7 +167,7 @@
     },
     "packages/lint": {
       "name": "@hyperframes/lint",
-      "version": "0.7.22",
+      "version": "0.7.38",
       "dependencies": {
         "@hyperframes/parsers": "workspace:*",
         "linkedom": "^0.18.12",
@@ -182,7 +183,7 @@
     },
     "packages/parsers": {
       "name": "@hyperframes/parsers",
-      "version": "0.7.22",
+      "version": "0.7.38",
       "dependencies": {
         "@babel/parser": "^7.27.0",
         "acorn": "^8.17.0",
@@ -202,7 +203,7 @@
     },
     "packages/player": {
       "name": "@hyperframes/player",
-      "version": "0.7.22",
+      "version": "0.7.38",
       "dependencies": {
         "@hyperframes/core": "workspace:*",
       },
@@ -217,7 +218,7 @@
     },
     "packages/producer": {
       "name": "@hyperframes/producer",
-      "version": "0.7.22",
+      "version": "0.7.38",
       "dependencies": {
         "@fontsource/archivo-black": "^5.2.8",
         "@fontsource/eb-garamond": "^5.2.7",
@@ -261,7 +262,7 @@
     },
     "packages/sdk": {
       "name": "@hyperframes/sdk",
-      "version": "0.7.22",
+      "version": "0.7.38",
       "dependencies": {
         "@hyperframes/core": "workspace:*",
         "@hyperframes/parsers": "workspace:*",
@@ -288,7 +289,7 @@
     },
     "packages/shader-transitions": {
       "name": "@hyperframes/shader-transitions",
-      "version": "0.7.22",
+      "version": "0.7.38",
       "dependencies": {
         "html2canvas": "^1.4.1",
       },
@@ -300,7 +301,7 @@
     },
     "packages/studio": {
       "name": "@hyperframes/studio",
-      "version": "0.7.22",
+      "version": "0.7.38",
       "dependencies": {
         "@codemirror/autocomplete": "^6.20.1",
         "@codemirror/commands": "^6.10.3",
@@ -348,7 +349,7 @@
     },
     "packages/studio-server": {
       "name": "@hyperframes/studio-server",
-      "version": "0.7.22",
+      "version": "0.7.38",
       "dependencies": {
         "@hyperframes/core": "workspace:*",
         "@hyperframes/parsers": "workspace:*",
@@ -365,6 +366,25 @@
         "vitest": "^3.2.4",
       },
     },
+    "packages/validate": {
+      "name": "@hyperframes/validate",
+      "version": "0.7.38",
+      "dependencies": {
+        "@hyperframes/core": "workspace:*",
+        "@hyperframes/engine": "workspace:*",
+        "@hyperframes/producer": "workspace:*",
+        "linkedom": "^0.18.12",
+        "puppeteer-core": "24.40.0",
+      },
+      "devDependencies": {
+        "@types/node": "^25.0.10",
+        "happy-dom": "^20.9.0",
+        "tsup": "^8.0.0",
+        "tsx": "^4.21.0",
+        "typescript": "^5.0.0",
+        "vitest": "^3.2.4",
+      },
+    },
   },
   "overrides": {
     "@types/react": "^19.0.0",
@@ -741,6 +761,8 @@
 
     "@hyperframes/studio-server": ["@hyperframes/studio-server@workspace:packages/studio-server"],
 
+    "@hyperframes/validate": ["@hyperframes/validate@workspace:packages/validate"],
+
     "@img/colour": ["@img/colour@1.1.0", "", {}, "sha512-Td76q7j57o/tLVdgS746cYARfSyxk8iEfRxewL9h4OMzYhbW4TAcppl0mT4eyqXddh6L/jwoM75mo7ixa/pCeQ=="],
 
     "@img/sharp-darwin-arm64": ["@img/sharp-darwin-arm64@0.34.5", "", { "optionalDependencies": { "@img/sharp-libvips-darwin-arm64": "1.2.4" }, "os": "darwin", "cpu": "arm64" }, "sha512-imtQ3WMJXbMY4fxb/Ndp6HBTNVtWCUI0WdobyheGf5+ad6xX8VIDO8u2xE4qc/fr08CKG/7dDseFtn6M6g/r3w=="],
@@ -2177,6 +2199,8 @@
 
     "@google-cloud/storage/google-auth-library": ["google-auth-library@9.15.1", "", { "dependencies": { "base64-js": "^1.3.0", "ecdsa-sig-formatter": "^1.0.11", "gaxios": "^6.1.1", "gcp-metadata": "^6.1.0", "gtoken": "^7.0.0", "jws": "^4.0.0" } }, "sha512-Jb6Z0+nvECVz+2lzSMt9u98UsoakXxA2HGHMCxh+so3n90XgYWkq5dur19JAJV7ONiJY22yBTyJB1TSkvPq9Ng=="],
 
+    "@hyperframes/validate/puppeteer-core": ["puppeteer-core@24.40.0", "", { "dependencies": { "@puppeteer/browsers": "2.13.0", "chromium-bidi": "14.0.0", "debug": "^4.4.3", "devtools-protocol": "0.0.1581282", "typed-query-selector": "^2.12.1", "webdriver-bidi-protocol": "0.4.1", "ws": "^8.19.0" } }, "sha512-MWL3XbUCfVgGR0gRsidzT6oKJT2QydPLhMITU6HoVWiiv4gkb6gJi3pcdAa8q4HwjBTbqISOWVP4aJiiyUJvag=="],
+
     "@isaacs/cliui/string-width": ["string-width@5.1.2", "", { "dependencies": { "eastasianwidth": "^0.2.0", "emoji-regex": "^9.2.2", "strip-ansi": "^7.0.1" } }, "sha512-HnLOCR3vjcY8beoNLtcjZ5/nxn2afmME6lhrDrebokqMap+XbeW8n9TXpPDOqdGK5qcI3oT0GKTW6wC7EMiVqA=="],
 
     "@isaacs/cliui/strip-ansi": ["strip-ansi@7.2.0", "", { "dependencies": { "ansi-regex": "^6.2.2" } }, "sha512-yDPMNjp4WyfYBkHnjIRLfca1i6KMyGCtsVgoKe/z1+6vukgaENdgGBZt+ZmKPc4gavvEZ5OgHfHdrazhgNyG7w=="],
@@ -2295,6 +2319,10 @@
 
     "@google-cloud/storage/google-auth-library/gcp-metadata": ["gcp-metadata@6.1.1", "", { "dependencies": { "gaxios": "^6.1.1", "google-logging-utils": "^0.0.2", "json-bigint": "^1.0.0" } }, "sha512-a4tiq7E0/5fTjxPAaH4jpjkSv/uCaU2p5KC6HVGrvl0cDjA8iBZv4vv1gyzlmK0ZUKqwpOyQMKzZQe3lTit77A=="],
 
+    "@hyperframes/validate/puppeteer-core/@puppeteer/browsers": ["@puppeteer/browsers@2.13.0", "", { "dependencies": { "debug": "^4.4.3", "extract-zip": "^2.0.1", "progress": "^2.0.3", "proxy-agent": "^6.5.0", "semver": "^7.7.4", "tar-fs": "^3.1.1", "yargs": "^17.7.2" }, "bin": { "browsers": "lib/cjs/main-cli.js" } }, "sha512-46BZJYJjc/WwmKjsvDFykHtXrtomsCIrwYQPOP7VfMJoZY2bsDF9oROBABR3paDjDcmkUye1Pb1BqdcdiipaWA=="],
+
+    "@hyperframes/validate/puppeteer-core/devtools-protocol": ["devtools-protocol@0.0.1581282", "", {}, "sha512-nv7iKtNZQshSW2hKzYNr46nM/Cfh5SEvE2oV0/SEGgc9XupIY5ggf84Cz8eJIkBce7S3bmTAauFD6aysMpnqsQ=="],
+
     "@isaacs/cliui/string-width/emoji-regex": ["emoji-regex@9.2.2", "", {}, "sha512-L18DaJsXSUk2+42pv8mLs5jJT2hqFkFE4j21wOmgbUqsZ2hL72NsUU785g9RXgo3s0ZNgVl42TiHp3ZtOv/Vyg=="],
 
     "@isaacs/cliui/strip-ansi/ansi-regex": ["ansi-regex@6.2.2", "", {}, "sha512-Bq3SmSpyFHaWjPk8If9yc6svM8c56dB5BAtW4Qbw5jHTwwXXcTLoRMkpDJp6VL0XzlWaCHTXrkFURMYmD0sLqg=="],
diff --git a/package.json b/package.json
index 33b4b16ce2..b998490327 100644
--- a/package.json
+++ b/package.json
@@ -11,7 +11,7 @@
   "type": "module",
   "scripts": {
     "dev": "bun run studio",
-    "build": "bun run --filter '@hyperframes/{parsers,lint,studio-server}' build && bun run --filter @hyperframes/core build && bun run --filter '@hyperframes/{core,engine,producer,player,studio,shader-transitions,aws-lambda,gcp-cloud-run,sdk}' build && bun run --filter @hyperframes/cli build",
+    "build": "bun run --filter '@hyperframes/{parsers,lint,studio-server}' build && bun run --filter @hyperframes/core build && bun run --filter '@hyperframes/{core,engine,producer,player,studio,shader-transitions,aws-lambda,gcp-cloud-run,sdk}' build && bun run --filter @hyperframes/validate build && bun run --filter @hyperframes/cli build",
     "build:producer": "bun run --filter @hyperframes/producer build",
     "studio": "bun run --filter @hyperframes/studio dev",
     "build:hyperframes-runtime": "bun run --filter @hyperframes/core build:hyperframes-runtime",
diff --git a/packages/cli/package.json b/packages/cli/package.json
index d907879201..7b2dc37457 100644
--- a/packages/cli/package.json
+++ b/packages/cli/package.json
@@ -54,6 +54,7 @@
     "@hyperframes/producer": "workspace:*",
     "@hyperframes/studio": "workspace:*",
     "@hyperframes/studio-server": "workspace:*",
+    "@hyperframes/validate": "workspace:*",
     "@types/adm-zip": "^0.5.7",
     "@types/fontkit": "^2.0.9",
     "@types/mime-types": "^3.0.1",
diff --git a/packages/cli/scripts/build-copy.mjs b/packages/cli/scripts/build-copy.mjs
index 55f198e91a..11d5f7355e 100644
--- a/packages/cli/scripts/build-copy.mjs
+++ b/packages/cli/scripts/build-copy.mjs
@@ -99,7 +99,8 @@ async function main() {
     cpSync(layoutAuditScript, join(DIST, "commands", "layout-audit.browser.js"));
   }
 
-  const contrastAuditScript = join(CLI_ROOT, "src", "commands", "contrast-audit.browser.js");
+  // Owned by @hyperframes/validate; bundled CLI loads it from dist/commands via page.addScriptTag.
+  const contrastAuditScript = join(CLI_ROOT, "..", "validate", "src", "contrast-audit.browser.js");
   if (existsSync(contrastAuditScript)) {
     cpSync(contrastAuditScript, join(DIST, "commands", "contrast-audit.browser.js"));
   }
diff --git a/packages/cli/src/commands/layout-audit.browser.test.ts b/packages/cli/src/commands/layout-audit.browser.test.ts
index e084637f29..bea24800ab 100644
--- a/packages/cli/src/commands/layout-audit.browser.test.ts
+++ b/packages/cli/src/commands/layout-audit.browser.test.ts
@@ -6,7 +6,6 @@ import { fileURLToPath } from "node:url";
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const script = readFileSync(join(__dirname, "layout-audit.browser.js"), "utf-8");
-const contrastScript = readFileSync(join(__dirname, "contrast-audit.browser.js"), "utf-8");
 
 interface RectInput {
   left: number;
@@ -196,47 +195,6 @@ describe("layout-audit.browser content overlap", () => {
   });
 });
 
-describe("contrast-audit.browser clip-path visibility", () => {
-  afterEach(() => {
-    vi.restoreAllMocks();
-    vi.unstubAllGlobals();
-    document.body.innerHTML = "";
-    delete (document as unknown as { elementFromPoint?: unknown }).elementFromPoint;
-    delete (window as unknown as { __contrastAudit?: unknown }).__contrastAudit;
-  });
-
-  it("excludes text clipped to nothing by clip-path from contrast reports", async () => {
-    document.body.innerHTML = `
-      <div id="root" data-composition-id="main" data-width="640" data-height="360">
-        <div id="headline">Hidden text</div>
-      </div>
-    `;
-
-    vi.spyOn(window, "getComputedStyle").mockImplementation((element) => {
-      const id = (element as Element).id;
-      return {
-        display: "block",
-        visibility: "visible",
-        opacity: "1",
-        color: "rgb(0, 0, 0)",
-        fontSize: "32px",
-        fontWeight: "400",
-        clipPath: id === "headline" ? "inset(0px 100% 0px 0px)" : "none",
-      } as unknown as CSSStyleDeclaration;
-    });
-
-    vi.spyOn(document.getElementById("headline")!, "getBoundingClientRect").mockReturnValue(
-      rect({ left: 100, top: 100, width: 400, height: 80 }),
-    );
-    (document as unknown as { elementFromPoint: () => Element | null }).elementFromPoint = () =>
-      null;
-
-    installContrastScript();
-
-    expect(await runContrastAudit()).toEqual([]);
-  });
-});
-
 // Both blocks overlap heavily; only the exemption on block A should suppress
 // the finding, so a missing exemption would surface as a failure here.
 function expectExemptFromOverlap(aOverrides: { color?: string; attrs?: string }): void {
@@ -446,39 +404,6 @@ function installAuditScript(): void {
   window.eval(script);
 }
 
-function installContrastScript(): void {
-  class MockImage {
-    onload: (() => void) | null = null;
-    onerror: (() => void) | null = null;
-    naturalWidth = 640;
-    naturalHeight = 360;
-
-    set src(_value: string) {
-      this.onload?.();
-    }
-  }
-
-  vi.stubGlobal("Image", MockImage);
-  const getContextSpy = vi.spyOn(HTMLCanvasElement.prototype, "getContext") as unknown as {
-    mockReturnValue(value: CanvasRenderingContext2D): void;
-  };
-  getContextSpy.mockReturnValue({
-    drawImage() {},
-    getImageData() {
-      return { data: new Uint8ClampedArray(640 * 360 * 4).fill(255) };
-    },
-  } as unknown as CanvasRenderingContext2D);
-  window.eval(contrastScript);
-}
-
-async function runContrastAudit(): Promise<Array<Record<string, unknown>>> {
-  return (
-    window as unknown as {
-      __contrastAudit: (imgBase64: string, time: number) => Promise<Array<Record<string, unknown>>>;
-    }
-  ).__contrastAudit("stub", 0);
-}
-
 function runAudit(): Array<{
   code: string;
   selector: string;
diff --git a/packages/cli/src/commands/validate.test.ts b/packages/cli/src/commands/validate.test.ts
index 7353806c41..022b208a70 100644
--- a/packages/cli/src/commands/validate.test.ts
+++ b/packages/cli/src/commands/validate.test.ts
@@ -1,138 +1,7 @@
-import { describe, expect, it, vi } from "vitest";
-import {
-  extractCompositionErrorsFromLint,
-  navigationTimeoutHint,
-  raceMediaReady,
-  resolveNavigationTimeoutMs,
-  shouldIgnoreRequestFailure,
-  waitForPreferredSeekTarget,
-} from "./validate.js";
+import { describe, expect, it } from "vitest";
+import { extractCompositionErrorsFromLint } from "./validate.js";
 import type { ProjectLintResult } from "../utils/lintProject.js";
 
-// validateInBrowser lazy-loads the producer localize helpers via loadProducer;
-// mock it so these unit tests never resolve @hyperframes/producer's built dist.
-vi.mock("../utils/producer.js", () => ({
-  loadProducer: vi.fn(async () => ({
-    localizeRemoteMediaSources: vi.fn(async (html: string) => ({
-      html,
-      remoteMediaAssets: new Map(),
-    })),
-    localizeRemoteImageSources: vi.fn(async (html: string) => ({
-      html,
-      remoteMediaAssets: new Map(),
-    })),
-    localizeRemoteFontFaces: vi.fn(async (html: string) => ({
-      html,
-      remoteMediaAssets: new Map(),
-    })),
-  })),
-}));
-
-// Regression for the validate audio-duration-probe timeout: a slow-loading
-// media element's duration was snapshotted once, at a fixed point in time,
-// and any element still mid-load was permanently misreported as unreadable.
-// raceMediaReady is the extracted wiring auditClipDurations now uses to wait
-// for `loadedmetadata` up to a deadline instead. Node's built-in EventTarget
-// satisfies the same duck-typed shape as a real HTMLMediaElement here, so
-// this is a real test of the race/cleanup logic, not a browser mock.
-describe("raceMediaReady", () => {
-  class FakeMediaElement extends EventTarget {
-    duration = NaN;
-  }
-
-  it("resolves immediately when duration is already available", async () => {
-    const el = new FakeMediaElement();
-    el.duration = 12.5;
-    const start = Date.now();
-    await raceMediaReady(el, Date.now() + 5000);
-    expect(Date.now() - start).toBeLessThan(50);
-  });
-
-  it("resolves as soon as loadedmetadata fires, before the deadline", async () => {
-    const el = new FakeMediaElement();
-    const promise = raceMediaReady(el, Date.now() + 5000);
-    setTimeout(() => {
-      el.duration = 8;
-      el.dispatchEvent(new Event("loadedmetadata"));
-    }, 20);
-    const start = Date.now();
-    await promise;
-    expect(Date.now() - start).toBeLessThan(200);
-  });
-
-  it("resolves on error without hanging until the deadline", async () => {
-    const el = new FakeMediaElement();
-    const promise = raceMediaReady(el, Date.now() + 5000);
-    setTimeout(() => el.dispatchEvent(new Event("error")), 20);
-    const start = Date.now();
-    await promise;
-    expect(Date.now() - start).toBeLessThan(200);
-  });
-
-  it("falls back to the deadline when no event ever fires", async () => {
-    const el = new FakeMediaElement();
-    const start = Date.now();
-    await raceMediaReady(el, Date.now() + 50);
-    expect(Date.now() - start).toBeGreaterThanOrEqual(40);
-  });
-});
-
-describe("shouldIgnoreRequestFailure", () => {
-  it("ignores aborted media preload requests", () => {
-    expect(
-      shouldIgnoreRequestFailure("http://127.0.0.1:3000/assets/sfx.wav", "net::ERR_ABORTED"),
-    ).toBe(true);
-    expect(shouldIgnoreRequestFailure("http://127.0.0.1:3000/video.mp4", "net::ERR_ABORTED")).toBe(
-      true,
-    );
-    expect(
-      shouldIgnoreRequestFailure(
-        "https://www.heygenverse.com/s/50f13ccf-9002-4d80-b567-9d4c0eac30d8/raw",
-        "net::ERR_ABORTED",
-        "media",
-      ),
-    ).toBe(true);
-  });
-
-  it("keeps non-media and non-aborted failures reportable", () => {
-    expect(
-      shouldIgnoreRequestFailure("http://127.0.0.1:3000/assets/map.png", "net::ERR_ABORTED"),
-    ).toBe(false);
-    expect(
-      shouldIgnoreRequestFailure(
-        "https://www.heygenverse.com/s/50f13ccf-9002-4d80-b567-9d4c0eac30d8/raw",
-        "net::ERR_ABORTED",
-        "xhr",
-      ),
-    ).toBe(false);
-    expect(
-      shouldIgnoreRequestFailure("http://127.0.0.1:3000/assets/sfx.wav", "net::ERR_FAILED"),
-    ).toBe(false);
-  });
-});
-
-describe("waitForPreferredSeekTarget", () => {
-  it("waits for the runtime player/bridge target before falling back to raw timelines", async () => {
-    const page = {
-      waitForFunction: vi.fn(async () => undefined),
-    };
-
-    await waitForPreferredSeekTarget(page, 123);
-
-    expect(page.waitForFunction).toHaveBeenCalledWith(expect.any(Function), { timeout: 123 });
-  });
-
-  it("does not fail validation when only the legacy raw timeline fallback is available", async () => {
-    const page = {
-      waitForFunction: vi.fn(async () => {
-        throw new Error("waiting failed: timeout");
-      }),
-    };
-
-    await expect(waitForPreferredSeekTarget(page, 1)).resolves.toBeUndefined();
-  });
-});
-
 describe("extractCompositionErrorsFromLint", () => {
   // `bundleToSingleHtml` (the inliner validate.ts bundles through) is
   // intentionally tolerant of missing/empty/unparsable data-composition-src
@@ -236,39 +105,3 @@ describe("extractCompositionErrorsFromLint", () => {
     expect(errors.map((e) => e.text)).toEqual(["scene-a is empty", "scene-b is empty"]);
   });
 });
-
-// Regression: `validate` used a hardcoded 10s page-navigation timeout that
-// ignored --timeout, so a composition loading GSAP from a CDN <script> (which
-// blocks domcontentloaded) failed with an opaque "Navigation timeout of 10000ms"
-// even though the full render's larger budget rode it out — with no knob to
-// extend it. resolveNavigationTimeoutMs makes --timeout raise the nav budget
-// (never below the 10s floor); navigationTimeoutHint replaces the opaque error.
-describe("resolveNavigationTimeoutMs", () => {
-  it("keeps the 10s floor when --timeout is unset or smaller", () => {
-    expect(resolveNavigationTimeoutMs(undefined)).toBe(10000);
-    expect(resolveNavigationTimeoutMs(3000)).toBe(10000); // the default --timeout
-    expect(resolveNavigationTimeoutMs(0)).toBe(10000);
-  });
-
-  it("raises the navigation budget to --timeout when it exceeds the floor", () => {
-    expect(resolveNavigationTimeoutMs(30000)).toBe(30000);
-  });
-});
-
-describe("navigationTimeoutHint", () => {
-  it("replaces a Puppeteer navigation-timeout error with an actionable CDN/--timeout hint", () => {
-    const hinted = navigationTimeoutHint(
-      new Error("Navigation timeout of 10000 ms exceeded"),
-      10000,
-    );
-    expect(hinted).toBeInstanceOf(Error);
-    expect(hinted?.message).toContain("10000ms");
-    expect(hinted?.message).toContain("CDN");
-    expect(hinted?.message).toContain("--timeout");
-  });
-
-  it("returns null for any non-navigation-timeout error so the caller rethrows it as-is", () => {
-    expect(navigationTimeoutHint(new Error("net::ERR_CONNECTION_REFUSED"), 10000)).toBeNull();
-    expect(navigationTimeoutHint("some string failure", 10000)).toBeNull();
-  });
-});
diff --git a/packages/cli/src/commands/validate.ts b/packages/cli/src/commands/validate.ts
index 07b5334ba7..4889b160fe 100644
--- a/packages/cli/src/commands/validate.ts
+++ b/packages/cli/src/commands/validate.ts
@@ -1,325 +1,15 @@
 import { defineCommand } from "citty";
-import { existsSync, mkdtempSync, readFileSync, rmSync } from "node:fs";
-import { tmpdir } from "node:os";
-import { join, dirname } from "node:path";
-import { fileURLToPath } from "node:url";
+import {
+  validateHtmlInBrowser,
+  type ConsoleEntry,
+  type ContrastEntry,
+} from "@hyperframes/validate";
 import { resolveProject, type ProjectDir } from "../utils/project.js";
 import { normalizeErrorMessage } from "../utils/errorMessage.js";
 import type { ProjectLintResult } from "../utils/lintProject.js";
-import { resolveCompositionViewportFromHtml } from "../utils/compositionViewport.js";
 import { c } from "../ui/colors.js";
 import { withMeta } from "../utils/updateCheck.js";
 
-const __filename = fileURLToPath(import.meta.url);
-const __dirname = dirname(__filename);
-
-interface ConsoleEntry {
-  level: "error" | "warning";
-  text: string;
-  url?: string;
-  line?: number;
-}
-
-interface ContrastEntry {
-  time: number;
-  selector: string;
-  text: string;
-  ratio: number;
-  wcagAA: boolean;
-  large: boolean;
-  fg: string;
-  bg: string;
-}
-
-const CONTRAST_SAMPLES = 5;
-const SEEK_SETTLE_MS = 150;
-const PREFERRED_SEEK_TARGET_WAIT_MS = 500;
-const MEDIA_EXTENSIONS = /\.(aac|flac|m4a|mov|mp3|mp4|oga|ogg|wav|webm)$/i;
-// Floor for the initial page navigation. A blocking external <script> (GSAP
-// from a CDN, etc.) delays `domcontentloaded`; the actual render (much larger
-// budget) rides it out, so validate's navigation must be at least as patient as
-// the user's --timeout, never stuck below this floor.
-const NAV_TIMEOUT_FLOOR_MS = 10000;
-
-// Navigation budget = the larger of the floor and the user's --timeout, so
-// `--timeout` (already the "wait longer for slow loads" knob for media/settle)
-// also extends navigation instead of being ignored by a hardcoded 10s.
-export function resolveNavigationTimeoutMs(optTimeout?: number): number {
-  return Math.max(NAV_TIMEOUT_FLOOR_MS, optTimeout ?? 0);
-}
-
-// Turn Puppeteer's opaque "Navigation timeout of Nms exceeded" into an
-// actionable message: the usual cause is a blocking CDN <script> that render
-// tolerates but validate's tighter budget does not. Returns a replacement Error
-// for a navigation timeout, or null for any other error (caller rethrows as-is).
-export function navigationTimeoutHint(err: unknown, navTimeoutMs: number): Error | null {
-  const msg = err instanceof Error ? err.message : String(err);
-  if (!/navigation timeout/i.test(msg)) return null;
-  return new Error(
-    `Page navigation timed out after ${navTimeoutMs}ms. A blocking external <script> ` +
-      `(e.g. GSAP loaded from a CDN) can delay page load past this budget even when the ` +
-      `full render succeeds. Vendor the script locally (recommended for deterministic ` +
-      `renders), or re-run with a longer --timeout.`,
-  );
-}
-
-export function shouldIgnoreRequestFailure(
-  url: string,
-  errorText: string | undefined,
-  resourceType?: string,
-): boolean {
-  if (errorText !== "net::ERR_ABORTED") return false;
-  if (resourceType === "media") return true;
-  try {
-    return MEDIA_EXTENSIONS.test(new URL(url).pathname);
-  } catch {
-    return false;
-  }
-}
-
-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 waitForPreferredSeekTarget(page);
-  await page.evaluate((t: number) => {
-    // window.__player.renderSeek is exposed directly by the composition
-    // runtime (packages/core/src/runtime/init.ts) on every page load, and
-    // — unlike raw timeline.seek() — it also runs the runtime's own
-    // [data-start]/[data-duration] visibility sync, hiding clips outside
-    // their timeline window. window.__hf.seek only exists when the
-    // producer's render-pipeline bridge script has been injected, which
-    // validate's static preview server never does, so it was always
-    // falling through to the raw __timelines seek below and skipping that
-    // sync — leaving off-window elements looking fully visible to any
-    // check (e.g. the contrast audit) that reads computed style afterward.
-    const player = (window as unknown as { __player?: { renderSeek?: (t: number) => void } })
-      .__player;
-    if (player && typeof player.renderSeek === "function") {
-      player.renderSeek(t);
-      return;
-    }
-    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));
-}
-
-interface WaitForFunctionPage {
-  waitForFunction: (pageFunction: () => boolean, options: { timeout: number }) => Promise<unknown>;
-}
-
-export async function waitForPreferredSeekTarget(
-  page: WaitForFunctionPage,
-  timeoutMs = PREFERRED_SEEK_TARGET_WAIT_MS,
-): Promise<void> {
-  try {
-    await page.waitForFunction(
-      () => {
-        const w = window as unknown as {
-          __hf?: { seek?: unknown };
-          __player?: { renderSeek?: unknown };
-        };
-        return typeof w.__player?.renderSeek === "function" || typeof w.__hf?.seek === "function";
-      },
-      { timeout: timeoutMs },
-    );
-  } catch {
-    // Older/static pages may only expose raw window.__timelines. Keep the
-    // legacy fallback path rather than turning a missing player API into a
-    // validate failure.
-  }
-}
-
-/**
- * Race a media element's `loadedmetadata`/`error` event against a deadline,
- * whichever comes first. Already-ready elements resolve immediately.
- *
- * This is the same wiring as the inline copy inside `auditClipDurations`'s
- * `page.evaluate()` below — duplicated, not imported, because Puppeteer
- * serializes that closure's source and re-runs it in an isolated browser
- * realm with no access to this module's scope. Kept here (duck-typed on
- * `EventTarget`-shaped objects, not `HTMLMediaElement`) so the actual
- * race/cleanup logic has a real, deterministic unit test — Node's built-in
- * `EventTarget` satisfies the same shape without a browser or DOM library.
- * If you change one copy, change both.
- */
-export function raceMediaReady(
-  el: EventTarget & { duration: number },
-  deadlineMs: number,
-): Promise<void> {
-  if (Number.isFinite(el.duration) && el.duration > 0) return Promise.resolve();
-  return new Promise<void>((resolve) => {
-    const onReady = () => {
-      el.removeEventListener("loadedmetadata", onReady);
-      el.removeEventListener("error", onReady);
-      clearTimeout(timer);
-      resolve();
-    };
-    el.addEventListener("loadedmetadata", onReady, { once: true });
-    el.addEventListener("error", onReady, { once: true });
-    const timer = setTimeout(onReady, Math.max(0, deadlineMs - Date.now()));
-  });
-}
-
-/**
- * Flag `<video>`/`<audio>` clips whose source is meaningfully shorter than their
- * `data-duration` slot (the slot gets silently shortened in renders). Runs in
- * the live page to read each element's intrinsic `.duration`, which static lint
- * can't see.
- */
-async function auditClipDurations(
-  page: import("puppeteer-core").Page,
-  analyzeClipMediaFit: typeof import("@hyperframes/engine").analyzeClipMediaFit,
-  extraWaitMs: number,
-): Promise<ConsoleEntry[]> {
-  // fallow-ignore-next-line complexity
-  const clips = await page.evaluate(async (maxWaitMs: number) => {
-    const nodes = Array.from(
-      document.querySelectorAll("video[data-duration], audio[data-duration]"),
-    ) as HTMLMediaElement[];
-
-    // The caller's page-settle sleep is a flat, unconditional wait shared with
-    // other audits — it isn't aware of how long any given media element takes
-    // to load metadata. A slow-loading audio file (large narration WAV, remote
-    // source) can still be mid-fetch when that sleep elapses, which read as
-    // el.duration === NaN and was misreported as "could not read the duration"
-    // even though the render pipeline (which properly awaits media readiness)
-    // handles the same file fine. Give still-loading elements one more real
-    // chance via loadedmetadata before giving up, instead of a single fixed-time
-    // snapshot. Elements that already have a duration resolve immediately, so
-    // this adds no latency in the common case.
-    const deadline = Date.now() + maxWaitMs;
-    await Promise.all(
-      nodes.map((el) => {
-        if (Number.isFinite(el.duration) && el.duration > 0) return Promise.resolve();
-        return new Promise<void>((resolve) => {
-          // fallow-ignore-next-line code-duplication
-          const cleanup = () => {
-            el.removeEventListener("loadedmetadata", onReady);
-            el.removeEventListener("error", onReady);
-            clearTimeout(timer);
-          };
-          const onReady = () => {
-            cleanup();
-            resolve();
-          };
-          el.addEventListener("loadedmetadata", onReady, { once: true });
-          el.addEventListener("error", onReady, { once: true });
-          const timer = setTimeout(onReady, Math.max(0, deadline - Date.now()));
-        });
-      }),
-    );
-
-    const rows: Array<{
-      id: string;
-      kind: string;
-      slot: number;
-      mediaStart: number;
-      duration: number;
-      loop: boolean;
-    }> = [];
-    for (const el of nodes) {
-      const slot = parseFloat(el.getAttribute("data-duration") ?? "");
-      if (!(slot > 0)) continue;
-      rows.push({
-        id: el.id || el.getAttribute("src") || `(${el.tagName.toLowerCase()})`,
-        kind: el.tagName === "AUDIO" ? "Audio" : "Video",
-        slot,
-        mediaStart: parseFloat(el.getAttribute("data-media-start") ?? "0") || 0,
-        duration: el.duration,
-        loop: el.loop || el.getAttribute("data-loop") === "true",
-      });
-    }
-    return rows;
-  }, extraWaitMs);
-
-  const warnings: ConsoleEntry[] = [];
-  const unreadable: string[] = [];
-  for (const clip of clips) {
-    if (!Number.isFinite(clip.duration) || clip.duration <= 0) {
-      // Metadata never loaded (e.g. slow remote source) — record so the gap in
-      // coverage isn't silent, rather than dropping it.
-      unreadable.push(clip.id);
-      continue;
-    }
-    const mediaSeconds = Math.max(0, clip.duration - clip.mediaStart);
-    const fit = analyzeClipMediaFit({ slotSeconds: clip.slot, mediaSeconds, loop: clip.loop });
-    if (!fit) continue;
-    warnings.push({
-      level: "warning",
-      text:
-        `${clip.kind} "${clip.id}" is ${mediaSeconds.toFixed(2)}s but its slot (data-duration) ` +
-        `is ${clip.slot.toFixed(2)}s — the slot is shortened to the media length when rendered. ` +
-        `Set data-duration to ~${mediaSeconds.toFixed(2)}s if that isn't intended.`,
-    });
-  }
-  if (unreadable.length > 0) {
-    warnings.push({
-      level: "warning",
-      text:
-        `Could not read the duration of ${unreadable.length} media element(s) within the ` +
-        `validate timeout (${unreadable.join(", ")}); their slot vs. source fit was not checked. ` +
-        `Re-run with a longer --timeout if the source is slow to load.`,
-    });
-  }
-  return warnings;
-}
-
-async function runContrastAudit(page: import("puppeteer-core").Page): Promise<ContrastEntry[]> {
-  const duration = await getCompositionDuration(page);
-  if (duration <= 0) return [];
-
-  await page.addScriptTag({ content: loadContrastAuditScript() });
-
-  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;
-}
-
-function loadContrastAuditScript(): string {
-  const candidates = [
-    join(__dirname, "contrast-audit.browser.js"),
-    join(__dirname, "commands", "contrast-audit.browser.js"),
-  ];
-
-  for (const candidate of candidates) {
-    if (existsSync(candidate)) return readFileSync(candidate, "utf-8");
-  }
-
-  throw new Error("Missing contrast audit browser script");
-}
-
 /**
  * Pull the `missing_or_empty_sub_composition` lint findings out of a
  * `lintProject` result and shape them as `ConsoleEntry`s. Extracted as a
@@ -335,46 +25,14 @@ export function extractCompositionErrorsFromLint(
     .map((f) => ({ level: "error" as const, text: f.message }));
 }
 
-// Match the render pipeline: localize remote <img>/<video>/<audio>/@font-face
-// into a temp dir (served as an extra asset root) so validate resolves them
-// same-origin and doesn't false-fail on cross-origin (crossorigin/CORS) fetches
-// the real render never makes. Best-effort: no-op on any failure.
-async function localizeRemoteAssets(
-  html: string,
-): Promise<{ html: string; assetRoots: string[]; cleanup: () => void }> {
-  let dir: string | undefined;
-  try {
-    const { loadProducer } = await import("../utils/producer.js");
-    const { localizeRemoteMediaSources, localizeRemoteImageSources, localizeRemoteFontFaces } =
-      await loadProducer();
-    dir = mkdtempSync(join(tmpdir(), "hf-validate-assets-"));
-    const assetDir = dir;
-    const media = await localizeRemoteMediaSources(html, assetDir);
-    const images = await localizeRemoteImageSources(media.html, assetDir);
-    const fonts = await localizeRemoteFontFaces(images.html, assetDir);
-    const count =
-      media.remoteMediaAssets.size + images.remoteMediaAssets.size + fonts.remoteMediaAssets.size;
-    return {
-      html: fonts.html,
-      assetRoots: count > 0 ? [assetDir] : [],
-      cleanup: () => rmSync(assetDir, { recursive: true, force: true }),
-    };
-  } catch {
-    // Best-effort: drop any partial temp dir before falling back to remote URLs.
-    if (dir) rmSync(dir, { recursive: true, force: true });
-    return { html, assetRoots: [], cleanup: () => {} };
-  }
-}
-
 async function validateInBrowser(
   project: ProjectDir,
   opts: { timeout?: number; contrast?: boolean },
 ): Promise<{ errors: ConsoleEntry[]; warnings: ConsoleEntry[]; contrast?: ContrastEntry[] }> {
   const projectDir = project.dir;
   const { bundleToSingleHtml } = await import("@hyperframes/core/compiler");
-  const { ensureBrowser } = await import("../browser/manager.js");
-  const { serveStaticProjectHtml } = await import("../utils/staticProjectServer.js");
   const { lintProject } = await import("../utils/lintProject.js");
+  const { ensureBrowser } = await import("../browser/manager.js");
 
   // Fail fast on missing/empty/unparsable data-composition-src references
   // before spending time bundling and launching a browser. The bundler
@@ -390,107 +48,14 @@ async function validateInBrowser(
   // previous post-bundle regex substitution (which matched `src="..."` on the
   // runtime tag) is no longer needed — there's no `src` attribute to match.
   const html = await bundleToSingleHtml(projectDir);
-
-  const localized = await localizeRemoteAssets(html);
-  const server = await serveStaticProjectHtml(
+  const browser = await ensureBrowser();
+  return validateHtmlInBrowser(html, {
+    browserExecutablePath: browser.executablePath,
     projectDir,
-    localized.html,
-    undefined,
-    localized.assetRoots,
-  ).catch((err) => {
-    // Server never started — the finally below won't run, so clean up here.
-    localized.cleanup();
-    throw err;
+    timeout: opts.timeout,
+    contrast: opts.contrast,
+    prependErrors: compositionErrors,
   });
-
-  const errors: ConsoleEntry[] = [...compositionErrors];
-  const warnings: ConsoleEntry[] = [];
-  let contrast: ContrastEntry[] | undefined;
-  const viewport = resolveCompositionViewportFromHtml(html);
-
-  try {
-    const browser = await ensureBrowser();
-    const puppeteer = await import("puppeteer-core");
-    const { buildChromeArgs, analyzeClipMediaFit } = await import("@hyperframes/engine");
-    const browserGpuMode =
-      process.env.PRODUCER_BROWSER_GPU_MODE === "software" ? "software" : "hardware";
-    const chromeBrowser = await puppeteer.default.launch({
-      headless: true,
-      executablePath: browser.executablePath,
-      args: buildChromeArgs({ ...viewport, captureMode: "screenshot" }, { browserGpuMode }),
-    });
-
-    const page = await chromeBrowser.newPage();
-    await page.setViewport(viewport);
-
-    page.on("console", (msg) => {
-      const type = msg.type();
-      const loc = msg.location();
-      const text = msg.text();
-      if (type === "error") {
-        if (text.startsWith("Failed to load resource")) return;
-        errors.push({ level: "error", text, url: loc.url, line: loc.lineNumber });
-      } else if (type === "warn") {
-        warnings.push({ level: "warning", text, url: loc.url, line: loc.lineNumber });
-      }
-    });
-
-    page.on("pageerror", (err) => {
-      const text = normalizeErrorMessage(err);
-      // CDN scripts (e.g. GSAP from jsdelivr) returning HTML error pages
-      // instead of JS produce "Unexpected token '<'" SyntaxErrors. These
-      // are network failures, not composition authoring errors.
-      if (text.includes("Unexpected token '<'") || text.includes("Unexpected token '&lt;'")) return;
-      errors.push({ level: "error", text });
-    });
-
-    page.on("requestfailed", (req) => {
-      const url = req.url();
-      if (url.includes("favicon") || url.startsWith("data:")) return;
-      const failureText = req.failure()?.errorText;
-      if (shouldIgnoreRequestFailure(url, failureText, req.resourceType())) return;
-      const path = decodeURIComponent(new URL(url).pathname).replace(/^\//, "");
-      errors.push({
-        level: "error",
-        text: `Failed to load ${path}: ${failureText ?? "net::ERR_FAILED"}`,
-        url,
-      });
-    });
-
-    page.on("response", (res) => {
-      if (res.status() >= 400) {
-        const url = res.url();
-        if (url.includes("favicon")) return;
-        const path = decodeURIComponent(new URL(url).pathname).replace(/^\//, "");
-        errors.push({ level: "error", text: `${res.status()} loading ${path}`, url });
-      }
-    });
-
-    const navTimeoutMs = resolveNavigationTimeoutMs(opts.timeout);
-    try {
-      await page.goto(server.url, { waitUntil: "domcontentloaded", timeout: navTimeoutMs });
-    } catch (err) {
-      const hinted = navigationTimeoutHint(err, navTimeoutMs);
-      if (hinted) throw hinted;
-      throw err;
-    }
-    await new Promise((r) => setTimeout(r, opts.timeout ?? 3000));
-
-    for (const w of await auditClipDurations(page, analyzeClipMediaFit, opts.timeout ?? 3000)) {
-      warnings.push(w);
-    }
-
-    if (opts.contrast) {
-      contrast = await runContrastAudit(page);
-    }
-
-    await chromeBrowser.close();
-  } finally {
-    await server.close();
-    localized.cleanup();
-  }
-
-  return { errors, warnings, contrast };
 }
 
 function printContrastFailures(failures: ContrastEntry[]) {
diff --git a/packages/cli/vitest.config.ts b/packages/cli/vitest.config.ts
index 1b212e5fc8..2f1e116c07 100644
--- a/packages/cli/vitest.config.ts
+++ b/packages/cli/vitest.config.ts
@@ -14,6 +14,13 @@ export default defineConfig({
         find: /^@hyperframes\/core$/,
         replacement: resolve(__dirname, "../core/src/index.ts"),
       },
+      // @hyperframes/validate's dist isn't built in the Test job (unlike core/lint), and
+      // validate.ts imports it at module load. Resolve to source; validate's src pulls
+      // engine/producer only via dynamic import, so nothing unbuilt loads eagerly.
+      {
+        find: /^@hyperframes\/validate$/,
+        replacement: resolve(__dirname, "../validate/src/index.ts"),
+      },
     ],
   },
   test: {
diff --git a/packages/validate/package.json b/packages/validate/package.json
new file mode 100644
index 0000000000..7d05050657
--- /dev/null
+++ b/packages/validate/package.json
@@ -0,0 +1,58 @@
+{
+  "name": "@hyperframes/validate",
+  "version": "0.7.38",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/heygen-com/hyperframes",
+    "directory": "packages/validate"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "type": "module",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": {
+      "bun": "./src/index.ts",
+      "node": "./dist/index.js",
+      "import": "./src/index.ts",
+      "types": "./src/index.ts"
+    },
+    "./package.json": "./package.json"
+  },
+  "publishConfig": {
+    "access": "public",
+    "exports": {
+      ".": {
+        "import": "./dist/index.js",
+        "types": "./dist/index.d.ts"
+      },
+      "./package.json": "./package.json"
+    },
+    "main": "./dist/index.js",
+    "types": "./dist/index.d.ts"
+  },
+  "scripts": {
+    "build": "tsup && cp src/contrast-audit.browser.js dist/",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "echo skip"
+  },
+  "dependencies": {
+    "@hyperframes/core": "workspace:*",
+    "@hyperframes/engine": "workspace:*",
+    "@hyperframes/producer": "workspace:*",
+    "linkedom": "^0.18.12",
+    "puppeteer-core": "24.40.0"
+  },
+  "devDependencies": {
+    "@types/node": "^25.0.10",
+    "happy-dom": "^20.9.0",
+    "tsup": "^8.0.0",
+    "tsx": "^4.21.0",
+    "typescript": "^5.0.0",
+    "vitest": "^3.2.4"
+  }
+}
diff --git a/packages/validate/src/browserValidate.test.ts b/packages/validate/src/browserValidate.test.ts
new file mode 100644
index 0000000000..c1dc3b3eec
--- /dev/null
+++ b/packages/validate/src/browserValidate.test.ts
@@ -0,0 +1,149 @@
+import { describe, expect, it, vi } from "vitest";
+import {
+  navigationTimeoutHint,
+  raceMediaReady,
+  resolveNavigationTimeoutMs,
+  shouldIgnoreRequestFailure,
+  waitForPreferredSeekTarget,
+} from "./browserValidate.js";
+
+// Regression for the validate audio-duration-probe timeout: a slow-loading
+// media element's duration was snapshotted once, at a fixed point in time,
+// and any element still mid-load was permanently misreported as unreadable.
+// raceMediaReady is the extracted wiring auditClipDurations now uses to wait
+// for `loadedmetadata` up to a deadline instead. Node's built-in EventTarget
+// satisfies the same duck-typed shape as a real HTMLMediaElement here, so
+// this is a real test of the race/cleanup logic, not a browser mock.
+describe("raceMediaReady", () => {
+  class FakeMediaElement extends EventTarget {
+    duration = NaN;
+  }
+
+  it("resolves immediately when duration is already available", async () => {
+    const el = new FakeMediaElement();
+    el.duration = 12.5;
+    const start = Date.now();
+    await raceMediaReady(el, Date.now() + 5000);
+    expect(Date.now() - start).toBeLessThan(50);
+  });
+
+  it("resolves as soon as loadedmetadata fires, before the deadline", async () => {
+    const el = new FakeMediaElement();
+    const promise = raceMediaReady(el, Date.now() + 5000);
+    setTimeout(() => {
+      el.duration = 8;
+      el.dispatchEvent(new Event("loadedmetadata"));
+    }, 20);
+    const start = Date.now();
+    await promise;
+    expect(Date.now() - start).toBeLessThan(200);
+  });
+
+  it("resolves on error without hanging until the deadline", async () => {
+    const el = new FakeMediaElement();
+    const promise = raceMediaReady(el, Date.now() + 5000);
+    setTimeout(() => el.dispatchEvent(new Event("error")), 20);
+    const start = Date.now();
+    await promise;
+    expect(Date.now() - start).toBeLessThan(200);
+  });
+
+  it("falls back to the deadline when no event ever fires", async () => {
+    const el = new FakeMediaElement();
+    const start = Date.now();
+    await raceMediaReady(el, Date.now() + 50);
+    expect(Date.now() - start).toBeGreaterThanOrEqual(40);
+  });
+});
+
+describe("shouldIgnoreRequestFailure", () => {
+  it("ignores aborted media preload requests", () => {
+    expect(
+      shouldIgnoreRequestFailure("http://127.0.0.1:3000/assets/sfx.wav", "net::ERR_ABORTED"),
+    ).toBe(true);
+    expect(shouldIgnoreRequestFailure("http://127.0.0.1:3000/video.mp4", "net::ERR_ABORTED")).toBe(
+      true,
+    );
+    expect(
+      shouldIgnoreRequestFailure(
+        "https://www.heygenverse.com/s/50f13ccf-9002-4d80-b567-9d4c0eac30d8/raw",
+        "net::ERR_ABORTED",
+        "media",
+      ),
+    ).toBe(true);
+  });
+
+  it("keeps non-media and non-aborted failures reportable", () => {
+    expect(
+      shouldIgnoreRequestFailure("http://127.0.0.1:3000/assets/map.png", "net::ERR_ABORTED"),
+    ).toBe(false);
+    expect(
+      shouldIgnoreRequestFailure(
+        "https://www.heygenverse.com/s/50f13ccf-9002-4d80-b567-9d4c0eac30d8/raw",
+        "net::ERR_ABORTED",
+        "xhr",
+      ),
+    ).toBe(false);
+    expect(
+      shouldIgnoreRequestFailure("http://127.0.0.1:3000/assets/sfx.wav", "net::ERR_FAILED"),
+    ).toBe(false);
+  });
+});
+
+describe("waitForPreferredSeekTarget", () => {
+  it("waits for the runtime player/bridge target before falling back to raw timelines", async () => {
+    const page = {
+      waitForFunction: vi.fn(async () => undefined),
+    };
+
+    await waitForPreferredSeekTarget(page, 123);
+
+    expect(page.waitForFunction).toHaveBeenCalledWith(expect.any(Function), { timeout: 123 });
+  });
+
+  it("does not fail validation when only the legacy raw timeline fallback is available", async () => {
+    const page = {
+      waitForFunction: vi.fn(async () => {
+        throw new Error("waiting failed: timeout");
+      }),
+    };
+
+    await expect(waitForPreferredSeekTarget(page, 1)).resolves.toBeUndefined();
+  });
+});
+
+// Regression: `validate` used a hardcoded 10s page-navigation timeout that
+// ignored --timeout, so a composition loading GSAP from a CDN <script> (which
+// blocks domcontentloaded) failed with an opaque "Navigation timeout of 10000ms"
+// even though the full render's larger budget rode it out — with no knob to
+// extend it. resolveNavigationTimeoutMs makes --timeout raise the nav budget
+// (never below the 10s floor); navigationTimeoutHint replaces the opaque error.
+describe("resolveNavigationTimeoutMs", () => {
+  it("keeps the 10s floor when --timeout is unset or smaller", () => {
+    expect(resolveNavigationTimeoutMs(undefined)).toBe(10000);
+    expect(resolveNavigationTimeoutMs(3000)).toBe(10000); // the default --timeout
+    expect(resolveNavigationTimeoutMs(0)).toBe(10000);
+  });
+
+  it("raises the navigation budget to --timeout when it exceeds the floor", () => {
+    expect(resolveNavigationTimeoutMs(30000)).toBe(30000);
+  });
+});
+
+describe("navigationTimeoutHint", () => {
+  it("replaces a Puppeteer navigation-timeout error with an actionable CDN/--timeout hint", () => {
+    const hinted = navigationTimeoutHint(
+      new Error("Navigation timeout of 10000 ms exceeded"),
+      10000,
+    );
+    expect(hinted).toBeInstanceOf(Error);
+    expect(hinted?.message).toContain("10000ms");
+    expect(hinted?.message).toContain("CDN");
+    expect(hinted?.message).toContain("--timeout");
+  });
+
+  it("returns null for any non-navigation-timeout error so the caller rethrows it as-is", () => {
+    expect(navigationTimeoutHint(new Error("net::ERR_CONNECTION_REFUSED"), 10000)).toBeNull();
+    expect(navigationTimeoutHint("some string failure", 10000)).toBeNull();
+  });
+});
diff --git a/packages/validate/src/browserValidate.ts b/packages/validate/src/browserValidate.ts
new file mode 100644
index 0000000000..55a98a97d0
--- /dev/null
+++ b/packages/validate/src/browserValidate.ts
@@ -0,0 +1,507 @@
+import { existsSync, mkdtempSync, readFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { normalizeErrorMessage } from "./errorMessage.js";
+import { resolveCompositionViewportFromHtml } from "./compositionViewport.js";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+export interface ConsoleEntry {
+  level: "error" | "warning";
+  text: string;
+  url?: string;
+  line?: number;
+}
+
+export interface ContrastEntry {
+  time: number;
+  selector: string;
+  text: string;
+  ratio: number;
+  wcagAA: boolean;
+  large: boolean;
+  fg: string;
+  bg: string;
+}
+
+const CONTRAST_SAMPLES = 5;
+const SEEK_SETTLE_MS = 150;
+const PREFERRED_SEEK_TARGET_WAIT_MS = 500;
+const MEDIA_EXTENSIONS = /\.(aac|flac|m4a|mov|mp3|mp4|oga|ogg|wav|webm)$/i;
+// Floor for the initial page navigation. A blocking external <script> (GSAP
+// from a CDN, etc.) delays `domcontentloaded`; the actual render (much larger
+// budget) rides it out, so validate's navigation must be at least as patient as
+// the user's --timeout, never stuck below this floor.
+const NAV_TIMEOUT_FLOOR_MS = 10000;
+
+// Navigation budget = the larger of the floor and the user's --timeout, so
+// `--timeout` (already the "wait longer for slow loads" knob for media/settle)
+// also extends navigation instead of being ignored by a hardcoded 10s.
+export function resolveNavigationTimeoutMs(optTimeout?: number): number {
+  return Math.max(NAV_TIMEOUT_FLOOR_MS, optTimeout ?? 0);
+}
+
+// Turn Puppeteer's opaque "Navigation timeout of Nms exceeded" into an
+// actionable message: the usual cause is a blocking CDN <script> that render
+// tolerates but validate's tighter budget does not. Returns a replacement Error
+// for a navigation timeout, or null for any other error (caller rethrows as-is).
+export function navigationTimeoutHint(err: unknown, navTimeoutMs: number): Error | null {
+  const msg = err instanceof Error ? err.message : String(err);
+  if (!/navigation timeout/i.test(msg)) return null;
+  return new Error(
+    `Page navigation timed out after ${navTimeoutMs}ms. A blocking external <script> ` +
+      `(e.g. GSAP loaded from a CDN) can delay page load past this budget even when the ` +
+      `full render succeeds. Vendor the script locally (recommended for deterministic ` +
+      `renders), or re-run with a longer --timeout.`,
+  );
+}
+
+export function shouldIgnoreRequestFailure(
+  url: string,
+  errorText: string | undefined,
+  resourceType?: string,
+): boolean {
+  if (errorText !== "net::ERR_ABORTED") return false;
+  if (resourceType === "media") return true;
+  try {
+    return MEDIA_EXTENSIONS.test(new URL(url).pathname);
+  } catch {
+    return false;
+  }
+}
+
+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 waitForPreferredSeekTarget(page);
+  await page.evaluate((t: number) => {
+    // window.__player.renderSeek is exposed directly by the composition
+    // runtime (packages/core/src/runtime/init.ts) on every page load, and
+    // — unlike raw timeline.seek() — it also runs the runtime's own
+    // [data-start]/[data-duration] visibility sync, hiding clips outside
+    // their timeline window. window.__hf.seek only exists when the
+    // producer's render-pipeline bridge script has been injected, which
+    // validate's static preview server never does, so it was always
+    // falling through to the raw __timelines seek below and skipping that
+    // sync — leaving off-window elements looking fully visible to any
+    // check (e.g. the contrast audit) that reads computed style afterward.
+    const player = (window as unknown as { __player?: { renderSeek?: (t: number) => void } })
+      .__player;
+    if (player && typeof player.renderSeek === "function") {
+      player.renderSeek(t);
+      return;
+    }
+    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));
+}
+
+interface WaitForFunctionPage {
+  waitForFunction: (pageFunction: () => boolean, options: { timeout: number }) => Promise<unknown>;
+}
+
+export async function waitForPreferredSeekTarget(
+  page: WaitForFunctionPage,
+  timeoutMs = PREFERRED_SEEK_TARGET_WAIT_MS,
+): Promise<void> {
+  try {
+    await page.waitForFunction(
+      () => {
+        const w = window as unknown as {
+          __hf?: { seek?: unknown };
+          __player?: { renderSeek?: unknown };
+        };
+        return typeof w.__player?.renderSeek === "function" || typeof w.__hf?.seek === "function";
+      },
+      { timeout: timeoutMs },
+    );
+  } catch {
+    // Older/static pages may only expose raw window.__timelines. Keep the
+    // legacy fallback path rather than turning a missing player API into a
+    // validate failure.
+  }
+}
+
+/**
+ * Race a media element's `loadedmetadata`/`error` event against a deadline,
+ * whichever comes first. Already-ready elements resolve immediately.
+ *
+ * This is the same wiring as the inline copy inside `auditClipDurations`'s
+ * `page.evaluate()` below — duplicated, not imported, because Puppeteer
+ * serializes that closure's source and re-runs it in an isolated browser
+ * realm with no access to this module's scope. Kept here (duck-typed on
+ * `EventTarget`-shaped objects, not `HTMLMediaElement`) so the actual
+ * race/cleanup logic has a real, deterministic unit test — Node's built-in
+ * `EventTarget` satisfies the same shape without a browser or DOM library.
+ * If you change one copy, change both.
+ */
+export function raceMediaReady(
+  el: EventTarget & { duration: number },
+  deadlineMs: number,
+): Promise<void> {
+  if (Number.isFinite(el.duration) && el.duration > 0) return Promise.resolve();
+  return new Promise<void>((resolve) => {
+    const onReady = () => {
+      el.removeEventListener("loadedmetadata", onReady);
+      el.removeEventListener("error", onReady);
+      clearTimeout(timer);
+      resolve();
+    };
+    el.addEventListener("loadedmetadata", onReady, { once: true });
+    el.addEventListener("error", onReady, { once: true });
+    const timer = setTimeout(onReady, Math.max(0, deadlineMs - Date.now()));
+  });
+}
+
+/**
+ * Flag `<video>`/`<audio>` clips whose source is meaningfully shorter than their
+ * `data-duration` slot (the slot gets silently shortened in renders). Runs in
+ * the live page to read each element's intrinsic `.duration`, which static lint
+ * can't see.
+ */
+async function auditClipDurations(
+  page: import("puppeteer-core").Page,
+  analyzeClipMediaFit: typeof import("@hyperframes/engine").analyzeClipMediaFit,
+  extraWaitMs: number,
+): Promise<ConsoleEntry[]> {
+  // fallow-ignore-next-line complexity
+  const clips = await page.evaluate(async (maxWaitMs: number) => {
+    const nodes = Array.from(
+      document.querySelectorAll("video[data-duration], audio[data-duration]"),
+    ) as HTMLMediaElement[];
+
+    // The caller's page-settle sleep is a flat, unconditional wait shared with
+    // other audits — it isn't aware of how long any given media element takes
+    // to load metadata. A slow-loading audio file (large narration WAV, remote
+    // source) can still be mid-fetch when that sleep elapses, which read as
+    // el.duration === NaN and was misreported as "could not read the duration"
+    // even though the render pipeline (which properly awaits media readiness)
+    // handles the same file fine. Give still-loading elements one more real
+    // chance via loadedmetadata before giving up, instead of a single fixed-time
+    // snapshot. Elements that already have a duration resolve immediately, so
+    // this adds no latency in the common case.
+    const deadline = Date.now() + maxWaitMs;
+    await Promise.all(
+      nodes.map((el) => {
+        if (Number.isFinite(el.duration) && el.duration > 0) return Promise.resolve();
+        return new Promise<void>((resolve) => {
+          const cleanup = () => {
+            el.removeEventListener("loadedmetadata", onReady);
+            el.removeEventListener("error", onReady);
+            clearTimeout(timer);
+          };
+          const onReady = () => {
+            cleanup();
+            resolve();
+          };
+          el.addEventListener("loadedmetadata", onReady, { once: true });
+          el.addEventListener("error", onReady, { once: true });
+          const timer = setTimeout(onReady, Math.max(0, deadline - Date.now()));
+        });
+      }),
+    );
+
+    const rows: Array<{
+      id: string;
+      kind: string;
+      slot: number;
+      mediaStart: number;
+      duration: number;
+      loop: boolean;
+    }> = [];
+    for (const el of nodes) {
+      const slot = parseFloat(el.getAttribute("data-duration") ?? "");
+      if (!(slot > 0)) continue;
+      rows.push({
+        id: el.id || el.getAttribute("src") || `(${el.tagName.toLowerCase()})`,
+        kind: el.tagName === "AUDIO" ? "Audio" : "Video",
+        slot,
+        mediaStart: parseFloat(el.getAttribute("data-media-start") ?? "0") || 0,
+        duration: el.duration,
+        loop: el.loop || el.getAttribute("data-loop") === "true",
+      });
+    }
+    return rows;
+  }, extraWaitMs);
+
+  const warnings: ConsoleEntry[] = [];
+  const unreadable: string[] = [];
+  for (const clip of clips) {
+    if (!Number.isFinite(clip.duration) || clip.duration <= 0) {
+      // Metadata never loaded (e.g. slow remote source) — record so the gap in
+      // coverage isn't silent, rather than dropping it.
+      unreadable.push(clip.id);
+      continue;
+    }
+    const mediaSeconds = Math.max(0, clip.duration - clip.mediaStart);
+    const fit = analyzeClipMediaFit({ slotSeconds: clip.slot, mediaSeconds, loop: clip.loop });
+    if (!fit) continue;
+    warnings.push({
+      level: "warning",
+      text:
+        `${clip.kind} "${clip.id}" is ${mediaSeconds.toFixed(2)}s but its slot (data-duration) ` +
+        `is ${clip.slot.toFixed(2)}s — the slot is shortened to the media length when rendered. ` +
+        `Set data-duration to ~${mediaSeconds.toFixed(2)}s if that isn't intended.`,
+    });
+  }
+  if (unreadable.length > 0) {
+    warnings.push({
+      level: "warning",
+      text:
+        `Could not read the duration of ${unreadable.length} media element(s) within the ` +
+        `validate timeout (${unreadable.join(", ")}); their slot vs. source fit was not checked. ` +
+        `Re-run with a longer --timeout if the source is slow to load.`,
+    });
+  }
+  return warnings;
+}
+
+async function runContrastAudit(page: import("puppeteer-core").Page): Promise<ContrastEntry[]> {
+  const duration = await getCompositionDuration(page);
+  if (duration <= 0) return [];
+
+  await page.addScriptTag({ content: loadContrastAuditScript() });
+
+  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;
+}
+
+function loadContrastAuditScript(): string {
+  const candidates = [
+    join(__dirname, "contrast-audit.browser.js"),
+    join(__dirname, "commands", "contrast-audit.browser.js"),
+  ];
+
+  for (const candidate of candidates) {
+    if (existsSync(candidate)) return readFileSync(candidate, "utf-8");
+  }
+
+  throw new Error("Missing contrast audit browser script");
+}
+
+// Match the render pipeline: localize remote <img>/<video>/<audio>/@font-face
+// into a temp dir (served as an extra asset root) so validate resolves them
+// same-origin and doesn't false-fail on cross-origin (crossorigin/CORS) fetches
+// the real render never makes. Best-effort: no-op on any failure.
+async function localizeRemoteAssets(
+  html: string,
+): Promise<{ html: string; assetRoots: string[]; cleanup: () => void }> {
+  let dir: string | undefined;
+  try {
+    // Non-literal specifier: @hyperframes/producer resolves to built dist at runtime, but its exports
+    // has no source condition, so fallow's static graph can't resolve it during the pre-build audit.
+    const producerPkg = "@hyperframes/producer";
+    const { localizeRemoteMediaSources, localizeRemoteImageSources, localizeRemoteFontFaces } =
+      (await import(producerPkg)) as typeof import("@hyperframes/producer");
+    dir = mkdtempSync(join(tmpdir(), "hf-validate-assets-"));
+    const assetDir = dir;
+    const media = await localizeRemoteMediaSources(html, assetDir);
+    const images = await localizeRemoteImageSources(media.html, assetDir);
+    const fonts = await localizeRemoteFontFaces(images.html, assetDir);
+    const count =
+      media.remoteMediaAssets.size + images.remoteMediaAssets.size + fonts.remoteMediaAssets.size;
+    return {
+      html: fonts.html,
+      assetRoots: count > 0 ? [assetDir] : [],
+      cleanup: () => rmSync(assetDir, { recursive: true, force: true }),
+    };
+  } catch {
+    // Best-effort: drop any partial temp dir before falling back to remote URLs.
+    if (dir) rmSync(dir, { recursive: true, force: true });
+    return { html, assetRoots: [], cleanup: () => {} };
+  }
+}
+
+// Wire console / pageerror / failed-request / HTTP-status diagnostics into the shared errors/warnings buffers.
+function attachDiagnosticListeners(
+  page: import("puppeteer-core").Page,
+  errors: ConsoleEntry[],
+  warnings: ConsoleEntry[],
+): void {
+  page.on("console", (msg) => {
+    const type = msg.type();
+    const loc = msg.location();
+    const text = msg.text();
+    if (type === "error") {
+      if (text.startsWith("Failed to load resource")) return;
+      errors.push({ level: "error", text, url: loc.url, line: loc.lineNumber });
+    } else if (type === "warn") {
+      warnings.push({ level: "warning", text, url: loc.url, line: loc.lineNumber });
+    }
+  });
+
+  page.on("pageerror", (err) => {
+    const text = normalizeErrorMessage(err);
+    // CDN scripts (e.g. GSAP from jsdelivr) returning HTML error pages
+    // instead of JS produce "Unexpected token '<'" SyntaxErrors. These
+    // are network failures, not composition authoring errors.
+    if (text.includes("Unexpected token '<'") || text.includes("Unexpected token '&lt;'")) return;
+    errors.push({ level: "error", text });
+  });
+
+  page.on("requestfailed", (req) => {
+    const url = req.url();
+    if (url.includes("favicon") || url.startsWith("data:")) return;
+    const failureText = req.failure()?.errorText;
+    if (shouldIgnoreRequestFailure(url, failureText, req.resourceType())) return;
+    const path = decodeURIComponent(new URL(url).pathname).replace(/^\//, "");
+    errors.push({
+      level: "error",
+      text: `Failed to load ${path}: ${failureText ?? "net::ERR_FAILED"}`,
+      url,
+    });
+  });
+
+  page.on("response", (res) => {
+    if (res.status() >= 400) {
+      const url = res.url();
+      if (url.includes("favicon")) return;
+      const path = decodeURIComponent(new URL(url).pathname).replace(/^\//, "");
+      errors.push({ level: "error", text: `${res.status()} loading ${path}`, url });
+    }
+  });
+}
+
+/** Options for {@link validateHtmlInBrowser}. */
+export interface BrowserValidateOptions {
+  /** Path to the Chrome/Chromium executable to launch (caller owns browser discovery). */
+  browserExecutablePath: string;
+  /** Dir to serve sibling files from (default: an empty temp dir — HTML-only). */
+  projectDir?: string;
+  /** Chrome viewport (default: derived from the comp's data-width/height). */
+  viewport?: { width: number; height: number };
+  timeout?: number;
+  contrast?: boolean;
+  /** Findings to prepend (e.g. the caller's static composition errors). */
+  prependErrors?: ConsoleEntry[];
+  /** Extra checks on the SAME loaded page before teardown (findings merged) — e.g. a consumer's caption-zone / out-of-frame gates. */
+  onPage?: (
+    page: import("puppeteer-core").Page,
+  ) => Promise<{ errors?: ConsoleEntry[]; warnings?: ConsoleEntry[] }>;
+}
+
+// Run the on-page audits (clip-duration → warnings, optional WCAG contrast, caller onPage); returns contrast entries.
+async function runPageAudits(
+  page: import("puppeteer-core").Page,
+  opts: BrowserValidateOptions,
+  analyzeClipMediaFit: typeof import("@hyperframes/engine").analyzeClipMediaFit,
+  errors: ConsoleEntry[],
+  warnings: ConsoleEntry[],
+): Promise<ContrastEntry[] | undefined> {
+  for (const w of await auditClipDurations(page, analyzeClipMediaFit, opts.timeout ?? 3000)) {
+    warnings.push(w);
+  }
+
+  const contrast = opts.contrast ? await runContrastAudit(page) : undefined;
+
+  if (opts.onPage) {
+    const extra = await opts.onPage(page);
+    if (extra.errors) errors.push(...extra.errors);
+    if (extra.warnings) warnings.push(...extra.warnings);
+  }
+
+  return contrast;
+}
+
+/** Load a pre-bundled HyperFrame ``index.html`` in headless Chrome and report runtime findings — the reusable core behind the ``validate`` command (mirrors ``@hyperframes/lint``'s ``lintHyperframeHtml``). */
+export async function validateHtmlInBrowser(
+  html: string,
+  opts: BrowserValidateOptions,
+): Promise<{ errors: ConsoleEntry[]; warnings: ConsoleEntry[]; contrast?: ContrastEntry[] }> {
+  const { serveStaticProjectHtml } = await import("./staticProjectServer.js");
+
+  // Serve siblings from the caller's project dir when given; otherwise an empty temp dir (HTML-only).
+  const ownTempDir = opts.projectDir
+    ? undefined
+    : mkdtempSync(join(tmpdir(), "hf-validate-serve-"));
+  const projectDir = opts.projectDir ?? (ownTempDir as string);
+
+  const localized = await localizeRemoteAssets(html);
+  const server = await serveStaticProjectHtml(
+    projectDir,
+    localized.html,
+    undefined,
+    localized.assetRoots,
+  ).catch((err) => {
+    // Server never started — the finally below won't run, so clean up here.
+    localized.cleanup();
+    if (ownTempDir) rmSync(ownTempDir, { recursive: true, force: true });
+    throw err;
+  });
+
+  const errors: ConsoleEntry[] = [...(opts.prependErrors ?? [])];
+  const warnings: ConsoleEntry[] = [];
+  let contrast: ContrastEntry[] | undefined;
+  const viewport = opts.viewport ?? resolveCompositionViewportFromHtml(html);
+
+  try {
+    const puppeteer = await import("puppeteer-core");
+    const { buildChromeArgs, analyzeClipMediaFit } = await import("@hyperframes/engine");
+    const browserGpuMode =
+      process.env.PRODUCER_BROWSER_GPU_MODE === "software" ? "software" : "hardware";
+    const chromeBrowser = await puppeteer.default.launch({
+      headless: true,
+      executablePath: opts.browserExecutablePath,
+      args: buildChromeArgs({ ...viewport, captureMode: "screenshot" }, { browserGpuMode }),
+    });
+
+    const page = await chromeBrowser.newPage();
+    await page.setViewport(viewport);
+    attachDiagnosticListeners(page, errors, warnings);
+
+    const navTimeoutMs = resolveNavigationTimeoutMs(opts.timeout);
+    try {
+      await page.goto(server.url, { waitUntil: "domcontentloaded", timeout: navTimeoutMs });
+    } catch (err) {
+      const hinted = navigationTimeoutHint(err, navTimeoutMs);
+      if (hinted) throw hinted;
+      throw err;
+    }
+    await new Promise((r) => setTimeout(r, opts.timeout ?? 3000));
+
+    contrast = await runPageAudits(page, opts, analyzeClipMediaFit, errors, warnings);
+
+    await chromeBrowser.close();
+  } finally {
+    await server.close();
+    localized.cleanup();
+    if (ownTempDir) rmSync(ownTempDir, { recursive: true, force: true });
+  }
+
+  return { errors, warnings, contrast };
+}
diff --git a/packages/validate/src/compositionViewport.ts b/packages/validate/src/compositionViewport.ts
new file mode 100644
index 0000000000..441fcc3dc1
--- /dev/null
+++ b/packages/validate/src/compositionViewport.ts
@@ -0,0 +1,36 @@
+import { ensureDOMParser } from "./dom.js";
+
+const DEFAULT_VIEWPORT = { width: 1920, height: 1080 } as const;
+const MAX_VIEWPORT_DIMENSION = 4096;
+
+function parseViewportDimension(value: string | null): number | null {
+  if (!value) return null;
+  const parsed = Number.parseInt(value, 10);
+  if (!Number.isFinite(parsed) || parsed <= 0) return null;
+  return Math.min(parsed, MAX_VIEWPORT_DIMENSION);
+}
+
+/**
+ * Pull `data-width` + `data-height` from the document's first composition
+ * root (the element with `data-composition-id` plus both dimension attrs
+ * — the same selector the producer uses to lay out the page). Returns
+ * `null` when no such root exists or either attr is invalid, so callers
+ * can distinguish "no declared dimensions" from "declared 1920×1080".
+ */
+function findCompositionDimensions(html: string): { width: number; height: number } | null {
+  ensureDOMParser();
+  const doc = new DOMParser().parseFromString(html, "text/html");
+  const root = doc.querySelector("[data-composition-id][data-width][data-height]");
+  if (!root) return null;
+  const width = parseViewportDimension(root.getAttribute("data-width"));
+  const height = parseViewportDimension(root.getAttribute("data-height"));
+  if (width === null || height === null) return null;
+  return { width, height };
+}
+
+export function resolveCompositionViewportFromHtml(html: string): {
+  width: number;
+  height: number;
+} {
+  return findCompositionDimensions(html) ?? DEFAULT_VIEWPORT;
+}
diff --git a/packages/cli/src/commands/contrast-audit.browser.js b/packages/validate/src/contrast-audit.browser.js
similarity index 100%
rename from packages/cli/src/commands/contrast-audit.browser.js
rename to packages/validate/src/contrast-audit.browser.js
diff --git a/packages/validate/src/contrast-audit.browser.test.ts b/packages/validate/src/contrast-audit.browser.test.ts
new file mode 100644
index 0000000000..5c86d7810c
--- /dev/null
+++ b/packages/validate/src/contrast-audit.browser.test.ts
@@ -0,0 +1,105 @@
+// @vitest-environment happy-dom
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const contrastScript = readFileSync(join(__dirname, "contrast-audit.browser.js"), "utf-8");
+
+interface RectInput {
+  left: number;
+  top: number;
+  width: number;
+  height: number;
+}
+
+describe("contrast-audit.browser clip-path visibility", () => {
+  afterEach(() => {
+    vi.restoreAllMocks();
+    vi.unstubAllGlobals();
+    document.body.innerHTML = "";
+    delete (document as unknown as { elementFromPoint?: unknown }).elementFromPoint;
+    delete (window as unknown as { __contrastAudit?: unknown }).__contrastAudit;
+  });
+
+  it("excludes text clipped to nothing by clip-path from contrast reports", async () => {
+    document.body.innerHTML = `
+      <div id="root" data-composition-id="main" data-width="640" data-height="360">
+        <div id="headline">Hidden text</div>
+      </div>
+    `;
+
+    vi.spyOn(window, "getComputedStyle").mockImplementation((element) => {
+      const id = (element as Element).id;
+      return {
+        display: "block",
+        visibility: "visible",
+        opacity: "1",
+        color: "rgb(0, 0, 0)",
+        fontSize: "32px",
+        fontWeight: "400",
+        clipPath: id === "headline" ? "inset(0px 100% 0px 0px)" : "none",
+      } as unknown as CSSStyleDeclaration;
+    });
+
+    vi.spyOn(document.getElementById("headline")!, "getBoundingClientRect").mockReturnValue(
+      rect({ left: 100, top: 100, width: 400, height: 80 }),
+    );
+    (document as unknown as { elementFromPoint: () => Element | null }).elementFromPoint = () =>
+      null;
+
+    installContrastScript();
+
+    expect(await runContrastAudit()).toEqual([]);
+  });
+});
+
+function installContrastScript(): void {
+  class MockImage {
+    onload: (() => void) | null = null;
+    onerror: (() => void) | null = null;
+    naturalWidth = 640;
+    naturalHeight = 360;
+
+    set src(_value: string) {
+      this.onload?.();
+    }
+  }
+
+  vi.stubGlobal("Image", MockImage);
+  const getContextSpy = vi.spyOn(HTMLCanvasElement.prototype, "getContext") as unknown as {
+    mockReturnValue(value: CanvasRenderingContext2D): void;
+  };
+  getContextSpy.mockReturnValue({
+    drawImage() {},
+    getImageData() {
+      return { data: new Uint8ClampedArray(640 * 360 * 4).fill(255) };
+    },
+  } as unknown as CanvasRenderingContext2D);
+  window.eval(contrastScript);
+}
+
+async function runContrastAudit(): Promise<Array<Record<string, unknown>>> {
+  return (
+    window as unknown as {
+      __contrastAudit: (imgBase64: string, time: number) => Promise<Array<Record<string, unknown>>>;
+    }
+  ).__contrastAudit("stub", 0);
+}
+
+function rect({ left, top, width, height }: RectInput): DOMRect {
+  return {
+    left,
+    top,
+    right: left + width,
+    bottom: top + height,
+    width,
+    height,
+    x: left,
+    y: top,
+    toJSON() {
+      return this;
+    },
+  } as DOMRect;
+}
diff --git a/packages/validate/src/dom.ts b/packages/validate/src/dom.ts
new file mode 100644
index 0000000000..e4d178f065
--- /dev/null
+++ b/packages/validate/src/dom.ts
@@ -0,0 +1,11 @@
+import { DOMParser } from "linkedom";
+
+/**
+ * Polyfill DOMParser on globalThis so @hyperframes/core's parseHtml works in Node.js.
+ * Safe to call multiple times — only sets the global once.
+ */
+export function ensureDOMParser(): void {
+  if (typeof globalThis.DOMParser === "undefined") {
+    (globalThis as Record<string, unknown>).DOMParser = DOMParser;
+  }
+}
diff --git a/packages/validate/src/errorMessage.ts b/packages/validate/src/errorMessage.ts
new file mode 100644
index 0000000000..f2928f1404
--- /dev/null
+++ b/packages/validate/src/errorMessage.ts
@@ -0,0 +1,18 @@
+export function normalizeErrorMessage(error: unknown): string {
+  if (error instanceof Error) return error.message;
+  if (typeof error === "string") return error;
+  if (typeof error === "object" && error !== null) {
+    const msg = (error as Record<string, unknown>).message;
+    if (typeof msg === "string") return msg;
+    try {
+      return JSON.stringify(error);
+    } catch {
+      try {
+        return `{${Object.keys(error as object).join(", ")}}`;
+      } catch {
+        /* truly opaque object */
+      }
+    }
+  }
+  return String(error ?? "unknown error");
+}
diff --git a/packages/validate/src/index.ts b/packages/validate/src/index.ts
new file mode 100644
index 0000000000..670767e783
--- /dev/null
+++ b/packages/validate/src/index.ts
@@ -0,0 +1,6 @@
+export {
+  validateHtmlInBrowser,
+  type BrowserValidateOptions,
+  type ConsoleEntry,
+  type ContrastEntry,
+} from "./browserValidate.js";
diff --git a/packages/validate/src/staticProjectServer.ts b/packages/validate/src/staticProjectServer.ts
new file mode 100644
index 0000000000..ea26451aff
--- /dev/null
+++ b/packages/validate/src/staticProjectServer.ts
@@ -0,0 +1,123 @@
+import { createServer, type ServerResponse } from "node:http";
+import { createReadStream, existsSync, statSync } from "node:fs";
+import { isAbsolute, relative, resolve } from "node:path";
+import { getMimeType } from "@hyperframes/core/studio-api";
+
+export interface StaticProjectServer {
+  url: string;
+  port: number;
+  close: () => Promise<void>;
+}
+
+/**
+ * Serve a file with HTTP Range support. Chromium needs byte-range seekability
+ * to determine the duration of formats that carry it in a trailing/implicit
+ * position (notably WAV, which otherwise reports `.duration` as `Infinity`
+ * however long it buffers). A plain 200 with no `Accept-Ranges` makes the
+ * media element non-seekable, so `hyperframes validate` would spuriously warn
+ * that a perfectly valid local WAV's duration "could not be read".
+ */
+function serveFileWithRange(
+  filePath: string,
+  rangeHeader: string | undefined,
+  res: ServerResponse,
+) {
+  const size = statSync(filePath).size;
+  const headers: Record<string, string> = {
+    "Content-Type": getMimeType(filePath),
+    "Accept-Ranges": "bytes",
+  };
+
+  // Resolve the requested byte window. Absent/malformed Range serves the
+  // whole file (200); a valid `bytes=start-end` (including the open-ended
+  // `start-` and suffix `-N` forms) serves a 206 slice.
+  const last = size - 1;
+  let start = 0;
+  let end = last;
+  let status = 200;
+  const match = rangeHeader ? /^bytes=(\d*)-(\d*)$/.exec(rangeHeader.trim()) : null;
+  if (match) {
+    const hasStart = match[1] !== "";
+    start = hasStart ? Number(match[1]) : Math.max(0, size - Number(match[2]));
+    end = !hasStart ? last : match[2] !== "" ? Math.min(Number(match[2]), last) : last;
+
+    if (start > end || start > last) {
+      res.writeHead(416, { ...headers, "Content-Range": `bytes */${size}` });
+      res.end();
+      return;
+    }
+    status = 206;
+    headers["Content-Range"] = `bytes ${start}-${end}/${size}`;
+  }
+  headers["Content-Length"] = String(end - start + 1);
+
+  // Stream only the requested window instead of buffering the whole file: a
+  // 1KB Range of a 50MB asset must not allocate 50MB. createReadStream reads
+  // just `[start, end]` and closes its own fd on end/error. writeHead is
+  // deferred to `open` so a failed open can still answer 500.
+  const stream = createReadStream(filePath, { start, end });
+  stream.on("open", () => {
+    res.writeHead(status, headers);
+    stream.pipe(res);
+  });
+  stream.on("error", () => {
+    if (!res.headersSent) res.writeHead(500);
+    res.end();
+    stream.destroy();
+  });
+}
+
+export async function serveStaticProjectHtml(
+  projectDir: string,
+  html: string,
+  bindErrorMessage = "Failed to bind local HTTP server",
+  // Extra dirs to resolve non-index requests against, after projectDir (e.g. a
+  // temp dir of localized remote assets).
+  assetRoots: readonly string[] = [],
+): Promise<StaticProjectServer> {
+  const roots = [projectDir, ...assetRoots];
+  // fallow-ignore-next-line complexity
+  const server = createServer((req, res) => {
+    const url = req.url ?? "/";
+    if (url === "/" || url === "/index.html") {
+      res.writeHead(200, { "Content-Type": "text/html" });
+      res.end(html);
+      return;
+    }
+
+    const requestPath = decodeURIComponent(url).replace(/^\//, "");
+    for (const root of roots) {
+      const filePath = resolve(root, requestPath);
+      const rel = relative(root, filePath);
+      if (rel.startsWith("..") || isAbsolute(rel)) continue; // traversal guard; try next root
+      if (existsSync(filePath)) {
+        serveFileWithRange(filePath, req.headers.range, res);
+        return;
+      }
+    }
+    res.writeHead(404);
+    res.end();
+  });
+
+  const port = await new Promise<number>((resolvePort, rejectPort) => {
+    server.on("error", rejectPort);
+    // Bind loopback only (SECURITY F-001): a bare listen(0) binds 0.0.0.0/::,
+    // which an IDE's port auto-forward surfaces as a transient "preview". The
+    // snapshot browser is co-located (url below is already 127.0.0.1).
+    server.listen(0, "127.0.0.1", () => {
+      const addr = server.address();
+      const resolvedPort = typeof addr === "object" && addr ? addr.port : 0;
+      if (!resolvedPort) rejectPort(new Error(bindErrorMessage));
+      else resolvePort(resolvedPort);
+    });
+  });
+
+  return {
+    url: `http://127.0.0.1:${port}/`,
+    port,
+    close: () =>
+      new Promise<void>((resolveClose) => {
+        server.close(() => resolveClose());
+      }),
+  };
+}
diff --git a/packages/validate/tsconfig.json b/packages/validate/tsconfig.json
new file mode 100644
index 0000000000..96f38bce00
--- /dev/null
+++ b/packages/validate/tsconfig.json
@@ -0,0 +1,18 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "strict": true,
+    "noUncheckedIndexedAccess": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "outDir": "./dist",
+    "rootDir": "./src"
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist", "**/*.test.ts"]
+}
diff --git a/packages/validate/tsup.config.ts b/packages/validate/tsup.config.ts
new file mode 100644
index 0000000000..f5380e58e2
--- /dev/null
+++ b/packages/validate/tsup.config.ts
@@ -0,0 +1,14 @@
+import { defineConfig } from "tsup";
+
+export default defineConfig({
+  entry: { index: "src/index.ts" },
+  format: ["esm"],
+  outDir: "dist",
+  target: "node22",
+  platform: "node",
+  bundle: true,
+  splitting: false,
+  sourcemap: true,
+  clean: true,
+  dts: true,
+});