Skip to content

Write HTML. Render video. Built for agents.

fix(lint): check no longer fails projects that inline the GSAP library (#6018)

Miguel Ángel50e7e8df69e8
diff --git a/packages/lint/src/rules/core.test.ts b/packages/lint/src/rules/core.test.ts
index 31e2445cf1..90ca08ef63 100644
--- a/packages/lint/src/rules/core.test.ts
+++ b/packages/lint/src/rules/core.test.ts
@@ -1208,6 +1208,172 @@ describe("core rules", () => {
});
});
+ describe("non_deterministic_code — inlined GSAP library", () => {
+ // UMD wrapper, banner and internals excerpted from [email protected] dist/gsap.min.js.
+ const banner = "/*! GSAP 3.14.2 | @license Copyright 2025, GreenSock. All rights reserved. */";
+ const gsapUmd =
+ '!function(t,e){"object"==typeof exports&&"undefined"!=typeof module?e(exports):' +
+ '"function"==typeof define&&define.amd?define(["exports"],e):e((t=t||self).window=t.window||{})}' +
+ '(this,function(e){"use strict";function gb(t){return t.sort(function(){return.5-Math.random()})}' +
+ "function Ic(){var t=Date.now(),o=[];return o}});";
+ const pastedGsap = `${banner}\n${gsapUmd}`;
+ const producerInlinedGsap = `/* inlined: https://cdn.jsdelivr.net/npm/[email protected]/dist/gsap.min.js */\n${gsapUmd}`;
+ // Unminified builds carry the banner inside the factory.
+ const unminifiedGsap = gsapUmd.replace('"use strict";', `"use strict";${banner}`);
+ const inlinedUnminifiedGsap = `/* inlined: https://cdn.jsdelivr.net/npm/[email protected]/dist/gsap.js */\n(${unminifiedGsap.slice(1, -1)});`;
+ const separatedGsap = `${banner};${gsapUmd}`;
+ const umdBundle = (body: string) =>
+ `(function (root, factory) {\nif (typeof define === "function" && define.amd) define([], factory); else factory();\n})(this, function () {\n${body}\n});`;
+ // Rollup 4 `--format umd` output for `import { gsap } from "gsap"` plus author code, excerpted.
+ const rollupBundle = `(function (global, factory) {
+ typeof exports === 'object' && typeof module !== 'undefined' ? factory(exports) :
+ typeof define === 'function' && define.amd ? define(['exports'], factory) :
+ (global = typeof globalThis !== 'undefined' ? globalThis : global || self, factory(global.Composition = {}));
+})(this, (function (exports) { 'use strict';
+
+ ${banner}
+
+ var _config = {
+ autoSleep: 120,
+ force3D: "auto",
+ nullTargetWarn: 1,
+ units: {
+ lineHeight: ""
+ }
+ };
+
+ window.authorSeed = Math.random();
+ window.authorTime = Date.now();
+
+ exports.gsap = gsapWithCSS;
+
+}));`;
+ // The same import through Rollup UMD plus Terser, excerpted: the banner stays inside the factory.
+ const minifiedRollupBundle = `!function(t,e){"object"==typeof exports&&"undefined"!=typeof module?e(exports):"function"==typeof define&&define.amd?define(["exports"],e):e((t="undefined"!=typeof globalThis?globalThis:t||self).Composition={})}(this,function(t){"use strict";function r(t,e){t.prototype=Object.create(e.prototype),t.prototype.constructor=t,t.__proto__=e}\n${banner}\nvar Ji=Ar.registerPlugin($i)||Ar;Ji.core.Tween,window.authorSeed=Math.random(),window.authorTime=Date.now(),t.gsap=Ji});`;
+ const comp = (library: string, author = "") => `
+<html><body>
+ <div data-composition-id="main" data-width="1920" data-height="1080" data-start="0" data-duration="5"></div>
+ <script>${library}</script>
+ <script>const tl = gsap.timeline({ paused: true }); ${author} window.__timelines = { main: tl };</script>
+</body></html>`;
+ const labels = async (html: string) =>
+ (await lintHyperframeHtml(html)).findings
+ .filter((f) => f.code === "non_deterministic_code")
+ .map((f) => f.message.match(/`(.+?)`/)?.[1]);
+
+ it.each([
+ ["pasted with its banner", pastedGsap],
+ ["inlined by the producer", producerInlinedGsap],
+ ["unminified and inlined by the producer", inlinedUnminifiedGsap],
+ [
+ "inlined by the producer from an unversioned dist URL with a query and hash",
+ inlinedUnminifiedGsap.replace(
+ "https://cdn.jsdelivr.net/npm/[email protected]/dist/gsap.js",
+ "https://unpkg.com/gsap/dist/gsap.js?module#top",
+ ),
+ ],
+ ["after a statement separator", separatedGsap],
+ ])("does not flag GSAP's own internals when %s", async (_shape, library) => {
+ expect(await labels(comp(library))).toEqual([]);
+ });
+
+ it("still flags the author's Math.random() in a script next to inlined GSAP", async () => {
+ expect(await labels(comp(pastedGsap, "const r = Math.random();"))).toEqual(["Math.random()"]);
+ });
+
+ it("still flags author calls before and after GSAP in the same script", async () => {
+ const library = `const a = Math.random();\n${pastedGsap}\nconst b = performance.now();`;
+ expect(await labels(comp(library))).toEqual(["Math.random()", "performance.now()"]);
+ });
+
+ it("checks an outer wrapper that only borrows define.amd from a nested library", async () => {
+ const library = `(function (root, factory) {\n${banner}\nwindow.seed = Math.random();\n${gsapUmd}\n})(this, function () {});`;
+ expect(await labels(comp(library))).toEqual(["Math.random()", "Date.now()"]);
+ });
+
+ it("checks a UMD wrapper whose GSAP banner is separated from it by other code", async () => {
+ expect(await labels(comp(`${banner}\nwindow.x = 1;\n${gsapUmd}`))).toEqual([
+ "Math.random()",
+ "Date.now()",
+ ]);
+ });
+
+ it.each([
+ [
+ "joined to it with a comma",
+ `${banner}\n${gsapUmd.slice(0, -1)}, window.seed = Math.random();`,
+ ],
+ [
+ "beside it inside an outer wrapper",
+ `(function () {\n${pastedGsap}\nwindow.seed = Math.random();\n})();`,
+ ],
+ [
+ "beside it inside an outer two-argument wrapper",
+ `(function (root, factory) {\n${pastedGsap}\nwindow.seed = Math.random();\n})(this, function () {});`,
+ ],
+ [
+ "beside it inside an outer UMD bundle",
+ umdBundle(`${pastedGsap}\nwindow.seed = Math.random();`),
+ ],
+ [
+ "beside producer-inlined unminified GSAP inside an outer UMD bundle",
+ umdBundle(`${inlinedUnminifiedGsap}\nwindow.seed = Math.random();`),
+ ],
+ [
+ "beside separated GSAP inside an outer UMD bundle",
+ umdBundle(`${separatedGsap}\nwindow.seed = Math.random();`),
+ ],
+ [
+ "beside a stray banner inside an outer UMD bundle",
+ umdBundle(`${banner}\nwindow.seed = Math.random();\n${pastedGsap}`),
+ ],
+ ])("still flags author code %s", async (_shape, library) => {
+ expect(await labels(comp(library))).toEqual(["Math.random()"]);
+ });
+
+ it("flags author code that Rollup bundles into one factory with GSAP's banner", async () => {
+ expect(await labels(comp(rollupBundle))).toEqual(["Math.random()", "Date.now()"]);
+ });
+
+ it.each([
+ "gsap-composition.js",
+ "composition.js",
+ "scene.js?vendor=gsap",
+ "https://example.com/gsap-demo/scene.js",
+ ])("flags author code in a minified bundle inlined from %s", async (src) => {
+ const library = `/* inlined: ${src} */\n${minifiedRollupBundle}`;
+ expect(await labels(comp(library))).toEqual(["Math.random()", "Date.now()"]);
+ });
+
+ // Known limit: a banner inside a factory cannot be told apart from a bundled one, so it exempts nothing.
+ it.each([
+ ["pasted unminified GSAP", unminifiedGsap],
+ [
+ "unminified GSAP beside author code in an outer UMD bundle",
+ umdBundle(`${unminifiedGsap}\nwindow.seed = Math.random();`),
+ ],
+ ])("checks %s, whose banner sits inside its factory", async (_shape, library) => {
+ expect(await labels(comp(library))).toEqual(["Math.random()", "Date.now()"]);
+ });
+
+ it.each([
+ ["a string", `const label = "GreenSock"; const x = Math.random();`],
+ ["a comment", `// eased like GreenSock\nconst x = Math.random();`],
+ ["a spoofed banner", `${banner}\nwindow.seed = Math.random();`],
+ ["a spoofed inlining comment", `/* inlined: gsap.min.js */\nwindow.seed = Math.random();`],
+ [
+ "a banner plus define.amd in a string",
+ `${banner}\nwindow.seed = ("define.amd", Math.random());`,
+ ],
+ [
+ "a banner plus define.amd in a comment",
+ `${banner}\nwindow.seed = /* define.amd */ Math.random();`,
+ ],
+ ])("still flags author code whose script mentions GSAP in %s", async (_where, author) => {
+ expect(await labels(comp("", author))).toEqual(["Math.random()"]);
+ });
+ });
+
describe("timeline_id_mismatch — only top-level registry keys are composition ids", () => {
const comp = (script: string) => `
<html><body>
diff --git a/packages/lint/src/rules/core.ts b/packages/lint/src/rules/core.ts
index 404f90bff2..3f73e79e62 100644
--- a/packages/lint/src/rules/core.ts
+++ b/packages/lint/src/rules/core.ts
@@ -12,6 +12,7 @@ import {
truncateSnippet,
stripJsComments,
stripStringLiterals,
+ blankInlinedGsapLibrary,
extractCompositionIdsFromCss,
extractTimelineRegistryKeys,
getInlineScriptSyntaxError,
@@ -940,7 +941,7 @@ export const coreRules: Array<(ctx: LintContext) => HyperframeLintFinding[]> = [
];
for (const script of scripts) {
- const withoutComments = stripJsComments(script.content);
+ const withoutComments = stripJsComments(blankInlinedGsapLibrary(script.content));
// Strings are content, not code. A composition that DISPLAYS source (the
// code-snippet blocks, /pr-to-video) carries `Math.random()` inside a string
// literal it never executes, and reported itself non-deterministic with no
diff --git a/packages/lint/src/utils.ts b/packages/lint/src/utils.ts
index 4f6c289308..ddc71a2269 100644
--- a/packages/lint/src/utils.ts
+++ b/packages/lint/src/utils.ts
@@ -2,7 +2,8 @@
// Nothing in this file should emit findings — it only parses and extracts.
import { Parser } from "htmlparser2";
-import { parse } from "acorn";
+import { parse, type CallExpression, type Comment, type Program } from "acorn";
+import { base, recursive, simple } from "acorn-walk";
export type OpenTag = {
raw: string;
@@ -559,6 +560,104 @@ export function stripJsComments(source: string): string {
return scanJsComments(source).out;
}
+// A GreenSock banner, or the producer's inlined-source comment when its URL path is an npm gsap dist file.
+function isGsapLibraryComment(comment: Comment): boolean {
+ if (comment.type !== "Block") return false;
+ const { value } = comment;
+ const src = /^\s*inlined:\s*(\S+)\s*$/.exec(value)?.[1]?.split(/[?#]/)[0];
+ return (
+ (value.startsWith("!") && /\bGreenSock\b/.test(value)) ||
+ (src !== undefined && /(?:^|\/)gsap(?:@[^/]+)?\/dist\/[^/]+\.js$/.test(src))
+ );
+}
+
+/** GSAP's UMD wrapper `function (g, f) { ...define.amd... }(this, function (e) {...})`, AMD in its own body. */
+function isUmdWrapperCall(call: CallExpression): boolean {
+ const [scope, factory] = call.arguments;
+ if (
+ call.callee.type !== "FunctionExpression" ||
+ call.arguments.length !== 2 ||
+ scope?.type !== "ThisExpression" ||
+ factory?.type !== "FunctionExpression"
+ )
+ return false;
+ let checksAmd = false;
+ recursive(call.callee.body, null, {
+ Function() {},
+ MemberExpression(member, state, visit) {
+ if (
+ !member.computed &&
+ member.object.type === "Identifier" &&
+ member.object.name === "define" &&
+ member.property.type === "Identifier" &&
+ member.property.name === "amd"
+ )
+ checksAmd = true;
+ base.MemberExpression?.(member, state, visit);
+ },
+ });
+ return checksAmd;
+}
+
+/**
+ * A GSAP banner belongs only to the wrapper right after it. A banner inside a factory exempts nothing:
+ * a bundler (Rollup ESM to UMD) puts it in the same factory as author code.
+ */
+function bannerOwner(
+ banner: Comment,
+ source: string,
+ commentAt: Map<number, Comment>,
+ wrappers: CallExpression[],
+): CallExpression | undefined {
+ let next = banner.end;
+ for (;;) {
+ while (/[\s!;(]/.test(source[next] ?? "")) next++;
+ const comment = commentAt.get(next);
+ if (!comment) break;
+ next = comment.end;
+ }
+ return wrappers.find((call) => call.start === next);
+}
+
+/** Offsets of inlined GSAP library code: the UMD wrapper call each GSAP banner belongs to. */
+function findInlinedGsapLibrarySpans(source: string): Array<[number, number]> {
+ if (!/GreenSock|inlined:/.test(source)) return [];
+ const comments: Comment[] = [];
+ let program: Program;
+ try {
+ program = parse(source, {
+ ecmaVersion: "latest",
+ sourceType: "script",
+ allowReturnOutsideFunction: true,
+ onComment: comments,
+ });
+ } catch {
+ return [];
+ }
+ const banners = comments.filter(isGsapLibraryComment);
+ const wrappers: CallExpression[] = [];
+ simple(program, {
+ CallExpression(call) {
+ if (isUmdWrapperCall(call)) wrappers.push(call);
+ },
+ });
+ const commentAt = new Map(comments.map((comment) => [comment.start, comment]));
+ const owners = new Set<CallExpression>();
+ for (const banner of banners) {
+ const owner = bannerOwner(banner, source, commentAt, wrappers);
+ if (owner) owners.add(owner);
+ }
+ return [...owners].map((call): [number, number] => [call.start, call.end]);
+}
+
+export function blankInlinedGsapLibrary(source: string): string {
+ let out = source;
+ for (const [start, end] of findInlinedGsapLibrarySpans(source)) {
+ out = out.slice(0, start) + " ".repeat(end - start) + out.slice(end);
+ }
+ return out;
+}
+
export function stripJsCode(source: string): string {
const { out, balanced } = scanJsComments(source);
return balanced ? stripJsStringLiterals(out) : source;