feat(cli): bake proxies into published archives (#2595)

* 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. * feat(cli): bake proxies into published archives Published pages are static, so there is no server to negotiate with: publish transcodes proxies for hostile assets into the archive and rewrites the video sources that point at them. Audio elements keep their originals, since audio decodes independently of the video codec. Splits the archive build from the zip step so publish can transform between them. cloud render keeps calling the unchanged composition and still uploads originals, which its regression test pins. * fix(cli): harden proxy pre-resolution * fix(cli): surface publish proxy outcomes * test(cli): remove ffmpeg from archive guard * test(cli): normalize publish fixture path
2026-09-12 07:09:59 +00:00 · 2026-07-17 02:50:28 -04:00
parent 4ad582606b
commit 35eff5038b
5 changed files with 574 additions and 10 deletions
@@ -0,0 +1,264 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join, resolve } from "node:path";
+
+// The error class lives inside this `vi.hoisted` block (not a plain top-level
+// `class`) because `vi.mock` factories run during static-import resolution —
+// before any of the test file's own top-level statements execute — so a
+// `class` declared below would still be in its temporal dead zone. Mirrors
+// the pattern in `commands/play.test.ts`.
+const mocks = vi.hoisted(() => {
+  class FakeProxyTranscodeError extends Error {
+    readonly exitCode: number | null;
+    readonly stderrTail: string;
+    constructor(message: string, exitCode: number | null = null, stderrTail = "") {
+      super(message);
+      this.name = "ProxyTranscodeError";
+      this.exitCode = exitCode;
+      this.stderrTail = stderrTail;
+    }
+  }
+  return {
+    resolveProxy: vi.fn<(projectDir: string, absoluteSourcePath: string) => Promise<string>>(),
+    scanProjectMediaCodecMap: vi.fn<
+      (...args: unknown[]) => Promise<
+        Record<
+          string,
+          {
+            codecName: string;
+            browserHostile: boolean;
+            representativeMime: string | null;
+            hasAlpha?: boolean;
+          }
+        >
+      >
+    >(),
+    ProxyTranscodeError: FakeProxyTranscodeError,
+    waitForProxy: vi.fn(<T>(promise: Promise<T>, _timeoutMs?: number) => promise),
+  };
+});
+const FakeProxyTranscodeError = mocks.ProxyTranscodeError;
+
+vi.mock("@hyperframes/studio-server/proxy-transcoder", () => ({
+  resolveProxy: mocks.resolveProxy,
+  ProxyTranscodeError: mocks.ProxyTranscodeError,
+  waitForProxy: mocks.waitForProxy,
+  TRANSCODE_TIMEOUT_MS: 15 * 60 * 1000,
+}));
+
+vi.mock("@hyperframes/studio-server/media-codec-map", () => ({
+  scanProjectMediaCodecMap: mocks.scanProjectMediaCodecMap,
+}));
+
+const { bakeMediaProxies, PROXY_ARCHIVE_PREFIX } = await import("./publishProxyBake.js");
+
+// No real project directory is touched: `scanProjectMediaCodecMap` (which
+// would otherwise walk `projectDir`) and `resolveProxy` (which would
+// transcode from it) are both mocked above, mirroring `checkBrowser.test.ts`'s
+// `PROJECT: ProjectDir = { dir: "/project", ... }` fixture.
+const PROJECT_DIR = resolve("/project");
+
+const tempDirs: string[] = [];
+function tmpProxyFile(content: string): string {
+  const dir = mkdtempSync(join(tmpdir(), "hf-publish-proxy-bake-"));
+  tempDirs.push(dir);
+  const path = join(dir, "proxy.mp4");
+  writeFileSync(path, content, "utf-8");
+  return path;
+}
+
+function indexHtml(...tags: string[]): Buffer {
+  return Buffer.from(`<html><body>${tags.join("\n")}</body></html>`, "utf-8");
+}
+
+afterEach(() => {
+  mocks.resolveProxy.mockReset();
+  mocks.scanProjectMediaCodecMap.mockReset();
+  for (const dir of tempDirs.splice(0)) rmSync(dir, { recursive: true, force: true });
+});
+
+describe("bakeMediaProxies", () => {
+  it("bakes a proxy for a hostile video: original stays, proxy is added under _proxy/, HTML rewritten to it", async () => {
+    mocks.scanProjectMediaCodecMap.mockResolvedValue({
+      "/clip.mp4": { codecName: "hevc", browserHostile: true, representativeMime: "video/mp4" },
+    });
+    const proxyPath = tmpProxyFile("PROXY_H264_BYTES");
+    mocks.resolveProxy.mockResolvedValue(proxyPath);
+
+    const fileContents = new Map<string, Buffer>([
+      ["index.html", indexHtml(`<video src="clip.mp4" muted></video>`)],
+      ["clip.mp4", Buffer.from("ORIGINAL_HEVC_BYTES", "utf-8")],
+    ]);
+
+    const manifest = await bakeMediaProxies(PROJECT_DIR, fileContents);
+
+    // Original bytes untouched.
+    expect(fileContents.get("clip.mp4")?.toString("utf-8")).toBe("ORIGINAL_HEVC_BYTES");
+
+    // Proxy added under the archive prefix with the transcoded bytes.
+    const proxyEntries = [...fileContents.keys()].filter((k) =>
+      k.startsWith(`${PROXY_ARCHIVE_PREFIX}/`),
+    );
+    expect(proxyEntries).toHaveLength(1);
+    expect(fileContents.get(proxyEntries[0]!)?.toString("utf-8")).toBe("PROXY_H264_BYTES");
+
+    // HTML rewritten to reference the proxy, not the original.
+    const html = fileContents.get("index.html")!.toString("utf-8");
+    expect(html).toContain(proxyEntries[0]!);
+    expect(html).not.toContain('src="clip.mp4"');
+
+    expect(mocks.resolveProxy).toHaveBeenCalledWith(PROJECT_DIR, join(PROJECT_DIR, "clip.mp4"));
+    expect(mocks.waitForProxy).toHaveBeenCalledWith(expect.any(Promise), 15 * 60 * 1000);
+    expect(manifest).toEqual({ proxied: ["/clip.mp4"], skippedAlpha: [], failed: [] });
+  });
+
+  it("never rewrites an <audio> sharing the hostile video's src; the original file stays for it", async () => {
+    mocks.scanProjectMediaCodecMap.mockResolvedValue({
+      "/clip.mp4": { codecName: "hevc", browserHostile: true, representativeMime: "video/mp4" },
+    });
+    mocks.resolveProxy.mockResolvedValue(tmpProxyFile("PROXY_H264_BYTES"));
+
+    const fileContents = new Map<string, Buffer>([
+      [
+        "index.html",
+        indexHtml(`<video src="clip.mp4" muted></video>`, `<audio src="clip.mp4"></audio>`),
+      ],
+      ["clip.mp4", Buffer.from("ORIGINAL_HEVC_BYTES", "utf-8")],
+    ]);
+
+    await bakeMediaProxies(PROJECT_DIR, fileContents);
+
+    const html = fileContents.get("index.html")!.toString("utf-8");
+    expect(html).toContain('<audio src="clip.mp4">');
+    expect(html).not.toMatch(/<video src="clip\.mp4"/);
+    expect(fileContents.get("clip.mp4")?.toString("utf-8")).toBe("ORIGINAL_HEVC_BYTES");
+  });
+
+  it("fails publish with an explicit manifest when a required opaque proxy cannot be built", async () => {
+    mocks.scanProjectMediaCodecMap.mockResolvedValue({
+      "/clip.mp4": { codecName: "hevc", browserHostile: true, representativeMime: "video/mp4" },
+    });
+    mocks.resolveProxy.mockRejectedValue(new FakeProxyTranscodeError("ffmpeg exited with code 1"));
+    const fileContents = new Map<string, Buffer>([
+      ["index.html", indexHtml(`<video src="clip.mp4" muted></video>`)],
+      ["clip.mp4", Buffer.from("ORIGINAL_HEVC_BYTES", "utf-8")],
+    ]);
+
+    await expect(bakeMediaProxies(PROJECT_DIR, fileContents)).rejects.toMatchObject({
+      name: "ProxyBakeError",
+      manifest: {
+        proxied: [],
+        skippedAlpha: [],
+        failed: [{ path: "/clip.mp4", error: "ffmpeg exited with code 1" }],
+      },
+    });
+
+    expect([...fileContents.keys()].some((k) => k.startsWith(`${PROXY_ARCHIVE_PREFIX}/`))).toBe(
+      false,
+    );
+    expect(fileContents.get("index.html")?.toString("utf-8")).toContain('src="clip.mp4"');
+    expect(fileContents.get("clip.mp4")?.toString("utf-8")).toBe("ORIGINAL_HEVC_BYTES");
+  });
+
+  it("bakes and rewrites a percent-encoded src through the same resolution path the scan uses", async () => {
+    mocks.scanProjectMediaCodecMap.mockResolvedValue({
+      "/assets/my clip.mp4": {
+        codecName: "hevc",
+        browserHostile: true,
+        representativeMime: "video/mp4",
+      },
+    });
+    const proxyPath = tmpProxyFile("PROXY_H264_BYTES");
+    mocks.resolveProxy.mockResolvedValue(proxyPath);
+
+    const fileContents = new Map<string, Buffer>([
+      ["index.html", indexHtml(`<video src="assets/my%20clip.mp4" muted></video>`)],
+      ["assets/my clip.mp4", Buffer.from("ORIGINAL_HEVC_BYTES", "utf-8")],
+    ]);
+
+    await bakeMediaProxies(PROJECT_DIR, fileContents);
+
+    // Baked: the proxy entry landed under _proxy/.
+    const proxyEntries = [...fileContents.keys()].filter((k) =>
+      k.startsWith(`${PROXY_ARCHIVE_PREFIX}/`),
+    );
+    expect(proxyEntries).toHaveLength(1);
+
+    // Rewritten: the percent-encoded src now points at the proxy.
+    const html = fileContents.get("index.html")!.toString("utf-8");
+    expect(html).toContain(proxyEntries[0]!);
+    expect(html).not.toContain("assets/my%20clip.mp4");
+  });
+
+  it("reports an alpha-bearing hostile asset as skipped while keeping HTML on the original", async () => {
+    mocks.scanProjectMediaCodecMap.mockResolvedValue({
+      "/clip.mov": {
+        codecName: "prores",
+        browserHostile: true,
+        representativeMime: null,
+        hasAlpha: true,
+      },
+    });
+    const fileContents = new Map<string, Buffer>([
+      ["index.html", indexHtml(`<video src="clip.mov" muted></video>`)],
+      ["clip.mov", Buffer.from("ORIGINAL_PRORES_4444_BYTES", "utf-8")],
+    ]);
+
+    const manifest = await bakeMediaProxies(PROJECT_DIR, fileContents);
+
+    expect(mocks.resolveProxy).not.toHaveBeenCalled();
+    expect([...fileContents.keys()].some((k) => k.startsWith(`${PROXY_ARCHIVE_PREFIX}/`))).toBe(
+      false,
+    );
+    expect(fileContents.get("index.html")?.toString("utf-8")).toContain('src="clip.mov"');
+    expect(manifest).toEqual({ proxied: [], skippedAlpha: ["/clip.mov"], failed: [] });
+  });
+
+  it("returns deterministic manifest ordering across concurrent transcodes", async () => {
+    mocks.scanProjectMediaCodecMap.mockResolvedValue({
+      "/z.mov": { codecName: "hevc", browserHostile: true, representativeMime: null },
+      "/a.mov": { codecName: "hevc", browserHostile: true, representativeMime: null },
+    });
+    const zProxy = tmpProxyFile("Z");
+    const aProxy = tmpProxyFile("A");
+    mocks.resolveProxy.mockImplementation(async (_projectDir, sourcePath) =>
+      sourcePath.endsWith("z.mov") ? zProxy : aProxy,
+    );
+    const fileContents = new Map<string, Buffer>([
+      ["index.html", indexHtml(`<video src="z.mov"></video>`, `<video src="a.mov"></video>`)],
+      ["z.mov", Buffer.from("Z")],
+      ["a.mov", Buffer.from("A")],
+    ]);
+
+    const manifest = await bakeMediaProxies(PROJECT_DIR, fileContents);
+
+    expect(manifest.proxied).toEqual(["/a.mov", "/z.mov"]);
+  });
+
+  it("is a no-op when no asset is browser-hostile", async () => {
+    mocks.scanProjectMediaCodecMap.mockResolvedValue({
+      "/clip.mp4": { codecName: "h264", browserHostile: false, representativeMime: null },
+    });
+
+    const fileContents = new Map<string, Buffer>([
+      ["index.html", indexHtml(`<video src="clip.mp4" muted></video>`)],
+      ["clip.mp4", Buffer.from("ORIGINAL_H264_BYTES", "utf-8")],
+    ]);
+
+    await bakeMediaProxies(PROJECT_DIR, fileContents);
+
+    expect(mocks.resolveProxy).not.toHaveBeenCalled();
+    expect(fileContents.size).toBe(2);
+    expect(fileContents.get("index.html")?.toString("utf-8")).toContain('src="clip.mp4"');
+  });
+
+  it("never scans (and is a no-op) when the archive has no HTML entries", async () => {
+    const fileContents = new Map<string, Buffer>([["clip.mp4", Buffer.from("BYTES", "utf-8")]]);
+
+    await bakeMediaProxies(PROJECT_DIR, fileContents);
+
+    expect(mocks.scanProjectMediaCodecMap).not.toHaveBeenCalled();
+    expect(fileContents.size).toBe(1);
+  });
+});