@hyperframes/engine 0.8.167 → 0.8.169

package/dist/config.d.ts

@@ -5,13 +5,14 @@
  * env var sprawl with a structured interface. Env vars still work as
  * fallbacks for backward compatibility during migration.
  */
+import { type DistributedFps } from "@hyperframes/core/distributed-fps";
 /**
  * Full engine configuration. All fields are wired through the config
  * object; env vars serve as backward-compatible fallbacks resolved
  * in `resolveConfig()`.
  */
 export interface EngineConfig {
-    fps: 24 | 30 | 60;
+    fps: DistributedFps;
     quality: "draft" | "standard" | "high";
     format: "jpeg" | "png";
     jpegQuality: number;

package/dist/config.js

@@ -6,6 +6,7 @@
  * fallbacks for backward compatibility during migration.
  */
 import { tmpdir } from "node:os";
+import { DISTRIBUTED_FPS } from "@hyperframes/core/distributed-fps";
 import { chromeMajorCeiling } from "./services/chromeHostCeiling.js";
 import { join } from "node:path";
 import { getSystemTotalMb, isLowMemorySystem, LOW_MEMORY_TOTAL_MB_THRESHOLD, } from "./services/systemMemory.js";
@@ -96,7 +97,7 @@ const POSITIVE_NUMBER_ENGINE_CONFIG_FIELDS = [
     "extractCacheMaxBytes",
 ];
 const ENUM_ENGINE_CONFIG_FIELDS = {
-    fps: [24, 30, 60],
+    fps: DISTRIBUTED_FPS,
     quality: ["draft", "standard", "high"],
     format: ["jpeg", "png"],
     browserGpuMode: ["software", "hardware", "auto"],

package/dist/services/browserManager.d.ts

@@ -122,7 +122,7 @@ type GpuConfig = Partial<Pick<EngineConfig, "browserGpuMode" | "disableGpu" | "c
  */
 export declare function usesSoftwareWebGpu(requiresWebGpu: boolean | undefined, config?: GpuConfig): boolean;
 export declare function buildChromeArgs(options: BuildChromeArgsOptions, config?: GpuConfig): string[];
-/** Does the composition's root element declare `data-requires-webgpu`? */
+/** Does the root, or a mounted root (data-hf-inner-root once bundled), declare `data-requires-webgpu`? */
 export declare function compositionRequiresWebGpu(html: string): boolean;
 /** No hardware WebGPU adapter on this host; distinct from a browser or navigation failure. */
 export declare class WebGpuUnavailableError extends Error {

package/dist/services/browserManager.js

@@ -879,12 +879,13 @@ export function buildChromeArgs(options, config) {
     }
     return chromeArgs;
 }
-/** Does the composition's root element declare `data-requires-webgpu`? */
+/** Does the root, or a mounted root (data-hf-inner-root once bundled), declare `data-requires-webgpu`? */
 export function compositionRequiresWebGpu(html) {
     for (const tag of scanHtmlOpeningTags(html)) {
         const names = tag.attributes.map((attribute) => attribute.name);
-        if (names.includes("data-composition-id"))
-            return names.includes("data-requires-webgpu");
+        const isRoot = names.includes("data-composition-id") || names.includes("data-hf-inner-root");
+        if (isRoot && names.includes("data-requires-webgpu"))
+            return true;
     }
     return false;
 }

package/dist/services/chunkEncoder.d.ts

@@ -43,6 +43,8 @@ export interface MuxVideoWithAudioOptions extends Partial<Pick<EngineConfig, "ff
      * depend on the file extension alone.
      */
     audioCodec?: "aac";
+    /** Replaces `-i <videoPath>` (which is then unused), e.g. with a concat-demuxer input. */
+    videoInputArgs?: readonly string[];
     /**
      * @deprecated No longer used. `-avoid_negative_ts` is never passed for
      * mp4/mov muxing (ffmpeg's `auto` default already resolves to `disabled`

package/dist/services/chunkEncoder.js

@@ -587,7 +587,7 @@ export async function muxVideoWithAudio(videoPath, audioPath, outputPath, signal
     const isWebm = outputPath.endsWith(".webm");
     const isMov = outputPath.endsWith(".mov");
     const shouldCopyAudio = isWebm ? false : await shouldCopyAacSidecar(audioPath, config);
-    const args = ["-i", videoPath, "-i", audioPath, "-c:v", "copy"];
+    const args = [...(config?.videoInputArgs ?? ["-i", videoPath]), "-i", audioPath, "-c:v", "copy"];
     if (isWebm) {
         args.push("-c:a", "libopus", "-b:a", "128k");
     }

package/dist/services/frameCapture.d.ts

@@ -12,7 +12,7 @@ import { type MotionBlurPlan } from "./motionBlur.js";
 import { type BrowserLease, type CaptureMode } from "./browserManager.js";
 import { pageScreenshotCapture } from "./screenshotService.js";
 import { type EngineConfig } from "../config.js";
-import type { CaptureOptions, CaptureResult, CaptureBufferResult, CapturePerfSummary, CaptureWarning, SubTimelineWaitMemo, SubTimelineWaitOutcome } from "../types.js";
+import type { CaptureOptions, CaptureVideoMetadataHint, CaptureResult, CaptureBufferResult, CapturePerfSummary, CaptureWarning, SubTimelineWaitMemo, SubTimelineWaitOutcome } from "../types.js";
 import { type ChromeMemorySampler, type ChromePids } from "./chromeMemorySampler.js";
 export { isMemoryExhaustionError, isTransientBrowserError } from "./captureFailure.js";
 export type { CaptureOptions, CaptureResult, CaptureBufferResult, CapturePerfSummary };
@@ -427,6 +427,7 @@ export declare function recordSubTimelineWarning(session: CaptureSession, timeou
  * PRINFRA-300 (blank hook scene, zero diagnostics, "fixed" by re-render).
  */
 export declare function buildLiveMapWarning(libraries: readonly string[]): CaptureWarning;
+export declare function applyVideoMetadataHints(page: Page, hints: readonly CaptureVideoMetadataHint[] | undefined): Promise<void>;
 /** Thrown once a VFX chain fails: the frames it paints would render without the effect. */
 export declare class VfxFailureError extends Error {
     readonly detail: string;

package/dist/services/frameCapture.js

@@ -434,14 +434,14 @@ async function waitForCloseWithTimeout(promise) {
  * screenshots carry a real alpha channel (Chrome resets the override on every
  * navigation, so this must run after page load).
  *
- * drawElement is also skipped when supersampling (deviceScaleFactor > 1):
+ * drawElement is also skipped when scaling (deviceScaleFactor other than 1):
  * `drawElementImage` reads the canvas at CSS pixels and has no equivalent of
  * `Page.captureScreenshot`'s clip+scale, so it would silently capture at 1x and
  * drop the requested supersample. Such renders fall through to the screenshot
- * path (preMode already forces "screenshot" for DPR > 1).
+ * path (preMode already forces "screenshot" for DPR other than 1).
  */
 async function initDrawElementOrTransparentBackground(session, page, logInitPhase) {
-    const supersampling = (session.options.deviceScaleFactor ?? 1) > 1;
+    const supersampling = (session.options.deviceScaleFactor ?? 1) !== 1;
     // forceScreenshot is an explicit routing decision made upstream (render-mode
     // compat hints like raw requestAnimationFrame, alpha formats, low-memory) —
     // drawElement must not override it. Concretely: an rAF-compat comp on
@@ -469,7 +469,7 @@ async function initDrawElementOrTransparentBackground(session, page, logInitPhas
         session.deGateReason = "supersampling";
         session.deFallbackTrigger = "supersampling";
         console.log("[engine] --experimental-fast-capture disabled for this render: drawElementImage " +
-            "ignores deviceScaleFactor, so supersampled (DPR > 1) output uses screenshot capture.");
+            "ignores deviceScaleFactor, so scaled (DPR other than 1) output uses screenshot capture.");
     }
     if ((session.config?.useDrawElement ?? false) && !supersampling && forceScreenshot) {
         session.deGateReason = "render_mode_hint";
@@ -769,8 +769,8 @@ export async function createCaptureSession(serverUrl, outputDir, options, onBefo
     // (the captured surface is sized by the OS window in CSS pixels regardless
     // of `Emulation.setDeviceMetricsOverride`'s DPR). When supersampling we
     // need explicit clip+scale on `Page.captureScreenshot`, so fall back to
-    // the screenshot path for any DPR > 1.
-    const supersampling = (options.deviceScaleFactor ?? 1) > 1;
+    // the screenshot path for any DPR other than 1.
+    const supersampling = (options.deviceScaleFactor ?? 1) !== 1;
     const requestedGpuMode = config?.browserGpuMode ?? DEFAULT_CONFIG.browserGpuMode;
     const resolvedGpuMode = await resolveBrowserGpuMode(requestedGpuMode, {
         chromePath: headlessShell ?? undefined,
@@ -1529,11 +1529,12 @@ async function decodeAllImages(page) {
         }));
     });
 }
-async function applyVideoMetadataHints(page, hints) {
+export async function applyVideoMetadataHints(page, hints) {
     if (!hints || hints.length === 0)
         return;
     // fallow-ignore-next-line complexity
-    await page.evaluate((metadataHints) => {
+    await page.evaluate(async (metadataHints) => {
+        const posters = new Set();
         for (const hint of metadataHints) {
             if (!hint.id ||
                 !Number.isFinite(hint.width) ||
@@ -1544,18 +1545,18 @@ async function applyVideoMetadataHints(page, hints) {
             }
             const video = (window.__hfMediaEl?.(hint.id) ??
                 document.getElementById(hint.id));
-            if (!video)
+            if (!video || video.hasAttribute("poster"))
                 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}`;
-            }
+            const svg = `<svg xmlns="http://www.w3.org/2000/svg" width="${hint.width}" height="${hint.height}"/>`;
+            const intrinsicSizePoster = `data:image/svg+xml,${encodeURIComponent(svg)}`;
+            video.poster = intrinsicSizePoster;
+            posters.add(intrinsicSizePoster);
         }
+        await Promise.all([...posters].map((src) => {
+            const image = new Image();
+            image.src = src;
+            return image.decode();
+        }));
     }, [...hints]);
 }
 async function waitForOptionalTailwindReady(page, timeoutMs) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hyperframes/engine",
-  "version": "0.8.167",
+  "version": "0.8.169",
   "description": "Seekable web page to video rendering engine (Puppeteer + FFmpeg)",
   "repository": {
     "type": "git",
@@ -50,8 +50,8 @@
     "linkedom": "^0.18.12",
     "puppeteer": "^25.8.0",
     "puppeteer-core": "^25.8.0",
-    "@hyperframes/parsers": "^0.8.167",
-    "@hyperframes/core": "^0.8.167"
+    "@hyperframes/core": "^0.8.169",
+    "@hyperframes/parsers": "^0.8.169"
   },
   "devDependencies": {
     "@types/node": "^25.0.10",