feat(cli): add --at-transitions to inspect for sampling at tween boundaries

[leorivastech]

Summary

Fixes #1380. inspect samples evenly spaced timestamps, so a sub-second overlap window at a transition boundary slips between samples by construction — no sample count fixes that. This adds the proposed --at-transitions mode.

What it does

With --at-transitions, inspect collects every tween start/end boundary from the registered timelines (window.__timelines, via getChildren() — the same mechanic runtime/timeline.ts uses for scene ranges) and samples at each boundary plus the midpoint of every segment between consecutive boundaries, in addition to the existing even spacing.

The midpoints matter: sampling exactly at a boundary can land on an element at opacity 0. In the issue's repro, t=11.35 shows capB still invisible — the midpoint t≈11.45 has both captions half-visible at the same position, which is where the overlap is undeniable. The unit tests use that exact repro shape.

Implementation notes: nested tween times are converted to the registered timeline's coordinates by climbing the parent chain (startTime + timeScale per ancestor, invoked bound — GSAP getters read internal state through this); GSAP-only — adapters without getChildren are skipped gracefully. Every collected boundary is sampled by default. An optional --max-transition-samples caps the count; when it truncates, the omitted count is reported as a console warning and as transitionSamplesDropped in the JSON output (always present with the flag, 0 when coverage was complete).

Design choices left open (happy to flip any of these)

• Opt-in flag, additive: v1 changes nothing for anyone not passing the flag, and boundary samples add to even spacing rather than replacing it (even samples keep whole-timeline coverage for static issues). If you'd rather have this as default behavior with a --no-transitions opt-out — trivial flip on the same machinery.
• CSS/WAAPI boundaries (document.getAnimations()) would be a natural follow-up for non-GSAP compositions.

Verification

• layoutAudit.test.ts — 16/16 pass (new cases include the issue's repro shape, a 200-tween dense shape sampled in full with no cap, and the explicit cap reporting the exact omitted count)
• End-to-end against packages/producer/tests/gsap-letters-render-compat: default returns transitionSamples: [0, 0.65, 1.3, 1.9, 2.5, 3.1, 3.7] with transitionSamplesDropped: 0; --max-transition-samples 3 returns 3 samples (extremes kept) with dropped: 4 plus the console warning; without the flag, output is byte-identical to current behavior.
• typecheck on @hyperframes/cli passes; oxlint / oxfmt --check clean; fallow audit gate clean.

[miguel-heygen]

Thanks for picking this up. I think this needs one correctness fix before merge: --at-transitions is documented and titled as sampling every tween start/end boundary, but buildTransitionSampleTimes silently caps the transition-derived samples at 40 using an evenly-strided subset. On a dense timeline, that means the new mode can still skip the specific short boundary window it was added to catch, with no warning or dropped-count metadata in the CLI output. Please either sample all collected transition times, or expose an explicit cap/dropped count and make the default high enough for the issue shape so users are not told they sampled transitions when some were omitted.

[leorivastech]

Agreed on all points — the silent cap contradicts the flag's promise. I have time right now, so on it: default will sample every collected boundary (no cap), with an optional --max-transition-samples that, when it truncates, reports a dropped count both in the console output and as JSON metadata. Update incoming shortly.

[leorivastech]

Done in e41b795 — went with both halves of your either/or:

• Default now samples every collected boundary — no cap. Anyone passing --at-transitions is explicitly asking for the deep pass; correctness wins.
• The cap still exists but only behind the new --max-transition-samples flag, and when it truncates it's loud: a console warning with the omitted count, and transitionSamplesDropped in the JSON (always present with the flag, 0 when coverage was complete).

Verified E2E on the gsap-letters fixture: default returns all 7 samples with dropped: 0; --max-transition-samples 3 returns 3 (extremes kept) with dropped: 4 and the console warning. Tests updated: no-cap samples all 399 of a 200-tween shape; explicit cap reports the exact omitted count.

[leorivastech]

Heads up: commits need signatures to be mergeable (flagged on #1385) — setting up signing now and will re-push this branch signed as well.

[leorivastech]

Branch re-pushed with both commits signed and Verified (same content, no code changes — commit SHAs changed from the re-sign: 3cdb022 + a497a5c).