fix(runtime): decide a nested clip's timing convention by its start, not its end

[felipecaldas]

Summary

resolveAbsoluteMediaStartSeconds picks between the two conventions #2859 identified by testing the clip's authored end. What actually distinguishes them is where the clip starts, so a composition-local clip is misread as root-global whenever its duration merely exceeds its host's mount offset — and it renders blank for the tail of its own slot.

This is the same failure #2859 fixed, one case further along.

The bug

const authoredEnd = authoredDuration > 0 ? authoredStart + authoredDuration : authoredStart;
const overlapsHostWindow =
  hostEnd == null
    ? authoredStart >= inheritedStart                    // start-based
    : authoredStart < hostEnd &&
      (authoredEnd > inheritedStart || authoredStart === inheritedStart);   // end-based
return overlapsHostWindow ? authoredStart : inheritedStart + authoredStart;

A composition-local clip is authored from its host's zero, so what identifies it is that its start sits below the host's absolute start. Its duration says nothing about which convention it uses.

Worked example, from a real project:

host slot   data-start="2.96"  data-duration="4.375"     (2.96 .. 7.335)
inner video data-start="0.000" data-duration="4.375"     (composition-local)

authoredEnd = 0 + 4.375 = 4.375  >  inheritedStart 2.96   ->  read as ROOT-GLOBAL
-> scheduled 0 .. 4.375
-> the ancestor visibility gate clips the front to the host window
-> visible 2.96 .. 4.375, blank for the remaining ~3s of its own slot

Note the two branches above already disagree with each other — the hostEnd == null branch tests the start. This PR makes both use the start, which is also what the comment above them describes.

Why it hides

The misreading only produces a visible hole when 0 < mountOffset < duration.

scene	mount	duration	verdict on main	outcome
0	0	2.958	inheritedStart <= 0 → early return	fine
1	2.96	4.375	4.375 > 2.96 → "root-global"	~3s blank
2	7.333	2.583	2.583 < 7.333 → local	fine
3–5	later	shorter	local	fine

Every other scene in that project mounts later than its own duration, so it fell through to the correct branch by accident. Five scenes correct by luck and one broken looks exactly like a healthy project.

How to reproduce

1. Deterministic, in this repo — the added test. packages/core/src/runtime/init.test.ts:

keeps a composition-local clip visible for its whole slot when its duration exceeds the mount offset

It builds a host at data-start="2.96" data-duration="4.375" containing a video at data-start="0.000" data-duration="4.375", then asserts __hfResolveMediaStartSeconds resolves to 2.96 and that the clip is still visible at t=7.2 (late in its own slot).

On main it fails:

bunx vitest run --config packages/core/vitest.config.ts \
  packages/core/src/runtime/init.test.ts

It asserts a late instant inside the slot, not just the resolved start — the resolved start alone was never the visible symptom.

2. In a render. Mean frame luminance is the cheapest way to ask "did anything paint?":

hyperframes render <project> --output /tmp/r.mp4
ffmpeg -ss 5.5 -i /tmp/r.mp4 -frames:v 1 -vf format=gray -f rawvideo - \
  | python3 -c "import sys;d=sys.stdin.buffer.read();print(sum(d)/len(d))"

