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

packages/cli/src/commands/publish.ts

@@ -7,7 +7,13 @@ import type { Example } from "./_examples.js";
 import { c } from "../ui/colors.js";
 import { lintProject } from "../utils/lintProject.js";
 import { formatLintFindings } from "../utils/lintFormat.js";
-import { publishProjectArchive } from "../utils/publishProject.js";
+import {
+  buildPublishFileMap,
+  publishProjectArchive,
+  zipPublishFileMap,
+} from "../utils/publishProject.js";
+import { bakeMediaProxies } from "../utils/publishProxyBake.js";
+import { resolveAutoProxy } from "../utils/projectConfig.js";
 import { tryResolveCredential } from "../auth/index.js";
 import {
   ensureProjectId,
@@ -23,6 +29,7 @@ export const examples: Example[] = [
   ["Update an existing published project in place", "hyperframes publish --update <url|id>"],
   ["Publish to a shared team space", "hyperframes publish --space <space-id>"],
   ["Skip the consent prompt (scripts)", "hyperframes publish --yes"],
+  ["Skip baking H.264 proxies for browser-hostile video codecs", "hyperframes publish --no-proxy"],
 ];
 
 /** Extract a project id from a published URL (with or without scheme, query, or hash) or accept a bare id. */
@@ -67,6 +74,11 @@ export default defineCommand({
       type: "string",
       description: "Publish into a shared team space (its id) so teammates update one link",
     },
+    proxy: {
+      type: "boolean",
+      description:
+        "Bake H.264 proxies for browser-hostile video codecs (e.g. HEVC) into the published archive. Default: on, unless disabled via hyperframes.json media.autoProxy. Pass --no-proxy to skip.",
+    },
   },
   async run({ args }) {
     const rawArg = args.dir;
@@ -137,19 +149,41 @@ export default defineCommand({
 
     clack.intro(c.bold("hyperframes publish"));
     const publishSpinner = clack.spinner();
-    publishSpinner.start("Uploading project...");
+    publishSpinner.start("Preparing project...");
 
     try {
+      // Resolution order (per hyperframes.json's `media.autoProxy`): an
+      // explicit --proxy/--no-proxy flag wins in either direction, else the
+      // committed config, else on by default.
+      const proxyFlagValue = typeof args.proxy === "boolean" ? args.proxy : undefined;
+      const autoProxy = resolveAutoProxy(dir, proxyFlagValue);
+      const fileMap = buildPublishFileMap(dir);
+      let proxyBakeManifest: Awaited<ReturnType<typeof bakeMediaProxies>> | undefined;
+      if (autoProxy) {
+        proxyBakeManifest = await bakeMediaProxies(dir, fileMap);
+      }
+      const archive = zipPublishFileMap(fileMap);
+      publishSpinner.message("Uploading project...");
+
       const published = await publishProjectArchive(dir, {
         public: args.public === true,
         projectId: requestedProjectId,
         spaceId,
+        archive,
       });
       publishSpinner.stop(c.success("Project published"));
 
       console.log();
       console.log(`  ${c.dim("Project")}    ${c.accent(published.title)}`);
       console.log(`  ${c.dim("Files")}      ${String(published.fileCount)}`);
+      if (proxyBakeManifest) {
+        console.log(`  ${c.dim("Proxies")}    ${String(proxyBakeManifest.proxied.length)} baked`);
+        if (proxyBakeManifest.skippedAlpha.length > 0) {
+          console.log(
+            `  ${c.dim("Proxy note")} ${String(proxyBakeManifest.skippedAlpha.length)} alpha source(s) kept original`,
+          );
+        }
+      }
 
       if (published.claimed) {
         // The server returns the same id on an in-place update, a fresh id on create.

packages/cli/src/utils/publishProject.test.ts

@@ -21,11 +21,13 @@ vi.mock("./projectLink.js", () => ({
 }));
 
 import {
+  buildPublishFileMap,
   createPublishArchive,
   getPublishApiBaseUrl,
   localizeExternalAssets,
   publishProjectArchive,
   uploadTimeoutMs,
+  zipPublishFileMap,
 } from "./publishProject.js";
 
 function makeProjectDir(): string {
@@ -208,6 +210,41 @@ describe("createPublishArchive", () => {
   });
 });
 
+describe("createPublishArchive (U6 cloud-render regression guard)", () => {
+  // `cloud/render.ts` (`maybeUploadProject`) calls `createPublishArchive`
+  // directly and must never see baked proxies (R2): this pins that
+  // `createPublishArchive` is exactly the thin composition of
+  // `buildPublishFileMap` + `zipPublishFileMap` with no baking hook, and that
+  // a local video asset's original bytes/HTML pass through unmodified.
+  it("keeps a source video byte-identical and excludes proxies from the cloud-render archive", () => {
+    const dir = makeProjectDir();
+    try {
+      writeFileSync(
+        join(dir, "index.html"),
+        `<html><body><video src="clip.mp4"></video></body></html>`,
+        "utf-8",
+      );
+      const originalVideo = Buffer.from("original-video-bytes");
+      writeFileSync(join(dir, "clip.mp4"), originalVideo);
+
+      const direct = createPublishArchive(dir);
+      const composed = zipPublishFileMap(buildPublishFileMap(dir));
+
+      expect(direct.buffer.equals(composed.buffer)).toBe(true);
+      expect(direct.fileCount).toBe(composed.fileCount);
+
+      const zip = new AdmZip(direct.buffer);
+      const entries = zip.getEntries().map((e) => e.entryName);
+      expect(entries).toEqual(expect.arrayContaining(["index.html", "clip.mp4"]));
+      expect(entries.some((e) => e.startsWith("_proxy/"))).toBe(false);
+      expect(zip.readFile("clip.mp4")?.equals(originalVideo)).toBe(true);
+      expect(zip.readAsText("index.html")).toContain('src="clip.mp4"');
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+});
+
 describe("localizeExternalAssets", () => {
   it("copies external src/href assets and rewrites HTML paths", () => {
     const result = localizeSingleAsset("logo.png", "PNG_DATA", (rel) =>

packages/cli/src/utils/publishProject.ts

@@ -254,18 +254,44 @@ function rewriteCssUrls(
   return { css: rewritten, modified };
 }
 
-function rewriteHtmlAttributes(
-  ctx: ExternalAssetContext,
+/** Resolves a raw attribute value (plus the referrer's absolute directory) to
+ * the archive path it should point at, or `null` to leave it untouched. */
+export type HtmlAttributeResolver = (rawValue: string, referrerAbsDir: string) => string | null;
+
+interface RewriteHtmlAttributesOptions {
+  /** Attributes to inspect (default: src + href, matching the external-asset
+   * localization use case below). */
+  attrs?: string[];
+  /** CSS selector narrowing which elements are inspected (default: derived
+   * from `attrs`, e.g. `"[src], [href]"`). Callers that only care about one
+   * tag (e.g. `<video>`) pass something like `"video[src]"`. */
+  selector?: string;
+}
+
+/**
+ * Walk every element matching `selector` (default: anything with `src`/
+ * `href`) and rewrite the given `attrs` whose value `resolveTarget` maps to an
+ * archive path. Shared by `localizeHtmlEntry` below (external-asset
+ * localization) and `publishProxyBake.ts` (proxy baking only rewrites
+ * `<video src>`), so the rewrite mechanics (attribute walk + entry-relative
+ * path rewrite) live in one place while each caller supplies its own
+ * resolution rule.
+ */
+export function rewriteHtmlAttributes(
   document: Document,
   referrerAbsDir: string,
   entryPath: string,
+  resolveTarget: HtmlAttributeResolver,
+  options: RewriteHtmlAttributesOptions = {},
 ): boolean {
+  const attrs = options.attrs ?? ["src", "href"];
+  const selector = options.selector ?? attrs.map((attr) => `[${attr}]`).join(", ");
   let modified = false;
-  for (const el of document.querySelectorAll("[src], [href]")) {
-    for (const attr of ["src", "href"]) {
+  for (const el of document.querySelectorAll(selector)) {
+    for (const attr of attrs) {
       const val = (el.getAttribute(attr) || "").trim();
       if (!val) continue;
-      const archivePath = tryResolveExternal(ctx, val, referrerAbsDir);
+      const archivePath = resolveTarget(val, referrerAbsDir);
       if (!archivePath) continue;
       el.setAttribute(attr, posix.relative(posix.dirname(entryPath), archivePath));
       modified = true;
@@ -305,7 +331,9 @@ function rewriteStyleBlocks(
 function localizeHtmlEntry(ctx: ExternalAssetContext, entryPath: string, content: Buffer): void {
   const referrerAbsDir = resolve(ctx.absProjectDir, dirname(entryPath));
   const { document } = parseHTML(content.toString("utf-8"));
-  const attrsChanged = rewriteHtmlAttributes(ctx, document, referrerAbsDir, entryPath);
+  const attrsChanged = rewriteHtmlAttributes(document, referrerAbsDir, entryPath, (val, dir) =>
+    tryResolveExternal(ctx, val, dir),
+  );
   const stylesChanged = rewriteStyleBlocks(ctx, document, referrerAbsDir, entryPath);
   if (attrsChanged || stylesChanged) {
     ctx.fileContents.set(entryPath, Buffer.from(document.toString(), "utf-8"));
@@ -350,7 +378,14 @@ export function localizeExternalAssets(
   return ctx.externalMap.size;
 }
 
-export function createPublishArchive(projectDir: string): PublishArchiveResult {
+/**
+ * Walk the project dir, read every non-ignored file, and localize external
+ * (out-of-project) asset references. Returns the in-memory archive file map —
+ * the seam `publish.ts` hooks a proxy-baking transform into (U6) between this
+ * and `zipPublishFileMap` below. `cloud render` never sees this seam: it
+ * keeps calling `createPublishArchive` directly.
+ */
+export function buildPublishFileMap(projectDir: string): Map<string, Buffer> {
   const absProjectDir = resolve(projectDir);
   const filePaths: string[] = [];
   collectProjectFiles(absProjectDir, absProjectDir, filePaths);
@@ -364,7 +399,12 @@ export function createPublishArchive(projectDir: string): PublishArchiveResult {
   }
 
   localizeExternalAssets(absProjectDir, fileContents);
+  return fileContents;
+}
 
+/** Zip an in-memory archive file map (from `buildPublishFileMap`, optionally
+ * transformed in between, e.g. by proxy baking) into the final archive buffer. */
+export function zipPublishFileMap(fileContents: Map<string, Buffer>): PublishArchiveResult {
   const archive = new AdmZip();
   for (const [filePath, content] of fileContents) {
     archive.addFile(filePath, content);
@@ -376,6 +416,17 @@ export function createPublishArchive(projectDir: string): PublishArchiveResult {
   };
 }
 
+/**
+ * Thin composition of `buildPublishFileMap` + `zipPublishFileMap` — signature
+ * and behavior UNCHANGED from before the U6 split. `cloud render`
+ * (`commands/cloud/render.ts`, `maybeUploadProject`) calls this directly and
+ * must stay byte-identical (never see baked proxies); only `publish.ts` calls
+ * the two halves separately with a baking transform in between.
+ */
+export function createPublishArchive(projectDir: string): PublishArchiveResult {
+  return zipPublishFileMap(buildPublishFileMap(projectDir));
+}
+
 export function getPublishApiBaseUrl(): string {
   return (
     process.env["HYPERFRAMES_PUBLISHED_PROJECTS_API_URL"] ||
@@ -513,6 +564,14 @@ export interface PublishOptions {
   projectId?: string;
   /** Shared team space id, sent as X-Space-Id so team members converge. Only when authenticated. */
   spaceId?: string;
+  /**
+   * Pre-built archive to upload instead of building one fresh from
+   * `projectDir` via `createPublishArchive`. `publish.ts` passes this so it
+   * can bake proxies into the file map between `buildPublishFileMap` and
+   * `zipPublishFileMap` (U6); callers that omit it (e.g. `feedback`'s
+   * minimal-repro publish) keep today's behavior unchanged.
+   */
+  archive?: PublishArchiveResult;
 }
 
 export async function publishProjectArchive(
@@ -521,7 +580,7 @@ export async function publishProjectArchive(
 ): Promise<PublishedProjectResponse> {
   const isPublic = opts.public === true;
   const title = basename(projectDir);
-  const archive = createPublishArchive(projectDir);
+  const archive = opts.archive ?? createPublishArchive(projectDir);
   const apiBaseUrl = getPublishApiBaseUrl();
   const credential = await tryResolveCredential();
   const authHeaders = credential ? buildAuthHeaders(credential) : {};

packages/cli/src/utils/publishProxyBake.test.ts

@@ -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);
+  });
+});

packages/cli/src/utils/publishProxyBake.ts

@@ -0,0 +1,170 @@
+/**
+ * Publish-time proxy baking (U6 of
+ * docs/plans/2026-07-14-002-feat-transparent-media-proxies-plan.md).
+ *
+ * Published pages are static (no server), so the on-demand `?hf-proxy=h264`
+ * negotiation the preview/play surfaces use (U3/U4) isn't possible there.
+ * Instead this scans the archive's HTML entries for local `<video src>`
+ * references to browser-hostile codecs (HEVC, ProRes, ...), transcodes each
+ * one via the shared studio-server proxy transcoder, adds the proxy bytes to
+ * the archive under a `_proxy/` prefix, and rewrites ONLY the matching
+ * `<video src>` attributes in the archive's HTML copies to point at the
+ * proxy.
+ *
+ * `<audio>` elements are never rewritten: verified (per the plan's Key
+ * Technical Decisions) that AAC demuxes fine from an HEVC container in an
+ * HEVC-less browser, so an `<audio>` sharing a hostile video's src plays the
+ * original untouched. On-disk project files are never modified — only the
+ * in-memory archive file map passed in by `publish.ts` (built via
+ * `buildPublishFileMap`, baked here, then zipped via `zipPublishFileMap`).
+ * `cloud render` never calls this: it uses `createPublishArchive` directly,
+ * which has no baking hook (R2 in the plan).
+ *
+ * Alpha-bearing sources remain explicit skips because H.264 would destroy
+ * transparency. A failed opaque-hostile transcode aborts publish with a
+ * structured manifest rather than silently shipping an unplayable asset.
+ */
+
+import { readFile } from "node:fs/promises";
+import { basename, dirname, resolve } from "node:path";
+import { parseHTML } from "linkedom";
+import { rewriteAssetPath } from "@hyperframes/parsers/asset-paths";
+import {
+  cleanAssetUrl,
+  isRemoteOrInlineUrl,
+  resolveLocalAssetCandidates,
+} from "@hyperframes/parsers/asset-resolution";
+import {
+  scanProjectMediaCodecMap,
+  type HtmlSourceLike,
+} from "@hyperframes/studio-server/media-codec-map";
+import {
+  ProxyTranscodeError,
+  resolveProxy,
+  waitForProxy,
+  TRANSCODE_TIMEOUT_MS,
+} from "@hyperframes/studio-server/proxy-transcoder";
+import { rewriteHtmlAttributes } from "./publishProject.js";
+
+/** Archive-path prefix for baked proxy files, mirroring `localizeExternalAssets`'s `_ext/`. */
+export const PROXY_ARCHIVE_PREFIX = "_proxy";
+
+export interface ProxyBakeManifest {
+  proxied: string[];
+  skippedAlpha: string[];
+  failed: Array<{ path: string; error: string }>;
+}
+
+class ProxyBakeError extends Error {
+  readonly manifest: ProxyBakeManifest;
+
+  constructor(manifest: ProxyBakeManifest) {
+    const summary = manifest.failed.map((entry) => `${entry.path}: ${entry.error}`).join("; ");
+    super(`Unable to bake required browser media proxies (${summary})`);
+    this.name = "ProxyBakeError";
+    this.manifest = manifest;
+  }
+}
+
+function emptyManifest(): ProxyBakeManifest {
+  return { proxied: [], skippedAlpha: [], failed: [] };
+}
+
+function isHtmlEntry(path: string): boolean {
+  return path.endsWith(".html") || path.endsWith(".htm");
+}
+
+/**
+ * Mutates `fileContents` in place: adds a `_proxy/<hash>.mp4` entry for every
+ * browser-hostile local video asset referenced from the archive's HTML, and
+ * rewrites those HTML entries' matching `<video src>` attributes to point at
+ * the proxy. Returns a structured manifest; throws ProxyBakeError when any
+ * required opaque proxy cannot be prepared.
+ */
+export async function bakeMediaProxies(
+  projectDir: string,
+  fileContents: Map<string, Buffer>,
+): Promise<ProxyBakeManifest> {
+  const manifest = emptyManifest();
+  const absProjectDir = resolve(projectDir);
+  const htmlEntries = [...fileContents.entries()].filter(([path]) => isHtmlEntry(path));
+  if (htmlEntries.length === 0) return manifest;
+
+  const htmlSources: HtmlSourceLike[] = htmlEntries.map(([entryPath, content]) => ({
+    html: content.toString("utf-8"),
+    compSrcPath: entryPath,
+  }));
+
+  const codecMap = await scanProjectMediaCodecMap(absProjectDir, htmlSources);
+  const hostileEntries = Object.entries(codecMap).filter(([, facts]) => facts.browserHostile);
+  const hostilePathnames: string[] = [];
+  for (const [pathname, facts] of hostileEntries) {
+    if (facts.hasAlpha) {
+      // Alpha sources are never proxied: an H.264 proxy would destroy the
+      // transparency (e.g. ProRes 4444 alpha). Keep the original in place.
+      manifest.skippedAlpha.push(pathname);
+      continue;
+    }
+    hostilePathnames.push(pathname);
+  }
+  if (hostilePathnames.length === 0) return manifest;
+
+  // Absolute source path -> archive path of its baked proxy. Built by
+  // resolving each map key back to an absolute path the same way
+  // `compositionServer.ts`'s `injectMediaCodecMap` does, since the map is
+  // keyed by project-root-relative URL pathname (per the plan's KTD), not a
+  // filesystem path.
+  const proxyByAbsolutePath = new Map<string, string>();
+
+  await Promise.all(
+    hostilePathnames.map(async (pathname) => {
+      const absoluteSourcePath = resolve(absProjectDir, pathname.replace(/^\/+/, ""));
+      try {
+        const proxyPath = await waitForProxy(
+          resolveProxy(absProjectDir, absoluteSourcePath),
+          TRANSCODE_TIMEOUT_MS,
+        );
+        const archivePath = `${PROXY_ARCHIVE_PREFIX}/${basename(proxyPath)}`;
+        fileContents.set(archivePath, await readFile(proxyPath));
+        proxyByAbsolutePath.set(absoluteSourcePath, archivePath);
+        manifest.proxied.push(pathname);
+      } catch (err) {
+        const reason = err instanceof ProxyTranscodeError ? err.message : String(err);
+        manifest.failed.push({ path: pathname, error: reason });
+      }
+    }),
+  );
+
+  manifest.proxied.sort();
+  manifest.skippedAlpha.sort();
+  manifest.failed.sort((a, b) => a.path.localeCompare(b.path));
+  if (manifest.failed.length > 0) throw new ProxyBakeError(manifest);
+  if (proxyByAbsolutePath.size === 0) return manifest;
+
+  for (const [entryPath, content] of htmlEntries) {
+    const { document } = parseHTML(content.toString("utf-8"));
+    const referrerAbsDir = resolve(absProjectDir, dirname(entryPath));
+    const modified = rewriteHtmlAttributes(
+      document,
+      referrerAbsDir,
+      entryPath,
+      (rawValue) => {
+        const cleaned = cleanAssetUrl(rawValue);
+        if (!cleaned || isRemoteOrInlineUrl(cleaned)) return null;
+        // Resolve the raw attribute value the same way the scan did
+        // (rewriteAssetPath to root-relative, then decodeUrlPathVariants via
+        // resolveLocalAssetCandidates) so percent-encoded and root-absolute
+        // srcs match the map keys the scan produced.
+        const rootRelativeSrc = rewriteAssetPath(entryPath, cleaned);
+        for (const candidate of resolveLocalAssetCandidates(absProjectDir, rootRelativeSrc)) {
+          const archivePath = proxyByAbsolutePath.get(candidate);
+          if (archivePath) return archivePath;
+        }
+        return null;
+      },
+      { selector: "video[src]", attrs: ["src"] },
+    );
+    if (modified) fileContents.set(entryPath, Buffer.from(document.toString(), "utf-8"));
+  }
+  return manifest;
+}