fix(sdk): moveElement survives GSAP animation per-axis via runtime delta translate

[vanceingalls]

Problem

A committed moveElement (which correctly writes data-x/data-y) did not durably reposition an element that is GSAP-animated on that axis. After a seek or reload, the element rendered with the animation's value on its animated axis and the editor's offset only on the non-animated axis — dragging an animated element kept only X or only Y. Root cause chain:

• data-x/data-y had zero render-time consumers — only the editor-model parser and generator touch them. Hosts (Pacific) papered over this with a CSS-translate shim.
• GSAP folds a CSS translate that is present at its first parse of an element into its cached transform and sets translate: none; an absolute tween then discards the folded value on the animated axis. Measured and reproduced (headless-Chrome spike, GSAP 3.15).
• A translate set after GSAP's first parse is never read, folded, or cleared across seeks — it composes natively with the animated transform, with zero accumulation. That timing rule is the fix.

This closes the 2026-06-29 HANDOFF (moveElement-survives-animation) and locks the edit-vs-time semantics: canvas edits apply at every point in time; the animation plays relative to the edited position. Keyframe-at-playhead editing stays a future explicit opt-in op.

Design

• handleMoveElement captures the pre-edit baseline once per element into data-hf-edit-base-x/y (inverse-symmetric; undo removes them).
• The runtime (new packages/core/src/runtime/positionEdits.ts) renders translate = (data-x − base, data-y − base) — a pure delta, so generator-built compositions that duplicate data-x into tl.set() don't double-apply, and the edit composes identically over GSAP tweens, tl.set positions, and CSS positioning.
• Applied at runtime init (covers GSAP-free / CSS / WAAPI / static compositions) and re-applied at every timeline bind (soft-reload / rebind paths). A WeakMap guard skips re-apply when the written translate was consumed externally (lazy-tween fold), preventing double-apply; editor commits force.
• Ships inside the runtime IIFE → covers CLI preview, embedded SDK consumers, and producer renders with one mechanism.
• The iframe adapter's drag channel now uses the same translate: applyDraft composes the pre-drag translate with the accumulated delta (visible drag in any composition, no host CSS needed — the old --hf-studio-dx/dy vars are no longer written, which also removes a 2× drag on compositions with the documented var-consuming bridge CSS), cancelPreview restores the raw inline value, and commitPreview mirrors the committed attributes onto the live element so the position holds without an srcdoc reload.
• New subpath export: @hyperframes/core/runtime/position-edits.

Hardening (from high-effort adversarial review, all fixed in the second commit)

• Edits render with no usable GSAP timeline (apply at init, not only inside the boundDuration > 0 bind branch).
• Rebind double-apply after a lazily-created tween folds the translate — guarded.
• 2× drag with the authored CSS-var drag bridge — var writes removed, docs updated.
• Switching applyDraft to a new id reverts the abandoned element.
• cancelPreview never promotes a stylesheet-authored translate to a permanent inline style.
• commitPreview reverts the draft when dispatch throws.

Known limitation (documented in the module)

A tween created lazily at runtime that first-parses a marked element after the apply folds the edit (degrades to the pre-existing fold-loss, never double-applies).

Verification

• Browser acceptance test packages/engine/scripts/test-runtime-position-edits-browser.ts (real Chrome + GSAP + runtime IIFE, plain embedded runtime, no Studio shell): X-animated, Y-animated, and static elements hold both edited axes at every sampled time across the full seek range (exact expected values), plus a GSAP-free composition renders the edit at init.
• Suites: core 972, SDK 393, studio 1229 (+18 todo), test:hyperframe-runtime-ci chain, engine + SDK typecheck — all green.
• oxlint / oxfmt clean; fallow audit --gate new-only: 0 new findings.

🤖 Generated with Claude Code

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
hyperframes	🟢 Ready	View Preview	Jul 2, 2026, 8:58 PM

💡 Tip: Enable Workflows to automatically generate PRs for you.

[miga-heygen]

Review — SDK edit fix: moveElement survives GSAP animation per-axis

Verdict: LGTM ✅

This is a really well-engineered fix for a subtle and nasty bug. GSAP folds any CSS translate present at first parse into its cached transform and discards it on animated axes — so SDK moveElement edits were silently lost per-axis. The fix is a runtime delta-translate mechanism that composes additively after GSAP's initial parse, using the independent CSS translate longhand.

What's good

