From 8c1b6c515401a03e1a8394cff60b4e7410f14f0d Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Miguel=20=C3=81ngel?= <miguel.sierra@heygen.com>
Date: Fri, 17 Jul 2026 03:01:56 -0400
Subject: [PATCH] docs(media): document automatic proxying for hostile codecs
 (#2596)

* docs(media): document automatic proxying for hostile codecs

Describes the shipped behavior: which input codecs render, that live preview
auto-proxies what the browser cannot decode, where the cache lives, and how to
turn it off. Carries the skills notes and the hardening design documents.

* docs(media): align proxy guidance with runtime
---
 docs/guides/rendering.mdx                     |   4 +-
 docs/guides/troubleshooting.mdx               |  12 +-
 ...7-16-transparent-proxy-hardening-design.md | 128 ++++++++++++++++++
 packages/lint/src/hevcPreviewLint.ts          |   8 +-
 packages/lint/src/project.test.ts             |   2 +-
 skills-manifest.json                          |   4 +-
 .../references/variables-and-media.md         |   2 +-
 skills/media-use/SKILL.md                     |   9 +-
 8 files changed, 149 insertions(+), 20 deletions(-)
 create mode 100644 docs/superpowers/specs/2026-07-16-transparent-proxy-hardening-design.md

diff --git a/docs/guides/rendering.mdx b/docs/guides/rendering.mdx
index 7427b0e18..d46deb99e 100644
--- a/docs/guides/rendering.mdx
+++ b/docs/guides/rendering.mdx
@@ -166,9 +166,9 @@ Video assets referenced by a composition (a `<video src="...">` clip) are decode
 - VP8 / VP9 and ProRes 4444 (with alpha; see [Transparent Video](#transparent-video))
 - HDR sources (HLG / PQ) are tone-mapped for SDR renders; see the [HDR guide](/guides/hdr)
 
-The one caveat is **live preview**: `preview`, `play`, Studio, and published player pages play the file in a real browser, so playback there depends on that browser's codec support. Chrome (107+), Edge, and Safari hardware-decode HEVC on most modern machines; Firefox does not. If an HEVC asset shows a black frame in preview while rendering fine, generate an H.264 proxy for authoring (for example with `ffmpeg -i asset.mp4 -c:v libx264 -crf 18 proxy.mp4`, or via the media-use skill) and swap the original back in for the final render, or just keep the HEVC source, since the rendered output is unaffected.
+The one caveat is **live preview**: `preview`, `play`, Studio, and published player pages play the file in a real browser, so playback there depends on that browser's codec support. Chrome (107+), Edge, and Safari hardware-decode HEVC on most modern machines; Firefox does not. Preview handles this automatically: on first use, it transcodes the asset into a cached H.264 proxy (stored under `.transcode-cache/`, safe to delete) and serves that for playback, while render always uses the original file. `check` and `snapshot` prepare the same proxies before opening their browser phase. Publishing bakes the proxies into the published archive so static player pages work too. Opt out per command with `--no-proxy`, or project-wide by setting `media.autoProxy` to `false` in `hyperframes.json`.
 
-`hyperframes lint` emits an info-level `hevc_preview_codec` note when a composition references an HEVC video, as a reminder of this preview-only limitation.
+`hyperframes lint` emits an info-level `hevc_preview_codec` note when a composition references an HEVC video, naming the affected asset(s).
 
 ## Animated GIF
 
diff --git a/docs/guides/troubleshooting.mdx b/docs/guides/troubleshooting.mdx
index cdb4e459b..8043e64e0 100644
--- a/docs/guides/troubleshooting.mdx
+++ b/docs/guides/troubleshooting.mdx
@@ -137,15 +137,15 @@ If your issue is about a specific coding mistake (animations not working, video
   </Accordion>
 
   <Accordion title="Video asset plays black in preview but renders fine (HEVC/H.265)">
-    Rendering decodes video assets with FFmpeg, so HEVC (H.265) inputs render correctly on every platform. Live preview is different: `preview`, `play`, Studio, and published player pages play the file in your browser, and not every browser decodes HEVC (Chrome 107+, Edge, and Safari do on most modern hardware; Firefox does not).
+    Rendering decodes video assets with FFmpeg, so HEVC (H.265) inputs render correctly on every platform. Live preview is different: `preview`, `play`, Studio, and published player pages play the file in your browser, and not every browser decodes HEVC (Chrome 107+, Edge, and Safari do on most modern hardware; Firefox does not). This is now self-healing: preview detects an undecodable asset and automatically swaps in a cached H.264 proxy, so this should no longer show as a persistent black frame.
 
-    If an HEVC asset shows a black or frozen frame in preview:
+    If a hostile asset is still stuck black in preview:
 
-    1. Confirm the render itself is fine: `npx hyperframes render` output will contain the video.
-    2. For authoring, generate an H.264 proxy (`ffmpeg -i asset.mp4 -c:v libx264 -crf 18 proxy.mp4`) and point the composition at it while you iterate.
-    3. Swap the HEVC original back before the final render, or keep the proxy; both render correctly.
+    1. Confirm auto-proxying is not disabled: no `--no-proxy` flag, and `media.autoProxy` is not `false` in `hyperframes.json`.
+    2. Run `npx hyperframes doctor` to confirm ffmpeg/ffprobe are installed; the proxy transcode needs both.
+    3. Run `npx hyperframes lint --verbose`: the info-level `hevc_preview_codec` finding names every affected asset.
 
-    `npx hyperframes lint` flags HEVC assets with an info-level `hevc_preview_codec` note. See [Rendering: Input Video Codecs](/guides/rendering#input-video-codecs).
+    See [Rendering: Input Video Codecs](/guides/rendering#input-video-codecs).
   </Accordion>
 </AccordionGroup>
 
diff --git a/docs/superpowers/specs/2026-07-16-transparent-proxy-hardening-design.md b/docs/superpowers/specs/2026-07-16-transparent-proxy-hardening-design.md
new file mode 100644
index 000000000..03b9c7e4e
--- /dev/null
+++ b/docs/superpowers/specs/2026-07-16-transparent-proxy-hardening-design.md
@@ -0,0 +1,128 @@
+# Transparent Proxy Hardening Design
+
+## Context
+
+PR #2462 adds transparent authoring proxies for browser-hostile codecs. Its server-side
+FFmpeg architecture is the correct foundation: Chrome Headless Shell cannot decode HEVC
+through WebCodecs, and MediaBunny server support ultimately wraps FFmpeg through NodeAV.
+The review found lifecycle, policy, and coverage gaps that must be resolved before merge.
+
+## Goals
+
+- Preserve transparent preview recovery for hostile HEVC and ProRes media.
+- Never destroy alpha as an accidental fallback.
+- Bound CPU, memory, queue, cache, and caller wait time.
+- Apply one proxy policy consistently across scan, runtime rescue, check, and publish.
+- Make path lookup safe across Unicode/case differences without allowing project escapes.
+- Make partial publish behavior explicit and test render/publish separation with real media.
+- Preserve the existing system-FFmpeg subprocess boundary and zero new media runtime dependency.
+
+## Non-goals
+
+- Replacing FFmpeg with MediaBunny or NodeAV in this PR.
+- Proxying alpha-bearing media to opaque H.264.
+- Changing final render inputs or silently publishing incomplete hostile-media coverage.
+
+## Architecture
+
+### 1. Canonical project media identity
+
+Create one resolver used by codec-map lookup and proxy resolution:
+
+1. Resolve the authored path exactly first.
+2. Build a project-relative index normalized to POSIX separators, Unicode NFC, and lowercase.
+3. Use the normalized fallback only when it maps to exactly one file; ambiguous case/Unicode
+   collisions fail explicitly.
+4. Resolve symlinks with real paths and reject any source outside the real project root.
+
+The codec map stores canonical relative identities so scan and runtime rescue cannot disagree.
+
+### 2. One alpha-aware proxy policy
+
+Centralize the decision into a single policy function consumed by:
+
+- initial scan and prewarm,
+- mapped runtime recovery,
+- unlisted/runtime rescue,
+- check-browser recovery,
+- publish bake.
+
+Unknown/unlisted media is probed before transcoding. Alpha-bearing media is returned as an
+explicit unsupported result and is never sent through the opaque H.264 proxy path. Browser-safe
+mapped media follows the same policy at every runtime fallback tier.
+
+### 3. Bounded transcode lifecycle
+
+- Keep the two-process transcode semaphore.
+- Add a bounded wait queue and a typed overload error mapped to HTTP 503 plus Retry-After.
+- Deduplicate in-flight work by canonical cache key.
+- Cache transient failures only for a short TTL; keep FFmpeg-unavailable recoverable immediately.
+- Give publish/check callers explicit bounded waits. Caller timeout does not cancel shared work;
+  it returns a typed timeout while the deduplicated transcode may finish and warm the cache.
+- Preserve subprocess timeout/SIGKILL and atomic temp-then-rename behavior.
+
+### 4. Bounded cache
+
+Maintain cache metadata from file stat data and sweep opportunistically at a rate-limited cadence.
+Defaults:
+
+- 30-day maximum idle age,
+- 10 GiB maximum total size,
+- oldest-accessed entries removed first,
+- active/in-flight entries excluded,
+- stale temp files removed separately.
+
+Environment/config overrides allow constrained machines to lower the cap. Cache cleanup failures
+are warnings, never preview failures.
+
+### 5. Complete CLI/config plumbing
+
+Carry the resolved proxy setting through regular preview, dev, local-studio, and static server
+spawn paths. Both positive and negative CLI flags override config consistently. Add contract tests
+that exercise the final staticProjectServer arguments instead of only parser-level values.
+
+### 6. Explicit publish outcome
+
+Publish bake returns a structured manifest containing proxied, intentionally skipped, and failed
+assets. Hostile non-alpha failures stop publish with the asset list; alpha skips remain explicit.
+Callers surface the manifest in diagnostics so an incomplete publish cannot become a silent black
+frame. Final render/cloud-render archive creation remains on the original-media path.
+
+### 7. Regression coverage
+
+Tests must cover:
+
+- unlisted alpha rescue never invoking H.264 transcode,
+- transient failure expiry,
+- queue overload and HTTP 503 mapping,
+- case/Unicode fallback plus ambiguity rejection,
+- symlink/project containment,
+- publish/check caller timeout,
+- complete proxy flag forwarding,
+- cache size/age eviction while preserving in-flight entries,
+- publish manifest behavior,
+- reactive/tertiary policy parity,
+- bounded probe caches and global probe concurrency,
+- preview-script escaping,
+- a real hostile-codec fixture proving publish bake changes authoring archives while
+  render/cloud-render archives remain byte-identical and proxy-free.
+
+## Alternatives
+
+### Explicit pre-bake only
+
+This removes on-demand queueing but loses transparent cold-preview recovery. Rejected because it
+regresses the core authoring experience #2462 is meant to provide.
+
+### MediaBunny replacement or hybrid
+
+Browser MediaBunny inherits WebCodecs HEVC limits; its ProRes path adds a WASM extension and its
+server path adds NodeAV native bindings over FFmpeg. It would remove little application lifecycle
+code while weakening subprocess isolation. Rejected for this PR; a metadata-only spike can be
+evaluated independently later.
+
+## Rollout and merge gate
+
+The material head requires fresh adversarial review from Via and Rames, all required CI green,
+mergeable/dependency-clean state, and no unresolved human feedback. Skill-facing files already in
+the PR require Wenbo and Miao visibility before merge.
diff --git a/packages/lint/src/hevcPreviewLint.ts b/packages/lint/src/hevcPreviewLint.ts
index 0dcf0a15e..1ac6dc07e 100644
--- a/packages/lint/src/hevcPreviewLint.ts
+++ b/packages/lint/src/hevcPreviewLint.ts
@@ -145,12 +145,12 @@ export async function lintHevcPreviewCodec(
       message:
         `Video file(s) use the HEVC/H.265 codec: ${unique.join(", ")}. ` +
         "The render pipeline pre-decodes video with FFmpeg and never uses the browser's video decoder, so these render correctly. " +
-        "Live preview/player playback requires a browser with HEVC support. " +
-        "If preview playback fails, generate an H.264 proxy (e.g. via the media-use skill) and reference that instead.",
+        "Live preview/player playback automatically uses a cached H.264 proxy when the browser cannot decode HEVC. " +
+        "If playback still fails, verify ffmpeg/ffprobe are installed and auto-proxying is enabled.",
       fixHint:
         unique.length === 1
-          ? `Generate an H.264 proxy for "${unique[0]}" (e.g. via the media-use skill) if it fails to play in preview.`
-          : "Generate H.264 proxies for these files (e.g. via the media-use skill) if they fail to play in preview.",
+          ? `If "${unique[0]}" fails to play in preview, run hyperframes doctor and confirm media.autoProxy is not false.`
+          : "If these files fail to play in preview, run hyperframes doctor and confirm media.autoProxy is not false.",
     },
   ];
 }
diff --git a/packages/lint/src/project.test.ts b/packages/lint/src/project.test.ts
index ca20318f1..64440e8e6 100644
--- a/packages/lint/src/project.test.ts
+++ b/packages/lint/src/project.test.ts
@@ -323,7 +323,7 @@ describe("hevc_preview_codec", () => {
     expect(findings[0]?.severity).toBe("info");
     expect(findings[0]?.code).toBe("hevc_preview_codec");
     expect(findings[0]?.message).toContain("clip.mp4");
-    expect(findings[0]?.message).toContain("requires a browser with HEVC support");
+    expect(findings[0]?.message).toContain("automatically uses a cached H.264 proxy");
     expect(result.totalErrors).toBe(0);
     expect(result.results[0]?.result.ok).toBe(true);
   });
diff --git a/skills-manifest.json b/skills-manifest.json
index 4982b60c9..805f723b3 100644
--- a/skills-manifest.json
+++ b/skills-manifest.json
@@ -30,7 +30,7 @@
       "files": 11
     },
     "hyperframes-core": {
-      "hash": "546d4b1a0f0a8440",
+      "hash": "fa201c126c87fd89",
       "files": 17
     },
     "hyperframes-creative": {
@@ -46,7 +46,7 @@
       "files": 10
     },
     "media-use": {
-      "hash": "36630c2bb9d281da",
+      "hash": "b036210167a3ca39",
       "files": 133
     },
     "motion-graphics": {
diff --git a/skills/hyperframes-core/references/variables-and-media.md b/skills/hyperframes-core/references/variables-and-media.md
index 874d2aeac..4a4319110 100644
--- a/skills/hyperframes-core/references/variables-and-media.md
+++ b/skills/hyperframes-core/references/variables-and-media.md
@@ -106,4 +106,4 @@ Video elements must be muted and inline. Audio must be a separate `<audio>` elem
 
 For media duration: `<video>` and `<audio>` can omit `data-duration` if the media's intrinsic length is known and you want the full clip. Otherwise provide `data-duration` explicitly.
 
-Input codecs: render decodes video via FFmpeg (frames are pre-extracted and injected), so HEVC/H.265 assets (8/10-bit) render correctly everywhere; only live preview depends on the browser's codec support (`lint` emits an info-level `hevc_preview_codec` note; use an H.264 proxy for authoring if preview shows black).
+Input codecs: render decodes video via FFmpeg (frames are pre-extracted and injected), so HEVC/H.265 assets (8/10-bit) render correctly everywhere; live preview auto-proxies any browser-hostile asset (transcodes and caches an H.264 copy on first use, opt out with `--no-proxy` or `media.autoProxy: false`), and `lint` emits an info-level `hevc_preview_codec` note naming affected assets.
diff --git a/skills/media-use/SKILL.md b/skills/media-use/SKILL.md
index 39273b215..91a3e7e96 100644
--- a/skills/media-use/SKILL.md
+++ b/skills/media-use/SKILL.md
@@ -393,10 +393,11 @@ with `resolve --from <output> --type <type>` so it joins the ledger + global
 cache.
 
 HEVC/H.265 sources need no conversion for **render** (FFmpeg pre-decodes all
-input video); only live preview depends on the browser's codec support. If an
-HEVC asset previews black, make an H.264 authoring proxy (`ffmpeg -i in.mp4
--c:v libx264 -crf 18 proxy.mp4`), register it with `resolve --from`, and keep
-either file for the final render.
+input video) or for **preview** (auto-proxy transcodes and caches an H.264
+copy on first use, disable with `--no-proxy` or `media.autoProxy: false` in
+hyperframes.json). A manual H.264 proxy via `ffmpeg -i in.mp4 -c:v libx264
+-crf 18 proxy.mp4`, registered with `resolve --from`, remains available for
+edge cases (e.g. auto-proxy disabled, or ffmpeg unavailable at preview time).
 
 ## CLI tools used (what to run, and how to enable each)