route-graphics 1.36.0 → 1.38.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "route-graphics",
-  "version": "1.36.0",
+  "version": "1.38.0",
   "description": "A 2D graphics rendering interface that takes JSON input and renders pixels using PixiJS",
   "main": "dist/RouteGraphics.js",
   "type": "module",
@@ -35,6 +35,7 @@
     "lint:fix": "bunx prettier --write src",
     "prepare": "husky",
     "build": "node ./esbuild.js",
+    "benchmark:timeline": "node ./scripts/benchmarkTimeline.mjs",
     "render:png": "bun run build && node ./bin/route-graphics-render.js",
     "vt:docker:pull": "docker pull docker.io/han4wluc/rtgl:playwright-v1.57.0-rtgl-v1.1.0",
     "vt:generate": "bun run build && docker run --rm --user $(id -u):$(id -g) -e RTGL_VT_DEBUG=true -v \"$PWD:/workspace\" docker.io/han4wluc/rtgl:playwright-v1.57.0-rtgl-v1.1.0 rtgl vt generate --wait-event vt:ready",
@@ -51,6 +52,7 @@
   "dependencies": {
     "@pixi/unsafe-eval": "^7.4.3",
     "@wasm-audio-decoders/ogg-vorbis": "^0.1.20",
+    "gsap": "3.15.0",
     "hotkeys-js": "^4.0.0-beta.7",
     "js-yaml": "^4.1.0",
     "ogg-opus-decoder": "^1.7.3",

package/src/cli/inspectTimeline.js

@@ -0,0 +1,72 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+
+import { loadRenderDefinition } from "./renderConfig.js";
+import { normalizeRenderState } from "../util/normalizeRenderState.js";
+import {
+  compileAnimationTimelineProgram,
+  inspectTimelineProgram,
+} from "../plugins/animations/timeline/inspectProgram.js";
+
+export const inspectTimelineDefinition = ({
+  definition,
+  stateIndex = 0,
+  animationId,
+}) => {
+  if (!Number.isSafeInteger(stateIndex) || stateIndex < 0) {
+    throw new Error(
+      "Timeline inspection state index must be a non-negative safe integer.",
+    );
+  }
+  const rawState = definition.states[stateIndex];
+  if (!rawState) {
+    throw new Error(
+      `State index ${stateIndex} is out of range for ${definition.states.length} states.`,
+    );
+  }
+  const state = normalizeRenderState(rawState);
+  const indexedAnimations = state.animations.map((animation, index) => ({
+    animation,
+    index,
+  }));
+  const selected = animationId
+    ? indexedAnimations.filter(({ animation }) => animation.id === animationId)
+    : indexedAnimations;
+  if (animationId && selected.length === 0) {
+    throw new Error(
+      `Animation "${animationId}" was not found in state "${state.id ?? stateIndex}".`,
+    );
+  }
+
+  return {
+    schema: "route.timeline-inspection-set/v1",
+    state: { index: stateIndex, id: state.id ?? null },
+    animations: selected.map(({ animation, index }) => {
+      const sourcePath = `states[${stateIndex}].animations[${index}]`;
+      const program = compileAnimationTimelineProgram(animation, {
+        sourcePath,
+      });
+      return {
+        normalizedAst: animation,
+        ...inspectTimelineProgram(program),
+      };
+    }),
+  };
+};
+
+export const inspectTimelineFile = async ({
+  inputPath,
+  cwd = process.cwd(),
+  stateIndex = 0,
+  animationId,
+}) => {
+  if (!inputPath)
+    throw new Error("Timeline inspection requires an input YAML file.");
+  const absolutePath = path.resolve(cwd, inputPath);
+  const yamlSource = await fs.readFile(absolutePath, "utf8");
+  return inspectTimelineDefinition({
+    definition: loadRenderDefinition(yamlSource),
+    stateIndex,
+    animationId,
+  });
+};

package/src/cli/inspectTimeline.test.js

@@ -0,0 +1,135 @@
+import { describe, expect, it } from "vitest";
+import fs from "node:fs";
+import { inspectTimelineDefinition } from "./inspectTimeline.js";
+import { loadRenderDefinition } from "./renderConfig.js";
+import {
+  parseRouteGraphicsCliArgs,
+  runRouteGraphicsCli,
+} from "./routeGraphicsCli.js";
+
+const source = `
+states:
+  - id: demo
+    elements: []
+    animations:
+      - id: move
+        targetId: hero
+        type: update
+        gsap:
+          profile: portable-v1
+          steps:
+            - kind: mark
+              name: entrance
+            - kind: to
+              values: { x: 100 }
+              duration: 250
+`;
+
+describe("timeline inspector", () => {
+  it("reports normalized authoring, semantic program, and visualization lanes", () => {
+    const result = inspectTimelineDefinition({
+      definition: loadRenderDefinition(source),
+      stateIndex: 0,
+      animationId: "move",
+    });
+    expect(result.animations[0]).toMatchObject({
+      normalizedAst: { id: "move", gsap: { profile: "portable-v1" } },
+      summary: { duration: 250, clipCount: 1, frontend: "gsap" },
+      visualization: {
+        marks: { entrance: 0 },
+        lanes: [{ channel: "transform.x", start: 0, duration: 250 }],
+      },
+    });
+    expect(result.animations[0].semanticSignature).toContain(
+      '"schema":"route.timeline/v1"',
+    );
+  });
+
+  it("parses and runs inspect-timeline without launching a browser", async () => {
+    expect(
+      parseRouteGraphicsCliArgs([
+        "inspect-timeline",
+        "scene.yaml",
+        "--animation",
+        "move",
+        "--compact",
+      ]),
+    ).toMatchObject({
+      command: "inspect-timeline",
+      inputPath: "scene.yaml",
+      animationId: "move",
+      compact: true,
+    });
+
+    const stdout = {
+      value: "",
+      write(value) {
+        this.value += value;
+      },
+    };
+    const stderr = {
+      value: "",
+      write(value) {
+        this.value += value;
+      },
+    };
+    const exitCode = await runRouteGraphicsCli({
+      argv: ["inspect-timeline", "virtual.yaml", "--compact"],
+      cwd: "/virtual",
+      stdout,
+      stderr,
+    });
+    expect(exitCode).toBe(1);
+    expect(stdout.value).toBe("");
+    expect(stderr.value).toContain("ENOENT");
+    expect(() =>
+      parseRouteGraphicsCliArgs([
+        "inspect-timeline",
+        "scene.yaml",
+        "--output",
+        "ignored.json",
+      ]),
+    ).toThrow("--output is not supported by inspect-timeline");
+  });
+
+  it("preserves original animation indexes in source paths when filtering", () => {
+    const result = inspectTimelineDefinition({
+      definition: loadRenderDefinition(`
+states:
+  - elements: []
+    animations:
+      - id: first
+        targetId: one
+        type: update
+        tween:
+          x:
+            keyframes: [{ value: 1, duration: 10 }]
+      - id: second
+        targetId: two
+        type: update
+        tween:
+          x:
+            keyframes: [{ value: 2, duration: 10 }]
+`),
+      animationId: "second",
+    });
+    expect(result.animations[0].visualization.lanes[0].sourcePath).toContain(
+      "animations[1]",
+    );
+  });
+
+  it("compiles the checked-in portable GSAP example", () => {
+    const example = fs.readFileSync(
+      `${process.cwd()}/examples/portable-gsap.yaml`,
+      "utf8",
+    );
+    const result = inspectTimelineDefinition({
+      definition: loadRenderDefinition(example),
+    });
+    expect(result.animations[0].summary).toMatchObject({
+      programId: "card-entrance",
+      frontend: "gsap",
+      eventCount: 1,
+    });
+  });
+});

package/src/cli/routeGraphicsCli.js

@@ -15,15 +15,24 @@ import {
 import { getRendererBrowserLaunchOptions } from "./browserLaunch.js";
 import { renderMp4 } from "./renderVideo.js";
 import { parseStateSelection } from "./stateSelection.js";
+import { inspectTimelineFile } from "./inspectTimeline.js";
 
 const cliModuleDir = path.dirname(fileURLToPath(import.meta.url));
 const projectRoot = path.resolve(cliModuleDir, "..", "..");
 const bundlePath = path.join(projectRoot, "dist", "RouteGraphics.js");
 
 const SUPPORTED_FORMATS = new Set(["png", "mp4"]);
+const INSPECT_TIMELINE_OPTIONS = new Set([
+  "-h",
+  "--help",
+  "--state",
+  "--animation",
+  "--compact",
+]);
 
 const usage = `Usage:
   route-graphics render <input.yaml> -o <output> [options]
+  route-graphics inspect-timeline <input.yaml> [options]
 
 Options:
   -o, --output <path>              Output path. Supports .png and .mp4
@@ -50,6 +59,11 @@ Runtime options:
   --ffmpeg <path>                  ffmpeg path for MP4 output (default: ffmpeg)
   --timeout <ms>                   Browser-side render timeout (default: 15000)
   -h, --help                       Show this help
+
+Timeline inspection options:
+  --state <index>                  State index (default: 0)
+  --animation <id>                 Inspect one animation id
+  --compact                        Emit compact JSON instead of indented JSON
 `;
 
 const renderCommandUsage = usage;
@@ -223,13 +237,21 @@ export const parseRouteGraphicsCliArgs = (argv) => {
     };
   }
 
-  if (command !== "render") {
+  if (command !== "render" && command !== "inspect-timeline") {
     throw new Error(`Unknown command: ${command}`);
   }
 
   for (let index = 0; index < rest.length; index += 1) {
     const token = rest[index];
 
+    if (
+      command === "inspect-timeline" &&
+      token.startsWith("-") &&
+      !INSPECT_TIMELINE_OPTIONS.has(token)
+    ) {
+      throw new Error(`${token} is not supported by inspect-timeline.`);
+    }
+
     switch (token) {
       case "-h":
       case "--help":
@@ -268,6 +290,19 @@ export const parseRouteGraphicsCliArgs = (argv) => {
         );
         index += 1;
         break;
+      case "--animation":
+        if (command !== "inspect-timeline") {
+          throw new Error("--animation is only supported by inspect-timeline.");
+        }
+        options.animationId = readOptionValue(rest, index, token);
+        index += 1;
+        break;
+      case "--compact":
+        if (command !== "inspect-timeline") {
+          throw new Error("--compact is only supported by inspect-timeline.");
+        }
+        options.compact = true;
+        break;
       case "--states":
         options.stateSelection = readOptionValue(rest, index, token);
         index += 1;
@@ -890,6 +925,19 @@ export const runRouteGraphicsCli = async ({
   }
 
   try {
+    if (cliOptions.command === "inspect-timeline") {
+      const inspection = await inspectTimelineFile({
+        inputPath: cliOptions.inputPath,
+        cwd,
+        stateIndex: cliOptions.stateIndex ?? 0,
+        animationId: cliOptions.animationId,
+      });
+      stdout.write(
+        `${JSON.stringify(inspection, null, cliOptions.compact ? 0 : 2)}\n`,
+      );
+      return 0;
+    }
+
     const result = await runRender({ cliOptions, cwd });
     const totalDurationMS = performance.now() - startedAt;