fix(studio,core): persist manual position edits for GSAP-owned elements

[vanceingalls]

Summary

Fixes manual position edits (drag, resize) being lost on page refresh for elements animated by GSAP.

GSAP folds translate / x / y into its own transform cache and overwrites inline styles on every tick. Studio's path-offset patches stored translate: <px values> on the element, but GSAP wiped them at playback start — edits appeared to save but vanished after refresh.

Changes

manualEditsDom.ts

• reapplyPathOffsets: skips GSAP-animated elements (uses gsapAnimatesTransform(el), not just x/y check)
• applyStudioPathOffset: GSAP branch sets translate: none to yield ownership back to GSAP, then calls syncGsapOwnedTransformPosition() to apply the offset via gsap.set(el, {x, y})
• New syncGsapOwnedTransformPosition(): reads --hf-studio-offset-x/y CSS vars → calls gsap.set(el, {x, y})

manualEditsDomPatches.ts

• buildPathOffsetPatches: emits var(--hf-studio-offset-x, 0px) var(--hf-studio-offset-y, 0px) as the translate value when the live translate is none (GSAP-owned) but offset vars exist — persists the offset in a form GSAP can pick up on restore

manualEditsSnapshot.ts

• Captures gsapX/gsapY via gsap.getProperty() when element is GSAP-owned
• Restores via gsap.set() on rollback so undo/redo works through GSAP's cache

Test plan

• Drag a GSAP-animated element → save → refresh → element stays in new position
• Undo drag → element returns to original GSAP position
• Non-GSAP elements: drag still works as before (no regression)

🤖 Generated with Claude Code

[vanceingalls]

• fix(sdk,core): css tokenizer, override-set replay, setattribute safety, persist errors #1350
• fix(studio): watch external project dirs so preview ETag invalidates #1347
• fix(studio,core): persist manual position edits for GSAP-owned elements #1346 👈 (View in Graphite)
• feat(lint): add gsap_studio_edit_blocked rule for manual timeline + GSAP element targeting #1345
• feat(sdk): session API, optional history + persist-queue, adapters — Phase 3a complete #1325
• feat(sdk): scaffold @hyperframes/sdk — engine layer (model, RFC 6902 patches, mutate, apply-patches) #1324
• feat(core): expose hf-ids as subpath export for @hyperframes/sdk #1323
• main

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

[james-russo-rames-d-jusso]

Reviewed at 28a9e5c. Persists manual position edits for GSAP-owned elements end-to-end (live commit + reload + undo/redo). The GSAP CSSPlugin transform-cache semantics are correctly identified and the fix routes through three layers (live DOM, persisted source, snapshot/restore).

LGTM with two non-gating concerns + the same CI blocker as #1345.

Strengths

• Root cause identified correctly. GSAP's CSSPlugin folds CSS translate longhand into its internal transform cache at first tween init and writes translate: none every tick. Manual edits written as translate: <px> get wiped on the next tick. The PR doesn't fight the ownership — it yields it back to GSAP and routes the offset through GSAP's cache instead.
• GSAP_TRANSFORM_PROPS is the right widening. Old code checked only x/y; new code checks anything that affects the transform stack (x/y/xPercent/yPercent/scale/scaleX/scaleY/rotation/rotate/rotationX/rotationY/skewX/skewY/transform). Captures the actual ownership semantics — GSAP owns the whole stack the moment it tweens ANY transform prop, not just x/y. Opacity-only tweens correctly continue to fall through to the CSS path (not in the list).
• Three-layer routing is consistent. applyStudioPathOffset → live commit via gsap.set + translate: none. buildPathOffsetPatches → persisted source via var(--hf-studio-offset-x, 0px) var(--hf-studio-offset-y, 0px) translate (so reload re-folds through GSAP init). captureStudioPathOffset + restoreStudioPathOffset → undo/redo through gsap.set. All three paths agree on which elements GSAP owns (via gsapAnimatesTransform).
• StudioPathOffsetSnapshot.gsapX/gsapY: number | null — typed correctly with null as the "GSAP doesn't own this" sentinel. Restore path checks previous.gsapX != null || previous.gsapY != null before calling gsap.set, which is the right discriminator.
• STUDIO_GSAP_DRAG_INTERCEPT_ENABLED env flag with false default — gates the three intercept commits (path-offset, box-size, rotation) consistently and lets isElementGsapTargeted short-circuit to treat all elements as un-targeted. Sensible escape hatch for the keyframe-intercept work that's not yet hardened.

Concerns (non-gating)

