hyperframes 0.4.39 → 0.4.40

package/dist/cli.js

@@ -54,7 +54,7 @@ var VERSION;
 var init_version = __esm({
   "src/version.ts"() {
     "use strict";
-    VERSION = true ? "0.4.39" : "0.0.0-dev";
+    VERSION = true ? "0.4.40" : "0.0.0-dev";
   }
 });
 
@@ -26182,6 +26182,27 @@ async function pollPageExpression(page, expression, timeoutMs, intervalMs = 100)
   }
   return Boolean(await page.evaluate(expression));
 }
+async function applyVideoMetadataHints(page, hints) {
+  if (!hints || hints.length === 0) return;
+  await page.evaluate(
+    (metadataHints) => {
+      for (const hint of metadataHints) {
+        if (!hint.id || !Number.isFinite(hint.width) || !Number.isFinite(hint.height) || hint.width <= 0 || hint.height <= 0) {
+          continue;
+        }
+        const video = document.getElementById(hint.id);
+        if (!video) continue;
+        if (!video.hasAttribute("width")) video.setAttribute("width", String(hint.width));
+        if (!video.hasAttribute("height")) video.setAttribute("height", String(hint.height));
+        const computed = window.getComputedStyle(video);
+        if (!video.style.aspectRatio && (!computed.aspectRatio || computed.aspectRatio === "auto")) {
+          video.style.aspectRatio = `${hint.width} / ${hint.height}`;
+        }
+      }
+    },
+    [...hints]
+  );
+}
 async function initializeSession(session) {
   const { page, serverUrl } = session;
   page.on("console", (msg) => {
@@ -26225,6 +26246,7 @@ async function initializeSession(session) {
         `[FrameCapture] window.__hf not ready after ${pageReadyTimeout2}ms. Page must expose window.__hf = { duration, seek }.`
       );
     }
+    await applyVideoMetadataHints(page, session.options.videoMetadataHints);
     const skipIdsLiteral = JSON.stringify(session.options.skipReadinessVideoIds ?? []);
     const videosReady = await pollPageExpression(
       page,
@@ -26291,6 +26313,7 @@ async function initializeSession(session) {
       `[FrameCapture] window.__hf not ready after ${pageReadyTimeout}ms. Page must expose window.__hf = { duration, seek }.`
     );
   }
+  await applyVideoMetadataHints(page, session.options.videoMetadataHints);
   const beginframeSkipIdsLiteral = JSON.stringify(session.options.skipReadinessVideoIds ?? []);
   const videoDeadline = Date.now() + (session.config?.playerReadyTimeout ?? DEFAULT_CONFIG2.playerReadyTimeout);
   while (Date.now() < videoDeadline) {
@@ -34108,6 +34131,24 @@ function applyRenderModeHints(cfg, compiled, log2 = defaultLogger) {
     reasons: compiled.renderModeHints.reasons.map((reason) => reason.message)
   });
 }
+function collectVideoReadinessSkipIds(nativeHdrVideoIds, extractedVideos) {
+  return Array.from(
+    /* @__PURE__ */ new Set([
+      ...nativeHdrVideoIds,
+      ...extractedVideos.filter((video) => hasUsableVideoDimensions(video.metadata)).map((video) => video.videoId)
+    ])
+  ).sort();
+}
+function hasUsableVideoDimensions(metadata) {
+  return Number.isFinite(metadata.width) && Number.isFinite(metadata.height) && metadata.width > 0 && metadata.height > 0;
+}
+function collectVideoMetadataHints(extractedVideos) {
+  return extractedVideos.filter((video) => hasUsableVideoDimensions(video.metadata)).map((video) => ({
+    id: video.videoId,
+    width: video.metadata.width,
+    height: video.metadata.height
+  })).sort((a, b) => a.id.localeCompare(b.id));
+}
 function resolveRenderWorkerCount(totalFrames, requestedWorkers, cfg, compiled, composition, log2 = defaultLogger, measuredCaptureCost) {
   const captureCost = combineCaptureCostEstimates(
     estimateCaptureCostMultiplier(compiled, composition),
@@ -35119,6 +35160,8 @@ async function executeRenderJob(job, projectDir, outputPath, onProgress, abortSi
     let frameLookup = null;
     const compiledDir = join35(workDir, "compiled");
     let extractionResult = null;
+    let videoReadinessSkipIds = [];
+    let videoMetadataHints = [];
     const nativeHdrVideoIds = /* @__PURE__ */ new Set();
     const videoTransfers = /* @__PURE__ */ new Map();
     if (job.config.hdrMode !== "force-sdr" && composition.videos.length > 0) {
@@ -35175,6 +35218,11 @@ async function executeRenderJob(job, projectDir, outputPath, onProgress, abortSi
       if (extractionResult.extracted.length > 0) {
         frameLookup = createFrameLookupTable(composition.videos, extractionResult.extracted);
       }
+      videoReadinessSkipIds = collectVideoReadinessSkipIds(
+        nativeHdrVideoIds,
+        extractionResult.extracted
+      );
+      videoMetadataHints = collectVideoMetadataHints(extractionResult.extracted);
       perfStages.videoExtractMs = Date.now() - stage2Start;
       const existingAudioSrcs = new Set(composition.audios.map((a) => a.src));
       for (const ext of extractionResult.extracted) {
@@ -35288,9 +35336,10 @@ async function executeRenderJob(job, projectDir, outputPath, onProgress, abortSi
       format: needsAlpha ? "png" : "jpeg",
       quality: needsAlpha ? void 0 : job.config.quality === "draft" ? 80 : 95
     };
-    const buildHdrCaptureOptions = () => ({
+    const buildCaptureOptions = () => ({
       ...captureOptions,
-      skipReadinessVideoIds: Array.from(nativeHdrVideoIds)
+      videoMetadataHints,
+      skipReadinessVideoIds: videoReadinessSkipIds
     });
     let captureCalibration;
     let switchedToScreenshotAfterCalibration = false;
@@ -35303,7 +35352,7 @@ async function executeRenderJob(job, projectDir, outputPath, onProgress, abortSi
         calibrationSession = await createCaptureSession(
           fileServer.url,
           calibrationDir,
-          buildHdrCaptureOptions(),
+          buildCaptureOptions(),
           videoInjector,
           calibrationCfg
         );
@@ -35427,7 +35476,7 @@ async function executeRenderJob(job, projectDir, outputPath, onProgress, abortSi
       const domSession = await createCaptureSession(
         fileServer.url,
         framesDir,
-        buildHdrCaptureOptions(),
+        buildCaptureOptions(),
         createVideoFrameInjector(frameLookup),
         cfg
       );
@@ -35960,7 +36009,7 @@ async function executeRenderJob(job, projectDir, outputPath, onProgress, abortSi
               fileServer.url,
               workDir,
               tasks,
-              buildHdrCaptureOptions(),
+              buildCaptureOptions(),
               () => createVideoFrameInjector(frameLookup),
               abortSignal,
               (progress) => {
@@ -35990,7 +36039,7 @@ async function executeRenderJob(job, projectDir, outputPath, onProgress, abortSi
             const session = probeSession ?? await createCaptureSession(
               fileServer.url,
               framesDir,
-              buildHdrCaptureOptions(),
+              buildCaptureOptions(),
               videoInjector,
               cfg
             );
@@ -36045,7 +36094,7 @@ async function executeRenderJob(job, projectDir, outputPath, onProgress, abortSi
               initialWorkerCount: workerCount,
               allowRetry: job.config.workers === void 0,
               frameExt: needsAlpha ? "png" : "jpg",
-              captureOptions: buildHdrCaptureOptions(),
+              captureOptions: buildCaptureOptions(),
               createBeforeCaptureHook: () => createVideoFrameInjector(frameLookup),
               abortSignal,
               onProgress: (progress) => {
@@ -36080,7 +36129,7 @@ async function executeRenderJob(job, projectDir, outputPath, onProgress, abortSi
             const session = probeSession ?? await createCaptureSession(
               fileServer.url,
               framesDir,
-              buildHdrCaptureOptions(),
+              buildCaptureOptions(),
               videoInjector,
               cfg
             );

package/dist/skills/gsap/SKILL.md

@@ -5,6 +5,28 @@ description: GSAP animation reference for HyperFrames. Covers gsap.to(), from(),
 
 # GSAP
 
+## HyperFrames Contract
+
+HyperFrames controls GSAP through its `gsap` runtime adapter. Create a paused timeline synchronously, register it on `window.__timelines` with the exact `data-composition-id`, and let HyperFrames seek it.
+
+```html
+<script src="https://cdn.jsdelivr.net/npm/gsap@3.14.2/dist/gsap.min.js"></script>
+<script>
+  window.__timelines = window.__timelines || {};
+  const tl = gsap.timeline({ paused: true });
+
+  tl.from(".title", { y: 48, opacity: 0, duration: 0.6, ease: "power3.out" }, 0);
+  tl.to(".accent", { scaleX: 1, duration: 0.5, ease: "power2.out" }, 0.25);
+
+  window.__timelines["main"] = tl; // key must equal data-composition-id on the composition root
+</script>
+```
+
+- The registry key must match the composition root's `data-composition-id`.
+- Do not call `tl.play()` for render-critical motion.
+- Do not build timelines inside async code, timers, or event handlers.
+- Keep loops finite. HyperFrames renders finite video durations.
+
 ## Core Tween Methods
 
 - **gsap.to(targets, vars)** — animate from current state to `vars`. Most common.
@@ -21,7 +43,7 @@ Always use **camelCase** property names (e.g. `backgroundColor`, `rotationX`).
 - **ease** — `"power1.out"` (default), `"power3.inOut"`, `"back.out(1.7)"`, `"elastic.out(1, 0.3)"`, `"none"`.
 - **stagger** — number `0.1` or object: `{ amount: 0.3, from: "center" }`, `{ each: 0.1, from: "random" }`.
 - **overwrite** — `false` (default), `true`, or `"auto"`.
-- **repeat** — number or `-1` for infinite. **yoyo** — alternates direction with repeat.
+- **repeat** — finite number; never `-1` in HyperFrames. Compute repeats from the visible duration. **yoyo** — alternates direction with repeat.
 - **onComplete**, **onStart**, **onUpdate** — callbacks.
 - **immediateRender** — default `true` for from()/fromTo(). Set `false` on later tweens targeting the same property+element to avoid overwrite.
 
@@ -209,3 +231,10 @@ Pause or kill off-screen animations.
 - Chain animations with delay when a timeline can sequence them.
 - Create tweens before the DOM exists.
 - Skip cleanup — always kill tweens when no longer needed.
+- Use infinite repeat values in HyperFrames compositions. Use finite repeat counts computed from the visible duration.
+
+## Credits And References
+
+- HyperFrames adapter source: `packages/core/src/runtime/adapters/gsap.ts`.
+- GSAP documentation: https://gsap.com/docs/v3/
+- GSAP timeline pause and seek behavior: https://gsap.com/docs/v3/GSAP/Timeline/pause%28%29/

package/dist/templates/_shared/CLAUDE.md

@@ -11,6 +11,11 @@
 | **hyperframes-registry**   | `/hyperframes-registry`   | Installing blocks and components via `hyperframes add`                                            |
 | **website-to-hyperframes** | `/website-to-hyperframes` | Capturing a URL and turning it into a video — full website-to-video pipeline                      |
 | **gsap**                   | `/gsap`                   | GSAP animations for HyperFrames — tweens, timelines, easing, performance                          |
+| **animejs**                | `/animejs`                | Anime.js animations registered on `window.__hfAnime`                                              |
+| **css-animations**         | `/css-animations`         | CSS keyframes that HyperFrames can pause and seek                                                 |
+| **lottie**                 | `/lottie`                 | `lottie-web` and dotLottie players registered on `window.__hfLottie`                              |
+| **three**                  | `/three`                  | Three.js scenes rendered from HyperFrames `hf-seek` events                                        |
+| **waapi**                  | `/waapi`                  | Web Animations API motion driven through `document.getAnimations()`                               |
 
 > **Skills not available?** Ask the user to run `npx hyperframes skills` and restart their
 > agent session, or install manually: `npx skills add heygen-com/hyperframes`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hyperframes",
-  "version": "0.4.39",
+  "version": "0.4.40",
   "description": "HyperFrames CLI — create, preview, and render HTML video compositions",
   "repository": {
     "type": "git",