fix(engine): name the data-no-timeline opt-out in the timeline-timeout warning

[WaterrrForever]

The gap

A sub-composition timeline timeout emits two messages, and only one of them is useful:

	names the opt-out	names the pending ids	who reads it
stderr, inside pollSubCompositionTimelines	yes	yes	a human watching the run
structured CaptureWarning	no	no	render's summary, result.warnings, the SDK, CI

The structured one said only:

[sub_timeline_readiness_timeout] Sub-composition timelines did not become ready within 45000ms

render.ts re-prints that in the completed_with_warnings block and returns it in the
result's warnings array, so a programmatic caller gets the symptom with no remedy — and a
human reading scrollback gets it after the rich line has scrolled away.

It also reads as a fault to diagnose. The commonest cause is the opposite: a composition
driven by CSS animations or rAF never registers window.__timelines[id], so it is polled
for the whole playerReadyTimeout (45 s, packages/engine/src/config.ts) and then proceeds
with a warning. That composition is correct. It is paying 45 s a render because nothing told
the author the wait was theirs to switch off.

The change

• The timeout message says the wait can be intentional, names data-no-timeline as the
  opt-out, and keeps the async-setup case as the other branch.
• The pending composition ids were already computed for the stderr line and thrown away. An
  optional onPending callback carries them to the session, so the structured warning and
  its details.pendingCompositionIds name them too — matching the sub_timeline_script_failure
  branch, which already names its failed sources.
• The stderr text is unchanged; missing is still ids.join(", ").
• The script-failure branch is untouched and deliberately does not gain the
  data-no-timeline advice: there the timeline can never arrive, so that would be the wrong
  remedy.

Before / after, for a composition with no timeline:

- Sub-composition timelines did not become ready within 45000ms
+ Sub-composition timelines did not become ready within 45000ms (still unregistered: scene-2).
+ This can be intentional: a composition driven by CSS animations or rAF never registers
+ window.__timelines[id], and marking its host with data-no-timeline skips the wait entirely.
+ Otherwise, a composition that sets up asynchronously must register window.__timelines[id]
+ once setup completes.

Tests

packages/engine/src/services/frameCapture-subTimelineWarning.test.ts — 6 cases:
no warning on ready/absent outcome, the remedy named, the ids named, no empty
parenthetical when the list is empty, and the script-failure branch left alone.

I could not run vitest in this environment (no installed node_modules for the
workspace), so I will not claim the suite is green. What I did instead, and what I can
stand behind: I extracted recordCaptureWarnings and recordSubTimelineWarning verbatim
from the patched file and executed them under node --experimental-strip-types against the
same assertions plus a dedup case — 16/16 pass. Two mutants confirm the assertions
discriminate rather than passing by construction:

• the pre-patch message → 4 red (remedy, "intentional", window.__timelines[id], ids);
• the plausible-but-incomplete fix — names data-no-timeline but omits that the wait can
  be intentional → exactly 1 red, the assertion for that clause.

Please still run the real suite in CI; the extraction shares the production lines but not
the production module graph.

🤖 Generated with Claude Code

[miga-heygen]

Verified end-to-end against the diff at 3374069 (fresh clone, merge-base 326df8d vs main, matches the stated +193/-5 over 3 files exactly).

Both self-reported defects, verified fixed:

• CaptureWarning.details.pendingCompositionIds?: string[] is genuinely declared on the type (packages/engine/src/types.ts:33), not just used under a loosened/any shape.
• The enumerate step's cast is replaced with a real, total normalisation (frameCapture.ts:1816): Array.isArray(evaluated) ? evaluated.map((id) => String(id)) : []. Traced every shape page.evaluate can return (array, object, null, undefined, false) — none throw. Confirmed the actual regression by mutation test: reverting to (evaluated as string[]).join(", ") reproduces the exact original break (TypeError: ids is not iterable inside pollSubCompositionTimelines), and the new test file's "degrades to no ids instead of throwing" case catches it. Restored, re-ran green (7/7).
• Ran the two previously-broken tests in frameCapture-subTimelinePoll.test.ts directly: 4/4 pass at this head.

Wiring traced, not assumed: onPending → session.pendingTimelineIds → recordSubTimelineWarning → session.warnings → applyRenderWarningPolicy (in renderOrchestrator.ts) → job.warnings, the same pre-existing pipeline every other warning code already uses (proven correct by existing coverage on audio_processing_failed/media_readiness_timeout). cloneCaptureWarning spreads details before deep-cloning the array fields it knows about, so pendingCompositionIds survives the clone, just not via a dedicated deep-copy line like sources/failureReasons get — a shallow-clone gap that isn't live today (the array is freshly literal-constructed at the call site) but worth a one-line addition to cloneCaptureWarning if this ever gets mutated post-clone. Nit, not blocking.

Script-failure branch correctly left alone: confirmed by reading the branch condition directly — scriptFailure ? <unchanged messages> : <new timeout message with the remedy>. The reasoning holds: a script-load/runtime failure means the timeline can never register regardless of data-no-timeline, so pointing at that opt-out there would misdirect the fix. Test asserts the message excludes "data-no-timeline" on this branch.

Pending-id list is bounded by the number of [data-composition-id] hosts on the page, same bound the pre-existing scriptLoadFailures field already carries — no new unbounded-payload risk.

CI: all required checks green at this head (Build, Lint, Preflight, all regression shards, CLI smoke). No prior reviews on this PR to be additive to.

Verdict: APPROVE
Reasoning: Both self-reported defects are genuinely fixed, the fix is proven by mutation test (not just present), the reporting path is now total for every observed input shape, and the script-failure branch's exclusion of the remedy is deliberate and correct.

— Miga