feat(core): spring physics solver + runtime fixes [2/6]

[miguel-heygen]

Summary

Damped harmonic oscillator with 5 presets. Runtime totalTime nudge fix for GSAP 3.x. Stale CSS offset cleanup on load. SpringEaseEditor UI.

Part 2 of 6 — spring physics + runtime reliability. Depends on PR 1.

Test plan

• Spring presets produce valid CustomEase data
• Elements visible at t=0 after page refresh (nudge fix)

[miguel-heygen]

• feat(studio): runtime-synced design panel + 3D props + split polish #1188
• fix(studio): overlay jump, delete-all, split polish [9/10] #1191
• feat(studio): runtime-first dynamic keyframe system [8/10] #1190
• feat(studio): split clip at playhead for media elements [7/10] #1189
• feat(studio): design panel, timeline polish, feature flag [6/6] #1172
• feat(studio): keyframe hooks wiring — session, cache, toolbar [5/6] #1171
• feat(studio): keyframe diamonds, navigation, context menu [4/6] #1170
• feat(studio): GSAP runtime bridge + optimistic updates [3/6] #1169
• feat(core): spring physics solver + runtime fixes [2/6] #1168 👈 (View in Graphite)
• feat(core): GSAP keyframe parsing, mutations, and API routes [1/6] #1167
• main

This stack of pull requests is managed by Graphite. Learn more about stacking.

[jrusso1020]

Spring solver is mathematically sound; the runtime nudge fix is correct; the stale-CSS-offset cleanup is well-targeted. But there's an important question about an apparent test deletion that needs explicit confirmation before this lands.

Important question — regression of #1174 fix?

The init.test.ts diff drops the entire sub-composition audio global start offset (regression #1174) describe block (3 tests, -82 lines). Concurrently, three call sites in init.ts switch from resolveStartForElement(rawEl, 0) to Number.parseFloat(rawEl.dataset.start ?? "") (lines ~1907, ~1974, ~2042 in the new file). The original #1174 fix added resolveStartForElement to sum ancestor composition-host offsets so sub-composition audio with data-start="0" and a host at data-start="10" would be scheduled at global t=10 instead of global t=0.

If dataset.start is now read raw at those call sites, the #1174 regression returns. Two possible explanations:

1. Regression: the #1174 fix is broken again. Need re-verification of "audio inside <div data-composition-id=slide-2 data-start=10> schedules at global t=10, not t=0".
2. Refactor: dataset.start is now always-already-global by the time those code paths execute (some earlier pass canonicalizes it). The other call sites still go through resolveMediaStartSeconds (the renamed resolveStartForElement) so the host-offset path lives in one place.

Could you confirm which one? If (2), worth a code comment at the changed lines explaining that dataset.start is canonical-global here, plus a regression test for the #1174 case (the assertion you kept in place is seekTimes.length >= 2 which doesn't cover the host-offset semantic).

If (1), the fix needs revisiting before merge.

Spring physics solver — clean

• Damped harmonic oscillator with proper case-splitting on ζ (underdamped / critically damped / overdamped).
• Test coverage is the right shape: critically damped → no overshoot (within 1.005), underdamped → overshoot present, overdamped → monotonic, x-values span [0,1] monotonically, all 5 presets generate valid output.
• Settle-duration cap at 10s + Math.max(decayRate, 0.01) floor for the overdamped case — defensive.

Minor: if (zeta === 1) is exact-equality on a float. User-supplied damping that lands at e.g. 0.999999 from arithmetic falls into the underdamped branch and produces a near-identical (but not identical) curve. Visually imperceptible since the three branches converge as ζ→1, but worth a comment that the case split is for analytical simplicity, not numerical precision.

Runtime totalTime nudge — clean

The "GSAP 3.x skips render when totalTime equals _tTime" workaround is exactly right. The 0.001 nudge value is hardcoded — worth a comment confirming why that magnitude (smaller risks GSAP's tolerance still rejecting; larger risks visible glitch for time-sensitive consumers like audio scheduling).

Stale CSS offset cleanup — clean but silent. If a Studio drag offset was authored against an element later wrapped in a GSAP tween, the offset is silently dropped on rebind. Consider a postRuntimeMessage({code: "stale_offset_stripped", details: {selector}}) diagnostic so authors can see when their offsets got overridden by tween adoption. Non-blocking.

Test baseline updates concern — dogs-captions doubling

packages/producer/tests/dogs-captions/output/output.mp4: 57MB → 101MB. Roughly 2× size for the same composition. Many other baselines shift but in normal ranges (5MB → 9MB for style-2/10/11 looks like a recompute, not a doubling). The dogs-captions case is suspicious. Per workspace memory feedback_hyperframes_producer_baselines_in_docker.md, baselines must be generated inside Dockerfile.test not on host. Confirm the docker:test:update path was used for these — host-generated baselines drift from CI and the dogs-captions blowup could be a Chrome version mismatch leaking into the encoded output.

Review by Jerrai (hyperframes specialist)