@hyperframes/producer 0.8.177 → 0.8.179

package/dist/public-server.js

@@ -1407,9 +1407,9 @@ import {
 } from "node:fs";
 import { hostname, uptime } from "node:os";
 import { dirname as dirname3, join as join4 } from "node:path";
+import { RENDER_TEMP_DIR } from "@hyperframes/core/project-folders";
 var OWNER_FILE = "owner.json";
 var TRANSACTION_BACKUP = "backup";
-var RENDER_TEMP_DIR = /^(work-[0-9a-f]{8}(-[0-9a-f]{4}){3}-[0-9a-f]{12}|hf-render|\..+\.hf-transaction)-[A-Za-z0-9]{6}$/;
 function pidScope() {
   const attempt = (read) => {
     try {
@@ -6086,7 +6086,7 @@ function detectShaderTransitionUsage(html) {
   }
   return false;
 }
-async function resolveMediaDuration(src, mediaStart, playbackRate, baseDir, downloadDir, tagName, elementIdentity, log) {
+async function resolveMediaDuration(src, mediaStart, playbackRate, baseDir, downloadDir, tagName, elementIdentity, log, urlByAbsentLocalPath) {
   let filePath = src;
   if (isHttpUrl(src)) {
     if (!existsSync10(downloadDir)) mkdirSync6(downloadDir, { recursive: true });
@@ -6100,8 +6100,9 @@ async function resolveMediaDuration(src, mediaStart, playbackRate, baseDir, down
   } else {
     filePath = decodedUrlPath(src);
     if (!filePath.startsWith("/")) filePath = join13(baseDir, filePath);
+    filePath = urlByAbsentLocalPath?.get(filePath) ?? filePath;
   }
-  if (!existsSync10(filePath)) {
+  if (!isHttpUrl(filePath) && !existsSync10(filePath)) {
     return { duration: null, resolvedPath: filePath };
   }
   const withSrcContext = (error) => {
@@ -6164,7 +6165,7 @@ function markInferredVariableMediaDurations(html, unresolvedMedia) {
   }
   return changed ? document2.toString() : html;
 }
-async function compileHtmlFile(html, baseDir, downloadDir, log) {
+async function compileHtmlFile(html, baseDir, downloadDir, log, urlByAbsentLocalPath) {
   const { html: staticCompiled, unresolved } = compileTimingAttrs(html);
   const mediaUnresolved = unresolved.filter(
     (el) => (el.tagName === "video" || el.tagName === "audio") && el.src
@@ -6180,7 +6181,8 @@ async function compileHtmlFile(html, baseDir, downloadDir, log) {
         downloadDir,
         el.tagName,
         el.id,
-        log
+        log,
+        urlByAbsentLocalPath
       ).then(({ duration }) => ({ id: el.id, duration }))
     )
   );
@@ -6222,7 +6224,7 @@ async function compileHtmlFile(html, baseDir, downloadDir, log) {
   compiledHtml = compiledHtml.replace(/(<audio\b[^>]*)\s+crossorigin(?:=["'][^"']*["'])?/gi, "$1");
   return { html: compiledHtml, unresolvedCompositions };
 }
-async function parseSubCompositions(html, projectDir, downloadDir, visited = /* @__PURE__ */ new Set()) {
+async function parseSubCompositions(html, projectDir, downloadDir, visited = /* @__PURE__ */ new Set(), urlByAbsentLocalPath) {
   const subCompositions = /* @__PURE__ */ new Map();
   const { document: document2 } = parseHTML4(html);
   const compEls = document2.querySelectorAll("[data-composition-src]");
@@ -6248,13 +6250,16 @@ async function parseSubCompositions(html, projectDir, downloadDir, visited = /*
       const { html: compiledSub } = await compileHtmlFile(
         item.rawSubHtml,
         dirname6(item.filePath),
-        downloadDir
+        downloadDir,
+        void 0,
+        urlByAbsentLocalPath
       );
       const nested = await parseSubCompositions(
         compiledSub,
         projectDir,
         downloadDir,
-        item.nestedVisited
+        item.nestedVisited,
+        urlByAbsentLocalPath
       );
       return {
         srcPath: item.srcPath,
@@ -7012,9 +7017,16 @@ async function compileForRender(projectDir, htmlPath, downloadDir, options = {})
     rawHtml,
     projectDir,
     downloadDir,
-    options.log
+    options.log,
+    options.urlByAbsentLocalPath
+  );
+  const { subCompositions } = await parseSubCompositions(
+    compiledHtml,
+    projectDir,
+    downloadDir,
+    void 0,
+    options.urlByAbsentLocalPath
   );
-  const { subCompositions } = await parseSubCompositions(compiledHtml, projectDir, downloadDir);
   const fullHtml = ensureFullDocument(compiledHtml);
   const inlinedHtml = inlineSubCompositions(
     fullHtml,
@@ -7510,6 +7522,7 @@ async function runCompileStage(input) {
     allowSystemFontCapture,
     abortSignal,
     variables: input.variables,
+    urlByAbsentLocalPath: input.urlByAbsentLocalPath,
     animatedGifCacheDir: cfg.extractCacheDir ? join14(cfg.extractCacheDir, "animated-gif") : void 0,
     ffmpegProcessTimeout: cfg.ffmpegProcessTimeout
   });
@@ -8472,7 +8485,8 @@ async function runExtractVideosStage(input) {
     abortSignal,
     assertNotAborted,
     materializeSymlinks,
-    deferRangeExtraction
+    deferRangeExtraction,
+    urlByAbsentLocalPath
   } = input;
   const stage2Start = Date.now();
   const extractionPolicy = resolveVideoExtractionPolicy();
@@ -8566,7 +8580,8 @@ async function runExtractVideosStage(input) {
         maxTransientRetries: extractionPolicy.maxTransientRetries,
         collectProbeFailures: extractionPolicy.failureMode === "enforce",
         deferRangeExtraction,
-        contentKeyedDirs: [join16(compiledDir, REMOTE_MEDIA_SUBDIR)]
+        contentKeyedDirs: [join16(compiledDir, REMOTE_MEDIA_SUBDIR)],
+        urlByAbsentLocalPath
       },
       abortSignal,
       cfg,
@@ -8649,6 +8664,7 @@ async function runAudioStage(input) {
     audioGain,
     audios,
     masterFxChain,
+    urlByAbsentLocalPath,
     abortSignal,
     assertNotAborted,
     log
@@ -8668,7 +8684,7 @@ async function runAudioStage(input) {
         audioOutputPath,
         duration,
         abortSignal,
-        { ffmpegProcessTimeout, audioGain, masterFxChain },
+        { ffmpegProcessTimeout, audioGain, masterFxChain, urlByAbsentLocalPath },
         compiledDir
       );
     } catch (err) {
@@ -13835,6 +13851,17 @@ var DISTRIBUTED_RENDER_CAPABILITIES = Object.freeze({
 // src/services/render/stages/planHash.ts
 var FIELD_DELIMITER = Buffer.from([0]);
 
+// src/services/distributed/chunkAudio.ts
+import { appendRenderProvenanceArgs, describeFfmpegFailure as describeFfmpegFailure2, runFfmpeg as runFfmpeg5 } from "@hyperframes/engine";
+
+// src/services/distributed/mp4Stitch.ts
+var SCAN_BYTES = 64 * 1024;
+
+// src/services/distributed/chunkAudio.ts
+var SLICE_DIR = "audio-chunks";
+var SLICE_FRAME = `${SLICE_DIR}/frame.m4a`;
+var SLICE_LAYOUT = `${SLICE_DIR}/layout.json`;
+
 // src/services/distributed/planSize.ts
 var PLAN_ROOT_CATEGORY = {
   compiled: "compiled",

package/dist/services/distributed/chunkAudio.d.ts

@@ -15,6 +15,17 @@ interface AudioCut {
     packetCount: number;
 }
 export declare function audioCutForChunk(grid: AacPacketGrid, chunks: readonly ChunkSliceJson[], index: number, fps: Fps): AudioCut | null;
+export declare function chunkAudioSlicePath(index: number): string;
+/** Which chunks need a sliced-audio file: `"all"`, one index, or `null` if it is not one. */
+export declare function chunkAudioSliceTarget(path: string): "all" | number | null;
+export declare function writeChunkAudioSlices(input: {
+    audioPath: string;
+    planDir: string;
+    chunks: readonly ChunkSliceJson[];
+    fps: Fps;
+}): Promise<void>;
+/** The plan audio for a chunk: the whole file, or one rebuilt at `scratchPath` from its slice. */
+export declare function chunkAudioSource(planDir: string, chunkIndex: number, scratchPath: string): string | null;
 interface MuxInput {
     videoPath: string;
     audioPath: string | null;

package/dist/services/distributed/chunkFrames.d.ts

@@ -1,5 +1,6 @@
 import { type BeforeCaptureHook, BROWSER_GPU_NOT_SOFTWARE, type CaptureOptions, type EngineConfig, type ExtractedFrames, type FrameLookupTable } from "@hyperframes/engine";
 import type { LockedRenderConfig } from "../render/stages/freezePlan.js";
+import type { PlanV2RemoteSources } from "./planV2.js";
 import { type DistributedFormat, INVALID_VIDEO_METADATA, type PlanVideosJson } from "./shared.js";
 /** Distinct codes so adapters route retries per cause: a missing artifact may heal, a hash mismatch never. */
 export declare const FFMPEG_VERSION_MISMATCH = "FFMPEG_VERSION_MISMATCH";
@@ -33,6 +34,8 @@ export declare function buildChunkCaptureOptions(input: {
     encoder: Pick<LockedRenderConfig, "quality" | "deviceScaleFactor" | "variables">;
     videoCount: number;
     html: string;
+    skipReadinessVideoIds?: string[];
+    videoMetadataHints?: CaptureOptions["videoMetadataHints"];
 }): CaptureOptions;
 /** Extracts the given frames of deferred videos under the names a full extraction gives them. */
 export declare function extractDeferredVideoFramesForChunk(input: {
@@ -45,4 +48,5 @@ export declare function extractDeferredVideoFramesForChunk(input: {
     };
     outputRoot: string;
     cfg: Pick<EngineConfig, "ffmpegProcessTimeout">;
+    remoteSources?: PlanV2RemoteSources;
 }): Promise<ExtractedFrames[]>;

package/dist/services/distributed/mp4Stitch.d.ts

@@ -32,6 +32,7 @@ export interface TrackTable {
 /** Each track's sample tables, expanded to one entry per sample (and per chunk). */
 export declare function readTracks(moov: Buffer): TrackTable[];
 export declare function buildStitchedHeader(layouts: readonly Mp4Layout[]): Buffer;
+export declare function fileRange(path: string): ReadRange;
 /** Local join: the stitched header, then each chunk's mdat payload in order. Like the ffmpeg
  * join, it writes in a work folder beside `outputPath` and renames only a finished file there. */
 export declare function writeStitchedMp4(chunkPaths: readonly string[], outputPath: string): Promise<void>;

package/dist/services/distributed/plan.d.ts

@@ -201,15 +201,21 @@ export interface BuildLocalExecutionPlanOptions {
      * chunks write those frames into their own work directory.
      */
     readonly deferVideoExtraction?: boolean;
+    /** Project files absent locally: probe their URL and publish their existing digest. */
+    readonly remoteFiles?: Readonly<Record<string, RemoteProjectFile>>;
     /** Shared with the publisher so each plan file is hashed once. */
     readonly digests?: PlanFileDigests;
     /** Runs while the audio mixes, once `compiled/` and the video trees are final. */
     readonly whileAudioMixes?: () => Promise<void>;
-    /**
-     * mp4 chunks carry their own slice of the plan audio (renderChunk muxes it). Ignored for other
-     * formats and with `cfr`, which re-encodes.
-     */
+    /** mp4 chunks carry their plan-audio slice unless cfr re-encodes. */
     readonly chunksCarryAudio?: boolean;
+    /** With `chunksCarryAudio`, also write each chunk's audio packets to their own file. Plan v2 only. */
+    readonly sliceChunkAudio?: boolean;
+}
+export interface RemoteProjectFile {
+    readonly url: string;
+    readonly sha256: string;
+    readonly sizeBytes: number;
 }
 export declare function logPlanStage(log: ProducerLogger, stage: string, startedAt: number): void;
 /**

package/dist/services/distributed/planV2.d.ts

@@ -11,7 +11,7 @@
  * is absent, v2 explicitly falls back to the full-source pack.
  */
 import { type DistributedFps } from "@hyperframes/core";
-import { type DistributedRenderConfig } from "./plan.js";
+import { type BuildLocalExecutionPlanOptions, type DistributedRenderConfig } from "./plan.js";
 import { type PlanProtocolV2Descriptor } from "./planProtocol.js";
 import { type PlanV2ArtifactPublisher } from "./planV2Publisher.js";
 import { PLAN_V2_INTEGRITY_UNRECOVERABLE, PlanV2IntegrityError } from "./planV2Errors.js";
@@ -88,6 +88,8 @@ export interface PlanV2WithPublisherOptions {
      * can avoid a second set of data blocks.
      */
     readonly stagingParentDir?: string;
+    /** See {@link BuildLocalExecutionPlanOptions.remoteFiles}; needs a publisher with `referenceStoredBlob`. */
+    readonly remoteFiles?: BuildLocalExecutionPlanOptions["remoteFiles"];
     readonly chunksCarryAudio?: boolean;
 }
 export interface PlanV2MaterializationResult {
@@ -105,6 +107,13 @@ export interface PlanV2MaterializationResult {
     readonly sizeBytes: number;
     readonly audioPath: string | null;
 }
+export type PlanV2RemoteSources = Readonly<Record<string, string>>;
+export interface PlanV2MaterializeOptions {
+    /** Deferred video sources the chunk reads by URL; the caller vouches for their bytes. */
+    readonly remoteSources?: PlanV2RemoteSources;
+}
+/** A chunk-scoped compiled/ file is a deferred video source (see `artifactTargets`). */
+export declare function isPlanV2DeferredSourceArtifact(artifact: Readonly<PlanV2Artifact>): boolean;
 /** Publish a frozen local execution directory into an immutable local v2 transport. */
 export declare function createPlanV2FromExecutionPlan(executionPlanDir: string, planV2Dir: string): PlanV2Result;
 /**
@@ -147,6 +156,10 @@ export declare function listPlanV2ArtifactsForTarget(manifest: Readonly<PlanV2Ma
  * execution directory. The marker lets execution functions revalidate the
  * selected subset without requiring assembler-only audio in chunk workers.
  */
-export declare function materializePlanV2Target(planV2Dir: string, target: PlanV2MaterializationTarget, destinationDir: string): PlanV2MaterializationResult;
+export declare function materializePlanV2Target(planV2Dir: string, target: PlanV2MaterializationTarget, destinationDir: string, options?: Readonly<PlanV2MaterializeOptions>): PlanV2MaterializationResult;
 /** Revalidate a materialized subset immediately before execution. */
 export declare function validatePlanV2MaterializedTarget(planDir: string, expectedTarget: PlanV2MaterializationTarget): Readonly<PlanV2Manifest> | null;
+export declare function readValidatedPlanV2Materialization(planDir: string, expectedTarget: PlanV2MaterializationTarget): {
+    manifest: Readonly<PlanV2Manifest>;
+    remoteSources: PlanV2RemoteSources;
+} | null;

package/dist/services/distributed/planV2Publisher.d.ts

@@ -11,6 +11,7 @@ export interface PlanV2ArtifactPublisher {
      * adapters must finish reading/uploading it before the promise resolves.
      */
     putBlob(blob: Readonly<PlanV2PublishBlob>): Promise<void>;
+    referenceStoredBlob?(blob: Readonly<Omit<PlanV2PublishBlob, "sourcePath">>): Promise<void>;
     /** Commit the manifest only after every referenced blob is durable. */
     commitManifest(manifestBytes: string): Promise<void>;
     /** Idempotent best-effort cleanup for an unpublished or partial plan. */

package/dist/services/distributed/projectHash.d.ts

@@ -2,24 +2,29 @@
  * Content-addressing for a project directory, shared by the distributed-render
  * adapters' `deploySite` verbs.
  *
- * Each adapter uploads a project tarball to `…/sites/<siteId>/project.tar.gz`
- * and short-circuits the upload when the object already exists. `siteId` is a
+ * Each adapter uploads a project under `…/sites/<siteId>/` (AWS: a file list,
+ * Cloud Run: a tarball) and skips content already uploaded. `siteId` is a
  * SHA-256 over the project's files so identical content always maps to the
  * same key — that contract has to be byte-identical across adapters, which is
  * exactly why it lives here rather than being copy-pasted per adapter.
  */
 /**
- * SHA-256 over every regular file under `projectDir` (sorted by relative
- * path) → 16-character hex prefix. The prefix is the `siteId`.
+ * The files a site upload ships, as `/`-separated paths under `projectDir`. Symlinks are followed
+ * (root included), top-level {@link PLAN_PROJECT_DIR_SKIP_SEGMENTS} are left out as the plan stage
+ * does, and a dangling symlink throws.
+ */
+export declare function listSiteFiles(projectDir: string): string[];
+/**
+ * SHA-256 over a scheme tag plus each of {@link listSiteFiles}'s paths and
+ * bytes → 16-character hex prefix. The prefix is the `siteId`.
  *
  * The hash includes the relative path plus every byte of each file, so a
  * same-bytes rename still yields a fresh id. We trim to 16 chars because the
- * full 64 isn't useful in an object key for legibility. Top-level segments in
- * {@link PLAN_PROJECT_DIR_SKIP_SEGMENTS} (e.g. `node_modules`) are skipped to
- * match what the plan stage copies.
+ * full 64 isn't useful in an object key for legibility. Pass `files` when the
+ * caller already listed them, so the hashed set is the shipped set.
  *
  * Reads are synchronous: project trees are typically tens of MB at most
  * (HTML/CSS/JS plus a few composition assets), so the simpler shape wins over
  * a streaming pipeline.
  */
-export declare function hashProjectDir(projectDir: string): string;
+export declare function hashProjectDir(projectDir: string, files?: readonly string[]): string;

package/dist/services/htmlCompiler.d.ts

@@ -157,6 +157,8 @@ export interface CompileForRenderOptions {
      * mismatch warning). Optional so non-render callers can omit it.
      */
     log?: ProducerLogger;
+    /** Absolute project paths not on disk, readable at these URLs instead. */
+    urlByAbsentLocalPath?: ReadonlyMap<string, string>;
     /**
      * Threaded through to {@link injectDeterministicFontFaces}. When `true`,
      * deterministic font resolution and exhausted transient fetch failures

package/dist/services/render/stages/audioStage.d.ts

@@ -33,6 +33,7 @@ export interface AudioStageInput {
     /** Read-only view of `composition.audios`. */
     audios: CompositionMetadata["audios"];
     masterFxChain?: string;
+    urlByAbsentLocalPath?: ReadonlyMap<string, string>;
     abortSignal: AbortSignal | undefined;
     assertNotAborted: () => void;
     /** Where a per-track failure's detail goes. Optional so tests need not pass one. */

package/dist/services/render/stages/compileStage.d.ts

@@ -78,6 +78,8 @@ export interface CompileStageInput {
     allowSystemFontCapture?: boolean;
     /** Render-time variable overrides (`--variables`); see CompileForRenderOptions.variables. */
     variables?: Record<string, unknown>;
+    /** Absolute project paths not on disk, readable at these URLs instead. */
+    urlByAbsentLocalPath?: ReadonlyMap<string, string>;
 }
 export interface CompileStageResult {
     compiled: CompiledComposition;

package/dist/services/render/stages/extractVideosStage.d.ts

@@ -51,6 +51,7 @@ export interface ExtractVideosStageInput {
      */
     materializeSymlinks?: boolean;
     deferRangeExtraction?: boolean;
+    urlByAbsentLocalPath?: ReadonlyMap<string, string>;
 }
 export interface ExtractVideosStageResult {
     /** Result of `extractAllVideoFrames`, or `null` if the composition has no videos. */

package/dist/services/render/stages/freezePlan.d.ts

@@ -121,6 +121,14 @@ export type PlanFileDigests = Map<string, string>;
 export declare function planFileSha256(absolutePath: string, digests?: PlanFileDigests): string;
 /** Hash every file under `dir` into `digests` without blocking the event loop. */
 export declare function prehashPlanFiles(dir: string, digests: PlanFileDigests): Promise<void>;
+/** Plan file left in remote storage: hashed and published by digest, never copied into the plan. */
+export interface PlanRemoteFile {
+    readonly path: string;
+    readonly sha256: string;
+    readonly sizeBytes: number;
+}
+export declare function writePlanRemoteFiles(planDir: string, files: readonly PlanRemoteFile[]): void;
+export declare function readPlanRemoteFiles(planDir: string): PlanRemoteFile[];
 /**
  * Read a frozen plan directory back from disk and recompute its
  * content-addressed `planHash` over the actual on-disk bytes — including

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hyperframes/producer",
-  "version": "0.8.177",
+  "version": "0.8.179",
   "description": "HTML-to-video rendering engine using Chrome's BeginFrame API",
   "repository": {
     "type": "git",
@@ -35,11 +35,11 @@
     "postcss": "^8.4.0",
     "puppeteer": "^25.2.1",
     "puppeteer-core": "^25.2.1",
-    "@hyperframes/engine": "0.8.177",
-    "@hyperframes/lint": "0.8.177",
-    "@hyperframes/parsers": "0.8.177",
-    "@hyperframes/studio-server": "0.8.177",
-    "@hyperframes/core": "0.8.177"
+    "@hyperframes/core": "0.8.179",
+    "@hyperframes/engine": "0.8.179",
+    "@hyperframes/lint": "0.8.179",
+    "@hyperframes/studio-server": "0.8.179",
+    "@hyperframes/parsers": "0.8.179"
   },
   "devDependencies": {
     "@types/node": "^25.0.10",
@@ -48,7 +48,7 @@
     "tsx": "^4.21.0",
     "typescript": "^5.7.2",
     "vitest": "^4.1.11",
-    "@hyperframes/aws-lambda": "0.8.177"
+    "@hyperframes/aws-lambda": "0.8.179"
   },
   "engines": {
     "node": ">=22"

package/dist/services/audioExtractor.d.ts

@@ -1,38 +0,0 @@
-/**
- * Audio Extractor Service
- *
- * Extracts audio from media elements in the composition HTML,
- * applies timeline positioning, and mixes into a single audio track.
- */
-export interface AudioElement {
-    id: string;
-    src: string;
-    start: number;
-    duration: number;
-    mediaStart: number;
-    volume: number;
-    tagName: "audio" | "video";
-}
-export interface AudioTrack {
-    id: string;
-    srcPath: string;
-    start: number;
-    duration: number;
-    mediaStart: number;
-    volume: number;
-}
-/**
- * Parse audio/video elements from HTML to find media with audio.
- */
-export declare function parseAudioElements(html: string): AudioElement[];
-/**
- * Process all audio for a composition.
- *
- * @param htmlPath - Path to the composition HTML (for parsing media elements)
- * @param projectDir - Base directory for resolving relative media paths
- * @param workDir - Temporary working directory for intermediate files
- * @param outputPath - Final mixed audio output path
- * @param totalDuration - Total composition duration in seconds
- * @returns true if audio was produced, false if no audio elements found
- */
-export declare function processAudio(htmlPath: string, projectDir: string, workDir: string, outputPath: string, totalDuration: number): Promise<boolean>;