dsh-hyperframes 0.2.0 → 0.3.0

package/skills/hyperframes-animation/scripts/animation-map-sampling.test.mjs

@@ -0,0 +1,48 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { sampleTweenBboxes } from "./animation-map-sampling.mjs";
+
+test("samples every tween time in one browser evaluation", async () => {
+  const calls = [];
+  const seekTimes = [];
+  const originalGlobals = {
+    window: globalThis.window,
+    document: globalThis.document,
+    getComputedStyle: globalThis.getComputedStyle,
+  };
+  let currentTime = 0;
+  globalThis.window = { __hf: { seek: (time) => (currentTime = time) } };
+  globalThis.document = {
+    querySelector: () => ({
+      getBoundingClientRect: () => ({ x: currentTime, y: 20, width: 30, height: 40 }),
+    }),
+  };
+  globalThis.getComputedStyle = () => ({ opacity: "1", visibility: "visible", display: "block" });
+  const page = {
+    async evaluate(callback, payload) {
+      calls.push(payload);
+      const originalSeek = globalThis.window.__hf.seek;
+      globalThis.window.__hf.seek = (time) => {
+        seekTimes.push(time);
+        originalSeek(time);
+      };
+      return callback(payload);
+    },
+  };
+
+  try {
+    const result = await sampleTweenBboxes(page, "#card", [1, 2, 3]);
+
+    assert.deepEqual(result, [
+      { t: 1, x: 1, y: 20, w: 30, h: 40, opacity: 1, visible: true },
+      { t: 2, x: 2, y: 20, w: 30, h: 40, opacity: 1, visible: true },
+      { t: 3, x: 3, y: 20, w: 30, h: 40, opacity: 1, visible: true },
+    ]);
+    assert.deepEqual(seekTimes, [1, 2, 3]);
+    assert.deepEqual(calls, [{ selector: "#card", times: [1, 2, 3] }]);
+  } finally {
+    globalThis.window = originalGlobals.window;
+    globalThis.document = originalGlobals.document;
+    globalThis.getComputedStyle = originalGlobals.getComputedStyle;
+  }
+});

package/skills/{hyperframes → hyperframes-animation}/scripts/animation-map.mjs

@@ -6,19 +6,36 @@
 // human-readable summaries. Outputs a single animation-map.json.
 //
 // Usage:
-//   node skills/hyperframes/scripts/animation-map.mjs <composition-dir> \
+//   node skills/hyperframes-animation/scripts/animation-map.mjs <composition-dir> \
 //     [--frames N] [--out <dir>] [--min-duration S] [--width W] [--height H] [--fps N]
+//
+// Env:
+//   HYPERFRAMES_SKILL_PKG_VERSION — pin the @hyperframes/producer version used
+//     when bootstrapping (global skill installs cannot infer it; falls back to
+//     @latest with a warning otherwise).
 
 import { mkdir, writeFile } from "node:fs/promises";
 import { resolve, join } from "node:path";
-
+import { sampleTweenBboxes } from "./animation-map-sampling.mjs";
 import {
-  createFileServer,
-  createCaptureSession,
-  initializeSession,
-  closeCaptureSession,
-  getCompositionDuration,
-} from "@hyperframes/producer";
+  bundleCompositionForCapture,
+  hyperframesPackageSpec,
+  importPackagesOrBootstrap,
+  initializeSessionWithRetry,
+} from "./package-loader.mjs";
+
+const packages = await importPackagesOrBootstrap(
+  ["@hyperframes/producer", "@hyperframes/core", "@hyperframes/core/compiler"],
+  {
+    npmPackages: [
+      hyperframesPackageSpec("@hyperframes/producer"),
+      hyperframesPackageSpec("@hyperframes/core"),
+    ],
+  },
+);
+const { createFileServer, createCaptureSession, closeCaptureSession, getCompositionDuration } =
+  packages["@hyperframes/producer"];
+const { parseFps } = packages["@hyperframes/core"];
 
 // ─── CLI ─────────────────────────────────────────────────────────────────────
 
@@ -30,23 +47,43 @@ const OUT_DIR = resolve(args.out ?? ".hyperframes/anim-map");
 const MIN_DUR = Number(args["min-duration"] ?? 0.15);
 const WIDTH = Number(args.width ?? 1920);
 const HEIGHT = Number(args.height ?? 1080);
-const FPS = Number(args.fps ?? 30);
+const parsedFps = parseFps(args.fps ?? 30);
+if (!parsedFps.ok) die(`Invalid --fps "${args.fps ?? ""}": ${parsedFps.reason}`);
+const FPS = parsedFps.value;
 const COMP_DIR = resolve(args.composition);
 
 await mkdir(OUT_DIR, { recursive: true });
 
 // ─── Main ────────────────────────────────────────────────────────────────────
 
