In a seek-based HTML-to-MP4 renderer (HyperFrames, Remotion-style; frame N = timeline.seek(N/fps)), an overlay card is two independently scheduled things:
- the container, whose visibility the framework gates from
data-starttodata-start + data-duration, and - its child reveals, which you cue to spoken words from an ASR word list.
Nothing ties them together. Cue the container to the start of a beat and its first child to the keyword a few hundred ms later, and the render contains a fully-drawn, empty panel for that gap.
Real case: a talking-head recut whose hook card entered at 0.3003s with its kicker cued to "one thing" at 0.8008s. The finished MP4 opened on a blank glass rectangle above the subject for half a second - the half second that decides whether a short-form viewer scrolls.
Why every cheap check misses it:
hyperframes checkpassed clean: 0 lint errors, 0 runtime errors, 0 motion errors, 0 layout issues, 21/21 contrast checks. An empty container is valid; it is an editorial defect, not a structural one.- Mid-window snapshots look perfect. Sampling each card at the middle of its window (the obvious QA choice, and what a contact sheet gives you) shows every card fully composed.
- Watching the preview at speed does not reliably surface a 0.5s hole either.
The check that finds it: extract a frame at each timed element's window START (and at the first frame of the file), from the rendered output, not the preview:
for t in 0.32 3.72 6.13 11.07 16.75 21.40 31.33; do
ffmpeg -v error -y -ss $t -i out.mp4 -frames:v 1 /tmp/e_$t.png
done
ffmpeg -v error -y -i /tmp/e_0.32.png -i /tmp/e_3.72.png ... \
-filter_complex "[0][1]...hstack=N,crop=iw:520:0:180" /tmp/band.pngCropping to just the card band and hstacking turns the whole audit into one image: any panel that is a blank rectangle is a bug.
The rule: a timed container must arrive composed - at least one content element visible at the container's own start time. Then key later reveals to their words. Concretely, instead of
thcCardIn(tl, "#hook-in", 0.3003); // panel enters
thcReveal(tl, "#hk-kick", 0.8008); // ...500ms of nothing
thcReveal(tl, "#hk-hero", 1.2846);write
thcCardIn(tl, "#hook-in", 0.3003);
thcReveal(tl, "#hk-kick", 0.3003); // composed WITH the panel
thcReveal(tl, "#hk-hero", 0.8008); // hero now lands ON the keywordThe fix usually improves the edit anyway: it frees the largest type to land on the keyword instead of spending that cue on a small label.
This is the same family as fromTo's immediateRender: true (an element sits in its "from" state from t=0 on a paused timeline), but distinct in cause: here nothing is in a stale state, the content simply has not been scheduled yet. Both are only caught by looking at the START of a window rather than its middle.
Corollary for cards handed off by a push/shove: the incoming card must also be composed before the push begins, or the transition slides an empty panel into frame.