feat(cli): resolve proxies before check's timed browser phase (#2594)

* feat(studio-server): serve H.264 proxies from the preview route

Wires the codec manifest and the transcoder into the preview surface: the route
negotiates a proxy via a query param and serves it through the existing range
and ETag machinery, composition HTML carries a codec map for the runtime, and
hostile assets pre-warm so a first play does not wait on a cold transcode.
Exposes the three subpath exports the CLI surfaces consume upstack.

Drops the TEMP fallow entry added with the transcoder: it has real importers now.

* fix(studio-server): publish media proxy exports

* fix(parsers): scan HTML comments linearly

* feat(cli): let projects opt out of automatic proxying

Adds media.autoProxy to hyperframes.json plus --proxy/--no-proxy flags, and
forwards the resolved value into the studio and preview servers and the vite
adapter. Lands before the runtime slice that turns auto-proxying on, so the
switch exists before there is any behavior to switch off.

* fix(cli): align media config schema

* feat(core): swap undecodable video to its proxy at runtime

Adds the browser-side half: before first load the runtime consults the injected
codec map and swaps a hostile source to its proxy, and if a video still reports
zero decodable width it rescues it reactively. An HEVC file carrying AAC fires
no error event, so zero videoWidth, not the error event, is the reliable signal.
Audio elements and alpha sources are never proxied, render mode never proxies,
and each swap evicts the element's stale sync state and reports once.

This completes the loop: auto-proxying is live for preview and studio from here.
The opt-out (media.autoProxy, --no-proxy) shipped in the previous slice.

* feat(cli): serve proxies from play, present, and the static project server

Adds proxy negotiation to the CLI-side servers and gives play byte-range
serving it never had, so a swapped video can seek. The static project server
behind check, snapshot, compare and friends injects the codec map once, so all
of its callers inherit the behavior; snapshot forwards its own proxy flag.

* fix(cli): serve proxies for camera formats

* feat(cli): resolve proxies before check's timed browser phase

check pre-resolves hostile assets so a cold transcode cannot exhaust the
render-ready budget, and surfaces the runtime's proxy diagnostics as findings
so a swap is visible rather than silent.

* fix(cli): harden proxy pre-resolution

packages/cli/src/utils/checkBrowser.ts

@@ -1,5 +1,5 @@
 import { mkdirSync, writeFileSync } from "node:fs";
