feat(validate): extract @hyperframes/validate importable runtime validate

[xuanruli]

What

Extracts the browser-based validate into a new @hyperframes/validate package that exports validateHtmlInBrowser(html, opts) — mirroring how @hyperframes/lint exposes lintHyperframeHtml. The validate CLI command is behavior-unchanged; it now delegates to the package.

Why

The full validate harness (console/network/HTTP error capture, contrast + clip-duration audits, remote-asset localization, viewport-from-comp) only lived inline in the CLI command, so external consumers (e.g. the astral video-agent's validate_hyperframes bridge) can't reuse it. They reimplement a parallel headless harness that drifts from render:

• no asset localization → false CORS / net::ERR_FAILED on the crossorigin <img> S3 fetches the real render localizes first
• hardcoded 1920×1080 viewport → false out_of_frame on portrait comps
• hand-maintained runtime-parity that silently rots

Lint doesn't have this problem because it's an importable package. This gives validate the same shape, so there's one implementation everyone shares.

Design (mirrors the lint pattern)

• Package owns the machinery, caller owns I/O. validateHtmlInBrowser takes opts.browserExecutablePath — the CLI resolves Chrome via its own ensureBrowser() and passes it in. The package has no browser/manager, staying launch-agnostic (lint owns rules, not file I/O; validate owns the audit, not browser discovery).
• opts.onPage(page) runs caller checks on the same loaded page before teardown (findings merged into errors/warnings). This is the hook a downstream consumer uses to layer its own gates — e.g. the caption-zone / out-of-frame geometry checks — without a second browser load or a forked harness.
• contrast-audit.browser.js moves to the package (its only consumer). The CLI build copies it into dist/commands and the bundled runtime loads it via the same page.addScriptTag path.
• Small low-level helpers validate needs (static file server, comp-viewport parse, linkedom shim, error normalizer) are vendored into the package so it doesn't import from @hyperframes/cli (which depends on it). Folding cli + validate onto a shared low-level package is a sensible follow-up — flagged in .fallowrc duplicates.ignore with the repo's existing moved-code convention. (Maintainer call — happy to do it either way.)
• Tests move with the code they cover (pure-function unit tests + the contrast-script browser test). The CLI keeps only extractCompositionErrorsFromLint, a CLI-side lint→error shaping concern.

Verification

• @hyperframes/validate: build + typecheck clean, tests 13/13
• @hyperframes/cli: build clean, tests 1270/1270 (103 files)
• fallow audit --base origin/main: clean on 20 changed files
• e2e: hyperframes validate on a real composition through the package (Chrome launch + contrast audit) → ok: true

Follow-ups (not in this PR)

1. Point the astral validate_hyperframes bridge at validateHtmlInBrowser + pass onPage = caption-zone / out-of-frame gates, replacing its standalone bridge.mjs.
2. Optional: extract cli + validate's shared low-level helpers into a dedicated package to drop the vendored copies.

🤖 Generated with Claude Code