Skip to content

Commit 4ad5826

Browse files
authored
feat(lint): flag relative-value second writers and tl.set initial hides (#2612)
## What Part 2 of the GSAP seek-safety rules (stacks on #2611): the two rules that touch existing catalog content and required reconciliation with an existing rule. - `gsap_relative_value_second_writer` (error) — a relative var value (`y: "-=15"`) on a property whose target has another writer **active at the relative tween's start**. The relative base is captured at tween init, which reads a different partial state per seek path: sequential seek inits it mid-entrance, a cold render worker inits it at the entrance's end state, and the element teleports at chunk boundaries (production case: all scene nodes jumping ~20px mid-scene). Writers that complete strictly before the start are safe (children render in start-time order within a seek pass — verified against gsap 3.15.0) and are not flagged; neither are single-writer relatives, `from()`/`fromTo()`, build-time `gsap.set`, or relative position parameters (`"+=0.5"`). Selector resolution bails on combinators and cross-composition scoping rather than guessing. Findings aggregate per tween pair and report the overlap window. - `gsap_timeline_set_initial_hide` (warning) — initial-state hiding via `tl.set(target, vars, 0)` on a paused timeline is not rendered while the playhead sits at exactly 0, so frame 0 shows the unhidden state (verified against gsap 3.15.0: opacity stays 1 after `tl.time(0)`, applies only past 0). Exempt when the target is already hidden by authored CSS/inline styles or a standalone `gsap.set()`, and only sets preceding every tween in source order qualify (mutated position variables resolve to their initial binding in the parser — outro hard-kills don't masquerade as position-0 sets). - Reconciliation: `gsap_fullscreen_overlay_starts_visible`'s fixHint previously recommended exactly the flagged `tl.set(sel, {opacity:0}, 0)` pattern; it now recommends authored CSS hiding or immediate `gsap.set()`. - Docs for the full rule family in `docs/packages/lint.mdx`. ## Corpus impact (the reason this is its own PR) These two rules are the ones that fire on repo-shipped content: - `gsap_relative_value_second_writer`: 4 errors in `gooey-metaball`, all genuine overlaps. Measured with gsap 3.15.0: ballD diverges **3.31 xPercent / 1.99 yPercent (~8px/5px at 240px ball size)** between sequential and cold seek — a permanent base offset that appears as a teleport at a chunk boundary. Real but modest; happy to fix the block in a follow-up (start the drift at the entrance's end, or use absolute `fromTo`). - `gsap_timeline_set_initial_hide`: 10 warnings across the catalog after the CSS-hidden exemption (down from 54 pre-narrowing); spot-checked as genuine frame-0 pops with no authored hide (e.g. `vfx-text-cursor` `#phrase-b`). Adversarially reviewed the same way as #2611 (393-composition corpus + gsap semantics experiments); FP classes fixed and locked as negative tests: precede-only second writers, descendant/cross-composition selector mis-joins, CSS-hidden re-assertions, mutated position variables. ## Tests Full `packages/lint` suite green at 440 tests including multi-composition roots; `tsc`, oxlint, fallow audit clean.
1 parent f3d2100 commit 4ad5826

3 files changed

Lines changed: 608 additions & 2 deletions

File tree

‎docs/packages/lint.mdx‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -108,6 +108,19 @@ Detected issues include:
108108
- Deprecated attribute names
109109
- Missing composition dimensions (`data-width`, `data-height`)
110110
- Invalid `data-start` references to nonexistent clip IDs
111+
- Seek-order hazards that render differently on cold render workers: relative tween
112+
values (`"+=..."`) whose property has a second concurrent writer
113+
(`gsap_relative_value_second_writer`), `repeatRefresh` combined with relative values
114+
(`gsap_repeat_refresh_relative_value`), function-valued tween vars that measure the
115+
DOM or misuse the index parameter (`gsap_function_value_hazard`), DOM measurement
116+
reachable from timeline callbacks (`gsap_callback_dom_measurement`), and
117+
non-deterministic values like `gsap.utils.random()` / `"random(...)"`
118+
(`non_deterministic_code`)
119+
- SVG draw-on pitfalls: GSAP `strokeDasharray` writes on elements whose CSS declares a
120+
multi-component `stroke-dasharray` (`svg_drawon_css_dasharray_conflict`),
121+
`getTotalLength()` on paths with no `d` yet (`svg_measure_before_path_d`), and
122+
initial-state hides via `tl.set(..., 0)` that never render on frame 0
123+
(`gsap_timeline_set_initial_hide`)
111124

112125
<Info>
113126
For a full list of what the linter catches and how to fix each issue, see [Common Mistakes](/guides/common-mistakes) and [Troubleshooting](/guides/troubleshooting).

0 commit comments

Comments
 (0)