fix(engine): a render no longer decodes the videos it replaces with extracted frames - #6142

What

A render no longer starts a video decoder for each video it replaces with extracted frames. A film cut into 163 pieces from one 1080p source renders in 1.4 GB of Chrome memory instead of 6.9 GB, with identical output.

Why

For a video the renderer replaces with frames extracted by ffmpeg, the page's own decoder never supplies a pixel; the renderer already skips waiting for these videos (skipReadinessVideoIds). But the page still decoded every one: Chrome starts a parsed <video> at its default preload, and the runtime then forced preload="auto" and load() on each (preloadMedia, and the per-tick promotion in syncRuntimeMedia). Chrome keeps one decoder per element, so memory grows with the number of clips, not the number of distinct sources.

Measured on the devbox, one worker, 1280x720 output from one 1080p source, whole process tree sampled every 0.5 s (peak RSS):

About 34 MB per extra clip on main, none with the fix. The 163-clip output is the same 490 frames with the same per-frame hash before and after.

Related work

Preview already loads only media near the playhead (#4682, #5716); this is the render-side equivalent. Preview is untouched: the new behaviour needs __HF_RENDER_FRAME_VIDEO_IDS, which only a render sets.

How

• engine (renderFrameVideoHold.ts, frameCapture.ts): before any page script, the render hands the page the ids of the videos it replaces and a MutationObserver holds each at preload="none" the moment it is parsed (also for sub-compositions that add them later). It has to be at parse time: Chrome ignores a none set once the fetch has started.
• core runtime (preloadMedia.ts, media.ts): preloadMedia and the per-tick preload promotion leave those videos alone. One predicate, isRenderFrameVideo, owns the rule.

Videos the render does not replace (extraction failed, or not extracted) are not in the list and load as before, so readiness waits and native decoding are unchanged for them.

Test plan

• Failing first: preloadMedia.test.ts (a render-frame video is neither preloaded nor loaded; other videos and audio with the same id still are), media.test.ts (the per-tick sync keeps it at none), and the real-Chrome renderFrameVideoHold.browser.test.ts (listed ids parse at none at the top level, nested, and when added later; the unlisted one stays metadata). All fail against a no-op/old version and pass; core runtime 2342/2342 and the browser file 2/2, three runs in a row.
• Engine frameCapture suites 300/300; tsc --noEmit clean in core and engine; oxfmt and oxlint clean.
• Render and capture readiness: the 163-clip render reaches ready in about 1 s (unchanged), 490/490 frames identical.
• Seek and playback in preview are untouched (the id list is never set outside a render).
• Documentation updated (n/a)
• Comments follow CONTRIBUTING.md "Comments"