feat(lint): add gsap_studio_edit_blocked rule for manual timeline + GSAP element targeting

[vanceingalls]

Summary

Adds a new gsap_studio_edit_blocked lint rule that fires when a composition is edited manually (drag, resize, text edit) but the target element is animated by GSAP.

Manual edits to GSAP-controlled elements are silently overwritten at runtime because GSAP owns the transform/style — the edit appears to stick in the editor but vanishes on play. This rule surfaces that conflict at composition-lint time rather than confusing the author at preview time.

Rule behavior

• Detects elements targeted by gsap.to, gsap.from, gsap.fromTo, gsap.set, or gsap.timeline() tweens
• Fires on inline-style edits that overlap properties GSAP animates (position, transform, opacity, etc.)
• Reports the conflicting property and the GSAP tween that owns it
• Severity: warn (not error) — the edit may be intentional as a baseline

Test plan

• bun test packages/core — lint rule tests pass
• Manual: composition with gsap.to("#el", {x: 100}) + drag edit on #el → lint warning appears

🤖 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
• feat(lint): add gsap_studio_edit_blocked rule for manual timeline + GSAP element targeting #1345 👈 (View in Graphite)
• 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.

[miguel-heygen]

Clean, focused PR. The rule correctly gates on TIMELINE_REGISTRY_ASSIGN_PATTERN before scanning for mutation selectors, so it won't fire noise on scripts that use GSAP without registering timelines. Tests cover the four meaningful combinations (both conditions, each condition alone). A few items:

P2 — Rule fires one finding per script block, not per composition

GSAP_MUTATION_SELECTOR_RE collects selectors from the whole script and emits a single finding. If a page has two registered timelines in two separate <script> blocks, a selector in the second block that only targets elements of the first composition gets flagged even if it poses no studio-edit risk for its own composition. Given the current hyperframes pattern (one script per composition), this is likely fine in practice — but worth noting if multi-composition pages become a use case.

P2 — Regex matches inside string literals and comments

