From 124591a9d5d54fb90ab9ab832ced2b3af1527d11 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Miguel=20=C3=81ngel?= Date: Tue, 10 Nov 2026 21:46:26 +0000 Subject: [PATCH] fix(lint): flag a script that calls gsap before GSAP loads, and say so when a render fails on it (#7514) * fix(lint): flag a script that calls gsap before GSAP loads, and say so when a render fails on it * fix(lint): judge the first gsap call by when it runs, so a listener after a deferred GSAP passes * fix(lint): keep the gsap timing helper's comment to two lines --- .../frameCapture-subTimelineWarning.test.ts | 25 +++++++ packages/engine/src/services/frameCapture.ts | 10 ++- packages/lint/src/rules/gsap.test.ts | 66 +++++++++++++++++++ packages/lint/src/rules/gsap.ts | 35 +++++++++- packages/lint/src/scriptPositions.ts | 48 +++++++++++++- 5 files changed, 180 insertions(+), 4 deletions(-) diff --git a/packages/engine/src/services/frameCapture-subTimelineWarning.test.ts b/packages/engine/src/services/frameCapture-subTimelineWarning.test.ts index 3dc8fdc6ad..3fff029204 100644 --- a/packages/engine/src/services/frameCapture-subTimelineWarning.test.ts +++ b/packages/engine/src/services/frameCapture-subTimelineWarning.test.ts @@ -158,6 +158,31 @@ describe("recordSubTimelineWarning", () => { expect(message).not.toContain("failed to load"); }); + it("says GSAP was not loaded yet when a script reads timeline before GSAP runs", () => { + const session = makeSession({ + subTimelineWaitOutcome: "script_failure", + pageErrors: ["runtime-error:TypeError: Cannot read properties of null (reading 'timeline')"], + pendingTimelineIds: ["main"], + }); + recordSubTimelineWarning(session, 45_000); + + expect(session.warnings[0].message).toContain( + "GSAP was not loaded yet when that script ran: load the GSAP script before the first script that uses gsap.", + ); + }); + + it("adds no GSAP hint for a null read that is not GSAP's", () => { + const session = makeSession({ + subTimelineWaitOutcome: "script_failure", + pageErrors: [ + "runtime-error:TypeError: Cannot read properties of null (reading 'appendChild')", + ], + }); + recordSubTimelineWarning(session, 45_000); + + expect(session.warnings[0].message).not.toContain("GSAP was not loaded"); + }); + it("names the missing script, not the error it caused, when both are present", () => { const session = makeSession({ subTimelineWaitOutcome: "script_failure", diff --git a/packages/engine/src/services/frameCapture.ts b/packages/engine/src/services/frameCapture.ts index 890811d827..86c62e5f76 100644 --- a/packages/engine/src/services/frameCapture.ts +++ b/packages/engine/src/services/frameCapture.ts @@ -2653,6 +2653,14 @@ export function recordSubTimelineWarning(session: CaptureSession, timeoutMs: num const loadCauses = session.scriptLoadCauses ?? []; const pending = session.pendingTimelineIds ?? []; const pendingSuffix = pending.length > 0 ? ` (still unregistered: ${pending.join(", ")})` : ""; + // The render page's gsap reads null until GSAP's script runs, so a too-early gsap.timeline() surfaces as this. + const gsapNotLoaded = sources.some((s) => + /gsap is not defined|Cannot read properties of (?:null|undefined) \(reading '(?:timeline|registerPlugin)'\)/.test( + s, + ), + ) + ? " GSAP was not loaded yet when that script ran: load the GSAP script before the first script that uses gsap." + : ""; const isolated = session.isolatedCompositions ?? []; if (isolated.length > 0) { recordCaptureWarnings(session, [ @@ -2676,7 +2684,7 @@ export function recordSubTimelineWarning(session: CaptureSession, timeoutMs: num code: scriptFailure ? "sub_timeline_script_failure" : "sub_timeline_readiness_timeout", message: threwThenTimedOut ? `A composition script threw before its timeline registered` + - `${pendingSuffix} (${sources.join(", ")}). Fix the error; a composition animated by ` + + `${pendingSuffix} (${sources.join(", ")}).${gsapNotLoaded} Fix the error; a composition animated by ` + `CSS or rAF rather than a GSAP timeline must mark its host with data-no-timeline.` : scriptFailure ? `A sub-composition timeline script failed to load${scriptLoadCauseSuffix(loadCauses)} ` + diff --git a/packages/lint/src/rules/gsap.test.ts b/packages/lint/src/rules/gsap.test.ts index 05519569cc..50f652640e 100644 --- a/packages/lint/src/rules/gsap.test.ts +++ b/packages/lint/src/rules/gsap.test.ts @@ -1012,6 +1012,72 @@ describe("GSAP rules", () => { expect(finding?.message).toContain("GSAP"); }); + it.each([ + ["after the script that uses it", "", ''], + ["with defer before it", '', ""], + ])("reports gsap_loaded_after_use when the GSAP tag sits %s", async (_, before, after) => { + const html = ` + +
+ ${before} + + ${after} +`; + const result = await lintHyperframeHtml(html); + const finding = result.findings.find((f) => f.code === "gsap_loaded_after_use"); + expect(finding?.severity).toBe("error"); + expect(result.findings.find((f) => f.code === "missing_gsap_script")).toBeUndefined(); + }); + + it.each([ + [ + "a defer tag and a DOMContentLoaded listener", + '', + '', + "", + ], + [ + "a later tag and a load listener", + "", + '', + '', + ], + ])("does not report gsap_loaded_after_use for %s", async (_, head, body, after) => { + const html = `${head} +
+ ${body} + ${after} +`; + const result = await lintHyperframeHtml(html); + expect(result.findings.find((f) => f.code === "gsap_loaded_after_use")).toBeUndefined(); + }); + + it("reports gsap_loaded_after_use for a function called on the spot before a later tag", async () => { + const html = ` +
+ + +`; + const result = await lintHyperframeHtml(html); + expect(result.findings.find((f) => f.code === "gsap_loaded_after_use")?.severity).toBe("error"); + }); + + it("does not report gsap_loaded_after_use when GSAP loads in the head first", async () => { + const html = ` + +
+ +`; + const result = await lintHyperframeHtml(html); + expect(result.findings.find((f) => f.code === "gsap_loaded_after_use")).toBeUndefined(); + }); + it("does not report missing_gsap_script when GSAP CDN script is present", async () => { const html = ` diff --git a/packages/lint/src/rules/gsap.ts b/packages/lint/src/rules/gsap.ts index adef478304..ff9a620f5d 100644 --- a/packages/lint/src/rules/gsap.ts +++ b/packages/lint/src/rules/gsap.ts @@ -1,5 +1,5 @@ import postcss from "postcss"; -import { gsapCallOffset, containingCallOffset } from "../scriptPositions"; +import { gsapCallOffset, containingCallOffset, gsapRunsWhenScriptRuns } from "../scriptPositions"; interface LintParsedGsap { animations: Array<{ targetSelector: string; @@ -1509,6 +1509,39 @@ export const gsapRules: LintRule[] = [ /\b_gsScope\b/.test(t), ); + if (usesGsap && hasGsapScript && !hasInlineGsap && !canInheritGsapFromHost) { + // A classic script runs where it sits, so GSAP must load earlier: a deferred, async or later tag is too late. + const classic = (s: { attrs: string }) => { + const tag = `