@hyperframes/engine 0.8.183 → 0.8.185

package/dist/index.d.ts

@@ -53,7 +53,7 @@ export { MIXED_AUDIO_FILENAME, parseAudioElements, parseMasterFxChain, processCo
 export { audioFailureDiagnostics } from "./services/audioFailureDiagnostic.js";
 export { cloneCaptureWarning, cloneCaptureWarnings } from "./services/captureWarning.js";
 export type { AudioElement, AudioFailureReason, AudioFailureStage, AudioProcessingFailure, AudioFailureDiagnostic, AudioSubprocessEvidence, AudioTrack, AudioVolumeKeyframe, MixResult, } from "./services/audioMixer.types.js";
-export { calculateOptimalWorkers, computeWorkerSizing, selectVerifySampleIndicesForTask, verifyDiskDrawElementSamples, distributeFrames, distributeFramesInterleaved, executeParallelCapture, mergeWorkerFrames, getSystemResources, shouldDisableBrowserPoolForParallelWorker, type WorkerTask, type WorkerResult, type WorkerSizing, type WorkerSizingBound, type ParallelProgress, } from "./services/parallelCoordinator.js";
+export { calculateOptimalWorkers, computeWorkerSizing, selectVerifySampleIndicesForTask, verifyDiskDrawElementSamples, distributeFrames, distributeFramesInterleaved, executeParallelCapture, mergeWorkerFrames, getSystemResources, shouldDisableBrowserPoolForParallelWorker, type WorkerTask, type WorkerResult, type WorkerSizing, type WorkerSizingBound, type LandedFrame, type ParallelProgress, } from "./services/parallelCoordinator.js";
 export { createFileServer, type FileServerOptions, type FileServerHandle, } from "./services/fileServer.js";
 export { quantizeTimeToFrame, MEDIA_VISUAL_STYLE_PROPERTIES } from "@hyperframes/core";
 export { frameFileExtension } from "./services/frameCapture.js";

package/dist/services/browserManager.js

@@ -364,11 +364,7 @@ async function probeBeginFrameSupport(browser, timeoutMs = BEGINFRAME_PROBE_TIME
         };
     }
     if (page && !(await settleWithin(page.close(), BEGINFRAME_PROBE_CLEANUP_TIMEOUT_MS))) {
-        return {
-            supported: false,
-            detail: `${result.detail}; probe page cleanup timed out`,
-            durationMs: Date.now() - started,
-        };
+        return { ...result, detail: `${result.detail}; probe page cleanup timed out` };
     }
     return result;
 }

package/dist/services/frameCapture.js

@@ -1498,8 +1498,8 @@ export function buildLiveMapWarning(libraries) {
         message: `Live map viewport(s) detected in the composition (${libraries.join(", ")}). ` +
             `Map tiles load over the network at render time, which the deterministic-render ` +
             `contract forbids: frames captured before tiles arrive ship a blank or partial map ` +
-            `with no error. Bake the map to a video first (see the motion-graphics maps skill / ` +
-            `bake-basemap.mjs) and use the baked file as the imagery layer.`,
+            `with no error. Bake the map to a video first (the hyperframes skill's ` +
+            `scripts/bake-basemap.mjs, see references/film.md) and use the baked file as the imagery layer.`,
         details: { sources: [...libraries] },
     };
 }

package/dist/services/parallelCoordinator.d.ts

@@ -55,6 +55,13 @@ export interface ParallelProgress {
     workerProgress: Map<number, number>;
     /** Latest lifecycle transition; absent on ordinary completed-frame updates. */
     latestWorkerPhase?: ParallelWorkerPhaseDiagnostic;
+    /** Disk capture only: the frame file this update finished writing, readable from now on. */
+    landedFrame?: LandedFrame;
+}
+/** A captured frame file: `index` is its file index (`frame_<index>`), `path` where it was written. */
+export interface LandedFrame {
+    index: number;
+    path: string;
 }
 export type ParallelWorkerPhase = "browser_launch" | "browser_probe" | "session_init" | "frame_capture" | "frame_encode";
 export interface ParallelWorkerPhaseDiagnostic {

package/dist/services/parallelCoordinator.js

@@ -400,16 +400,18 @@ async function captureFrameRange(session, task, captureOptions, signal, onFrameC
             throw new Error("Parallel worker cancelled");
         const time = (i * captureOptions.fps.den) / captureOptions.fps.num;
         const fileFrameIdx = i - outputOffset;
+        let landedFrame;
         if (onFrameBuffer) {
             const { buffer } = await runCaptureOperation("frame_capture", i, () => captureFrameToBuffer(session, fileFrameIdx, time));
             await onFrameBuffer(i, buffer, session);
         }
         else {
-            await runCaptureOperation("frame_capture", i, () => captureFrame(session, fileFrameIdx, time));
+            const { path } = await runCaptureOperation("frame_capture", i, () => captureFrame(session, fileFrameIdx, time));
+            landedFrame = { index: fileFrameIdx, path };
         }
         framesCaptured++;
         if (onFrameCaptured)
-            onFrameCaptured(task.workerId, i);
+            onFrameCaptured(task.workerId, i, landedFrame);
     }
     return framesCaptured;
 }
