hyperframes-atom-author

name	hyperframes-atom-author
description	Author or revise Hyperframes HTML/CSS/GSAP video atoms for this pipeline. Use when creating scene atoms, transparent transition overlays, framed-content animations, diagram builds, web-demo canvases, focus zooms, or local Hyperframes render specs.

Hyperframes Atom Author

Overview

Create deterministic HTML motion atoms that Remotion can assemble. Follow the composer style spec and shot brief before writing any atom.

Inputs

• shot brief
• global style spec
• output path and duration
• whether output should be MP4, WebM with alpha, or PNG sequence
• neighboring shot summaries for continuity

Rules

• Load GSAP locally from node_modules when possible.
• Use data-composition-id, data-width, data-height, data-start, data-duration, and class="clip" correctly.
• Register paused timelines on window.__timelines[compositionId].
• Keep atoms style-consistent with the global spec.
• Design the layout before styling components. Inventory text, panels, callouts, presenter safe zones, and minimum readable sizes; choose the lowest-risk template that fits. Prefer top-down, single-focus, or sequential builds when side-by-side composition would make panels, labels, or indicators crowd each other.
• When a presenter dock is present, lay out the primary atom content inside the available safe stage. Fill the stage with a balanced composition; do not force a left/right layout just because a prior atom used one.
• Give every widget and motion beat an explicit job: orient, signal a section turn, compare, transform, inspect a detail, or recap. Remove decorative widgets and motion that cannot be tied to the current spoken idea.
• For full-frame presenter sections, Hyperframes overlays may add static or lightly moving side widgets, but they must stay outside the presenter face and hand-safe rectangles and must not compete with the speaker.
• Treat accents, pointers, rails, dots, and leader lines as real components with reserved space, not decorations painted over text. A vertical bar needs its own gutter; text must start after the gutter. If a pointer line and endpoint do not align as one polished component, remove it or replace it with a simpler highlight.
• Do not author ad hoc pointer systems. Use an existing vetted pointer component or a simpler container-level highlight; do not combine separate line, dot, glow, and label elements unless their geometry is tested together in layout-qc.
• Prefer transparent WebM for overlay transitions when the transition should layer over Remotion content.
• Verify the rendered alpha channel before using WebM as a Remotion overlay. If the alpha channel is missing, render a chroma-key MP4 and precompose it into the presenter recording before Remotion.
• Do not create opaque transition MP4s unless the whole frame is intentionally owned by the atom and the brief explains why a Remotion cut or match move is insufficient.
• Add a layout-qc JSON block for any atom that contains multiple text boxes, panels, presenter docks, or overlay widgets. Include visible box rects, reserved clear rects, component containment rules, and stage occupancy when a docked presenter is present.
• Keep text readable and avoid over-building.

Output

Return:

• files changed
• render command
• expected output asset
• visual QA notes
• any assumptions

Read references/hyperframes-patterns.md before implementing atoms, especially the layout-template and component-detail rules.