Nested paused GSAP timelines report duration 0, producing a silent all-black render

[miguel-heygen]

Describe the bug

Nesting paused child timelines into a parent makes the parent report duration() === 0.
Every seek then resolves to t=0, so the render is entirely blank — and lint, check and
validate all pass.

This matters because our own composition contract requires paused timelines
("GSAP timelines must be paused and registered on window.__timelines"). An author who
follows that guidance for each of two scenes and combines them with .add() gets a black
video and no warning.

Steps to reproduce

Reproduced against gsap 3.15.0, the version in the workspace (reported independently on
3.14.2):

import { gsap } from "gsap";

const mk = (paused) => {
  const t = gsap.timeline({ paused });
  t.to({ x: 0 }, { x: 1, duration: 3 }, 0);
  return t;
};

for (const paused of [true, false]) {
  const a = mk(paused), b = mk(paused);
  const parent = gsap.timeline({ paused: true });
  parent.add(a, 0);
  parent.add(b, 0);
  console.log(`children paused=${paused}: child.duration=${a.duration()} parent.duration=${parent.duration()}`);
}

children paused=true:  child.duration=3 parent.duration=0
children paused=false: child.duration=3 parent.duration=3

Each child's own duration() is correct and getChildren() returns them with correct
start/duration. Only the parent's duration collapses.

Impact

packages/core/src/runtime/init.ts:675 and :721, startResolver.ts:99 and
timeline.ts:170 all derive composition duration from timeline.duration(). A registered
parent built this way reports 0, so seek(t > 0) renders the t=0 state — every element
still hidden — and the output is black.

Nothing catches it. This was found from a real composition (a matrix-rain background and a
text-decode foreground, each on its own paused timeline, combined via .add()) that
produced an all-black render and passed every gate.

Suggested fix

This is arguably GSAP behaving as designed — a paused child does not advance — so the fix
belongs on our side, as an invariant we can state exactly:

A registered timeline with getChildren().length > 0 and duration() === 0 is always
wrong.

There is no legitimate composition with children spanning time and zero total duration, so
checking it has no false-positive case. Failing loudly there converts a silent black render
into an actionable error naming the composition id.

A lint rule could catch the common authored spelling (gsap.timeline({ paused: true })
passed to .add()), but the runtime check is the one that cannot be evaded, since the
timeline may be assembled dynamically.

[miguel-heygen]

Investigated: not a GSAP regression, and the fix should be different from what I proposed

It is not a regression

Identical behaviour on every version from 3.11.5 to the 3.15.0 we ship:

gsap	parent.duration()	after parent.seek(4.5)
3.11.5	0	a.x=0 b.x=0
3.12.5	0	a.x=0 b.x=0
3.13.0	0	a.x=0 b.x=0
3.14.0	0	a.x=0 b.x=0
3.14.2	0	a.x=0 b.x=0
3.15.0	0	a.x=0 b.x=0

No shipped block is affected either: nothing in registry/ nests a paused timeline
(files using .add() with two or more gsap.timeline({ paused: true }): none).

It is worse than the title says

The duration collapsing is only half of it. The children never render. Seeking the
parent to 4.5s — midway through the second scene — leaves both targets at their t=0 values,
because paused means that timeline's playhead does not advance and GSAP honours that for a
nested child. So even a correct duration would still capture frozen frames.

The framework already solves this, for a different path

packages/core/src/runtime/init.ts:1082 calls paused(false) on child timelines before
nesting them into the root. So this failure mode is known and handled.

It only covers collectRootChildCandidates (init.ts:1033), which walks
[data-composition-id] nodes and looks up timelines[childId] — the sub-composition
path. Timelines an author creates in a script and combines with .add() themselves are
never registered under a composition id, so the collector cannot see them and they are never
unpaused.

The fix, measured

My original suggestion was an invariant that errors on children > 0 && duration === 0.
That is still true, but making it work is better than failing it, and the ordering turns out
to matter:

approach	result
add paused children (today)	dur=0, nothing renders
unpause before .add()	dur=6, renders correctly
unpause after .add(), then invalidate()	dur=6, renders correctly
unpause after .add(), then read totalDuration()	dur=6, renders correctly
unpause after .add() and nothing else	dur=0, still broken

Unpausing alone is not enough — the parent caches its duration at .add() time, so a
recompute has to be forced. That last row is the trap for whoever implements this.

So: extend the existing unpause to the root timeline's own children and force the recompute.
Same mechanism the framework already trusts for sub-compositions, applied to the path that
currently has nothing. The zero-duration check is still worth keeping as a backstop for
anything neither path reaches, since it has no false-positive case.