diff --git a/packages/parsers/src/animationRuntimeDetection.test.ts b/packages/parsers/src/animationRuntimeDetection.test.ts
new file mode 100644
index 0000000000..e1f36d0902
--- /dev/null
+++ b/packages/parsers/src/animationRuntimeDetection.test.ts
@@ -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 = `
+
+
+
+
+`;
+
+ 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(`
+
+
+
+
+`);
+
+ 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(`
+
+
+
+
+
+`);
+
+ 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(`
+
+
+
+
+`);
+
+ expect(result.verdict).toBe("animejs");
+ expect(result.blocks).toMatchObject([{ engine: "animejs" }]);
+ });
+
+ it("ignores comment-only engine mentions when classifying scripts", () => {
+ const result = classifyAnimationRuntime(`
+
+
+
+
+`);
+
+ 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(
+ '',
+ ).verdict,
+ ).toBe("none");
+ expect(classifyAnimationRuntime("").verdict).toBe("none");
+ });
+
+ it("includes template script blocks but excludes template-only engines from the file verdict", () => {
+ const result = classifyAnimationRuntime(`
+
+
+
+
+
+
+`);
+
+ expect(result.verdict).toBe("none");
+ expect(result.blocks).toMatchObject([{ engine: "gsap", insideTemplate: true }]);
+ });
+});
diff --git a/packages/parsers/src/animationRuntimeDetection.ts b/packages/parsers/src/animationRuntimeDetection.ts
new file mode 100644
index 0000000000..1e9a528d52
--- /dev/null
+++ b/packages/parsers/src/animationRuntimeDetection.ts
@@ -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 `` 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();
+ 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();
+ 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,
+ 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("", 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("" || isHtmlWhitespace(afterName)) return candidate;
+ searchFrom = candidate + "= "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 !== "=";
+}
diff --git a/packages/parsers/src/index.ts b/packages/parsers/src/index.ts
index b8d8ccd203..969a92cdec 100644
--- a/packages/parsers/src/index.ts
+++ b/packages/parsers/src/index.ts
@@ -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";