fix: address QA report P0-P2 issues for 10/10 agent experience

[miguel-heygen]

Summary

Addresses all 8 issues from the QA report to improve agent and user experience.

P0 — Must Fix

• Blank template broken captions: Removed compositions/captions.html and its reference from the blank template. Every agent (10/10) hit 404 errors during render.
• Inner-wrapper example: Added a clear structural comment in the blank template showing the correct class="clip" + inner wrapper pattern.
• Sub-composition introspection: hyperframes compositions now reads external HTML files referenced via data-composition-src and shows their real duration/element count instead of 0.0s / 0 elements.

P1 — Fix Soon

• Font mapping warnings: Now lists all mapped fonts, suggests alternatives (use a mapped font, add @font-face, install locally), and links to docs.
• Browser 404s: Non-font "Failed to load resource" 404s now prefixed with [non-blocking] instead of [Browser:ERROR].
• Render concurrency: Default workers increased from cores/2 (max 4) to cores*3/4 (max 6). Added --concurrency alias.

P2 — Nice to Have

• Transform conflict fix suggestion: gsap_css_transform_conflict now suggests exact GSAP property replacements (e.g., xPercent: -50, yPercent: -50).
• Upgrade --yes: Now actually runs the install instead of just printing the command.

Before / After

Font mapping warning

Before:

[Compiler] No deterministic font mapping for: DM Sans

After:

[Compiler] No deterministic font mapping for: DM Sans
  Mapped fonts: arial → inter, courier → jetbrains-mono, ...
  To fix, pick one:
    1. Use a mapped font name instead (see list above)
    2. Add a @font-face block in your HTML with a local or hosted font file
    3. Install the font locally on the render machine (Docker: add to Dockerfile)
    4. Add an alias to FONT_ALIASES in deterministicFonts.ts (for contributors)

Browser 404s during render

Before: [Browser:ERROR] Failed to load resource: the server responded with a status of 404
After: [non-blocking] Failed to load resource: the server responded with a status of 404

Transform conflict lint

Before: Fix: Remove the transform from CSS and use tl.fromTo...
After: Fix: Remove transform: translate(-50%, -50%) from CSS and replace with GSAP properties: xPercent: -50, yPercent: -50

Compositions command

Before:

overlay   0.0s   1920×1080   0 elements

After:

overlay   8.0s   1920×1080   2 elements ← compositions/overlay.html

Test plan

• All 422 core tests pass
• TypeScript compiles cleanly (all 4 packages)
• Full monorepo build succeeds
• hyperframes init --template blank ships without broken captions reference

[miguel-heygen]

• feat: allow clip animation + ship <hyperframes-player> web component #209
• fix: address QA report P0-P2 issues for 10/10 agent experience #208 👈 (View in Graphite)
• main

This stack of pull requests is managed by Graphite. Learn more about stacking.

[miguel-heygen]

Merge activity

• Apr 6, 4:56 PM UTC: @miguel-heygen merged this pull request with Graphite.