On the project above (backdrop #0B0B0F ≈ 15 = nothing painted, content ≈ 90–120):

t (s)	0.5	2.5	3.5	4.5	5.5	6.5	7.5	9.5	12.5	15.5
before	107	107	104	15	16	16	161	131	107	128
after	107	107	104	89	73	75	161	131	107	128

After the change, a 76-frame scan at 0.25s across the full 18.9s render finds no unpainted frame.

Honest caveat on repro: I could not get this to reproduce in a stripped-down standalone project — a two-file project with the same attribute values, and even one built by lifting the failing slot and composition verbatim out of the real project, both rendered correctly on unpatched code. So something about the surrounding project context is part of the trigger and I have not isolated it. The unit test above is deterministic and does fail on main, and the real-project before/after is measured, but if you want a minimal standalone fixture, that gap is real and I'd rather flag it than hand you something I hadn't verified.

The evidence that identified the mechanism

Rather than fit a theory to the failure, I made it predict something counterintuitive: if a clip's duration is what tips it into being misread, then making a healthy clip longer should create a new hole.

scene-2 above is healthy. Its duration 2.583 → 8.000, slot untouched at 7.333–9.917:

t=7.5   base 161.4    ->  161.4
t=7.9   base 160.2    ->  160.1
t=8.1   base 160.6    ->   15.4   <- new hole, at exactly 8.0
t=9.5   base 131.2    ->   15.5

A longer clip rendering less, with the cutoff landing exactly on the new duration.

Three other hypotheses were eliminated first, each by a single-variable render: absolute-vs-relative composition time (changing the inner data-start 0.000→2.960 produced exactly the relative-semantics result), occlusion by a backdrop, and z-order via data-track-index (moving the affected slot to track 0 and a healthy one to track 5 gave byte-identical renders).

Blast radius

Behaviour changes only for clips with 0 <= authoredStart < hostStart. Everything else takes the same branch as before.

• pip-video-late-host — data-start="3.0" inside a host at 3.0 — is unaffected, since >= still reads it as root-global. Its unit test and golden render both pass.
• nested-sequential-video-local-start (from fix: offset nested template video timing #2859) passes.
• I could find no fixture in this repo in the changed class.

That last point cuts both ways: the class I changed is untested here either way, so the >= choice for 0 < authoredStart < hostStart is a judgement call rather than something your fixtures pin. If you know of a shipped project shape where a root-global clip legitimately starts before its host, that case would want a different rule and I'd defer to you on it.

Verification

• packages/core: 117 files / 2337 tests pass
• regression harness: nested-sequential-video-local-start and pip-video-late-host — 2/2 passed, 0 failed frames
• lint, format, typecheck clean
• Negative control: restoring the end-based test fails exactly the new test, and leaves the legacy PIP test passing

[miga-heygen]

LGTM — clean, well-reasoned fix. The investigation in the PR description is exceptional.

The core change is a one-concept simplification: replace the end-based convention test (authoredEnd > inheritedStart) with a start-based one (authoredStart >= inheritedStart). This aligns both branches of the conditional (the hostEnd == null branch was already start-based) and makes the variable name accurate (authoredStartIsRootGlobal instead of overlapsHostWindow, which described intersection when the actual question is timing convention).

What the fix does

Before: a composition-local clip (data-start="0") inside a host at 2.96s with duration 4.375s computed authoredEnd = 0 + 4.375 = 4.375 > inheritedStart 2.96, so it read as root-global and scheduled itself at 0..4.375 — the ancestor gate clipped the front, leaving a 3s black hole.

After: the test is authoredStart >= inheritedStart, which is 0 >= 2.96 → false → composition-local, so the clip inherits the host offset and schedules at 2.96..7.335.

The dead authoredDuration / authoredEnd computation is fully removed — no stale references.

What I verified

• SSOT: "Is this clip root-global?" now has one criterion across both branches: authoredStart >= inheritedStart. The hostEnd != null branch adds && authoredStart < hostEnd as a bounds guard (a root-global clip starting past its host's end is nonsensical, so composition-local is the safe fallback), but the primary discriminator is the same.
• Legacy PIP case preserved: host@45.4 + video@45.4 → authoredStart >= inheritedStart → true → root-global. The >= keeps this case on the same path. The existing pip-video-late-host test confirms.
• Boundary at authoredStart === inheritedStart: reads as root-global in both branches, which is correct for PIP-style clips whose start matches the host's.
• Composition-local with sub-offset: host@5 + clip@1 → 1 >= 5 → false → 5 + 1 = 6. Correct — the clip starts 1s into the host.
• Root scene early return: inheritedStart <= 0 returns authoredStart directly, so root-level clips never reach the changed code.
• Test quality: Asserts both the resolved start (.toBeCloseTo(2.96)) AND visibility at the previously-black instants (5.5, 7.2). Also checks slot boundaries — hidden at 7.4 (past end) and 2.5 (before start). The "late instant" assertion is the critical one, catching the actual visible symptom rather than just the resolved value.
• Stale concept scan: authoredDuration and authoredEnd fully removed. No surviving references in comments, tests, or logic.
• Blast radius: Only clips with 0 <= authoredStart < hostStart take a different branch. Everything else is unchanged.

The honest caveat about not isolating the full trigger in a standalone project is appreciated — the unit test is deterministic and the real-project measurements are convincing, and hand-waving away the gap would have been worse than flagging it.

Review by Miga

[miguel-heygen]

@felipecaldas can you sign the commit to merge it pls?

[felipecaldas]

absolutely, ill get it done when tomorrow as its past midnight here 👍

[felipecaldas]

@miguel-heygen it's very verified :)