import { existsSync, linkSync, mkdtempSync, mkdirSync, readFileSync, rmSync, writeFileSync, } from "node:fs"; import { tmpdir } from "node:os"; import { join } from "node:path"; import { beforeAll, describe, expect, it, onTestFinished, vi } from "vitest"; import { runCommand } from "citty"; import type { ArgsDef } from "citty"; import { ensureDOMParser } from "../utils/dom.js"; import keyframesCommand from "./keyframes.js"; import { collectCompositions, collectShotSelectors, resolveScope, singleFileStage, surfaceComposition, } from "./keyframes.js"; import { ensureShotOutputDir } from "./motionShot.js"; // citty types `args` as Resolvable (object | promise | thunk); this // command always uses a static object, same narrowing as assertKnownFlags. function layoutArgDescription(): string { const rawDef = keyframesCommand.args; const args = rawDef && typeof rawDef === "object" ? (rawDef as ArgsDef) : undefined; const layout = args?.["layout"]; if (!layout || typeof layout !== "object" || !("description" in layout)) { throw new Error("expected keyframesCommand.args.layout.description to be defined"); } return String(layout.description); } beforeAll(() => ensureDOMParser()); const wrap = (script: string) => `
`; describe("keyframes JSON output", () => { it.each(["css", "anime"])("emits parseable JSON with --runtime %s", async (runtime) => { const dir = mkdtempSync(join(tmpdir(), "hf-keyframes-json-")); onTestFinished(() => rmSync(dir, { recursive: true, force: true })); const source = join(dir, "index.html"); writeFileSync(source, wrap("")); const log = vi.spyOn(console, "log").mockImplementation(() => {}); onTestFinished(() => log.mockRestore()); await runCommand(keyframesCommand, { rawArgs: [source, "--runtime", runtime, "--json"] }); const output = log.mock.calls.map((args) => args.join(" ")).join("\n"); const result: unknown = JSON.parse(output); expect(result).toMatchObject({ project: "index.html", runtime, compositions: [{ composition: "index.html", tweens: [], cssKeyframes: [], anime: [] }], }); }); }); describe("keyframes human output", () => { it("prints selectors, values and keyframe text from the project with control characters escaped", async () => { // Built rather than written: a literal control character in the source is a lint error. const esc = String.fromCharCode(27); const bel = String.fromCharCode(7); const dir = mkdtempSync(join(tmpdir(), "hf-keyframes-human-")); onTestFinished(() => rmSync(dir, { recursive: true, force: true })); const source = join(dir, "index.html"); writeFileSync( source, wrap( `const tl = gsap.timeline({ paused: true }); tl.to("#dot${esc}[2J", { x: "40px${esc}]52;c;cA==${bel}", duration: 1 }, 0); window.__timelines = { main: tl };`, ).replace( "", ``, ), ); const log = vi.spyOn(console, "log").mockImplementation(() => {}); onTestFinished(() => log.mockRestore()); await runCommand(keyframesCommand, { rawArgs: [source, "--runtime", "all"] }); const colors = new RegExp(`${esc}\\[[0-9;]*m`, "g"); const output = log.mock.calls .map((args) => args.join(" ")) .join("\n") .replace(colors, ""); expect(output).not.toContain(esc); expect(output).not.toContain(bel); expect(output).toContain("#dot\\x1b[2J"); expect(output).toContain("40px\\x1b]52;c;cA==\\x07"); expect(output).toContain("a\\x1b[1A"); }); }); describe("keyframes direct composition scope", () => { it("keeps the project root and passes the nested HTML entry to --shot", () => { const projectDir = mkdtempSync(join(tmpdir(), "hf-keyframes-target-")); onTestFinished(() => rmSync(projectDir, { recursive: true, force: true })); const compositionsDir = join(projectDir, "compositions"); mkdirSync(compositionsDir); writeFileSync(join(projectDir, "index.html"), wrap("")); const scenePath = join(compositionsDir, "scene.html"); writeFileSync(scenePath, wrap("")); const scope = resolveScope({ target: scenePath }); expect(scope.projectDir).toBe(projectDir); expect(scope.entryFile).toBe("compositions/scene.html"); expect(scope.singleFile).toBe(scenePath); }); }); describe("keyframes --shot on a bare HTML file", () => { const scene = ``; const mountingIndex = wrap("").replace( '
', '
', ); function project(index: string) { const projectDir = mkdtempSync(join(tmpdir(), "hf-keyframes-stage-")); onTestFinished(() => rmSync(projectDir, { recursive: true, force: true })); mkdirSync(join(projectDir, "compositions")); writeFileSync(join(projectDir, "index.html"), index); return projectDir; } it("stages a scene its project mounts from the project, so the scene keeps its shell", async () => { const projectDir = project(mountingIndex); const scenePath = join(projectDir, "compositions", "scene.html"); writeFileSync(scenePath, scene); expect(await singleFileStage(scenePath, projectDir)).toEqual({ root: projectDir, entries: [join(projectDir, "index.html"), scenePath], entryFile: "compositions/scene.html", }); }); it("stages any other file from its own folder, even under a folder holding index.html", async () => { const projectDir = project(wrap("")); const sentPath = join(projectDir, "compositions", "sent.html"); writeFileSync(sentPath, scene); expect(await singleFileStage(sentPath, projectDir)).toEqual({ root: join(projectDir, "compositions"), entries: [sentPath], entryFile: "sent.html", }); }); }); describe("keyframes shot output", () => { it("rejects an output path that would overwrite the composition source", () => { const projectDir = mkdtempSync(join(tmpdir(), "hf-keyframes-shot-source-")); onTestFinished(() => rmSync(projectDir, { recursive: true, force: true })); const sourcePath = join(projectDir, "index.html"); writeFileSync(sourcePath, wrap("")); expect(() => ensureShotOutputDir(sourcePath, sourcePath)).toThrow( /must not overwrite the composition source/, ); expect(readFileSync(sourcePath, "utf8")).toBe(wrap("")); }); it("rejects an existing output alias that refers to the composition source", () => { const projectDir = mkdtempSync(join(tmpdir(), "hf-keyframes-shot-alias-")); onTestFinished(() => rmSync(projectDir, { recursive: true, force: true })); const sourcePath = join(projectDir, "index.html"); const aliasPath = join(projectDir, "shot.png"); writeFileSync(sourcePath, wrap("")); linkSync(sourcePath, aliasPath); expect(() => ensureShotOutputDir(aliasPath, sourcePath)).toThrow( /must not overwrite the composition source/, ); }); it("creates a missing parent directory before writing --shot", () => { const projectDir = mkdtempSync(join(tmpdir(), "hf-keyframes-shot-dir-")); onTestFinished(() => rmSync(projectDir, { recursive: true, force: true })); const outputDir = join(projectDir, "nested", "proofs"); ensureShotOutputDir(join(outputDir, "shot.png")); expect(existsSync(outputDir)).toBe(true); }); }); describe("keyframes multi-stroke traces", () => { it("composites ≥2 position strokes on one element into a single trace", () => { const html = wrap(` const tl = gsap.timeline({ paused: true }); tl.to("#dot", { keyframes: { "0%": { x: -100, y: -150 }, "100%": { x: 80, y: -120 } }, duration: 1 }); tl.to("#dot", { keyframes: { "0%": { x: 80, y: 120 }, "100%": { x: 85, y: 140 } }, duration: 1 }); window.__timelines = [tl]; `); const { traces } = surfaceComposition(html, "index.html", "index.html"); expect(traces).toHaveLength(1); expect(traces[0]!.target).toBe("#dot"); expect(traces[0]!.strokes).toHaveLength(2); }); it("treats a 0-duration set() between strokes as a pen-up jump, not a drawn stroke", () => { const html = wrap(` const tl = gsap.timeline({ paused: true }); tl.to("#dot", { keyframes: { "0%": { x: 0, y: 0 }, "100%": { x: 100, y: 0 } }, duration: 1 }); tl.set("#dot", { x: 200, y: 200 }); tl.to("#dot", { keyframes: { "0%": { x: 200, y: 200 }, "100%": { x: 250, y: 250 } }, duration: 1 }); window.__timelines = [tl]; `); const { traces } = surfaceComposition(html, "index.html", "index.html"); expect(traces).toHaveLength(1); // two DRAWN strokes; the set() is the pen-up gap and is excluded expect(traces[0]!.strokes).toHaveLength(2); }); it("leaves a single-stroke element untraced (normal per-tween output)", () => { const html = wrap(` const tl = gsap.timeline({ paused: true }); tl.to("#dot", { keyframes: { "0%": { x: 0, y: 0 }, "50%": { x: 200, y: -100 }, "100%": { x: 0, y: 0 } }, duration: 3 }); window.__timelines = [tl]; `); const { traces, tweens } = surfaceComposition(html, "index.html", "index.html"); expect(traces).toHaveLength(0); expect(tweens.length).toBeGreaterThan(0); }); }); describe("keyframes composed-ancestor surfacing (nested elements)", () => { const nested = (script: string) => `
`; it("annotates a child tween with its animated ANCESTOR's motion", () => { const html = nested(` const tl = gsap.timeline({ paused: true }); tl.to("#hero", { keyframes: { "0%": { x: -300, y: 0 }, "100%": { x: 300, y: 0 } }, duration: 4 }, 0); tl.to("#core", { keyframes: { "0%": { scale: 1 }, "100%": { scale: 1.5 } }, duration: 4 }, 0); window.__timelines = [tl]; `); const { tweens } = surfaceComposition(html, "index.html", "index.html"); const core = tweens.find((t) => t.target === "#core"); expect(core?.composedWith?.map((a) => a.selector)).toContain("#hero"); // and the ancestor's path EXTENT is summarised (range, not endpoints — so a // closed loop still reveals its travel) expect(core?.composedWith?.[0]!.summary).toMatch(/x -300\.\.300/); }); it("does not annotate when the parent isn't animated", () => { const html = nested(` const tl = gsap.timeline({ paused: true }); tl.to("#core", { keyframes: { "0%": { scale: 1 }, "100%": { scale: 1.5 } }, duration: 4 }, 0); window.__timelines = [tl]; `); const { tweens } = surfaceComposition(html, "index.html", "index.html"); expect(tweens.find((t) => t.target === "#core")?.composedWith).toBeUndefined(); }); it.each(["template", "nested template"])( "keeps the parent motion of a child authored in a %s", (mode) => { const content = `
`; const html = mode === "template" ? `` : ``; const { tweens } = surfaceComposition(html, "beat.html", "beat.html"); expect(tweens).toHaveLength(2); expect(tweens.find((t) => t.target === "#core")?.composedWith).toEqual([ { selector: "#hero", summary: "x -300..300" }, ]); }, ); it("keeps animated ancestors ordered from the parent to the outer group", () => { const html = ``; const { tweens } = surfaceComposition(html, "beat.html", "beat.html"); expect(tweens.find((t) => t.target === "#core")?.composedWith).toEqual([ { selector: "#hero", summary: "x 0..300" }, { selector: "#stage", summary: "y 0..100" }, ]); }); it("keeps implicit parent starting values unresolved inside a template", () => { const html = ``; const { tweens } = surfaceComposition(html, "beat.html", "beat.html"); const hero = tweens.find((t) => t.target === "#hero"); expect(hero?.keyframes[0]?.properties.x).toBeUndefined(); expect(hero?.unresolved).toContain("endpointProperties"); expect(tweens.find((t) => t.target === "#core")?.composedWith).toEqual([ { selector: "#hero", summary: "(no resolved variation; runtime verification required)" }, ]); }); it("uses document matches before template matches for a repeated selector", () => { const html = `
`; const { tweens } = surfaceComposition(html, "beat.html", "beat.html"); expect(tweens.find((t) => t.target === "#core")?.composedWith).toBeUndefined(); }); it("does not treat an animated sibling as a template child's ancestor", () => { const html = ``; const { tweens } = surfaceComposition(html, "beat.html", "beat.html"); expect(tweens).toHaveLength(2); expect(tweens.every((tween) => tween.composedWith === undefined)).toBe(true); }); }); describe("keyframes runtime surfacing", () => { it("surfaces CSS @keyframes and their animated selectors", () => { const html = `
`; const { cssKeyframes } = surfaceComposition(html, "index.html", "index.html"); expect(cssKeyframes).toHaveLength(1); expect(cssKeyframes[0]!.name).toBe("rise"); expect(cssKeyframes[0]!.selectors).toContain(".dot"); expect(cssKeyframes[0]!.keyframes.map((kf) => kf.selector)).toEqual(["0%", "100%"]); }); it("does not let a CSS comment before @keyframes leak into the next rule's selector", () => { const html = `
`; const { cssKeyframes } = surfaceComposition(html, "index.html", "index.html"); expect(cssKeyframes[0]!.selectors).toEqual([".dot"]); }); it("surfaces Anime.js calls and explicit HyperFrames registration", () => { const html = wrap(` const tl = anime.createTimeline({ autoplay: false }); tl.add(".chip", { translateX: [0, 240], duration: 900 }); window.__hfAnime = window.__hfAnime || []; window.__hfAnime.push(tl); `); const { anime } = surfaceComposition(html, "index.html", "index.html"); expect(anime).toHaveLength(1); expect(anime[0]!.kind).toBe("timeline"); expect(anime[0]!.registered).toBe(true); expect(anime[0]!.targets).toContain(".chip"); expect(anime[0]!.durations).toContain(900); }); it("uses CSS and Anime targets as onion-shot candidates", () => { const cssHtml = `
`; const animeHtml = wrap(` const tl = anime.createTimeline({ autoplay: false }); tl.add(".chip", { translateX: [0, 240], duration: 900 }); window.__hfAnime = window.__hfAnime || []; window.__hfAnime.push(tl); `); const selectors = collectShotSelectors([ surfaceComposition(cssHtml, "css.html", "css.html"), surfaceComposition(animeHtml, "anime.html", "anime.html"), ]).map((item) => item.selector); expect(selectors).toEqual(expect.arrayContaining([".dot", ".chip"])); }); it("does not forward unresolved static targets as concrete shot selectors", () => { const html = wrap(` const tl = gsap.timeline({ paused: true }); tl.to(runtimeOnlyTarget(), { x: 240, duration: 1 }); tl.to("#drag", { x: 240, duration: 1 }); `); const selectors = collectShotSelectors([ surfaceComposition(html, "helper.html", "helper.html"), ]).map((item) => item.selector); expect(selectors).toEqual(["#drag"]); }); }); describe("keyframes template-wrapped sub-compositions", () => { // Sub-compositions are REQUIRED to put markup + script + style inside