docs(guides): add Claude Design → Send to HyperFrames single-file import guide

[somanshreddy]

Summary

Adds a self-contained authoring guide for the "Send to HyperFrames" import path — where a Claude Design composition is sent to HeyGen as a single HTML file, imported into a hosted project, and rendered in the cloud. This is a different workflow from the existing claude-design-hyperframes.md (download-ZIP + local-CLI-render), so it's a separate guide rather than edits to that one.

Why a new guide

The Send-to path differs from download-ZIP on every axis: one self-contained HTML (not a ZIP), assets inlined as data: URIs (no sibling fonts/ tree), enhanced in HyperFrames + cloud-rendered (not local Claude Code + CLI). One doc can't teach both without contradiction — most starkly, Send-to inverts the "base64 media → use a file reference" rule into "inline everything as data: URIs."

What it covers

• The single-self-contained-HTML wire format + the composition contract the importer validates (→ 422 on failure)
• Inline-brand-assets fidelity rules; no bundled/splash-loader artifacts; keep-the-original-as-reference
• A complete, importable worked skeleton (1920×1080, 8s, 5 scenes, one shader, count-ups, correct HyperShader.init + autoAlpha toggles + window.__timelines registration)
• The animation-pattern catalog and determinism rules

It is intentionally fully self-contained (no external doc references), because the authoring agent may not reliably fetch a second URL.

Validation

Reviewed for technical accuracy and internal consistency against a known-good composition that was actually imported and rendered to a correct MP4 — verified the contract, the scene tiling (0-8s), the shader-window math, the anchor/non-anchor visibility rules, and that every catalog tween fits its scene window.

🤖 Generated with Claude Code

[mintlify]

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

Project	Status	Preview	Updated (UTC)
hyperframes	🟢 Ready	View Preview	Jul 10, 2026, 9:25 AM

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

[miga-heygen]

Review — #2131: Claude Design → Send to HyperFrames authoring guide

Pure docs PR — one new markdown file at docs/guides/claude-design-send-to-hyperframes.md. No code changes.

What I checked

Composition contract (matches framework behavior):

• data-composition-id="main" on a live root (not <template>) — correct
• Numeric data-width/data-height/data-duration on root — correct
• data-start + data-duration on each scene, tiled end-to-end — correct
• window.__timelines["main"] = tl registration — correct (CLAUDE.md: "GSAP timelines must be paused and registered on window.__timelines")
• class="clip" on scenes — correct (CLAUDE.md: "Clips need class=\"clip\"")
• Timeline paused and built synchronously — correct

Asset rules (the key differentiator from download-ZIP):

• Base64 data: URIs for fonts/images — correct for single-file import
• CDN <script src> for runtime/GSAP/shaders (not inlined) — correct
• The "no relative paths, no expiring URLs" guidance is clearly explained

Determinism rules (match the framework):

• No Date.now(), unseeded Math.random(), setInterval, setTimeout, requestAnimationFrame, repeat: -1 — all correct per CLAUDE.md

Shader transition contract:

• scenes.length === transitions.length + 1 invariant — stated clearly and correctly
• autoAlpha for non-anchor scenes, opacity for anchor scenes (HyperShader-managed) — the explanation of WHY (HyperShader blanks to opacity:0) is excellent
• First anchor needs explicit tl.set("#sN", { opacity: 1 }, start) — correct
• "One contiguous chain for first draft" simplification is pragmatic

Skeleton (importable once filled):

• Scenes tile: 0→1.6→3.2→4.8→6.4→8.0 (5 scenes × 1.6s = 8s total) ✅
• Visibility toggles match the rules: s1 visible→hidden, s2/s3 autoAlpha toggle, s4 first-anchor opacity show, s5 HyperShader-managed ✅
• Shader transition at time: 6.15 = scene boundary 6.4 minus half of duration: 0.5 (6.4 - 0.25 = 6.15) ✅
• Counter patterns use onUpdate with tl.to (deterministic) ✅

One small note (not blocking): the "banned fonts" list in section 2 is opinionated design guidance, not a technical constraint. Fine for a guide targeting Claude Design's composition quality, but it's worth knowing this is taste, not a contract the importer enforces.

Verdict

Content: clean. Thorough, well-structured guide. The self-review checklist at the end is particularly good — it maps exactly to the failure modes the importer would catch. The shader visibility explanation is the clearest I've seen.

---

Review by Miga

[vanceingalls]

Review — #2131: Claude Design → Send to HyperFrames authoring guide

