Write HTML. Render video. Built for agents.
JavaScript aiai-agentsanimationclaude-codeffmpegframeworkgsaphtmlhtml-to-videomcpmotion-graphicspuppeteerrenderingtypescriptvideo-editor
docs: align infinite-repeat guidance with bounded repeat: -1 lint (#3795)
jbernard0776f799aaa41d5
diff --git a/docs/guides/claude-design-hyperframes.md b/docs/guides/claude-design-hyperframes.mdindex b16df8953e..d385055488 100644--- a/docs/guides/claude-design-hyperframes.md+++ b/docs/guides/claude-design-hyperframes.md@@ -374,7 +374,7 @@ The skeleton handles most structural rules. These are the runtime rules the skel| `Math.random()` | Seeded PRNG (only if you need randomness) || `Date.now()`, `performance.now()` | Hard-coded timing or `tl.time()` in `onUpdate` || `setInterval`, `setTimeout` | Timeline tweens + `onUpdate` |-| `repeat: -1` | `repeat: Math.max(0, Math.floor(duration / cycle) - 1)` |+| `repeat: -1` without root `data-duration` | a finite root `data-duration` (export clips to it), or `repeat: Math.max(0, Math.floor(duration / cycle) - 1)` || `stagger: { from: "random" }` | `from: "start"`, `"center"`, `"end"` || Async timeline construction | Synchronous at page load |@@ -416,7 +416,7 @@ Run before delivering. Check with actual code, not assumptions.- [ ] Shader transitions have boundary INSIDE the window: `time < boundary < time + duration`- [ ] No transition shorter than 0.3s- [ ] No exit tweens except on the final scene-- [ ] No `Date.now()`, unseeded `Math.random()`, `repeat: -1`+- [ ] No `Date.now()`, unseeded `Math.random()`, or `repeat: -1` without a finite root `data-duration`- [ ] No SVG filter data URLs as `background-image`- [ ] `window.__timelines["main"] = tl` matches `data-composition-id`diff --git a/docs/guides/claude-design-send-to-hyperframes.md b/docs/guides/claude-design-send-to-hyperframes.mdindex bfb3aa8077..17c4a8defc 100644--- a/docs/guides/claude-design-send-to-hyperframes.md+++ b/docs/guides/claude-design-send-to-hyperframes.md@@ -371,7 +371,7 @@ The cloud renderer seeks the timeline frame-by-frame. Non-deterministic or self-| `Date.now()`, `performance.now()` | hard-coded timing or `tl.time()` in `onUpdate` || `setInterval`, `setTimeout` | timeline tweens + `onUpdate` || `requestAnimationFrame` | GSAP tweens |-| `repeat: -1` | `repeat: Math.max(0, Math.floor(duration / cycle) - 1)` |+| `repeat: -1` without root `data-duration` | a finite root `data-duration` (export clips to it), or `repeat: Math.max(0, Math.floor(duration / cycle) - 1)` || `stagger: { from: "random" }` | `from: "start"`, `"center"`, or `"end"` || async timeline construction | build synchronously at page load || `video.play()` / `audio.play()` | the framework owns playback |@@ -429,6 +429,6 @@ You don't author any of this. Produce a clean, on-brand, correctly-timed silent- [ ] No exit tweens except on the final scene**Renders correctly:**-- [ ] No `Date.now()`, unseeded `Math.random()`, `setInterval/Timeout`, `requestAnimationFrame`, `repeat: -1`+- [ ] No `Date.now()`, unseeded `Math.random()`, `setInterval/Timeout`, `requestAnimationFrame`, or `repeat: -1` without a finite root `data-duration`- [ ] Timeline built synchronously; paused; framework owns playback- [ ] Colors and fonts exact; brand substance preserved: real headline/copy, distinctive figures/stats/data points, product names, and signature visuals carried over verbatim (form adapted, never genericized or invented); no placeholders; ≥2 animation patterns + mid-scene activity per scenediff --git a/skills-manifest.json b/skills-manifest.jsonindex 83d6b79b6c..8f68b27feb 100644--- a/skills-manifest.json+++ b/skills-manifest.json@@ -2,7 +2,7 @@"source": "heygen-com/hyperframes","skills": {"embedded-captions": {- "hash": "9ae9e4e06bf4b61e",+ "hash": "ebef42b483d02ab6","files": 144},"faceless-explainer": {@@ -10,7 +10,7 @@"files": 27},"figma": {- "hash": "1639b96642ac26c6",+ "hash": "ade0258f3cb1f378","files": 2},"general-video": {@@ -22,7 +22,7 @@"files": 29},"hyperframes-animation": {- "hash": "2a567656b9291f5a",+ "hash": "8c183924c57c2801","files": 122},"hyperframes-audio": {@@ -34,7 +34,7 @@"files": 11},"hyperframes-core": {- "hash": "96756e9138ed43d9",+ "hash": "010a65915fc7b45e","files": 11},"hyperframes-creative": {@@ -74,7 +74,7 @@"files": 34},"remotion-to-hyperframes": {- "hash": "e13e3681d9b0dd75",+ "hash": "833bb7855cd99d4f","files": 77},"slideshow": {@@ -82,7 +82,7 @@"files": 2},"talking-head-recut": {- "hash": "865d98665f0011da",+ "hash": "c9b7ab6112feb4e3","files": 28}}diff --git a/skills/embedded-captions/modes/standard/_anatomy.md b/skills/embedded-captions/modes/standard/_anatomy.mdindex 0eb3fa0232..74a0e9a207 100644--- a/skills/embedded-captions/modes/standard/_anatomy.md+++ b/skills/embedded-captions/modes/standard/_anatomy.md@@ -17,7 +17,7 @@ HyperFrames-native, so anyone can reproduce it:- **One paused GSAP timeline per composition**, registered to `window.__timelines[data-composition-id]`.- All timing in **seconds**; `data-start` / `data-duration` carry the scene window.-- **Deterministic + seek-safe** only — no `Math.random()`, no `Date.now()`, no infinite repeats, no un-seekable CSS animations. Every state is reachable by seeking the timeline to a time `t`.+- **Deterministic + seek-safe** only — no `Math.random()`, no `Date.now()`, no `repeat: -1` without a finite root `data-duration`, no un-seekable CSS animations. Every state is reachable by seeking the timeline to a time `t`.- GSAP transform aliases (`x`, `y`, `scale`, `rotation`); animate `opacity`, `filter`, `clipPath`, `textShadow`, `backgroundPosition`, `letterSpacing` — never layout props (width/top/left/margin).For the composition contract see `hyperframes-core`; eases + the animated-property allowlist see `hyperframes-gsap`; caption grouping/positioning/exit guarantees see `hyperframes-captions`.@@ -218,7 +218,7 @@ The gallery used a `setInterval` loop; HyperFrames needs the same beats as **abs- Timeline **paused**; registry key = `data-composition-id`.- **No CSS keyframe animation** on caption elements — all motion is GSAP tweens at absolute times (seek-safe).-- No `Math.random` / `Date.now` / infinite repeats.+- No `Math.random` / `Date.now` / `repeat: -1` without a finite root `data-duration`.- `display:inline-block` on every `.w` and the climax `span`.- **Hard-hide** each flow group at its end time; **CLIMAX_OUT ends at `opacity:0`** (or fully-clipped) so nothing lingers.- Gradient / `background-clip:text` / stroke fills go on `.climax span`, not the transformed `.climax`.diff --git a/skills/figma/SKILL.md b/skills/figma/SKILL.mdindex 9381ca33d4..cda8aec4db 100644--- a/skills/figma/SKILL.md+++ b/skills/figma/SKILL.md@@ -131,4 +131,4 @@ Storyboard files follow a grammar you can parse mechanically — don't eyeball,## Determinism-Never leave a Figma URL in the composition — freeze first. Never emit `repeat: -1`. Timelines paused, finite, literal `window.__timelines` keys. All Figma I/O at import time; render sees local files only.+Never leave a Figma URL in the composition — freeze first. Never emit `repeat: -1` without a finite root `data-duration`. Timelines paused, finite, literal `window.__timelines` keys. All Figma I/O at import time; render sees local files only.diff --git a/skills/hyperframes-animation/SKILL.md b/skills/hyperframes-animation/SKILL.mdindex 23ae488791..9cd8938f66 100644--- a/skills/hyperframes-animation/SKILL.md+++ b/skills/hyperframes-animation/SKILL.md@@ -63,7 +63,7 @@ Multiple runtimes can coexist in one composition. Each registers its instances o## Critical Constraints-**Prerequisite: `hyperframes-core` → Non-Negotiable Rules** (single paused timeline, `data-duration` governs length, no `Math.random` / `Date.now` / `performance.now`, no `repeat: -1`, no page-load `gsap.set` on later-scene clips, no `display` or raw `visibility` tweens, and no timeline construction inside `async` / `setTimeout` / `Promise`). GSAP `autoAlpha` and zero-duration visibility sets at explicit timeline boundaries remain allowed by core. Use those exceptions only on non-clip elements or wrappers inside a clip; the framework owns `.clip` lifecycle. Don't restate the full contract here.+**Prerequisite: `hyperframes-core` → Non-Negotiable Rules** (single paused timeline, `data-duration` governs length, no `Math.random` / `Date.now` / `performance.now`, no `repeat: -1` without a finite root `data-duration`, no page-load `gsap.set` on later-scene clips, no `display` or raw `visibility` tweens, and no timeline construction inside `async` / `setTimeout` / `Promise`). GSAP `autoAlpha` and zero-duration visibility sets at explicit timeline boundaries remain allowed by core. Use those exceptions only on non-clip elements or wrappers inside a clip; the framework owns `.clip` lifecycle. Don't restate the full contract here.Animation-craft additions on top of core's contract:diff --git a/skills/hyperframes-animation/adapters/gsap-timeline-and-labels.md b/skills/hyperframes-animation/adapters/gsap-timeline-and-labels.mdindex 98256c8560..504b9256a1 100644--- a/skills/hyperframes-animation/adapters/gsap-timeline-and-labels.md+++ b/skills/hyperframes-animation/adapters/gsap-timeline-and-labels.md@@ -16,7 +16,7 @@ tl.to(".a", { x: 100 }).to(".b", { y: 50 }).to(".c", { opacity: 0 });Timeline options:- **paused: true** — required in HyperFrames. The framework drives the playhead.-- **repeat**, **yoyo** — apply to the whole timeline. `repeat: -1` is forbidden; use finite counts.+- **repeat**, **yoyo** — apply to the whole timeline. `repeat: -1` requires a finite root `data-duration` (export clips to it); otherwise use finite counts.- **defaults** — vars merged into every child tween. Use this instead of repeating `ease` and `duration` on every line.## Position Parameterdiff --git a/skills/hyperframes-animation/adapters/gsap.md b/skills/hyperframes-animation/adapters/gsap.mdindex 53dddf92f0..c7824de33e 100644--- a/skills/hyperframes-animation/adapters/gsap.md+++ b/skills/hyperframes-animation/adapters/gsap.md@@ -96,7 +96,7 @@ HyperFrames is stricter than vanilla GSAP. Animate only:- Use both `svgOrigin` and `transformOrigin` on the same SVG element.- Chain animations with `delay` when a timeline can sequence them.- Create tweens before the DOM exists.-- Use infinite `repeat: -1` in HyperFrames compositions — use finite repeat counts computed from the visible duration.+- Use infinite `repeat: -1` without a finite root `data-duration` (with one, export clips to that window); when a loop must end before the composition does, use a finite repeat count computed from the visible duration.## Credits And Referencesdiff --git a/skills/hyperframes-animation/rules-index.md b/skills/hyperframes-animation/rules-index.mdindex 8568d22791..48327c8840 100644--- a/skills/hyperframes-animation/rules-index.md+++ b/skills/hyperframes-animation/rules-index.md@@ -8,7 +8,7 @@ Stated once here so individual rules don't repeat it. Every recipe in `rules/`:- runs on ONE **paused** GSAP timeline registered on `window.__timelines` (never autoplay, never a second timeline);- is **seek-safe both directions**: `fromTo` with explicit from-states (t=0 correct under seek; `immediateRender: false` when re-owning a target), absolute values — never relative `+=` tweens; state readable as a pure function of timeline time, no mutable trackers;-- is **deterministic**: no `Math.random()`, no `Date.now()` — index-derived pseudo-random and baked schedules only; finite repeats, never `repeat: -1`;+- is **deterministic**: no `Math.random()`, no `Date.now()` — index-derived pseudo-random and baked schedules only; finite repeats (`repeat: -1` only under a finite root `data-duration`);- animates **transforms and paint-only properties** — `width`/`height`/`top`/`left` tweens are forbidden (use scale/translate proxies, masks, or `anchored-layout-expand`);- caps group staggers so an arrival reads as one beat (`items × stagger ≤ ~0.5s`);- puts **no CSS `transition`** on animated elements (they interpolate independently of seek and flicker) and hints compositors with `will-change: transform` where many tweens run at once;diff --git a/skills/hyperframes-core/SKILL.md b/skills/hyperframes-core/SKILL.mdindex 9f4ea91acf..97e68da11f 100644--- a/skills/hyperframes-core/SKILL.md+++ b/skills/hyperframes-core/SKILL.md@@ -73,7 +73,7 @@ A lint **error** also switches off the layout and contrast audits: `check` thenSurfaced here; full rationale in the linked reference. Do not violate:-- No render-time clocks / unseeded `Math.random` / network / input-state; no `repeat: -1` (use a finite count). → `determinism-rules.md`+- No render-time clocks / unseeded `Math.random` / network / input-state; `repeat: -1` only under a finite root `data-duration` (export clips to it — otherwise use a finite count). → `determinism-rules.md`- Never tween `display`, `visibility`, or `autoAlpha` on a `.clip` element. The framework owns clip visibility, and `lint` rejects it (`gsap_animates_clip_element`). Animate a child instead. → `determinism-rules.md`- No `<br>` in body text; transformed elements must be block-level + sized; pulsing absolute decoratives need peak clearance. → `determinism-rules.md`- `<video>`/`<audio>` are found by a flat document query, so the framework seeks and decodes them at **any nesting depth** (including inside a sub-comp `<template>` or wrapper). One hard limit: `lint` errors if a `<video data-start>` sits inside another **plain** element that also has `data-start`, and the failure is real (wrong source frames, then the clip vanishes mid-slot), so put the timing on the wrapper or on the video, never both. Sub-composition hosts are exempt: media inside a sub-composition renders correctly. The other caveat is timelines, not placement: a sub-comp timeline can't animate host-root elements. → `variables-and-media.md`diff --git a/skills/hyperframes-core/references/determinism-rules.md b/skills/hyperframes-core/references/determinism-rules.mdindex 55f445d57b..2a7f9ce553 100644--- a/skills/hyperframes-core/references/determinism-rules.md+++ b/skills/hyperframes-core/references/determinism-rules.md@@ -25,7 +25,7 @@ Rendered frames must be reproducible from the requested time. Do **not** use any- Unseeded `Math.random()`. Use a seeded PRNG if random-looking placement is needed.- Render-time network fetches for required assets. Inline or pre-bundle them.- Hover, scroll, pointer, or focus state. The renderer has no input events.-- Infinite loops such as `repeat: -1`. Compute a finite count: `repeat: Math.max(0, Math.floor(duration / cycleDuration) - 1)` — **`floor`, not `ceil`** (`ceil` overshoots `data-duration` and trips the `gsap_repeat_ceil_overshoot` lint; `max(0, …)` avoids a negative repeat = infinite).+- Unbounded infinite loops. `repeat: -1` is allowed only when the root declares a finite `data-duration` — deterministic seeking and export clip to that explicit window (`gsap_infinite_repeat` demotes to a warning). Without a finite composition duration it stays a hard error: the timeline can report an unbounded length and render planning fails. When the loop itself must end **before** the composition does, compute a finite count: `repeat: Math.max(0, Math.floor(duration / cycleDuration) - 1)` — **`floor`, not `ceil`** (`ceil` overshoots `data-duration` and trips the `gsap_repeat_ceil_overshoot` lint; `max(0, …)` avoids a negative repeat = infinite).Also avoid:diff --git a/skills/remotion-to-hyperframes/references/limitations.md b/skills/remotion-to-hyperframes/references/limitations.mdindex 4bae8d9da8..a9374a6405 100644--- a/skills/remotion-to-hyperframes/references/limitations.md+++ b/skills/remotion-to-hyperframes/references/limitations.md@@ -48,7 +48,7 @@ output but visually-identical video, so SSIM passes — just flag it.A bounded GSAP repeat can reproduce _visual_ repetition when its finite count is derivedfrom the visible duration. If the looped child has cross-iteration state (a counter, arandomness seed), HF won't reproduce it identically per iteration. Bow out unless the child-is fully deterministic per-iteration; never use `repeat: -1`.+is fully deterministic per-iteration; use `repeat: -1` only when the root declares a finite `data-duration`.### Remotion's `<Img>` with crossOrigindiff --git a/skills/talking-head-recut/SKILL.md b/skills/talking-head-recut/SKILL.mdindex fe87c925a6..616ebc258a 100644--- a/skills/talking-head-recut/SKILL.md+++ b/skills/talking-head-recut/SKILL.md@@ -1154,7 +1154,7 @@ decides where the actual visible card sits.- Register one paused master timeline as `window.__timelines["talking-head-recut"]`.- Build timelines synchronously at page load; no `async`, `setTimeout`, Promises, or media `play()` calls.- Do not use `Math.random()` or `Date.now()` in render paths.-- Do not use `repeat: -1`; calculate finite repeats from the video duration.+- `repeat: -1` is allowed only under the finite root `data-duration`; for loops that must end earlier, calculate finite repeats from the video duration.- Prefer GSAP transforms and opacity (`x`, `y`, `scale`, `rotation`, `opacity`) over layout properties (`top`, `left`, `width`, `height`) for motion.- Animate wrappers such as `#video-wrap`, not the video element dimensions directly.- Avoid animating the same property on the same element from multiple timelines at the same time.