-import { join } from "node:path";
+import { join, resolve } from "node:path";
 import type { Page } from "puppeteer-core";
 import {
   AUDIT_SEEK_OPTIONS,
@@ -18,6 +18,12 @@ import { normalizeErrorMessage } from "./errorMessage.js";
 import { ambiguousIssue, type MotionFrame } from "./motionAudit.js";
 import type { LayoutIssue, LayoutIssueCode, LayoutRect } from "./layoutAudit.js";
 import { serveStaticProjectHtml } from "./staticProjectServer.js";
+import { resolveAutoProxy } from "./projectConfig.js";
+import {
+  decideMediaProxyEligibility,
+  scanProjectMediaCodecMap,
+} from "@hyperframes/studio-server/media-codec-map";
+import { resolveProxy } from "@hyperframes/studio-server/proxy-transcoder";
 import { rectToBbox } from "./checkTypes.js";
 import type {
   AnchoredLayoutIssue,
@@ -82,6 +88,50 @@ interface FinishedContrast {
   bg: string;
 }
 
+/**
+ * Awaits the H.264 authoring proxy for every browser-hostile local video
+ * asset in `html` BEFORE the timed render-ready wait starts. `check`'s
+ * render-ready wait defaults to 3000ms (`DEFAULT_CHECK_OPTIONS.timeout`,
+ * passed through as `renderReadyTimeoutMs`), and a cold `.transcode-cache`
+ * cannot fit inside that window — without this, a project's first
+ * hostile-asset check (e.g. a fresh CI checkout) would race the timeout
+ * instead of paying a bounded one-time transcode cost
+ * (docs/plans/2026-07-14-002-feat-transparent-media-proxies-plan.md, unit U4).
+ * Best-effort: a probe or transcode failure does not fail `check`; one summary
+ * line records the pre-resolve outcome before the runtime attempts playback.
+ */
+export async function preResolveHostileMediaProxies(
+  projectDir: string,
+  html: string,
+  autoProxyOverride?: boolean,
+): Promise<void> {
+  if (!resolveAutoProxy(projectDir, autoProxyOverride)) return;
+  let codecMap: Awaited<ReturnType<typeof scanProjectMediaCodecMap>>;
+  try {
+    codecMap = await scanProjectMediaCodecMap(projectDir, [{ html }]);
+  } catch (err) {
+    console.info(
+      `[hyperframes] media proxy pre-resolve: scan failed (${normalizeErrorMessage(err)})`,
+    );
+    return;
+  }
+  const hostilePathnames = Object.entries(codecMap)
+    .filter(([, facts]) => decideMediaProxyEligibility(facts).eligible)
+    .map(([pathname]) => pathname);
+  if (hostilePathnames.length === 0) return;
+
+  const startedAt = Date.now();
+  const results = await Promise.allSettled(
+    hostilePathnames.map((pathname) =>
+      resolveProxy(projectDir, resolve(projectDir, pathname.replace(/^\/+/, ""))),
+    ),
+  );
+  const failed = results.filter((result) => result.status === "rejected").length;
+  console.info(
+    `[hyperframes] media proxy pre-resolve: ${results.length - failed}/${results.length} ready, ${failed} failed (${Date.now() - startedAt}ms)`,
+  );
+}
+
 export async function runBrowserCheck(
   project: ProjectDir,
   options: CheckOptions,
@@ -90,7 +140,14 @@ export async function runBrowserCheck(
 ): Promise<CheckBrowserResult> {
   const { bundleWithLocalizedFonts } = await import("./bundleWithLocalizedFonts.js");
   const html = await bundleWithLocalizedFonts(project.dir);
-  const server = await serveStaticProjectHtml(project.dir, html, "Failed to bind check server");
+  await preResolveHostileMediaProxies(project.dir, html, options.autoProxy);
+  const server = await serveStaticProjectHtml(
+    project.dir,
+    html,
+    "Failed to bind check server",
+    [],
+    options.autoProxy,
+  );
   const drafts: RuntimeDraft[] = [];
   let currentTime = 0;
   let chromeBrowser: import("puppeteer-core").Browser | undefined;
@@ -147,7 +204,13 @@ export async function captureFindingCrops(
   if (requests.length === 0) return [];
   const { bundleWithLocalizedFonts } = await import("./bundleWithLocalizedFonts.js");
   const html = await bundleWithLocalizedFonts(project.dir);
-  const server = await serveStaticProjectHtml(project.dir, html, "Failed to bind check server");
+  const server = await serveStaticProjectHtml(
+    project.dir,
+    html,
+    "Failed to bind check server",
+    [],
+    options.autoProxy,
+  );
   let chromeBrowser: import("puppeteer-core").Browser | undefined;
   const written: string[] = [];
   try {
@@ -180,6 +243,15 @@ export async function captureFindingCrops(
   }
 }
 
+// `swapToProxy` / `emitUnavailableDiagnostic` (packages/core/src/runtime/
+// mediaProxy.ts) embed their stable diagnostic codes in the console.info line
+// precisely so this scraper can match a token instead of prose. Matching the
+// shared "runtime_media_proxy_" prefix surfaces both codes; only those
+// runtime-emitted info lines should ever become findings here — an ordinary
+// `console.info` from a composition author's own script must not.
+const MEDIA_PROXY_MARKER_PREFIX = "[hyperframes] runtime_media_proxy_";
+const MEDIA_PROXY_UNAVAILABLE_MARKER = "[hyperframes] runtime_media_proxy_unavailable";
+
 function wireRuntimeListeners(page: Page, drafts: RuntimeDraft[], currentTime: () => number): void {
   page.on("console", (message) => {
     const type = message.type();
@@ -204,6 +276,18 @@ function wireRuntimeListeners(page: Page, drafts: RuntimeDraft[], currentTime: (
         url: location.url,
         line: location.lineNumber,
       });
+    } else if (type === "info" && text.startsWith(MEDIA_PROXY_MARKER_PREFIX)) {
+      const location = message.location();
+      drafts.push({
+        code: text.includes(MEDIA_PROXY_UNAVAILABLE_MARKER)
+          ? "media_proxy_unavailable"
+          : "media_proxy_fallback",
+        severity: "info",
+        message: text,
+        time: currentTime(),
+        url: location.url,
+        line: location.lineNumber,
+      });
     }
   });
   page.on("pageerror", (error) => {