docs: add Hyperframes vs Remotion comparison (closes #318)

[jrusso1020]

What

Adds an honest, detailed Hyperframes vs Remotion comparison to the docs, resolving #318.

Two pieces:

1. README — short paragraph acknowledging Remotion's influence (Hyperframes is inspired by Remotion; we kept attribution comments in the source for the patterns it pioneered), a compact 6-row comparison table, and a link to the full guide.
2. Full guide at docs/guides/hyperframes-vs-remotion.mdx — the substantive write-up: why we built Hyperframes, the core React-vs-HTML decision, and eight practical-difference subsections (agent authoring, library-clock animations with a GSAP side-by-side, arbitrary HTML/CSS/JS passthrough, auto-fallback for edge primitives, React component reuse, distributed rendering, visual editing, HDR output), plus a licensing comparison and a recap.

Nav entry added in docs/docs.json under Guides, between prompting and gsap-animation.

Why

In #318, tonxxd asked for a pros/cons comparison so users could pick the right tool. Two community PRs attempted it with generic tables (#322 closed, #329 open) but we committed publicly to a core-team comparison grounded in an internal write-up — this PR is that version. It's intended to supersede #329; happy to close it with a thank-you note once this merges.

How

• Adapted verbatim-in-structure from the internal HyperFrames vs Remotion write-up.
• Honest about where Remotion wins: React component reuse, mature Lambda distributed rendering, broader community, five years of production use, careful typed APIs.
• Honest about where Hyperframes wins: HTML-first authoring, agent-native ceiling, library-clock animation correctness (the GSAP GIFs make this concrete), HTML passthrough with no JSX rewrite, visual editor over the same DOM the renderer consumes.
• Licensing section links to the Remotion license page rather than hard-coding specific pricing numbers (which can drift).
• HDR listed as supported with a link to /guides/hdr (we shipped this in v0.4.x).
• GSAP side-by-side has a softened framing — "the remainder of the render captures an empty stage" rather than "most of the output is black frames."

Test plan

• bunx oxfmt --check passes on changed files (lefthook pre-commit ran clean)

• Local preview: cd docs && mintlify dev renders both the guide and the README without errors

• GIFs referenced at https://static.heygen.ai/hyperframes-oss/docs/images/comparisons/gsap-hf.gif and gsap-remotion.gif

• Manual testing performed

• Documentation updated (if applicable)

• Unit tests added/updated — N/A (docs-only)

Pre-merge step: upload GIFs to CDN

The GSAP comparison GIFs (~800 KB total) are staged in docs/images/comparisons/ (gitignored, standard Hyperframes docs pattern). Before merging, run:

aws sso login --profile engineering-767398024897   # if SSO expired
./scripts/upload-docs-images.sh

The MDX image tags will resolve once the upload completes. Until then the guide prose reads cleanly but the two embedded GIFs will be broken images.

(I attempted the upload from my session but the SSO token had expired.)

Notes

• The guide tone was reviewed against the team's public positioning — open to edits on any line that reads too strong. Specific sections worth a pair of eyes: the agent-training-data paragraph, the Remotion Lambda framing, and the "we architected Hyperframes" closing line.
• Supersedes docs: add Hyperframes vs Remotion comparison to README #329 (community PR with a generic table). I'll comment there pointing here once this is approved.

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
hyperframes	🟢 Ready	View Preview	Apr 20, 2026, 9:50 PM

💡 Tip: Enable Workflows to automatically generate PRs for you.

[vanceingalls]

click an element, drag to reposition, edit properties in a panel

while true for captions, we should clarify this isn't the case for all elements yet

[jrusso1020]

Good catch — updated in ffc8fe4. Reframed the section so the architectural point (shared DOM as source of truth) stays intact without overclaiming current feature coverage: direct manipulation ships for captions today, with broader element coverage building out from the same foundation.