• Root cause is spot-on: handleMoveElement captures a pre-edit baseline on first edit, and positionEdits.ts renders the delta at runtime via translate longhand — the only mechanism that composes with GSAP without fighting its cache.
• GSAP-fold detection via WeakMap (lastAppliedTranslate) is the minimal guard against double-apply without GSAP introspection. Clean.
• Iframe drag channel rewrite: direct translate instead of the old --hf-studio-dx/dy CSS custom properties, with proper revert/cancel/commit semantics. _mirrorCommittedMove correctly uses _draftPrevTranslate (captured at drag start) rather than the current inline value (which would be the draft-composed value). Subtle correctness point, handled correctly.
• Inverse/undo in mutate.ts correctly removes baseline attributes via null-valued inverse patch — verified by the test.
• Idempotency: applyPositionEdits fires at both init and timeline-bind, covering GSAP-free and post-parse windows. Capture-once via EDIT_ORIGINAL_TRANSLATE_ATTR + WeakMap fold guard ensures no double-apply. Comments explain the dual-call well for future maintainers.
• Test coverage is exceptional: unit tests for compose/apply logic, iframe adapter draft/commit/cancel lifecycle, mutate baseline capture/inverse, AND a real-browser acceptance test with GSAP + runtime IIFE validating computed positions at 4 time samples across 3 element types with 0.5px tolerance.

Ponytail

• splitTopLevelWhitespace duplication is justified — runtime IIFE can't import studio code. Fallow-ignore comment documents the isolation.
• readCurrentTranslate try/catch for cross-origin iframe edge cases — necessary.
• num() helper: parseFloat(value ?? "") would achieve the same as the null guard + Number.isFinite check, but behavior is identical either way. Pure nit.
• Lean already. Ship.

12 files changed, +858 / −61

[miguel-heygen]

Audited the runtime position-edit path, SDK iframe draft/commit path, mutation baseline capture, export wiring, and the browser acceptance test. The key contracts line up: moveElement captures a first-edit baseline, runtime renders the data-x/y delta through CSS translate after init/timeline-bind, iframe drafts use the same composition path without leaving stale draft state, and inverse patches remove the baseline attributes. CI is green, including SDK/core tests, browser/runtime checks, and regression shards.

Non-blocking note: the lazy-GSAP-first-parse limitation is documented in positionEdits.ts; if we ever support late-created tweens on edited elements, that path needs a separate strategy. Not a blocker for the current bug.

— Magi

Verdict: APPROVE
Reasoning: The fix targets the GSAP per-axis loss at the right boundary, keeps editor live-preview semantics coherent, and has focused unit plus real-browser coverage for the failure mode.

[james-russo-rames-d-jusso]

Reviewed at fe9459149b17e0373104c0c44d9e653ba77f11ff (second-pass; layered under Miga's LGTM + Miguel's APPROVE from earlier today).
Note: PR body 🤖 footer + both commits (2506c94f15, fe9459149b) carry Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> trailers; HF convention flags these — worth git rebase -i before merge if not squash-merging.

Summary — Second-pass on top of the domain team's approval. I focused on cross-cutting angles they naturally deprioritized: observability on the documented degradation path, cross-repo bridge coordination, subpath-export completeness, browser-test coverage of the boundary case that ORIGINATED the bug, and third-party SDK consumer backwards-compat. Miga's + Miguel's coverage of the core mechanism (delta-translate math, iframe draft/commit lifecycle, inverse-symmetric baseline, WeakMap fold guard, idempotency at init + timeline-bind) is complete and I have nothing to add there.

