Skip to content

Commit f3d2100

Browse files
authored
feat(lint): seek-order safety and SVG draw-on rules for GSAP timelines (#2611)
## What Five lint rules (plus one extended core pattern) for GSAP defect classes that pass every existing check but break rendered output — the narrow, corpus-clean half of what was originally one PR (split per review; part 2 with the two catalog-touching rules stacks on top as #2612). - `gsap_repeat_refresh_relative_value` (error) — `repeatRefresh: true` + relative value re-captures and accumulates per iteration; a cold seek into iteration N skips the accumulation (verified with gsap 3.15.0: sequential 47.5 vs cold 17.5). - `gsap_function_value_hazard` (error/warning) — function values that call a method on the first parameter (GSAP passes `(index, target, targets)` — the first param is a number, so `(el) => el.getTotalLength()` throws and aborts the seeked frame) or measure the DOM: transform-sensitive reads (`getBoundingClientRect`, `getComputedStyle`, `gsap.getProperty`) are errors; transform-invariant layout reads (`offsetWidth`, `getBBox`, ...) are warnings. Pure-index arithmetic, `gsap.utils.wrap/distribute`, dataset/attribute reads, and closures over build-time constants are exempt. - `gsap_callback_dom_measurement` (warning) — DOM layout measurement reachable from `tl.add()`/`tl.call()`/`eventCallback`/`onStart|onUpdate|...` via a two-hop named-function scan. The capture path seeks with `suppressEvents: false`, so callbacks re-fire on every seek and measured geometry is seek-order-dependent. `gsap.getProperty`-driven derived output (scramble/typewriter patterns) is exempt. - `svg_measure_before_path_d` (error/warning) — `getTotalLength()` on a `<path>` with no static `d`: error when no `d` assignment exists anywhere (returns 0 in Chrome, silently killing dash animations); warning when assignments exist only inside function bodies. Recognizes `setAttribute`, GSAP `attr: { d }`, and CSS `d: path()`. - `svg_drawon_css_dasharray_conflict` (error) — GSAP `strokeDasharray` on an element whose CSS declares a multi-component `stroke-dasharray`. GSAP merges per component, so `strokeDasharray: pathLength` computes to `"641.4px, 10px"` — the gap stays 10px, the hide-then-reveal hides only 10px, and the line stays visible all scene with a crawling notch. One of this repo's own producer fixtures has this exact bug (true positive from the corpus run). - `gsap.utils.random()` and `"random(...)"` string tween values added to `non_deterministic_code` (core) — each worker inits independently, so the same tween resolves different randoms across chunks. Both motivating production bugs (nodes teleporting at chunk boundaries; a draw-on line visible all scene) are minimally reproduced in the tests. ## Review hardening Two independent adversarial reviews ran before submission: a false-positive hunt over all 393 compositions in this repo plus 23 constructed adversarial snippets (with gsap 3.15.0 semantics experiments), and a maintainer-conventions pass. Fixed FP classes are locked in as negative tests: all-interpolation template ids, GSAP attr-plugin `d` writes, getProperty-driven callbacks, transform-invariant marquee reads. Corpus residue for these five rules: **1 error (a genuine dasharray bug in a producer fixture, happy to fix in a follow-up) and 2 warnings** (real layout reads in callbacks). ## Tests `packages/lint` green at this commit in isolation; `tsc`, oxlint, fallow audit clean. ## Notes for reviewers - All rules follow the file's conservative philosophy: anything not statically resolvable is skipped; false negatives over false positives. - Open question: should the cold-seek family gate on `HyperframeLinterOptions.distributed` (error when distributed, warning otherwise), following the `system_font_will_alias` precedent? Happy to wire either way.
1 parent 0561adc commit f3d2100

4 files changed

Lines changed: 1347 additions & 45 deletions

File tree

‎packages/lint/src/rules/core.test.ts‎

Lines changed: 66 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -922,6 +922,72 @@ body {
922922
// Date.now() is not used here
923923
window.__timelines["c1"] = gsap.timeline({ paused: true });
924924
</script>
925+
</body></html>`;
926+
const result = await lintHyperframeHtml(html);
927+
const finding = result.findings.find((f) => f.code === "non_deterministic_code");
928+
expect(finding).toBeUndefined();
929+
});
930+
931+
it("detects gsap.utils.random() in script content", async () => {
932+
const html = `
933+
<html><body>
934+
<div data-composition-id="c1" data-width="1920" data-height="1080"></div>
935+
<script>
936+
window.__timelines = window.__timelines || {};
937+
const tl = gsap.timeline({ paused: true });
938+
tl.to(".chip", { x: gsap.utils.random(-100, 100), duration: 1 }, 0);
939+
window.__timelines["c1"] = tl;
940+
</script>
941+
</body></html>`;
942+
const result = await lintHyperframeHtml(html);
943+
const finding = result.findings.find((f) => f.code === "non_deterministic_code");
944+
expect(finding).toBeDefined();
945+
expect(finding?.severity).toBe("error");
946+
expect(finding?.message).toContain("gsap.utils.random");
947+
});
948+
949+
it("detects GSAP 'random(...)' string tween values", async () => {
950+
const html = `
951+
<html><body>
952+
<div data-composition-id="c1" data-width="1920" data-height="1080"></div>
953+
<script>
954+
window.__timelines = window.__timelines || {};
955+
const tl = gsap.timeline({ paused: true });
956+
tl.to(".chip", { x: "random(-100, 100)", duration: 1 }, 0);
957+
window.__timelines["c1"] = tl;
958+
</script>
959+
</body></html>`;
960+
const result = await lintHyperframeHtml(html);
961+
const finding = result.findings.find((f) => f.code === "non_deterministic_code");
962+
expect(finding).toBeDefined();
963+
expect(finding?.message).toContain('"random(...)"');
964+
});
965+
966+
it("detects prefixed '+=random(...)' string tween values", async () => {
967+
const html = `
968+
<html><body>
969+
<div data-composition-id="c1" data-width="1920" data-height="1080"></div>
970+
<script>
971+
window.__timelines = window.__timelines || {};
972+
const tl = gsap.timeline({ paused: true });
973+
tl.to(".chip", { x: "+=random(-10, 10)", duration: 1 }, 0);
974+
window.__timelines["c1"] = tl;
975+
</script>
976+
</body></html>`;
977+
const result = await lintHyperframeHtml(html);
978+
const finding = result.findings.find((f) => f.code === "non_deterministic_code");
979+
expect(finding).toBeDefined();
980+
});
981+
982+
it("does NOT flag prose strings that merely mention random(", async () => {
983+
const html = `
984+
<html><body>
985+
<div data-composition-id="c1" data-width="1920" data-height="1080"></div>
986+
<script>
987+
window.__timelines = window.__timelines || {};
988+
const note = "avoid random(seed) helpers in render code";
989+
window.__timelines["c1"] = gsap.timeline({ paused: true });
990+
</script>
925991
</body></html>`;
926992
const result = await lintHyperframeHtml(html);
927993
const finding = result.findings.find((f) => f.code === "non_deterministic_code");

‎packages/lint/src/rules/core.ts‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -488,6 +488,17 @@ export const coreRules: Array<(ctx: LintContext) => HyperframeLintFinding[]> = [
488488
label: "crypto.getRandomValues()",
489489
hint: "Remove time-dependent code. Use a seeded PRNG for deterministic renders.",
490490
},
491+
{
492+
pattern: /gsap\.utils\.random\s*\(/,
493+
label: "gsap.utils.random()",
494+
hint: "Each render worker initializes independently, so random values diverge across chunks. Use a seeded PRNG or fixed values.",
495+
},
496+
{
497+
// GSAP string form: "random(...)" / "+=random(...)" — re-rolls at tween init.
498+
pattern: /["'`](?:[+-]=)?random\(\s*[-\d[]/,
499+
label: '"random(...)" tween value',
500+
hint: "GSAP random string values re-roll at tween init and each render worker initializes independently. Use fixed values or precompute with a seeded PRNG.",
501+
},
491502
];
492503

493504
for (const script of scripts) {

0 commit comments

Comments
 (0)