@hyperframes/producer 0.8.167 → 0.8.168

package/dist/plan-parity-contract.d.ts

@@ -5,9 +5,10 @@
  * different artifact layouts and hash schemas, so their plan hashes are not
  * expected to match even when they render identical output.
  */
+import type { DistributedFps } from "@hyperframes/core";
 export type PlanParityProtocol = "v1" | "v2";
 export interface PlanParityRenderConfig {
-    fps: 24 | 30 | 60;
+    fps: DistributedFps;
     width: number;
     height: number;
     format: "mp4";

package/dist/public-server.js

@@ -10,7 +10,7 @@ import {
   rmSync as rmSync10,
   createReadStream as createReadStream3
 } from "node:fs";
-import { resolve as resolve9, dirname as dirname12, join as join29 } from "node:path";
+import { resolve as resolve9, dirname as dirname12, join as join30 } from "node:path";
 import { tmpdir as tmpdir3 } from "node:os";
 import { parseArgs } from "node:util";
 import crypto from "node:crypto";
@@ -939,7 +939,7 @@ function resolveDeviceScaleFactor(input) {
   });
   if (!compat.ok) throw new Error(compat.message);
   const target = CANVAS_DIMENSIONS[input.outputResolution];
-  return target.width / input.compositionWidth;
+  return Math.max(target.width / input.compositionWidth, target.height / input.compositionHeight);
 }
 function writeCompiledArtifacts(compiled, workDir, includeSummary) {
   const compileDir = join3(workDir, "compiled");
@@ -7593,10 +7593,10 @@ async function runCompileStage(input) {
     hdrRequested: job.config.hdrMode === "force-hdr",
     alphaRequested: needsAlpha
   });