@@ -722,7 +724,7 @@ export async function executeParallelCapture(serverUrl, workDir, tasks, captureO
     const workerPhases = new Map();
     for (const task of tasks)
         workerProgress.set(task.workerId, 0);
-    const onFrameCaptured = (workerId, _frameIndex) => {
+    const onFrameCaptured = (workerId, _frameIndex, landedFrame) => {
         const current = workerProgress.get(workerId) || 0;
         workerProgress.set(workerId, current + 1);
         if (onProgress) {
@@ -732,6 +734,7 @@ export async function executeParallelCapture(serverUrl, workDir, tasks, captureO
                 capturedFrames,
                 activeWorkers: tasks.length,
                 workerProgress: new Map(workerProgress),
+                ...(landedFrame && { landedFrame }),
             });
         }
     };

package/dist/services/videoFrameExtractor.js

@@ -13,6 +13,7 @@ import { createConcurrencyLimit } from "../utils/concurrencyLimit.js";
 import { parseHTML } from "linkedom";
 import { isPathInside } from "@hyperframes/parsers/asset-paths";
 import { resolveProjectRelativeSrc } from "@hyperframes/parsers/asset-resolution";
+import { alphaDecoderFor } from "@hyperframes/parsers/media-alpha";
 import { MEDIA_RENDER_ID_ATTR, isAudibleVideoElement, fpsToFfmpegArg, fpsToNumber, MEDIA_DURATION_CLAMP_EPSILON_SECONDS, normalizeRateSpec, readElementRateSpec, shiftRateLane, sourceTimeAt, timeAtSourceTime, exportClipWindow, hasClipStarted, isInClipWindow, parseStrictFiniteTimingNumber, readMediaStart, toFps, firstFrameColourArgs, hdrToSdrToneMapFilter, parseFirstFrameColour, } from "@hyperframes/core";
 import { resolveReferencedStart } from "./referenceResolver.js";
 import { isKnownInactiveTimelineWindow } from "./mediaTimelineWindow.js";
@@ -376,7 +377,7 @@ export function parseVideoElements(html) {
             mediaStart: readMediaStart(el),
             playbackRate: readElementRateSpec(el),
             loop: el.hasAttribute("loop"),
-            hasAudio: hasAudioAttr === "true",
+            hasAudio: hasAudioAttr === "true" && isAudibleVideoElement(el),
             ...(isSelfOrAncestorHidden(el) ||
                 (isAudibleVideoElement(el) && isMemberGroupHidden(groupsById, el))
                 ? { hidden: true }
@@ -958,12 +959,7 @@ export function codecMayHaveAlpha(codec) {
     return ALPHA_CAPABLE_CODECS.has((codec ?? "").toLowerCase());
 }
 export function decoderForCodec(codec) {
-    const c = (codec ?? "").toLowerCase();
-    if (c === "vp9")
-        return "libvpx-vp9";
-    if (c === "vp8")
-        return "libvpx";
-    return c;
+    return alphaDecoderFor(codec) ?? (codec ?? "").toLowerCase();
 }
 export function resolveFrameFormat(metadata, requested) {
     if (metadata.hasAlpha || codecMayHaveAlpha(metadata.videoCodec))

package/dist/utils/ffprobe.d.ts

@@ -110,20 +110,6 @@ export declare function probeMediaProfile(filePath: string, options?: {
     signal?: AbortSignal;
 }): Promise<MediaProbeProfile>;
 export declare function extractPngMetadataFromBuffer(buf: Buffer): StillImageMetadata | null;
-/**
- * Does this pix_fmt carry an alpha channel?
- *
- * Exported so the test asserts the shipped predicate rather than a copy of
- * the pattern. Anchored at the start, matching studio-server's
- * mediaMetadata.ts: the previous inline pattern bound its `(^|[^a-z])` anchor
- * to the first alternative only — `|` is looser than concatenation — so the
- * guard was decorative for every other name. It also missed abgr, ya8/ya16
- * and ayuv64, and its `gray[a-z0-9]*a` branch matched only gray8a/gray16a,
- * names FFmpeg renamed to ya8/ya16 in 2013. A `ya8` grayscale-plus-alpha PNG
- * reported hasAlpha:false, resolveFrameFormat picked jpg, and the overlay
- * flattened to an opaque rectangle.
- */
-export declare function pixelFormatHasAlpha(pixelFormat: string): boolean;
 /**
  * Read an ffprobe tag case-insensitively. ffmpeg/libavformat versions disagree
  * on tag casing — VP9 alpha is `alpha_mode` in older builds and `ALPHA_MODE`

package/dist/utils/ffprobe.js

@@ -5,6 +5,7 @@ import { chunkCrc32 } from "./crc32.js";
 import { StringDecoder } from "node:string_decoder";
 import { basename } from "path";
 import { redactTelemetryString } from "@hyperframes/core";
+import { videoStreamHasAlpha } from "@hyperframes/parsers/media-alpha";
 import { urlInputArgs } from "./urlInput.js";
 import { FFPROBE_PATH_ENV, getFfprobeBinary } from "./ffmpegBinaries.js";
 import { ManagedChildProcess } from "./managedChildProcess.js";
@@ -437,22 +438,6 @@ export function extractPngMetadataFromBuffer(buf) {
     }
     return width > 0 && height > 0 ? { width, height, colorSpace: colorSpaceFromCicp } : null;
 }
-/**
- * Does this pix_fmt carry an alpha channel?
- *
- * Exported so the test asserts the shipped predicate rather than a copy of
- * the pattern. Anchored at the start, matching studio-server's
- * mediaMetadata.ts: the previous inline pattern bound its `(^|[^a-z])` anchor
- * to the first alternative only — `|` is looser than concatenation — so the
- * guard was decorative for every other name. It also missed abgr, ya8/ya16
- * and ayuv64, and its `gray[a-z0-9]*a` branch matched only gray8a/gray16a,
- * names FFmpeg renamed to ya8/ya16 in 2013. A `ya8` grayscale-plus-alpha PNG
- * reported hasAlpha:false, resolveFrameFormat picked jpg, and the overlay
- * flattened to an opaque rectangle.
- */
-export function pixelFormatHasAlpha(pixelFormat) {
-    return /^(?:yuva|rgba|argb|bgra|abgr|gbrap|ya|ayuv)/i.test(pixelFormat);
-}
 function extractStillImageMetadata(filePath) {
     try {
         return extractPngMetadataFromBuffer(readFileSync(filePath));
@@ -613,16 +598,7 @@ export async function extractMediaMetadata(filePath) {
         };
         const colorSpace = merged.colorTransfer || merged.colorPrimaries || merged.colorSpace ? merged : null;
         const pixelFormat = videoStream.pix_fmt || "";
-        const alphaMode = readTagCI(videoStream.tags, "alpha_mode");
-        const hasAlpha = pixelFormatHasAlpha(pixelFormat) || alphaMode === "1";
-        // Anchored at the start, matching studio-server's mediaMetadata.ts. The
-        // previous pattern bound its `(^|[^a-z])` anchor to the FIRST alternative
-        // only — `|` is looser than concatenation — so the guard was decorative
-        // for every other name. It also missed abgr, ya8/ya16 and ayuv64, and its
-        // `gray[a-z0-9]*a` branch matched only gray8a/gray16a, names FFmpeg
-        // renamed to ya8/ya16 in 2013. A `ya8` grayscale-plus-alpha PNG reported
-        // hasAlpha:false, resolveFrameFormat picked jpg, and the overlay
-        // flattened to an opaque rectangle.
+        const hasAlpha = videoStreamHasAlpha(videoStream);
         const containerDuration = output?.format.duration ? parseFloat(output.format.duration) : 0;
         const streamDuration = videoStream.duration ? parseFloat(videoStream.duration) : 0;
         const parsedStreamStart = videoStream.start_time ? parseFloat(videoStream.start_time) : 0;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hyperframes/engine",
-  "version": "0.8.183",
+  "version": "0.8.185",
   "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.183",
-    "@hyperframes/core": "^0.8.183"
+    "@hyperframes/core": "^0.8.185",
+    "@hyperframes/parsers": "^0.8.185"
   },
   "devDependencies": {
     "@types/node": "^25.0.10",