-const server = await createFileServer({ projectDir: COMP_DIR, port: 0 });
-const session = await createCaptureSession(
-  server.url,
-  OUT_DIR,
-  { width: WIDTH, height: HEIGHT, fps: FPS, format: "png" },
-  null,
-);
-await initializeSession(session);
-
+// Raw modular hosts do not mount child compositions in the capture helper.
+// Bundle first so duration/timeline discovery sees the same DOM as render/check.
+const bundle = await bundleCompositionForCapture(packages["@hyperframes/core/compiler"], COMP_DIR);
+let server;
+let session;
 try {
+  server = await createFileServer({
+    projectDir: COMP_DIR,
+    compiledDir: bundle.compiledDir,
+    port: 0,
+  });
+  // Canonical transient-init retry/cleanup (mirrors the render pipeline's
+  // probeStage): a valid modular project's sub-composition timelines register
+  // asynchronously, so the first attempt can time out as transient
+  // "zero duration / Runtime ready: false" — retry once with a fresh browser
+  // instead of false-failing the project.
+  session = await initializeSessionWithRetry(
+    packages["@hyperframes/producer"],
+    () =>
+      createCaptureSession(
+        server.url,
+        OUT_DIR,
+        { width: WIDTH, height: HEIGHT, fps: FPS, format: "png" },
+        null,
+      ),
+    { log: (message) => console.error(`animation-map: ${message}`) },
+  );
+
   const duration = await getCompositionDuration(session);
   const tweens = await enumerateTweens(session);
   const kept = tweens.filter((tw) => tw.end - tw.start >= MIN_DUR);
@@ -67,12 +104,11 @@ try {
       (_, k) => +(tw.start + ((k + 0.5) / FRAMES) * (tw.end - tw.start)).toFixed(3),
     );
 
-    const bboxes = [];
-    for (const t of times) {
-      await seekTo(session, t);
-      const bbox = await measureTarget(session, tw.selectorHint);
-      bboxes.push({ t, ...bbox });
-    }
+    // No selector means no element to measure (an onUpdate driver). Sampling anyway
+    // would hand querySelector an unmatchable string.
+    const bboxes = tw.selectorHint
+      ? await sampleTweenBboxes(session.page, tw.selectorHint, times)
+      : [];
 
     const animProps = tw.props.filter(
       (p) => !["parent", "overwrite", "immediateRender", "startAt", "runBackwards"].includes(p),
@@ -82,7 +118,8 @@ try {
 
     report.tweens.push({
       index: i + 1,
-      selector: tw.selectorHint,
+      selector: tw.selectorHint ?? "(onUpdate driver)",
+      driver: tw.driver,
       targets: tw.targetCount,
       props: animProps,
       start: +tw.start.toFixed(3),
@@ -106,8 +143,14 @@ try {
   // ── Composition-level analysis ──
   report.choreography = buildTimeline(report.tweens, duration);
   report.density = computeDensity(report.tweens, duration);
-  report.staggers = detectStaggers(report.tweens);
-  report.elements = buildElementLifecycles(report.tweens);
+  // Staggers and lifecycles are per-ELEMENT, and a driver tween has none. Keyed on
+  // tw.selector they would collapse every driver in the composition into one
+  // "(onUpdate driver)" pseudo-element with null geometry, and let three same-duration
+  // drivers read as a stagger no element performs. Density, dead zones and the timeline
+  // still count them — those are per-SPAN, which is what a driver does have.
+  const elementTweens = report.tweens.filter((tw) => tw.driver !== "onUpdate");
+  report.staggers = detectStaggers(elementTweens);
+  report.elements = buildElementLifecycles(elementTweens);
   report.deadZones = findDeadZones(report.density, duration);
   report.snapshots = await captureSnapshots(session, report.tweens, duration);
 
@@ -115,8 +158,9 @@ try {
 
   printSummary(report);
 } finally {
-  await closeCaptureSession(session).catch(() => {});
-  server.close();
+  if (session) await closeCaptureSession(session).catch(() => {});
+  server?.close();
+  bundle.cleanup();
 }
 
 // ─── Seek helper ────────────────────────────────────────────────────────────
@@ -151,17 +195,21 @@ async function enumerateTweens(session) {
       return cls ? `${el.tagName.toLowerCase()}.${cls}` : el.tagName.toLowerCase();
     };
 
-    const walk = (node, parentOffset = 0) => {
+    const walk = (node, parentOffset = 0, parentDriven = false) => {
       if (!node) return;
       if (typeof node.getChildren === "function") {
         const offset = parentOffset + (node.startTime?.() ?? 0);
+        // A TIMELINE can own the driver instead of the tween. The WebGL/uniform idiom is
+        // gsap.timeline({ onUpdate: renderFrame }) over children that tween plain uniform
+        // objects; those children carry no onUpdate of their own, so the driver has to
+        // reach them from above or their motion reads as a dead zone all the same.
+        const driven = parentDriven || typeof node.vars?.onUpdate === "function";
         for (const child of node.getChildren(true, true, true)) {
-          walk(child, offset);
+          walk(child, offset, driven);
         }
         return;
       }
       const targets = (node.targets?.() ?? []).filter((t) => t instanceof Element);
-      if (!targets.length) return;
       const vars = node.vars ?? {};
       const props = Object.keys(vars).filter(
         (k) =>
@@ -177,10 +225,28 @@ async function enumerateTweens(session) {
             "stagger",
           ].includes(k),
       );
+      // The proxy-driver idiom tweens a plain object and applies the motion in onUpdate,
+      // so targets() holds no Element. Dropping those tweens hid real motion from the
+      // map: computeDensity saw zero active tweens over their span and findDeadZones
+      // reported it as dead. There is no element to select or measure here, but the span
+      // is real, so keep the tween and mark why it carries no geometry.
+      //
+      // Under an inherited driver the tween must also CHANGE something. Its own onUpdate is
+      // proof of work by itself (a repaint loop need not animate a property), but a parent's
+      // is not: a bare `tl.to({}, { duration: D })` spacer inside a driven timeline advances
+      // the playhead without altering any value, so counting it would mask a genuine dead
+      // zone — the exact false positive the tween-local rule was careful to avoid.
+      const isProxyDriver =
+        targets.length === 0 &&
+        (typeof vars.onUpdate === "function" || (parentDriven && props.length > 0));
+      if (!targets.length && !isProxyDriver) return;
       const start = parentOffset + (node.startTime?.() ?? 0);
       const end = start + (node.duration?.() ?? 0);
       results.push({
-        selectorHint: selectorOf(targets[0]) ?? "(unknown)",
+        // null, not a placeholder string: this feeds document.querySelector downstream,
+        // so it must be absent rather than unmatchable.
+        selectorHint: isProxyDriver ? null : (selectorOf(targets[0]) ?? "(unknown)"),
+        driver: isProxyDriver ? "onUpdate" : "target",
         targetCount: targets.length,
         props,
         start,
@@ -195,30 +261,21 @@ async function enumerateTweens(session) {
   });
 }
 
-async function measureTarget(session, selector) {
-  return await session.page.evaluate((sel) => {
-    const el = document.querySelector(sel);
-    if (!el) return { x: 0, y: 0, w: 0, h: 0, missing: true };
-    const r = el.getBoundingClientRect();
-    const cs = getComputedStyle(el);
-    return {
-      x: Math.round(r.x),
-      y: Math.round(r.y),
-      w: Math.round(r.width),
-      h: Math.round(r.height),
-      opacity: parseFloat(cs.opacity),
-      visible: cs.visibility !== "hidden" && cs.display !== "none",
-    };
-  }, selector);
-}
-
 // ─── Tween description (the key output for agents) ──────────────────────────
 
 function describeTween(tw, props, bboxes, flags) {
   const dur = (tw.end - tw.start).toFixed(2);
   const parts = [];
 
-  parts.push(`${tw.selectorHint} animates ${props.join("+")} over ${dur}s (${tw.ease})`);
+  if (tw.selectorHint) {
+    parts.push(`${tw.selectorHint} animates ${props.join("+")} over ${dur}s (${tw.ease})`);
+  } else {
+    // An onUpdate driver: the span and props are known, the affected element is not.
+    parts.push(
+      `an onUpdate driver animates ${props.join("+")} over ${dur}s (${tw.ease}) — ` +
+        `motion is applied in JS, so no element geometry was measured`,
+    );
+  }
 
   // Movement
   const first = bboxes[0];
@@ -283,7 +340,10 @@ function computeFlags(tw, bboxes, { width, height }) {
   const flags = [];
   const dur = tw.end - tw.start;
 
-  if (bboxes.every((b) => b.w === 0 || b.h === 0)) flags.push("degenerate");
+  // No samples at all (an onUpdate driver has no element to measure) is not evidence of
+  // a degenerate or invisible box — `[].every()` is vacuously true, so guard the
+  // geometry-derived flags. The pacing flags below read only start/end and still apply.
+  if (bboxes.length && bboxes.every((b) => b.w === 0 || b.h === 0)) flags.push("degenerate");
 
   const anyOffscreen = bboxes.some(
     (b) =>
@@ -298,7 +358,10 @@ function computeFlags(tw, bboxes, { width, height }) {
   );
   if (anyOffscreen) flags.push("offscreen");
 
-  if (bboxes.every((b) => b.opacity !== undefined && b.opacity < 0.01 && b.visible)) {
+  if (
+    bboxes.length &&
+    bboxes.every((b) => b.opacity !== undefined && b.opacity < 0.01 && b.visible)
+  ) {
     flags.push("invisible");
   }