GSAP_MUTATION_SELECTOR_RE will match .to("#headline" inside a comment or a string variable like const doc = 'tl.to("#foo", ...)';. stripJsComments removes block/line comments before the check (good), but string literals aren't stripped. For .set/.to/.from/.fromTo in a string constant that's never called, this is a false positive. In the wild this is rare, but worth a note for future robustness.

P3 — TIMELINE_REGISTRY_ASSIGN_PATTERN reset between scripts

The TIMELINE_REGISTRY_ASSIGN_PATTERN regex is stateful (it has the i flag but not g, so .test() is safe). This is fine as written; just confirming the test call doesn't leave a sticky lastIndex.

P3 — fixHint text mentions "hyperframes runtime registers timelines automatically"

That statement is accurate for the composited runtime but may confuse users of the standalone SDK who see this in their own hand-authored scripts. Minor doc nit, not a blocker.

Overall: ✅ approve with the P2 notes above as awareness items.

[james-russo-rames-d-jusso]

Reviewed at 8024563. Bottom of the stack — adds a gsap_studio_edit_blocked lint warning. Clean rule, tightly scoped, well-tested.

LGTM. One small observation + one CI blocker.

Strengths

• Two-signal gate. The rule only fires when BOTH TIMELINE_REGISTRY_ASSIGN_PATTERN matches (script registers a timeline on window.__timelines) AND there's at least one .set|.to|.from|.fromTo("#id"|".class", ...) call. Both halves of the runtime contract have to be present — no false-positives from unregistered tweens or empty timelines.
• 5 test cases cover the discriminator surface: positive on #id, positive on .class, negative on no-selector timeline, negative on selector-without-registration, message-content lockdown for unique-target listing. The negative cases are the more valuable ones — they pin what shouldn't fire.
• stripJsComments applied first so commented-out tl.to(...) lines don't false-trigger. Inherits the existing GSAP-rule discipline.
• severity: "warning" is the right call — the GSAP-owns-position pattern is sometimes intentional (e.g. choreographed entrance), and the surface here is "you're about to lose drag edits silently," not "your composition is broken."
• fixHint is genuinely actionable — names the three escape hatches (don't register manually, use CSS for visibility, avoid drag-editing GSAP-owned elements). Future-author won't have to dig.

Observations (non-gating)

• Regex misses attribute selectors. GSAP_MUTATION_SELECTOR_RE requires # or . as the first char — so tl.to("[data-x]", {...}) is a valid GSAP target that won't trigger this lint, even though Studio's isElementGsapTargeted may still skip these elements at drag time. Most GSAP code does use #/. so the practical coverage is fine, but worth a follow-up if attribute-selector-targeted tweens turn out to be a common pattern.
• Bottom-of-stack means the runtime side (#1346) verifies the rule's claim. The message says "Studio cannot save drag/resize edits to these elements" — that claim depends on the runtime intercept that #1346 wires up. Stack alignment is fine since they land together.

Blocker

• Preflight (lint + format) fails on this PR: error: lockfile had changes, but lockfile is frozen. The lockfile in the tree is the SDK Phase 3a base's bun.lock, which appears stale relative to main. Likely needs a rebase or for the lockfile bump in #1350 to propagate down the stack. Not a code issue — but blocks the merge gate.

What I verified

• Diff: 3 files, +151/-1.
• Rule integrates with the existing gsapRules: LintRule<LintContext>[] array and uses the established TIMELINE_REGISTRY_ASSIGN_PATTERN + stripJsComments utilities from utils.ts.
• All 5 unit tests test the rule's specific code path (no incidental coverage from upstream rules).
• The // fallow-ignore-file code-duplication markers added to adapters.test.ts and gsap.test.ts are housekeeping for cross-file test-fixture overlap — unrelated to the lint rule itself.

What I didn't verify

• Ran bun test packages/core locally — trust the unit test signal from the file.
• The runtime-side isElementGsapTargeted matcher in #1346 — assumed to be selector-pattern-compatible with this rule's matcher.

— Review by Rames D Jusso

[miguel-heygen]

Clean, focused PR. The rule correctly gates on TIMELINE_REGISTRY_ASSIGN_PATTERN before scanning for mutation selectors, so it won't fire noise on scripts that use GSAP without registering timelines. Tests cover the four meaningful combinations (both conditions, each condition alone). A few items:

P2 — Rule fires one finding per script block, not per composition

GSAP_MUTATION_SELECTOR_RE collects selectors from the whole script and emits a single finding. If a page has two registered timelines in two separate <script> blocks, a selector in the second block that only targets elements of the first composition gets flagged even if it poses no studio-edit risk for its own composition. Given the current hyperframes pattern (one script per composition), this is likely fine in practice — but worth noting if multi-composition pages become a use case.

P2 — Regex matches inside string literals and comments

GSAP_MUTATION_SELECTOR_RE will match .to("#headline" inside a comment or a string variable like const doc = 'tl.to("#foo", ...)';. stripJsComments removes block/line comments before the check (good), but string literals aren't stripped. For .set/.to/.from/.fromTo in a string constant that's never called, this is a false positive. In the wild this is rare, but worth a note for future robustness.

P3 — TIMELINE_REGISTRY_ASSIGN_PATTERN reset between scripts

The TIMELINE_REGISTRY_ASSIGN_PATTERN regex is stateful (it has the i flag but not g, so .test() is safe). This is fine as written; just confirming the test call doesn't leave a sticky lastIndex.

P3 — fixHint text mentions "hyperframes runtime registers timelines automatically"

That statement is accurate for the composited runtime but may confuse users of the standalone SDK who see this in their own hand-authored scripts. Minor doc nit, not a blocker.

Overall: ✅ approve with the P2 notes above as awareness items.

The base branch was changed.