| 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.