[miguel-heygen]

Context

npx hyperframes render fails to load assets and produces all-black video. Root causes:

1. CDN scripts (GSAP, Lottie) are left as <script src="https://..."> in compiled HTML — the headless browser must fetch them over the network, which fails in Docker, CI, and firewalled environments
2. Assets referenced from outside the project directory (e.g. ../shared-assets/hero.png) 404 because the file server only serves from projectDir
3. When GSAP fails to load, the timeline never registers, all .clip elements stay visibility: hidden, and every frame is black — with no diagnostic output
4. The linter reports missing_gsap_script when GSAP is bundled inline (no <script src> tag), which blocks users from working around the CDN issue

What changed

1. CDN script inlining (htmlCompiler.ts)

compileForRender now downloads all external <script src="https://..."> tags at compile time and inlines their content into the HTML. Rendering no longer needs network access.

Before	After
<script src="https://cdn.jsdelivr.net/npm/gsap@3.12.5/dist/gsap.min.js"></script> stays in HTML, browser must fetch at runtime	Script downloaded during compilation, embedded as <script>/* inlined: https://... */\n...code...</script>
Docker/CI render → net::ERR_NAME_NOT_RESOLVED → black video	Render works fully offline
No feedback when CDN fails	[Compiler] WARNING: Failed to download CDN script: ... Consider bundling it locally

2. External asset copying (htmlCompiler.ts, renderOrchestrator.ts)

After compilation, the HTML is scanned for src, href, and CSS url() references that resolve outside projectDir. These files are copied into the compiled output directory so the file server can serve them.

Before	After
background-image: url(../shared-assets/hero.png) → 404 (file server can't serve outside projectDir)	Asset detected, copied to compiled dir, path rewritten → serves correctly
<img src="../shared-assets/logo.png"> → 404	Same fix — works for all src/href attributes and CSS url()

3. Black video diagnostics (renderOrchestrator.ts)

When composition duration is 0 (which would produce a black video), the error now probes the browser for diagnostics instead of a generic message.

Before	After
Invalid composition duration: 0. Check that GSAP timelines are registered.	Composition duration is 0 — this would produce a black video.\n\nDiagnostics:\n - GSAP is not loaded — CDN script may have failed to download. Bundle GSAP locally...\n - Browser: [Browser:PAGEERROR] gsap is not defined
Asset 404s during page load silently logged	[Render] Asset load failure: ... + [WARN] Browser encountered network failures during page load

4. Linter: recognize inline GSAP (core/lint/rules/gsap.ts)

The missing_gsap_script rule now recognizes GSAP bundled inline — matching the producer's inlining comment (/* inlined: ...gsap... */), GSAP library internals (_gsScope, GreenSock), and large inline scripts (>5KB) referencing gsap.

Before	After
User inlines GSAP → linter errors with missing_gsap_script	Inline GSAP detected, no false error
Producer inlines CDN → linter errors on the compiled HTML	Producer's /* inlined: ... */ comment recognized

Test plan

• pnpm build passes
• Core tests pass (410/410, +2 new)
• Reproduced baseline failures on main: CDN scripts not inlined, external assets 404, no diagnostics
• Verified fixes: CDN script inlined, external assets copied and served, diagnostics printed
• Render with working CDN → [Compiler] Inlined CDN script: ... → render succeeds
• Render with broken CDN → [Compiler] WARNING: Failed to download CDN script + browser errors surfaced
• Render with assets outside project dir → [Compiler] Found 1 asset(s) outside project directory → assets served correctly
• Linter with inline GSAP → no missing_gsap_script false positive

[jrusso1020]

Staff Review — PR #182

Overall: Well-crafted PR that solves a real, painful user problem. Approve with minor suggestions.

What's good

• Excellent PR description — the before/after tables make it immediately clear what changed and why. This is how all PRs should be documented.
• Four cohesive fixes that address the root causes rather than papering over symptoms: CDN inlining, external asset copying, black video diagnostics, and linter updates.
• Defense-in-depth on the asset copying path — resolve() canonicalization + startsWith check in the orchestrator prevents path traversal.
• Graceful degradation — if CDN download fails, it warns instead of crashing, and the diagnostics section tells the user exactly what went wrong.
• Promise.allSettled for CDN fetches is the right choice — one failed download shouldn't block others.

Suggestions (none blocking)

1. Unit tests for inlineExternalScripts and collectExternalAssets — these are ~140 lines of new logic on the critical render path with HTML parsing, regex, filesystem access, and network fetches. htmlCompiler.ts has no test file today. Strongly recommend adding htmlCompiler.test.ts as a fast follow.

2. Wrap diagnostics page.evaluate() in try/catch — if the browser tab crashed (which could be why duration is 0), the Puppeteer error would mask the more helpful "duration is 0" message.

3. Negative linter test case — add a test confirming that a small inline script using gsap.to() without bundling the library still triggers missing_gsap_script. Ensures the new hasInlineGsap check doesn't accidentally suppress real warnings.

4. Minor nits on comments and edge case awareness flagged inline.

Verdict

The code is safe, well-structured, and directly addresses the user-reported issues from the Slack thread. The missing unit tests are a gap I'd want closed soon, but not a merge blocker given the functional testing described. Ship it. 🚢

[miguel-heygen]

Merge activity

• Apr 1, 9:15 PM UTC: @miguel-heygen merged this pull request with Graphite.