feat(parsers): shared animation runtime classifier (U18)

This commit is contained in:
Miguel Angel Simon Sierra
2026-07-08 16:58:07 -04:00
parent 3e1ecf77bb
commit 3d1898e5ec
3 changed files with 520 additions and 0 deletions
@@ -0,0 +1,115 @@
import { describe, expect, it } from "vitest";
import { classifyAnimationRuntime } from "./animationRuntimeDetection.js";
describe("classifyAnimationRuntime", () => {
it("classifies a pure GSAP file as gsap", () => {
const html = `<!doctype html>
<html>
<body>
<script>
const tl = gsap.timeline({ paused: true });
gsap.to(".box", { x: 300, duration: 2 });
window.__timelines = [tl];
</script>
</body>
</html>`;
const result = classifyAnimationRuntime(html);
expect(result.verdict).toBe("gsap");
expect(result.blocks).toMatchObject([{ engine: "gsap", insideTemplate: false }]);
expect(html.slice(result.blocks[0]?.start, result.blocks[0]?.end)).toContain("gsap.timeline");
});
it("classifies a pure anime.js file as animejs", () => {
const result = classifyAnimationRuntime(`<!doctype html>
<html>
<body>
<script>
const tl = anime.createTimeline({ autoplay: false });
tl.add(".box", { x: 300, duration: 2000 }, 0);
hyperframesAnime.register("main", tl);
</script>
</body>
</html>`);
expect(result.verdict).toBe("animejs");
expect(result.blocks).toMatchObject([{ engine: "animejs", insideTemplate: false }]);
});
it("classifies files with both engines as mixed and preserves per-block tags", () => {
const result = classifyAnimationRuntime(`<!doctype html>
<html>
<body>
<script>
gsap.set(".box", { opacity: 0 });
anime.animate(".box", { opacity: 1, duration: 2000 });
</script>
<script>
gsap.from(".headline", { y: 40, duration: 1 });
</script>
</body>
</html>`);
expect(result.verdict).toBe("mixed");
expect(result.blocks.map((block) => block.engine)).toEqual(["mixed", "gsap"]);
});
it("classifies helper-only anime registration without the anime global as animejs", () => {
const result = classifyAnimationRuntime(`<!doctype html>
<html>
<body>
<script>
const scopedTimeline = buildScopedTimeline();
hyperframesAnime.register("main", scopedTimeline);
window.__hfAnime.push(scopedTimeline);
</script>
</body>
</html>`);
expect(result.verdict).toBe("animejs");
expect(result.blocks).toMatchObject([{ engine: "animejs" }]);
});
it("ignores comment-only engine mentions when classifying scripts", () => {
const result = classifyAnimationRuntime(`<!doctype html>
<html>
<body>
<script>
// this used to use gsap.timeline()
/* anime.createTimeline setup */
anime.animate(".box", { x: 100, duration: 2000 });
</script>
</body>
</html>`);
expect(result.verdict).toBe("animejs");
expect(result.blocks).toMatchObject([{ engine: "animejs" }]);
});
it("classifies empty files and files without meaningful inline scripts as none", () => {
expect(classifyAnimationRuntime("").verdict).toBe("none");
expect(
classifyAnimationRuntime(
'<!doctype html><script src="https://cdn.jsdelivr.net/npm/gsap/dist/gsap.min.js"></script>',
).verdict,
).toBe("none");
expect(classifyAnimationRuntime("<script> \n\t </script>").verdict).toBe("none");
});
it("includes template script blocks but excludes template-only engines from the file verdict", () => {
const result = classifyAnimationRuntime(`<!doctype html>
<html>
<body>
<template>
<script>
gsap.to(".template-box", { opacity: 1 });
</script>
</template>
</body>
</html>`);
expect(result.verdict).toBe("none");
expect(result.blocks).toMatchObject([{ engine: "gsap", insideTemplate: true }]);
});
});
@@ -0,0 +1,404 @@
/**
* Static animation-runtime classification for HyperFrames composition HTML.
*
* `classifyAnimationRuntime(html)` parses the source with linkedom and returns
* every inline script block with its content span in the original HTML string.
* A block engine may be `"mixed"` when GSAP and anime.js signals appear in the
* same script. Scripts nested under `<template>` are still returned with
* `insideTemplate: true` for future span-level ownership, but they do not affect
* the file-level verdict because template contents are inert until cloned.
*/
import { parseHTML } from "linkedom";
export type AnimationRuntimeEngine = "gsap" | "animejs";
export type AnimationRuntimeScriptEngine = AnimationRuntimeEngine | "mixed" | "none";
export type AnimationRuntimeVerdict = AnimationRuntimeScriptEngine;
export interface AnimationRuntimeScriptBlock {
engine: AnimationRuntimeScriptEngine;
start: number;
end: number;
insideTemplate: boolean;
}
export interface AnimationRuntimeClassification {
verdict: AnimationRuntimeVerdict;
blocks: AnimationRuntimeScriptBlock[];
}
interface RawScriptBlock {
text: string;
start: number;
end: number;
insideTemplate: boolean;
}
interface HtmlTag {
name: string;
source: string;
end: number;
closing: boolean;
selfClosing: boolean;
}
const GSAP_SIGNAL_PATTERNS = [
/\bgsap\s*\.\s*timeline\b/,
/\bgsap\s*\.\s*(?:fromTo|from|set|to)\s*\(/,
/\bgsap\s*\.\s*(?:config|defaults|registerPlugin)\s*\(/,
/\bgsap\s*\.\s*version\b/,
/\b(?:GreenSock|_gsScope)\b/,
/\bwindow\s*\.\s*__timelines\b/,
];
const ANIME_SIGNAL_PATTERNS = [
/\banime\s*\.\s*(?:animate|createTimeline|timeline)\s*\(/,
/\bhyperframesAnime\s*\.\s*register\s*\(/,
/\bwindow\s*\.\s*__hfAnime\b/,
];
export function classifyAnimationRuntime(html: string): AnimationRuntimeClassification {
const { document } = parseHTML(html);
if (collectInlineScriptElements(document).length === 0) {
return { verdict: "none", blocks: [] };
}
const blocks = findInlineScriptBlocks(html).map((block) => ({
engine: classifyScriptEngine(block.text),
start: block.start,
end: block.end,
insideTemplate: block.insideTemplate,
}));
return {
verdict: classifyFileVerdict(blocks),
blocks,
};
}
function collectInlineScriptElements(document: Document): Element[] {
const scripts: Element[] = [];
const seen = new Set<Element>();
const add = (script: Element): void => {
if (seen.has(script)) return;
seen.add(script);
scripts.push(script);
};
document.querySelectorAll("script:not([src])").forEach(add);
document.querySelectorAll("template").forEach((template) => {
template.querySelectorAll("script:not([src])").forEach(add);
});
return scripts;
}
function classifyFileVerdict(blocks: AnimationRuntimeScriptBlock[]): AnimationRuntimeVerdict {
const engines = new Set<AnimationRuntimeEngine>();
for (const block of blocks) {
if (block.insideTemplate) continue;
addBlockEngine(engines, block.engine);
}
if (engines.size === 2) return "mixed";
if (engines.has("gsap")) return "gsap";
if (engines.has("animejs")) return "animejs";
return "none";
}
function addBlockEngine(
engines: Set<AnimationRuntimeEngine>,
engine: AnimationRuntimeScriptEngine,
): void {
if (engine === "gsap" || engine === "mixed") engines.add("gsap");
if (engine === "animejs" || engine === "mixed") engines.add("animejs");
}
function classifyScriptEngine(scriptText: string): AnimationRuntimeScriptEngine {
const uncommented = stripJavaScriptComments(scriptText);
const hasGsap = GSAP_SIGNAL_PATTERNS.some((pattern) => pattern.test(uncommented));
const hasAnime = ANIME_SIGNAL_PATTERNS.some((pattern) => pattern.test(uncommented));
if (hasGsap && hasAnime) return "mixed";
if (hasGsap) return "gsap";
if (hasAnime) return "animejs";
return "none";
}
function findInlineScriptBlocks(html: string): RawScriptBlock[] {
const lowerHtml = html.toLowerCase();
const blocks: RawScriptBlock[] = [];
let index = 0;
let templateDepth = 0;
while (index < html.length) {
const tagStart = html.indexOf("<", index);
if (tagStart === -1) break;
if (html.startsWith("<!--", tagStart)) {
index = afterHtmlComment(html, tagStart);
continue;
}
const tag = readHtmlTag(html, tagStart);
if (!tag) {
index = tagStart + 1;
continue;
}
if (tag.name === "template") {
if (tag.closing) {
templateDepth = Math.max(0, templateDepth - 1);
} else if (!tag.selfClosing) {
templateDepth += 1;
}
index = tag.end + 1;
continue;
}
if (tag.name === "script" && !tag.closing) {
const contentStart = tag.end + 1;
const closeStart = findClosingScriptStart(lowerHtml, contentStart);
const contentEnd = closeStart ?? html.length;
if (!tagHasAttribute(tag.source, "src")) {
blocks.push({
text: html.slice(contentStart, contentEnd),
start: contentStart,
end: contentEnd,
insideTemplate: templateDepth > 0,
});
}
if (closeStart === null) break;
const closeTagEnd = findTagEnd(html, closeStart);
index = closeTagEnd === -1 ? html.length : closeTagEnd + 1;
continue;
}
index = tag.end + 1;
}
return blocks;
}
function afterHtmlComment(html: string, start: number): number {
const close = html.indexOf("-->", start + 4);
return close === -1 ? html.length : close + 3;
}
function readHtmlTag(html: string, start: number): HtmlTag | null {
const end = findTagEnd(html, start);
if (end === -1) return null;
const source = html.slice(start, end + 1);
const nameStart = tagNameStart(source);
if (nameStart === null) return null;
let nameEnd = nameStart;
while (nameEnd < source.length && isTagNameChar(source.charAt(nameEnd))) {
nameEnd += 1;
}
if (nameEnd === nameStart) return null;
return {
name: source.slice(nameStart, nameEnd).toLowerCase(),
source,
end,
closing: source.charAt(1) === "/",
selfClosing: tagIsSelfClosing(source),
};
}
function tagNameStart(source: string): number | null {
let index = 1;
if (source.charAt(index) === "/") index += 1;
while (index < source.length && isHtmlWhitespace(source.charAt(index))) {
index += 1;
}
return index < source.length ? index : null;
}
function findTagEnd(html: string, start: number): number {
let quote = "";
for (let index = start + 1; index < html.length; index += 1) {
const char = html.charAt(index);
if (quote) {
if (char === quote) quote = "";
continue;
}
if (char === '"' || char === "'") {
quote = char;
continue;
}
if (char === ">") return index;
}
return -1;
}
function tagIsSelfClosing(source: string): boolean {
let index = source.length - 2;
while (index >= 0 && isHtmlWhitespace(source.charAt(index))) {
index -= 1;
}
return source.charAt(index) === "/";
}
function tagHasAttribute(source: string, attrName: string): boolean {
const initialIndex = tagNameStart(source);
if (initialIndex === null) return false;
let index = initialIndex;
while (index < source.length && isTagNameChar(source.charAt(index))) {
index += 1;
}
while (index < source.length - 1) {
while (index < source.length && isHtmlWhitespace(source.charAt(index))) {
index += 1;
}
if (source.charAt(index) === "/" || source.charAt(index) === ">") return false;
const nameStart = index;
while (index < source.length && isAttributeNameChar(source.charAt(index))) {
index += 1;
}
if (nameStart === index) return false;
const name = source.slice(nameStart, index).toLowerCase();
if (name === attrName.toLowerCase()) return true;
while (index < source.length && isHtmlWhitespace(source.charAt(index))) {
index += 1;
}
if (source.charAt(index) !== "=") continue;
index += 1;
while (index < source.length && isHtmlWhitespace(source.charAt(index))) {
index += 1;
}
index = skipAttributeValue(source, index);
}
return false;
}
function skipAttributeValue(source: string, index: number): number {
const quote = source.charAt(index);
if (quote === '"' || quote === "'") {
let next = index + 1;
while (next < source.length && source.charAt(next) !== quote) {
next += 1;
}
return next < source.length ? next + 1 : source.length;
}
let next = index;
while (
next < source.length &&
!isHtmlWhitespace(source.charAt(next)) &&
source.charAt(next) !== ">"
) {
next += 1;
}
return next;
}
function findClosingScriptStart(lowerHtml: string, from: number): number | null {
let searchFrom = from;
while (searchFrom < lowerHtml.length) {
const candidate = lowerHtml.indexOf("</script", searchFrom);
if (candidate === -1) return null;
const afterName = lowerHtml.charAt(candidate + "</script".length);
if (afterName === ">" || isHtmlWhitespace(afterName)) return candidate;
searchFrom = candidate + "</script".length;
}
return null;
}
function stripJavaScriptComments(source: string): string {
let output = "";
let state: "code" | "lineComment" | "blockComment" | "single" | "double" | "template" = "code";
let escaped = false;
for (let index = 0; index < source.length; index += 1) {
const char = source.charAt(index);
const next = source.charAt(index + 1);
if (state === "lineComment") {
if (char === "\n" || char === "\r") {
output += char;
state = "code";
} else {
output += " ";
}
continue;
}
if (state === "blockComment") {
if (char === "*" && next === "/") {
output += " ";
index += 1;
state = "code";
} else {
output += char === "\n" || char === "\r" ? char : " ";
}
continue;
}
output += char;
if (state === "single" || state === "double" || state === "template") {
if (escaped) {
escaped = false;
continue;
}
if (char === "\\") {
escaped = true;
continue;
}
if (
(state === "single" && char === "'") ||
(state === "double" && char === '"') ||
(state === "template" && char === "`")
) {
state = "code";
}
continue;
}
if (char === "/" && next === "/") {
output = output.slice(0, -1) + " ";
index += 1;
state = "lineComment";
} else if (char === "/" && next === "*") {
output = output.slice(0, -1) + " ";
index += 1;
state = "blockComment";
} else if (char === "'") {
state = "single";
} else if (char === '"') {
state = "double";
} else if (char === "`") {
state = "template";
}
}
return output;
}
function isHtmlWhitespace(char: string): boolean {
return char === " " || char === "\n" || char === "\t" || char === "\r" || char === "\f";
}
function isTagNameChar(char: string): boolean {
return (
(char >= "a" && char <= "z") ||
(char >= "A" && char <= "Z") ||
(char >= "0" && char <= "9") ||
char === ":" ||
char === "-"
);
}
function isAttributeNameChar(char: string): boolean {
return char !== "" && !isHtmlWhitespace(char) && char !== "/" && char !== ">" && char !== "=";
}
+1
View File
@@ -2,6 +2,7 @@ export * from "./types.js";
export * from "./gsapParserExports.js";
export * from "./htmlParser.js";
export * from "./hfIds.js";
export * from "./animationRuntimeDetection.js";
export * from "./subCompositionValidity.js";
export * from "./outputResolutionCompatibility.js";
export { unrollComputedTimeline } from "./gsapUnroll.js";