Cross-repo status confirmed clean-additive: grepped Pacific + all heygen-com/* — the only remaining --hf-studio-dx/--hf-studio-dy references live inside heygen-com/hyperframes itself (the docs and iframe.ts refs are all updated to describe the new translate-based path). No paired Pacific PR required; the removed vars simply become inert without breaking any downstream reader.

Subpath export @hyperframes/core/runtime/position-edits verified complete in packages/core/package.json at HEAD — declared in both dev exports (bun/node/import/types → .ts) and publishConfig.exports (import/types → .js/.d.ts). No subpath-trap.

Second-pass concerns

• 🟡 packages/core/src/runtime/positionEdits.ts:97-103 — silent degradation on the documented lazy-tween fold-loss path. Miguel flagged the limitation non-blocking; my concern is that when it hits in prod, a customer sees "my moveElement didn't stick" with zero diagnostic signal. The WeakMap-guard early-return here is exactly the "lazy tween first-parsed after apply and folded the translate" case — silent skip degrading to fold-loss. init.ts:3,39 already imports emitAnalyticsEvent + swallow; a one-line emitAnalyticsEvent("moveedit_fold_loss", { hfId: el.getAttribute("data-hf-id") ?? null }) at the skip site turns an invisible partial failure into an observable one. Cheap; helpful for the eventual "we should support late-created tweens" workstream Miguel already noted.

• 🟡 packages/engine/scripts/test-runtime-position-edits-browser.ts:107-113 — both-axis-animated element uncovered. Fixture has #ax (X-only tween), #ay (Y-only), #st (static). Missing: an element animated on both axes in the same tween (gsap.fromTo("#axy", { x:0, y:0 }, { x:400, y:300, duration:4 })). This is the intersection case where per-axis fold-loss ORIGINATED per the PR body ("dragging an animated element kept only X or only Y" — implies both axes actively animated is the common shape). Adding #axy with the same 4-time-sample assertion pattern is ~10 lines and closes the last obvious geometry gap. Also worth considering: a gsap.set("#el", { x: 200 }, 1.0) at a specific time (tl.set), since the PR body explicitly claims the fix "composes identically over GSAP tweens, tl.set positions, and CSS positioning" but only the tween path is asserted in-browser.

• 🟡 AI-authorship trailers. PR body ends with 🤖 Generated with Claude Code; both commits (2506c94f15, fe9459149b) carry Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>. HF convention typically strips these — worth an interactive rebase before merge, or use squash-merge with a cleaned message.

Questions

• ↩️ packages/core/src/runtime/positionEdits.ts:110-118 — when a customer's OWN code writes an inline translate: 10px 20px before runtime init AND the element carries data-hf-edit-base-x/y (e.g. a third-party SDK consumer chose to persist HF-style baseline attrs alongside their own translate authoring), the first applyPositionEditToElement captures 10px 20px into EDIT_ORIGINAL_TRANSLATE_ATTR and additively composes the delta. That's semantically correct (customer's translate is preserved + edit stacks on top), but I want to check the intent — is composition-with-customer-authored-translate a supported contract, or should we detect + warn that HF is treating their inline translate as a baseline? I don't have evidence of a real consumer doing this today; asking because the SDK subpath is now public.

What I didn't verify

• Did NOT re-verify what Miga + Miguel covered: delta-translate math, composeTranslate correctness across all 4 branches, iframe adapter draft/commit/cancel state machine, _mirrorCommittedMove using _draftPrevTranslate, inverse-symmetric baseline, unit test suites.
• Did NOT check packages/engine/scripts/test-runtime-position-edits-browser.ts fixture beyond scenario coverage — assuming Miga's "exceptional test coverage" call on the assertion mechanics.
• Did NOT trace GSAP's internal 3.15 fold behavior — trusting the PR body's spike claim + Miguel's audit.
• Did NOT run the browser acceptance test locally; CI green covers it (all 40+ required checks pass at HEAD).

— Rames D Jusso

[vanceingalls]

Thanks all — feedback addressed in the latest commit:

@james-russo-rames-d-jusso (Rames):

• Fold-loss observability — done: the fold-guard skip site now emits a position_edit_fold_skipped runtime analytics event (new member of RuntimeAnalyticsEvent) carrying the element's data-hf-id, so the degradation is visible instead of "my edit didn't stick".
• Both-axis + tl.set coverage — done, and your tl.set suggestion caught a real gap: a positioned tl.set("#el", {x,y}, 1.0) first-parses the element at seek time — after the translate apply — and folded the edit (test initially failed with x=200, expected 250). Fixed properly rather than weakening the claim: applyPositionEditToElement now primes GSAP's transform cache (gsap.getProperty(el, "x")) before the first apply, so tweens and positioned set()s that first render later reuse the cache and never fold. The acceptance test now covers X-only, Y-only, both-axis, positioned tl.set, static, and GSAP-free elements — all holding both edited axes across the full seek range. The residual limitation narrows to "GSAP itself loads after the apply", which the fold guard degrades safely (skip + telemetry, never double-apply); module header updated.
• AI-authorship trailers — noted; suggest squash-merge with a cleaned message rather than rewriting the reviewed commits.
• Question (customer-authored inline translate + persisted baseline attrs) — composition-with-authored-translate is the intended contract, not an accident: the capture-once data-hf-edit-original-translate baseline exists precisely so an authored translate (inline or stylesheet, via the computed fallback) is preserved and the edit delta stacks on top. That's also what the adapter relies on for drag composition (see the -50% -50% centering test). Consumers hand-authoring data-hf-edit-base-x/y alongside their own translate get well-defined additive behavior. No warning added — it would fire on the supported path.

@miga-heygen: num() simplified to parseFloat(value ?? "") as suggested.

@miguel-heygen: the lazy-tween limitation you flagged is now substantially closed by the parse priming above — late-created tweens on edited elements compose correctly as long as GSAP was loaded when the edit was applied.

[miguel-heygen]

Reviewed the R2 delta at 38876885.

Verified the two prior follow-ups are addressed: the fold-skip guard now emits position_edit_fold_skipped through runtime analytics at the skip site, and the browser acceptance fixture now covers X-only, Y-only, both-axis GSAP, positioned tl.set, static, and GSAP-free paths. Also verified the GSAP cache priming is best-effort before the first translate write and stale --hf-studio-dx/dy consumers are grep-clean in HyperFrames/Pacific. CI is green.

Verdict: APPROVE
Reasoning: The incremental fix closes the prior coverage and observability gaps without changing the accepted runtime contract.