fix(producer): render servers only load assets from inside the project - #7579

What

Render servers (the producer HTTP handlers) and the distributed planner now load assets only from inside the project they are asked to render. Local hyperframes render, --start/--end range renders, hyperframes benchmark and Studio renders keep importing outside files such as ../shared/logo.png exactly as before.

Why

When markup points at a file outside the project directory, the compiler copies it into the render and serves it to the page. That is the right behaviour for a local render of your own project, which often shares a logo or font folder with sibling projects. A render service, though, should only read the project it was handed, so the producer needs a way to tell the two apart, with the service path as the default.

Related work

None.

How

• New opt-in, allowOutsideProjectAssets, on RenderConfig, CompileForRenderOptions and the planner options (plan() / buildLocalExecutionPlan). It is off by default. It is deliberately not a field on the serializable render request or DistributedRenderConfig: renderConfigFromRequest takes it as a runtime argument and sets it explicitly, so request JSON cannot turn it on.
• With it off:
  • no hf-ext/ copies are recorded;
  • an entry file or sub-composition that leads outside the project once symlinks are resolved is refused with "outside the project folder", the same as a ../ sub-composition already is. This covers the pre-flight check, the sub-composition compile and the inliner, and the entry read in the compile stage and in compileForRender;
  • compile-time media probes, GIF/HEIC prep and local font embedding skip any path that leaves the project once symlinks are resolved. The compile-time advice no longer probes a file that does not exist;
  • the compile and probe stages treat as missing any composition video, audio or image whose source resolves outside the project dir, the compiled dir or the render's own download dir. That includes absolute paths, file: URLs, ../ and percent-encoded ..%2F paths, and symlinks. A warning names each one as a missing source, and it never reaches ffprobe or ffmpeg. The frame extractor, audio mixer, media-type preflight, HDR probes and video-layer passthrough all read these filtered entries, and the check also covers sources a page script sets at runtime. Remote media fetched during the render still works;
  • the render file server checks project files by real path (compiled files stay lexical, since extracted-frame directories are linked in);
  • the planner's project copy skips symlinks that lead outside the project.
• Trusted callers pass true: the CLI local render and range render, hyperframes benchmark, the CLI Studio server render and the Vite Studio adapter render. The HTTP handlers, planV2 / planV2WithPublisher and the cloud adapters pass nothing.
• The regression harness reads renderConfig.allowOutsideProjectAssets from a fixture's meta.json. render-symlinked-assets sets it, because that fixture's src/shared link to a sibling folder is the trusted local case it exists to keep working.
• Preview bundling (bundleToSingleHtml) already inlines only real-path project files and is unchanged.
• Package size: the @hyperframes/producer unpacked budget goes from 3,165,274 to 3,210,000 bytes.
  • The tarball grows about 12.5 KB unpacked over main, all in shipped source. The new checks live in the compiler and render stages, and the index, public-server and distributed bundles each include those, at about 3.5 KB per bundle, plus typings.
  • main itself was within 400 bytes of the 1% tolerance.
  • No test files ship in the package.

No visible change

The one Studio line (packages/studio/vite.adapter.ts) passes the new opt-in, so Studio renders keep importing outside files exactly as before. Nothing on screen changes.

Test plan

• Unit tests added/updated
  • New outsideProjectAssets.test.ts. Every node:child_process call is recorded, and the media files outside the project are real clips, so a probe or extraction of one would succeed and be visible.
    • In-process default: the project reaches outside files through <img src="../…">, a <style> url(), an inline-style url(), a project symlink, and video/audio sources given as an absolute path, a file: URL, ../ and ..%2F.
      • There is no hf-ext/ entry, and the file server returns 404 for each path.
      • Each outside media element is reported as a missing source, and no recorded ffprobe/ffmpeg call names an outside file.
      • An https video in the same composition is still downloaded and its frames extracted.
    • Plan v2 default: no artifact carries hf-ext or the outside image, no ffprobe/ffmpeg call names an outside file, the remote clip is published, and a materialized chunk's file server returns 404.
    • A sub-composition symlinked to a file outside the project, and an entry index.html symlinked the same way, are refused both in-process and by Plan v2.
    • Trusted opt-in: the in-process compile and plan() still import outside files, and the symlinked sub-composition is compiled in.
  • Mutation checks:
    • Reverting all producer source to main fails the four default tests, and the opt-in test still passes.
    • Each guard reverted alone fails the test that covers it: the file server check, the media drop, the plan copy filter, the compile-time probe guard, the sub-composition check, and the entry checks.
  • The fileServer.test.ts symlinked-directory test now passes the opt-in and also checks for a 404 by default. The probeStage.test.ts fixture uses an existing project dir.
• Manual testing performed
  • Ran a full in-process render (executeRenderJob, headless Chrome) of a composition whose only image is ../shared/logo.png, a solid red PNG. With the opt-in, the output frame is red (253,0,0). Without it, the frame is black.
  • Ran the render-symlinked-assets regression fixture locally in-process and distributed-simulated.
    • With the flag, shared/brand.css loads and the frame matches the golden's layout.
    • Without the flag, the stylesheet 404s and PSNR drops to 6.4.
    • Off the regression Docker image, both this branch and unmodified main score 20.77 dB on this host because of system fonts. CI's image is the reference.
  • Typecheck passes for producer, cli and studio.
  • Related producer, cli and studio suites pass. The only failures seen were 60s/5s timeouts under host load. They also fail on unmodified main here, or pass when re-run alone.
• Documentation updated (if applicable)
• Comments follow CONTRIBUTING.md "Comments": they say why, not what, and a bug fix says what the code must do and how to reproduce the bug

— Rames Jusso

🤖 Generated with Claude Code