From 8fc8294dbddc82479c87f0e704854160e3412981 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Miguel=20=C3=81ngel?= Date: Tue, 8 Sep 2026 14:09:29 -0400 Subject: [PATCH] docs: clarify paused composition roots in project instructions (#3670) --- AGENTS.md | 2 +- CLAUDE.md | 2 +- packages/cli/src/templates/_shared/AGENTS.md | 5 ++++- packages/cli/src/templates/_shared/CLAUDE.md | 5 ++++- 4 files changed, 10 insertions(+), 4 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 604e14f3c3..ddfe13a42a 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -81,7 +81,7 @@ skills/ → AI agent skill definitions - **Package manager**: bun (not pnpm, not npm for workspace operations) - **Commit format**: Conventional commits (`feat:`, `fix:`, `docs:`, `refactor:`, `test:`) - **TypeScript**: Avoid `any` and `as T` assertions. Prefer type guards and narrowing. -- **Compositions**: HTML files with `data-*` attributes. Clips need `class="clip"`. GSAP timelines must be paused and registered on `window.__timelines`. +- **Compositions**: HTML files with `data-*` attributes. Clips need `class="clip"`. Register one paused GSAP root timeline per composition on `window.__timelines`. Scene timelines manually added to that root must not be paused, or they will not advance when the root is seeked. - **Frame Adapters**: Animation runtimes plug in via the seek-by-frame adapter pattern. GSAP is the primary adapter. - **Deterministic rendering**: No `Date.now()`, no unseeded `Math.random()`, no render-time network fetches. diff --git a/CLAUDE.md b/CLAUDE.md index 7f18f037ad..4c2e34ed91 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -111,7 +111,7 @@ skills/ → AI agent skill definitions - **Package manager**: bun (not pnpm, not npm for workspace operations) - **Commit format**: Conventional commits (`feat:`, `fix:`, `docs:`, `refactor:`, `test:`) - **TypeScript**: Avoid `any` and `as T` assertions. Prefer type guards and narrowing. -- **Compositions**: HTML files with `data-*` attributes. Clips need `class="clip"`. GSAP timelines must be paused and registered on `window.__timelines`. +- **Compositions**: HTML files with `data-*` attributes. Clips need `class="clip"`. Register one paused GSAP root timeline per composition on `window.__timelines`. Scene timelines manually added to that root must not be paused, or they will not advance when the root is seeked. - **Frame Adapters**: Animation runtimes plug in via the seek-by-frame adapter pattern. GSAP is the primary adapter. - **Deterministic rendering**: No `Date.now()`, no unseeded `Math.random()`, no render-time network fetches. diff --git a/packages/cli/src/templates/_shared/AGENTS.md b/packages/cli/src/templates/_shared/AGENTS.md index 6deb8e4ba5..45aa30b89f 100644 --- a/packages/cli/src/templates/_shared/AGENTS.md +++ b/packages/cli/src/templates/_shared/AGENTS.md @@ -90,11 +90,14 @@ Fix all errors before presenting the result. Warnings should be reviewed before 1. Every timed element needs `data-start` and a duration. `data-start` is what marks it as timed; `data-track-index` is an optional Studio display lane the render never reads 2. Give timed visual elements `class="clip"`. The framework keys visibility off `data-start`, not the class, but the shared `.clip` CSS is what gives a scene its full-frame box, and `lint` warns without it -3. Timelines must be paused and registered on `window.__timelines`: +3. Register one paused root timeline per composition on `window.__timelines`: ```js window.__timelines = window.__timelines || {}; window.__timelines["composition-id"] = gsap.timeline({ paused: true }); ``` + Scene timelines manually added to this root must not be paused. A paused + child does not advance when the root is seeked. The runtime activates + registered composition siblings, not arbitrary nested scene timelines. 4. Videos use `muted` with a separate `