[miguel-heygen]

What

A render now downloads each remote video or audio file once instead of twice. Compile gets faster by one download of every remote clip.

Why

Compile fetched each remote media URL two times:

1. The duration probe (resolveMediaDuration) downloaded it into the render's download folder.
2. Remote-media localisation then downloaded it again into _remote_media/ under that folder, so the composition can point at a local copy.

downloadToTemp reuses a finished download only when both the URL and the destination folder match, so the second request never hit the first file.

Why under 100 lines

One lever: the duration probe downloads into the folder localisation already uses, so the existing download cache serves the second request. The rest is the test.

Related work

Refs #5945.

How

resolveMediaDuration downloads remote media into join(downloadDir, REMOTE_MEDIA_SUBDIR), the folder localisation uses. Nothing else changes: the probe still reads the same file, localisation still rewrites the same relative paths.

Test plan

• Unit test added: htmlCompiler.remoteDownloadOnce.test.ts compiles a composition with one remote video and checks that every download request for it names the same folder (the download cache's key).
• Fails without the fix: htmlCompiler.remoteDownloadOnce.test.ts > asks for a remote video in one folder for both its duration probe and its localisation (expected 2 to be 1 with only the test applied).
• tsc --noEmit (producer) exit 0; htmlCompiler.test.ts 170 passed, htmlCompiler.probeCount.test.ts 1 passed; comment ratchet passes; oxfmt and oxlint clean.
• Manual testing performed: before/after on the real CLI (below).
• Documentation updated (not applicable)
• Comments follow CONTRIBUTING.md "Comments"

Before / after

Published hyperframes@0.8.210 vs the same bundle with only this change. Apple M4 Pro (14 cores, 24 GB), hyperframes render on repo fixtures with one remote video, interleaved, 5 runs each, medians. Peak RSS is the whole process tree.

fixture	compile	wall	peak RSS	output
style-11-prod, 1080x1920, 14 s	3.8 -> 2.0 s	14.13 -> 12.33 s (-12.7%)	2,876 -> 2,882 MB	byte-identical (same sha256, all 10 runs)
overlay-montage-prod + one mix-blend layer, 42 s	10.7 -> 4.9 s	34.04 -> 29.22 s (-14.2%)	4,136 -> 4,147 MB	within this fixture's own run-to-run variation

Every stage after compile is unchanged (wall minus compile: 10.33 -> 10.11 s and 24.56 -> 24.32 s). The saving scales with the size of the remote media and the network.

[github-actions]

Edit accuracy: accurate 271 (base branch 271), smooth 118 of those

The gate passes.
Smoothness is reported in the artifact, not gated. A case fails only if it fails 2 of 3 runs.

Quarantined, measured but not gated (0)

Unstable (3)

• seqplainkeys-none-center-r0-root-z100: tracking 0.06, pressJump 0, drop 0, reload 0, render 0.03, renderKey -, undo false, teleport true / tracking 0.06, pressJump 0, drop 0, reload 0, render 0.03, renderKey -, undo true, teleport true / tracking 0.06, pressJump 0, drop 0, reload 0, render 0.03, renderKey -, undo true, teleport true
• seqplainkeys-none-px-r0-root-z100: tracking 0.06, pressJump 0, drop 0, reload 0, render 0.03, renderKey -, undo false, teleport true / tracking 0.06, pressJump 0, drop 0, reload 0, render 0.03, renderKey -, undo true, teleport true / tracking 0.06, pressJump 0, drop 0, reload 0, render 0.03, renderKey -, undo true, teleport true
• seqplainkeys-none-pct-r0-root-z100: tracking 0.06, pressJump 0, drop 0, reload 0, render 0.03, renderKey -, undo false, teleport true / tracking 0.06, pressJump 0, drop 0, reload 0, render 0.03, renderKey -, undo true, teleport true / tracking 0.06, pressJump 0, drop 0, reload 0, render 0.03, renderKey -, undo true, teleport true

[heygengenesis]

Verdict: APPROVE · 0 blocker · 0 important · 0 nits · head 68e98d1e

Probe and localisation now call downloadToTemp with the same url\0destDir key, so localisation is a cache hit. They run in sequence, so there's no in-flight race. Every compileHtmlFile/localize* call gets the same downloadDir, and resolvedPath from the probe is not read. Checked locally: the new test fails on main's htmlCompiler.ts (expected 2 to be 1) and passes here. htmlCompiler.test.ts passes 170/170. CI is green at this head.