Verdict: LGTM — approve. Pure docs PR, one new file at docs/guides/claude-design-send-to-hyperframes.md. All CI green (30/30). Miga has already covered the CLAUDE.md-vs-guide accuracy pass thoroughly; my audit was additive against actual source files.

Independent verification

• 🟢 Shader-name catalog (guide L147): all 14 names — domain-warp, ridged-burn, whip-pan, sdf-iris, ripple-waves, gravitational-lens, cinematic-zoom, chromatic-split, swirl-vortex, thermal-distortion, flash-through-white, cross-warp-morph, light-leak, glitch — present in packages/shader-transitions/src/shaders/registry.ts. No fabrications.
• 🟢 CDN URLs (guide L168-170): gsap@3.14.2/dist/gsap.min.js, @hyperframes/core/dist/hyperframe.runtime.iife.js, @hyperframes/shader-transitions/dist/index.global.js — byte-identical to sibling docs/guides/claude-design-hyperframes.md:534-536 and packages/core/src/runtime/README.md (which enumerates hyperframe.runtime.iife.js as a real build artifact).
• 🟢 Composition contract (guide L51-56): data-composition-id on live root (not <template>), numeric data-width/data-height, data-duration, and window.__timelines[compositionId] = tl all match the diagnostics + fixHint messages emitted by packages/lint/src/rules/core.ts (including the "Timeline registered as X but no element has data-composition-id=X" invariant).
• 🟢 HyperShader.init skeleton call (guide L296-301): {bgColor, scenes: string[], transitions: TransitionConfig[], timeline} matches the HyperShaderConfig interface in packages/shader-transitions/src/hyper-shader.ts L57-66. Every TransitionConfig field the skeleton uses (time, shader, duration) is valid.
• 🟢 data-track-index="0" on scenes (guide L215-247): correct — packages/parsers/src/compositionContract.ts treats absent as default 0, so explicit 0 is safe.
• 🟢 Scene tiling math in the skeleton: 0 → 1.6 → 3.2 → 4.8 → 6.4 → 8.0 (5×1.6=8), root data-duration="8", and the shader transition at time: 6.15 = boundary 6.4 − duration/2 (0.25). Arithmetic checks out.
• 🟢 Self-review checklist (L401-427) enumerates exactly the failure modes the parser + lint would flag.

One non-blocking follow-up

• 🟢 nit — the "422 on failure" claim (L49) is a specific promise about the Send-to importer's HTTP status. That importer lives outside this repo so I couldn't byte-verify it; plausible, but worth double-checking on first real integration test that it isn't a 400 / 4xx-family drift. Not blocking.

Aspects audited: accuracy (against parsers/lint/shader-transitions source), consistency (against sibling ZIP-download guide), completeness (Send-to inverts asset rules cleanly; self-review checklist maps 1:1 to parser diagnostics), freshness (all 30 checks pass, no prior blockers).

— Via

[miguel-heygen]

Post-merge advisory review on exact head a3f9d53a5efb32fb42984f82f98311a027b300f2 (the guide is byte-identical on current main). Additive to Miga's contract pass and Via's approval.

The in-repo HyperFrames guidance is strong: the document's single-file composition contract, scene timing, track assignment, shader names/config, deterministic GSAP rules, and asset guidance agree with the parser/runtime surfaces and existing authoring guidance. The docs-only CI set completed cleanly, including docs validation, Mintlify, formatting, CodeQL, preview regression, and aggregate regression.

Important follow-up — the fixed 422 promise is not the external importer contract. docs/guides/claude-design-send-to-hyperframes.md:49 says invalid markup “422s.” I checked the two external implementation PRs that currently define this path: experiment-framework#41105 returns 400 Bad Request for URL/fetch/size failures and 403 Forbidden for ownership failures, while experiment-framework#41097 propagates the upstream status and explicitly tests 400 and 402. Both PRs are still open, so this is also not yet a stable shipped status contract. Please replace the fixed code with wording such as “the importer rejects the request with an HTTP error,” or document endpoint-specific statuses only after that external contract lands.

External scope note: I verified the available Send-to importer/backend PRs and the linked product/engineering intent. I did not treat future Enhance behavior as a stable implementation contract; the guide correctly labels that section as in-flight.

Verdict: COMMENT (post-merge: With fixes)
Reasoning: The HyperFrames authoring contract and documentation mechanics are sound, but the guide makes one concrete external API promise that is contradicted by the current implementation and should be corrected post-merge.

— Magi