@hyperframes/producer 0.8.176 → 0.8.178

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/plan.d.ts

@@ -201,16 +201,20 @@ 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;
 }
+export interface RemoteProjectFile {
+    readonly url: string;
+    readonly sha256: string;
+    readonly sizeBytes: number;
+}
 export declare function logPlanStage(log: ProducerLogger, stage: string, startedAt: number): void;
 /**
  * Result of the legacy v1 {@link plan} wrapper. The `planHash` is the

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.176",
+  "version": "0.8.178",
   "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/core": "0.8.176",
-    "@hyperframes/engine": "0.8.176",
-    "@hyperframes/parsers": "0.8.176",
-    "@hyperframes/lint": "0.8.176",
-    "@hyperframes/studio-server": "0.8.176"
+    "@hyperframes/core": "0.8.178",
+    "@hyperframes/engine": "0.8.178",
+    "@hyperframes/lint": "0.8.178",
+    "@hyperframes/parsers": "0.8.178",
+    "@hyperframes/studio-server": "0.8.178"
   },
   "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.176"
+    "@hyperframes/aws-lambda": "0.8.178"
   },
   "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>;