-  const outputWidth = width * deviceScaleFactor;
-  const outputHeight = height * deviceScaleFactor;
-  if (deviceScaleFactor > 1) {
-    log.info("Supersampling composition via deviceScaleFactor", {
+  const outputWidth = Math.round(width * deviceScaleFactor);
+  const outputHeight = Math.round(height * deviceScaleFactor);
+  if (deviceScaleFactor !== 1) {
+    log.info("Scaling composition via deviceScaleFactor", {
       compositionWidth: width,
       compositionHeight: height,
       outputResolution: effectiveResolution,
@@ -10876,6 +10876,22 @@ function assertMotionBlurSupported(motionBlur, route) {
   );
 }
 
+// src/services/render/outputScaleRoute.ts
+var UNSUPPORTED_REASON2 = {
+  sdr_streaming: null,
+  sdr_disk: null,
+  sdr_segmented: null,
+  hdr_layered: "the layered compositor, used for HDR content and for shader transitions in webm and mov, sizes its layers and its encoder from the composition"
+};
+function assertOutputScaleSupported(deviceScaleFactor, route) {
+  if (deviceScaleFactor === 1) return;
+  const reason = UNSUPPORTED_REASON2[route];
+  if (reason === null) return;
+  throw new Error(
+    `[Render] --resolution other than the composition's size is not supported on the "${route}" capture route: ${reason}. Render at the composition's size, or as mp4 with page-side compositing.`
+  );
+}
+
 // src/services/renderOrchestrator.ts
 function sampleDirectoryBytes(dir) {
   let total = 0;
@@ -11663,7 +11679,7 @@ async function closeOrphanedProbeForRetry(probe, closer, log, retryContext) {
   }
 }
 function resolveParallelCaptureMode(args) {
-  const supersampling = (args.deviceScaleFactor ?? 1) > 1;
+  const supersampling = (args.deviceScaleFactor ?? 1) !== 1;
   return args.headlessShell && args.platform === "linux" && !args.forceScreenshot && !supersampling ? "beginframe" : "screenshot";
 }
 function isCaptureParallelStreamRouterEnabled(env, resolvedMode) {
@@ -12311,7 +12327,7 @@ async function executeRenderPipeline(input) {
       minFrames: deSingleMinFrames,
       singleWorkerStreamingOk: shouldUseStreamingEncode(cfg, outputFormat, 1, job.duration),
       layeredOrEffectRoute: hasHdrContent || compiled.hasShaderTransitions,
-      supersampling: deviceScaleFactor > 1,
+      supersampling: deviceScaleFactor !== 1,
       probeDeGated: probeSession !== null && probeSession.captureMode !== "drawelement" && !probeSession.deInitDeferred,
       experimentalParallelDeOptIn: process.env.PRODUCER_EXPERIMENTAL_FAST_CAPTURE === "true" || // Verified parallel DE streaming (opt-in) wants its parallelism kept.
       process.env.HF_DE_PARALLEL_STREAM === "true"
@@ -12347,7 +12363,7 @@ async function executeRenderPipeline(input) {
       totalFrames,
       minFrames: deParallelMinFrames,
       layeredOrEffectRoute: hasHdrContent || compiled.hasShaderTransitions,
-      supersampling: deviceScaleFactor > 1,
+      supersampling: deviceScaleFactor !== 1,
       probeDeGated: probeSession !== null && probeSession.captureMode !== "drawelement" && !probeSession.deInitDeferred,
       experimentalParallelDeOptIn: process.env.PRODUCER_EXPERIMENTAL_FAST_CAPTURE === "true" || process.env.HF_DE_PARALLEL_STREAM === "true",
       routerEnabled: deParallelRouterEnabled,
@@ -12731,6 +12747,7 @@ async function executeRenderPipeline(input) {
     });
     const syncCapturePlan = () => {
       assertMotionBlurSupported(job.config.motionBlur, capturePlan.kind);
+      assertOutputScaleSupported(deviceScaleFactor, capturePlan.kind);
       workerCount = capturePlan.workerCount;
       captureForceScreenshot = capturePlan.forceScreenshot;
       useStreamingEncode = capturePlan.kind === "sdr_streaming";
@@ -12904,8 +12921,8 @@ async function executeRenderPipeline(input) {
             outputFormat,
             streamingEncoderOptions: {
               fps: job.config.fps,
-              width,
-              height,
+              width: captureCompositionWidth ?? width,
+              height: captureCompositionHeight ?? height,
               codec: preset.codec,
               preset: preset.preset,
               quality: effectiveQuality,
@@ -12996,8 +13013,8 @@ async function executeRenderPipeline(input) {
               outputFormat,
               streamingEncoderOptions: {
                 fps: job.config.fps,
-                width,
-                height,
+                width: captureCompositionWidth ?? width,
+                height: captureCompositionHeight ?? height,
                 codec: preset.codec,
                 preset: preset.preset,
                 quality: effectiveQuality,
@@ -13727,10 +13744,13 @@ import { parseEncoderOptions } from "@hyperframes/studio-server/encoder-options"
 // src/renderRequest.ts
 import {
   isVideoFrameFormat as isVideoFrameFormat2,
-  resolveConfig as resolveConfig3,
+  resolveConfig as resolveConfig4,
   validateEngineConfigSnapshot as validateEngineConfigSnapshot2
 } from "@hyperframes/engine";
-import { VALID_CANVAS_RESOLUTIONS } from "@hyperframes/core";
+import {
+  VALID_CANVAS_RESOLUTIONS,
+  isDistributedFps as isDistributedFps2
+} from "@hyperframes/core";
 
 // src/services/distributed/renderConfigValidation.ts
 import {
@@ -13738,6 +13758,82 @@ import {
   isVideoFrameFormat,
   validateEngineConfigSnapshot
 } from "@hyperframes/engine";
+import { DISTRIBUTED_FPS, isDistributedFps } from "@hyperframes/core";
+
+// src/services/distributed/plan.ts
+import { audioFailureDiagnostics as audioFailureDiagnostics3 } from "@hyperframes/engine";
+import { extname as extname4, isAbsolute as isAbsolute4, join as join29, relative as relative4, sep as sep3 } from "node:path";
+import { fpsToNumber as fpsToNumber10 } from "@hyperframes/core";
+import {
+  getEncoderPreset as getEncoderPreset4,
+  normalizeVp9CpuUsed,
+  resolveConfig as resolveConfig3
+} from "@hyperframes/engine";
+
+// src/services/distributed/planProtocol.ts
+var PLAN_SCHEMA_VERSION = 1;
+var PLAN_ARTIFACT_LAYOUT = "plan-dir-v1";
+var PLAN_HASH_SCHEMA = "hyperframes-plan-hash-v1";
+var PLAN_V2_SCHEMA_VERSION = 2;
+var PLAN_V2_ARTIFACT_LAYOUT = "content-addressed-plan-v2";
+var PLAN_V2_HASH_SCHEMA = "hyperframes-plan-manifest-hash-v2";
+var PLAN_PROTOCOL_V1 = Object.freeze({
+  schemaVersion: PLAN_SCHEMA_VERSION,
+  artifactLayout: PLAN_ARTIFACT_LAYOUT,
+  hashSchema: PLAN_HASH_SCHEMA
+});
+var PLAN_PROTOCOL_V2 = Object.freeze({
+  schemaVersion: PLAN_V2_SCHEMA_VERSION,
+  artifactLayout: PLAN_V2_ARTIFACT_LAYOUT,
+  hashSchema: PLAN_V2_HASH_SCHEMA
+});
+var DISTRIBUTED_RENDER_CAPABILITIES = Object.freeze({
+  roles: Object.freeze({
+    planner: Object.freeze({
+      produces: Object.freeze([PLAN_PROTOCOL_V1, PLAN_PROTOCOL_V2])
+    }),
+    chunk: Object.freeze({
+      accepts: Object.freeze([PLAN_PROTOCOL_V1, PLAN_PROTOCOL_V2]),
+      acceptsLegacyV1WithoutDescriptor: true
+    }),
+    assembler: Object.freeze({
+      accepts: Object.freeze([PLAN_PROTOCOL_V1, PLAN_PROTOCOL_V2]),
+      acceptsLegacyV1WithoutDescriptor: true
+    })
+  })
+});
+
+// src/services/render/stages/planHash.ts
+var FIELD_DELIMITER = Buffer.from([0]);
+
+// src/services/distributed/shared.ts
+import { execFile as execFileCallback } from "node:child_process";
+import { promisify as promisify2 } from "node:util";
+import {
+  getFfmpegBinary,
+  MIXED_AUDIO_FILENAME as MIXED_AUDIO_FILENAME3
+} from "@hyperframes/engine";
+var PLAN_AUDIO_RELATIVE_PATH = MIXED_AUDIO_FILENAME3;
+var execFile = promisify2(execFileCallback);
+
+// src/services/distributed/planSize.ts
+var PLAN_ROOT_CATEGORY = {
+  compiled: "compiled",
+  [PLAN_AUDIO_RELATIVE_PATH]: "audio",
+  meta: "metadata",
+  "plan.json": "metadata"
+};
+
+// src/services/distributed/plan.ts
+var PLAN_DIR_SIZE_LIMIT_BYTES = 2 * 1024 * 1024 * 1024;
+var FREEZE_OWNED_PLAN_FILES = [
+  "plan.json",
+  join29("meta", "composition.json"),
+  join29("meta", "encoder.json"),
+  join29("meta", "chunks.json")
+];
+
+// src/services/distributed/renderConfigValidation.ts
 var InvalidConfigError = class extends Error {
   // Read via Error.prototype.toString; fallow can't see it.
   // fallow-ignore-next-line unused-class-member
@@ -13944,7 +14040,7 @@ function createRenderRequest(input) {
     outputPath: input.outputPath,
     options: {
       ...omitUndefinedProperties(input.options),
-      engineConfig: input.engineConfig ?? resolveConfig3(input.engineOverrides)
+      engineConfig: input.engineConfig ?? resolveConfig4(input.engineOverrides)
     }
   };
   return parseRenderRequest(serializeRenderRequest(request));
@@ -14161,8 +14257,8 @@ async function resolveInlineRenderHtml(body) {
 }
 function materializeInlineProject(html, options) {
   const tempRoot = process.env.PRODUCER_TMP_PROJECT_DIR || tmpdir3();
-  const tempProjectDir = mkdtempSync4(join29(tempRoot, "producer-project-"));
-  writeFileSync6(join29(tempProjectDir, "index.html"), html, "utf-8");
+  const tempProjectDir = mkdtempSync4(join30(tempRoot, "producer-project-"));
+  writeFileSync6(join30(tempProjectDir, "index.html"), html, "utf-8");
   return {
     prepared: {
       input: { projectDir: tempProjectDir, ...options },

package/dist/regression-harness-distributed.d.ts

@@ -25,12 +25,12 @@
  * capture jitter, so the harness can't use it as a per-test gate.
  *
  * Not every fixture can run in distributed-simulated mode. Distributed mode
- * refuses HDR mp4, NTSC framerates, and non-{24,30,60} fps at plan time.
+ * refuses HDR mp4, NTSC framerates, and fps outside DISTRIBUTED_FPS at plan time.
  * Fixtures that don't meet the constraints are skipped — the harness logs
  * the reason and the fixture is treated as "passed (skipped)" in
  * distributed-simulated mode.
  */
-import type { Fps } from "@hyperframes/core";
+import { type DistributedFps, type Fps } from "@hyperframes/core";
 import { type DistributedFormat } from "./services/distributed/shared.js";
 /**
  * Three-mode contract that backs `--mode=<value>` on the regression
@@ -67,8 +67,8 @@ export type DistributedSupportResult = {
  * Decide whether a fixture's `renderConfig` is one the distributed pipeline
  * can actually run. Two hard gates:
  *
- *   - fps must be `{ num: 24|30|60, den: 1 }`. `DistributedRenderConfig.fps`
- *     accepts only the three integer values, and rationals like
+ *   - fps must be `{ num: <DISTRIBUTED_FPS member>, den: 1 }`. `DistributedRenderConfig.fps`
+ *     accepts only those integer values, and rationals like
  *     `{ num: 30000, den: 1001 }` (NTSC) trip the type system at the call
  *     site. We surface this gate in code rather than only in TS so the
  *     harness can skip the fixture cleanly instead of throwing.
@@ -95,7 +95,7 @@ export interface RunDistributedSimulatedInput {
     /** Where to write the assembled final mp4 / mov / png-sequence directory. */
     renderedOutputPath: string;
     /** From the fixture's renderConfig — must pass `checkDistributedSupport`. */
-    fps: 24 | 30 | 60;
+    fps: DistributedFps;
     format: DistributedFormat;
     /**
      * Codec for `format: "mp4"`. Defaults to `"h264"`; pass `"h265"` to

package/dist/regression-harness-lambda-local-types.d.ts

@@ -8,6 +8,7 @@
  * adapter's shape without pulling the aws-lambda graph into producer's
  * type-check pass.
  */
+import type { DistributedFps } from "@hyperframes/core";
 import type { DistributedFormat } from "./services/distributed/shared.js";
 /** Inputs for {@link runLambdaLocalRender}. Same contract as `runDistributedSimulatedRender`. */
 export interface RunLambdaLocalInput {
@@ -16,7 +17,7 @@ export interface RunLambdaLocalInput {
     projectDir: string;
     tempRoot: string;
     renderedOutputPath: string;
-    fps: 24 | 30 | 60;
+    fps: DistributedFps;
     /**
      * Width/height from the fixture's renderConfig. Forwarded directly to
      * the Lambda event so this mode catches drift if the handler ever

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

@@ -10,14 +10,10 @@
  * decodable). For png-sequence chunks (each chunk is a directory of
  * frames) this is a straight directory merge with global re-numbering.
  *
- * Mux + faststart for mp4 / mov / webm go through the engine's
- * `muxVideoWithAudio` + `applyFaststart` helpers — same path the
- * in-process renderer uses; we just feed concat output rather than
- * streaming-encoder output. (Faststart is a no-op for webm and mov —
- * applyFaststart copies the input verbatim.) Audio length is
- * pad-or-trimmed to `frameCount / fps` via
- * `padOrTrimAudioToVideoFrameCount` so the mux step doesn't introduce
- * sub-millisecond drift at the end of long renders.
+ * Join, audio mux and mp4 faststart run as one ffmpeg pass over the concat
+ * demuxer, so disk holds the chunks plus one output copy. Audio is first
+ * pad-or-trimmed to `frameCount / fps` (frames summed over the chunks) so
+ * the mux adds no drift at the end of long renders.
  *
  * Pure function over local paths. No networking. The caller is responsible
  * for moving `outputPath` to its orchestration-level storage.

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

@@ -1,8 +1,8 @@
-import { type CanvasResolution } from "@hyperframes/core";
+import { type CanvasResolution, type DistributedFps } from "@hyperframes/core";
 import { type EngineConfig, type VideoFrameFormat, type AudioProcessingFailure } from "@hyperframes/engine";
 import { type ProducerLogger } from "../../logger.js";
 import { type RenderJob, type RenderStrictness } from "../renderOrchestrator.js";
-import { type ChunkSliceJson } from "../render/stages/freezePlan.js";
+import { type ChunkSliceJson, type PlanFileDigests } from "../render/stages/freezePlan.js";
 import { type DistributedFormat } from "./shared.js";
 import { type PlanProtocolV1Descriptor } from "./planProtocol.js";
 import { type PlanSizeBreakdown } from "./planSize.js";
@@ -13,7 +13,7 @@ import { type PlanSizeBreakdown } from "./planSize.js";
  */
 export interface DistributedRenderConfig {
     /** Integer frame rate. Distributed renders only accept integer fps; the in-process renderer's `Fps` rational handles NTSC. */
-    fps: 24 | 30 | 60;
+    fps: DistributedFps;
     width: number;
     height: number;
     /**
@@ -79,8 +79,15 @@ export interface DistributedRenderConfig {
      * old 8-second-GOP behavior.
      */
     chunkSize?: number;
-    /** Default `16`. Caps long renders to fewer-but-longer chunks for operational fairness. */
+    /**
+     * Caps the chunk count. When omitted, chunks are sized from `workerConcurrency` and
+     * `workerTimeoutSeconds` (see {@link resolveMaxParallelChunks}); without those, `16`.
+     */
     maxParallelChunks?: number;
+    /** Seconds a chunk worker may run before the platform kills it (Lambda: the function timeout). */
+    workerTimeoutSeconds?: number;
+    /** How many chunk workers can run at once (Lambda: reserved concurrency). */
+    workerConcurrency?: number;
     /**
      * Upper bound on frames-per-chunk, in frames. Optional; when omitted (the
      * default) chunk sizing is unchanged. When set, chunking targets the fewest
@@ -174,7 +181,7 @@ export interface LocalExecutionPlan {
     executionPlanHash: string;
     chunkCount: number;
     totalFrames: number;
-    fps: 24 | 30 | 60;
+    fps: DistributedFps;
     width: number;
     height: number;
     format: DistributedFormat;
@@ -194,7 +201,12 @@ export interface BuildLocalExecutionPlanOptions {
      * chunks write those frames into their own work directory.
      */
     readonly deferVideoExtraction?: boolean;
+    /** 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>;
 }
+export declare function logPlanStage(log: ProducerLogger, stage: string, startedAt: number): void;
 /**
  * Result of the legacy v1 {@link plan} wrapper. The `planHash` is the
  * content-addressed identifier that adapters key replay short-circuits off of.
@@ -208,7 +220,7 @@ export interface PlanResult {
     planHash: string;
     chunkCount: number;
     totalFrames: number;
-    fps: 24 | 30 | 60;
+    fps: DistributedFps;
     width: number;
     height: number;
     format: DistributedFormat;
@@ -228,9 +240,8 @@ export declare function applyDistributedAudioWarningPolicy(job: RenderJob, audio
  */
 export declare const PLAN_PROJECT_DIR_SKIP_SEGMENTS: ReadonlySet<string>;
 /**
- * Default chunk size in frames (~8s @ 30fps; fits Lambda's 15-min cap).
- * Used when the caller explicitly passes this value. When `chunkSize` is
- * `undefined`, `plan()` auto-sizes from `maxParallelChunks` instead.
+ * Chunk size in frames (~8s @ 30fps) for callers that want a fixed GOP.
+ * `plan()` never applies it on its own; an undefined `chunkSize` auto-sizes.
  */
 export declare const DEFAULT_CHUNK_SIZE = 240;
 /** Default cap on parallel chunks for operational fairness across renders. */
@@ -242,6 +253,23 @@ export declare const DEFAULT_MAX_PARALLEL_CHUNKS = 16;
  * outweighs the parallelism gain on tiny renders.
  */
 export declare const MIN_CHUNK_SIZE = 10;
+/** Most chunks one render may plan; `validateDistributedRenderConfig` enforces it on `maxParallelChunks`. */
+export declare const MAX_PARALLEL_CHUNKS_CEILING = 256;
+/** Predicted seconds for one chunk of `frames` frames at `megapixels` output pixels per frame. */
+export declare function estimateChunkSeconds(frames: number, megapixels: number): number;
+/** Non-retryable: even {@link MAX_PARALLEL_CHUNKS_CEILING} chunks cannot fit the worker time limit. */
+export declare const CHUNK_EXCEEDS_WORKER_TIMEOUT = "CHUNK_EXCEEDS_WORKER_TIMEOUT";
+export declare class ChunkExceedsWorkerTimeoutError extends Error {
+    readonly code: typeof CHUNK_EXCEEDS_WORKER_TIMEOUT;
+    constructor(predictedChunkSeconds: number, workerTimeoutSeconds: number);
+}
+/**
+ * The `maxParallelChunks` a plan uses: explicit chunking flags win; otherwise one wave across
+ * `workerConcurrency`, widened so each chunk fits `workerTimeoutSeconds`; with neither, 16.
+ */
+export declare function resolveMaxParallelChunks(config: Pick<DistributedRenderConfig, "maxParallelChunks" | "chunkSize" | "targetChunkFrames" | "workerTimeoutSeconds" | "workerConcurrency">, totalFrames: number, 
+/** Output pixels per frame, after supersampling. */
+megapixels: number, log?: ProducerLogger): number;
 /**
  * Default hard ceiling on `<planDir>/` size in bytes. 2 GB fits inside
  * AWS Lambda's 10 GB `/tmp` alongside the chunk worker's captured frames

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

@@ -10,6 +10,7 @@
  * FrameLookupTable at every captured global frame. If legacy video metadata
  * 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 PlanProtocolV2Descriptor } from "./planProtocol.js";
 import { type PlanV2ArtifactPublisher } from "./planV2Publisher.js";
@@ -45,7 +46,7 @@ export interface PlanV2Manifest {
     readonly sourcePlanV1Hash: string;
     readonly chunkCount: number;
     readonly totalFrames: number;
-    readonly fps: 24 | 30 | 60;
+    readonly fps: DistributedFps;
     readonly width: number;
     readonly height: number;
     readonly format: DistributedFormat;
@@ -71,7 +72,7 @@ export interface PlanV2Result {
     readonly sourcePlanV1Hash: string;
     readonly chunkCount: number;
     readonly totalFrames: number;
-    readonly fps: 24 | 30 | 60;
+    readonly fps: DistributedFps;
     readonly width: number;
     readonly height: number;
     readonly format: DistributedFormat;

package/dist/services/render/audioPadTrim.d.ts

@@ -48,8 +48,8 @@ export interface PadTrimAudioInput {
     /** Deadline for each ffmpeg process; defaults to the engine's `ffmpegProcessTimeout`. */
     timeoutMs?: number;
     /**
-     * Optional injectables for unit tests. Production callers omit them and
-     * get the real `ffprobe`/`ffmpeg`-backed implementations.
+     * Optional injectables. Tests stub them; the distributed assembler supplies
+     * the frame probe because its video is still separate chunks.
      */
     probeVideoFrameInfo?: (videoPath: string) => Promise<ProbeVideoFrameInfo>;
     probeAudioInfo?: (audioPath: string, signal?: AbortSignal) => Promise<AudioProbeInfo>;
@@ -111,3 +111,4 @@ export declare function buildPadTrimAudioArgs(audioPath: string, outputPath: str
  * for the assembled video.
  */
 export declare function padOrTrimAudioToVideoFrameCount(input: PadTrimAudioInput): Promise<PadTrimAudioResult>;
+export declare function defaultProbeVideoFrameInfo(videoPath: string, signal?: AbortSignal): Promise<ProbeVideoFrameInfo>;

package/dist/services/render/outputScaleRoute.d.ts

@@ -0,0 +1,8 @@
+/**
+ * One owner for "does this capture route honour an output resolution other than the composition's".
+ * The scale is Chrome's deviceScaleFactor; a route that sizes its own buffers and encoder from the
+ * composition would encode at native size while the render reports the requested one.
+ */
+import type { CapturePlan } from "./capturePlan.js";
+/** Throw a named error when an output resolution other than the composition's meets a route that ignores it. */
+export declare function assertOutputScaleSupported(deviceScaleFactor: number, route: CapturePlan["kind"]): void;

package/dist/services/render/shared.d.ts

@@ -55,18 +55,16 @@ export declare function projectBrowserEndToCompositionTimeline(existingStart: nu
  * `deviceScaleFactor`. The composition's intrinsic dimensions stay the
  * page-layout viewport; the screenshot lands at output dims via DPR.
  *
- * The scale must be a positive integer ≥ 1 — fractional DPRs introduce
+ * Upsampling must be by a whole number — fractional DPRs above 1 introduce
  * visible aliasing and we'd rather fail loudly than produce a blurry
- * 4K render. Downsampling (output < composition) is rejected because
- * the user is unlikely to have intended it; if the use case appears
- * we can plumb a separate flag.
+ * 4K render. A smaller preset (720p, 480p) takes a DPR under 1, so Chrome
+ * rasterizes straight at the smaller size.
  *
  * Throws on:
  *   - HDR + outputResolution (HDR compositor processes raw pixel buffers
  *     at composition dimensions and would need parallel scaling).
  *   - Aspect-ratio mismatch (e.g. landscape composition → portrait-4k).
- *   - Non-integer scale ratio.
- *   - Downsampling (output dimensions smaller than composition).
+ *   - Non-integer upsampling ratio.
  */
 export declare function resolveDeviceScaleFactor(input: {
     compositionWidth: number;

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

@@ -107,6 +107,7 @@ export interface FreezePlanInput {
     totalFrames: number;
     /** Whether the plan's mixed-audio artifact was produced. */
     hasAudio: boolean;
+    digests?: PlanFileDigests;
 }
 export interface FreezePlanResult {
     /** Absolute path to `plan.json`. */
@@ -114,6 +115,11 @@ export interface FreezePlanResult {
     /** Content-addressed planHash; see {@link computePlanHash}. */
     planHash: string;
 }
+/** sha256 by absolute path. A staged plan file never changes, so one plan hashes it once. */
+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>;
 /**
  * Read a frozen plan directory back from disk and recompute its
  * content-addressed `planHash` over the actual on-disk bytes — including
@@ -130,7 +136,7 @@ export interface FreezePlanResult {
  * callers should catch those as `MISSING_PLAN_ARTIFACT` rather than
  * lumping them with hash drift.
  */
-export declare function recomputePlanHashFromPlanDir(planDir: string): string;
+export declare function recomputePlanHashFromPlanDir(planDir: string, digests?: PlanFileDigests): string;
 /**
  * Freeze a plan directory: write `meta/*.json` + top-level `plan.json`, then
  * compute `planHash` over the canonicalized contents.

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

@@ -94,3 +94,6 @@ export declare function canonicalJsonStringify(value: unknown): string;
  * by the eventual `freezePlan` to hash assets on disk.
  */
 export declare function sha256Hex(bytes: Uint8Array | string): string;
+/** Hash large plan artifacts with bounded memory (important above the legacy 2 GiB cap). */
+export declare function sha256File(path: string): string;
+export declare function sha256FileAsync(path: string): Promise<string>;

package/dist/services/renderOrchestrator.d.ts

@@ -846,7 +846,7 @@ export declare function shouldPreferSingleWorkerDrawElement(args: {
      * telemetry and keep the probe session alive through the heaviest stage.
      */
     layeredOrEffectRoute: boolean;
-    /** deviceScaleFactor > 1 — the engine's supersampling gate blocks DE. */
+    /** deviceScaleFactor other than 1 — the engine's supersampling gate blocks DE. */
     supersampling: boolean;
     /**
      * The probe session already ran the engine's init-time DE gates and DE did

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hyperframes/producer",
-  "version": "0.8.167",
+  "version": "0.8.168",
   "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.167",
-    "@hyperframes/lint": "0.8.167",
-    "@hyperframes/parsers": "0.8.167",
-    "@hyperframes/core": "0.8.167",
-    "@hyperframes/studio-server": "0.8.167"
+    "@hyperframes/core": "0.8.168",
+    "@hyperframes/parsers": "0.8.168",
+    "@hyperframes/lint": "0.8.168",
+    "@hyperframes/studio-server": "0.8.168",
+    "@hyperframes/engine": "0.8.168"
   },
   "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.167"
+    "@hyperframes/aws-lambda": "0.8.168"
   },
   "engines": {
     "node": ">=22"