• patchStyleAttrString in sourceMutation.ts uses naïve split(";") — the SAME bug #1350 fixes. Stacking lands #1346's helper, then #1350 replaces it with a proper tokenizer. Brief landing of a known-broken helper inside the stack is fine since they merge together, but worth being explicit in the PR body (or in #1350) that this is intentional cross-PR sequencing. As-is, a reader of #1346 alone would not realize the helper is provisional.
• syncGsapOwnedTransformPosition re-checks gsapAnimatesTransform — fine, but the caller (applyStudioPathOffset) already confirmed it before calling. Internal double-check is defensive but redundant. Minor.

Nit

• No unit test for the new live-DOM GSAP cache push. The manualEditsDomPatches.test.ts tests the patch-builder side (which emits the var() translate), but no test stubs window.gsap = { set: vi.fn() } and asserts applyStudioPathOffset invokes it with the offset. The reload path is tested implicitly via the patch shape, but the live path is uncovered. Worth a happy-dom test as follow-up — locks down "Studio writes via gsap.set when GSAP owns" so a future refactor of syncGsapOwnedTransformPosition can't silently regress.

Blocker

• Preflight (lint + format) fails on this PR: same error: lockfile had changes, but lockfile is frozen cascade as #1345. Bun lockfile drift from the SDK Phase 3a base. Address before landing.

What I verified

• Diff: 12 files, +185/-16.
• gsapAnimatesProperty(el, ...GSAP_TRANSFORM_PROPS) semantics: signature is "any of these props" (per the existing fn's variadic shape), so passing the spread checks if ANY transform prop is tweened — correct widening.
• applyStudioPathOffsetDraft GSAP path also widened from gsapAnimatesProperty(el, "x", "y") to gsapAnimatesTransform(element) — consistent.
• The patch builder's translate fallback (var(--hf-studio-offset-x, 0px) var(--hf-studio-offset-y, 0px)) is well-formed CSS shorthand and the GSAP CSSPlugin will fold the resolved values at init. The 0px defaults guard against unset vars.
• Snapshot/restore round-trip math checks out: captures gsap.getProperty(el, "x"|"y") as numbers (Number() coerces, || 0 on NaN); restores via gsap.set with the captured values.

What I didn't verify

• Did NOT run a live drag-save-reload locally — the comment trail and unit-test coverage make me confident, but empirical confirmation belongs in the test-plan checklist Vance has on the PR body.
• Did NOT verify the lint rule from #1345 fires on the same element selectors that this PR's isElementGsapTargeted runtime check skips — assumed Vance authored both with matching selector semantics.
• Did NOT verify readStudioPathOffset returns the just-written CSS var (read-after-write on inline style should be synchronous, but I didn't trace).

— Review by Rames D Jusso

[miguel-heygen]

Good fix — the root cause is clearly identified (GSAP bakes CSS translate into style.transform at init and writes translate: none every tick) and the solution is correctly threaded through snapshot/restore, draft positioning, patch building, and commit. The STUDIO_GSAP_DRAG_INTERCEPT_ENABLED guard is a safe escape hatch.

P1 — syncGsapOwnedTransformPosition has a redundant gsapAnimatesTransform guard

In applyStudioPathOffset, the call to syncGsapOwnedTransformPosition is already inside an if (gsapAnimatesTransform(element)) branch. Inside the helper, the check fires again: if (!gsapAnimatesTransform(element)) return;. Not a correctness bug here, but the double-check indicates the guard invariant isn't clearly documented — a future refactor moving the call site could silently drop the outer guard and the inner guard would paper over it. The inner guard should be kept for defensive safety, but a comment like // already checked by caller — defensive guard would clarify intent.

P2 — Snapshot gsapX/gsapY captures live GSAP cache, not the pre-draft committed baseline

captureStudioPathOffset is called at drag-start and snapshots gsap.getProperty(el, "x"). If a prior uncommitted drag already moved the element via gsap.set, the snapshot records the mid-session position rather than the last committed value. On rollback, restoreStudioPathOffset restores to the mid-session origin, not the true pre-drag baseline. This matches the existing CSS snapshot contract (which also snapshots live inline styles), but it should be documented as an invariant in the type comment for gsapX/gsapY.

P2 — buildPathOffsetPatches: empty-string inlineTranslate falls through to the var() branch silently

const translateValue =
  inlineTranslate && inlineTranslate !== "none"
    ? inlineTranslate
    : hasOffsetVars
      ? `var(...)`
      : null;

inlineTranslate && ... is falsy for "", so an empty string lands in the hasOffsetVars branch and emits the var-based fallback. That's probably correct, but !inlineTranslate || inlineTranslate === "none" states the intent explicitly.

P3 — STUDIO_GSAP_DRAG_INTERCEPT_ENABLED is undeclared in env.d.ts

The new env flag doesn't appear in the Vite env type declarations. TypeScript will accept the string lookup but lose type safety on the value. Worth adding to the VITE interface.

Overall solid fix for a genuinely tricky GSAP ownership problem. P1/P2 are code-quality flags, not correctness blockers. Approving.

The base branch was changed.