# Hyper-Animator Critical Checklist > Extracted from SKILL.md Step 8 (Critical Checklist) and Step 9 (Manual Check Details). > Every generated composition MUST satisfy ALL items in the Critical Checklist before being presented to the user or rendered. These are not optional — they come from analyzing 124 working HyperFrames source files and the renderer's runtime expectations. --- ## Critical Checklist (Step 8) ### 1. Root Composition Attributes **WHY:** The HyperFrames runtime identifies, dimensions, and schedules compositions by `data-composition-id`, `data-width`, `data-height`, and `data-duration`. Without them, the composition is invisible to the renderer. ```html
``` --- ### 2. Paused GSAP Timeline with Registration **WHY:** The HyperFrames renderer controls playback externally via `tl.play()`, `tl.pause()`, `tl.progress()`. A self-playing timeline cannot be synchronized. The `paused: true` flag is non-negotiable. ```javascript window.__timelines = window.__timelines || {}; var tl = gsap.timeline({ paused: true }); // ... build tweens ... tl.to({}, { duration: totalDuration }, 0); window.__timelines["my-composition"] = tl; ``` --- ### 3. Scoped CSS **WHY:** Compositions are embedded in a shared rendering context. Unscoped CSS can leak and corrupt other compositions' visuals. ```css [data-composition-id="my-composition"] .title { font-size: 64px; } ``` Scope ALL rules under `[data-composition-id="..."]` or a unique class/id prefix. --- ### 4. Timeline Padded to Declared Duration **WHY:** Without padding, the renderer may terminate the composition before all visual elements have completed their animation. ```javascript tl.to({}, { duration: totalDuration }, 0); // pads from t=0 ``` The timeline MUST cover exactly the duration declared in `data-duration`. --- ### 5. No Date.now() for Primary Timing **WHY:** `Date.now()` creates desyncs during render because the JS execution clock and the render frame clock are different timelines. ```javascript // GOOD — renderer controls progress: tl.progress(0.5); // OR: tl.time(15); ``` Exception: `Date.now()` is acceptable only for logging/tracing — never for visual output, animation timing, or noise generation. --- ### 6. No setInterval for Animation Timing **WHY:** `setInterval()` is unreliable for frame-accurate render. The execution interval drifts under load, producing jittery output. ```javascript // GOOD — GSAP ticker for frame callbacks: gsap.ticker.add(function() { if (tl.isActive()) { /* update companion state */ } }); ``` --- ### 7. No Math.random() for Visual Generation **WHY:** `Math.random()` is the #1 cause of "looks different every render" bugs. The frame-screenshot renderer evaluates JS on each frame with wall-clock time, so any `Math.random()` call produces a new value, causing flicker and unreproducible output. ```javascript function mulberry32(a) { return function() { a |= 0; a = a + 0x6D2B79F5 | 0; var t = Math.imul(a ^ a >>> 15, 1 | a); t = t + Math.imul(t ^ t >>> 7, 61 | t) ^ t; return ((t ^ t >>> 14) >>> 0) / 4294967296; }; } var rng = mulberry32(20260630); // Fixed seed ``` Replace ALL `Math.random()` calls with `rng()` for particles, glitch offsets, noise, starfields, etc. --- ### 8. Async Resource Handling + Producer Readiness Gate **WHY:** If the timeline registers before resources (fonts, images, WebGL) are ready, the initial render frame will be blank. The producer (render engine) polls `window.__renderReady` before beginning frame capture — without it, the render may appear stuck or produce blank frames. ```javascript // After ALL async resources are loaded, signal readiness to the producer: Promise.all([document.fonts.ready, ...imageLoadPromises]).then(() => { window.__renderReady = true; // producer waits for this before capture buildLayout(); var tl = gsap.timeline({ paused: true }); window.__timelines["my-comp"] = tl; }); ``` For WebGL/Three.js, use `Promise.all` with a CSS fallback in case WebGL fails to initialize. For WebGL/Three.js, use `Promise.all` with a CSS fallback in case WebGL fails to initialize. --- ### 9. Four-Layer Visual Structure **WHY:** This layering matches how the most successful HyperFrames catalog blocks are structured, providing depth and readability. 1. **Atmosphere** (background) — gradients, particles, grain overlays. Lowest z-index. 2. **Subject** (main content) — product mockups, text, charts, code. Highest visual priority. 3. **Motion Accent** — decorative animations, shimmer, scan lines that add energy. 4. **Focus/Finish** — final-frame CTA text, logo reveal, outro branding. Each layer can be its own `
` element with independent timing. --- ### 10. Preview via hyperframes play **WHY:** Injecting custom player HTML into the composition causes the HyperFrames renderer to treat the overlay as a separate composition, leading to `root_missing_composition_id` and `Cannot read properties of null` errors. The composition HTML must stay pure for rendering. HyperFrames provides a built-in `` web component via `hyperframes play` that handles all playback controls (play/pause/seek/volume/speed). No player UI should be injected into the composition. **Setup:** `preview-gen.py --input --output ` fixes audio element ids and creates an `index.html` symlink in the output directory. This makes the directory compatible with `hyperframes play`. **Preview command:** `hyperframes play ` — starts a local server and opens the browser with the built-in player. --- ### 10b. Interactive Debugging via Studio **WHY:** When a composition renders with visual defects, the user can click the problematic element in Studio. The Agent Context Bridge (`hyperframes preview --context --json --context-fields selection`) returns precise element metadata, enabling targeted fixes instead of guesswork. **Workflow:** 1. User reports a visual issue 2. User opens Studio: `hyperframes preview ` 3. User clicks the problematic element 4. Query: `hyperframes preview --context --json --context-fields selection` 5. AI reads `hfId`/`selector` and makes a precise fix --- ### 11. Audio Integration (Conditional) **WHY:** The frame-screenshot renderer cannot capture real-time Web Audio API (AudioContext) synthesis. All audio must be pre-rendered as WAV files and referenced via `