@hyperframes/producer 0.9.20 → 0.9.21

package/dist/index.js

@@ -410,6 +410,68 @@ ${seededRandomBlock}
     }
   };
 
+  // Timers set once rendering has started run on film time: each seek fires every timer due by then, in
+  // due order. Until a seek after the page reports ready, timers keep the wall clock: setup code waits on
+  // them while the renderer may already be seeking.
+  var rendering = false;
+  var timerQueue = [];
+  var nextTimerId = 1000000000;
+  var firingDepth = 0;
+  function addTimer(callback, delay, args, repeats) {
+    // A timer set from a firing timer waits at least 1 ms, so a zero-delay chain cannot stall a seek.
+    var ms = Math.max(firingDepth > 0 ? 1 : 0, Number(delay) || 0);
+    var entry = { id: nextTimerId++, callback: callback, args: args, due: virtualNowMs + ms, every: repeats ? Math.max(1, ms) : 0, cancelled: false };
+    timerQueue.push(entry);
+    return entry.id;
+  }
+  function cancelTimer(id) {
+    for (var i = 0; i < timerQueue.length; i++) {
+      if (timerQueue[i].id === id) {
+        timerQueue[i].cancelled = true;
+        return true;
+      }
+    }
+    return false;
+  }
+  function fireDueTimers(untilMs) {
+    // Frame times are fractional, so a timer due on a frame lands a rounding error past it; it still fires on it.
+    untilMs += 0.000001;
+    while (true) {
+      var next = null;
+      for (var i = 0; i < timerQueue.length; i++) {
+        var candidate = timerQueue[i];
+        if (!candidate.cancelled && candidate.due <= untilMs && (next === null || candidate.due < next.due)) next = candidate;
+      }
+      if (next === null) break;
+      var dueMs = next.due;
+      if (next.every) next.due += next.every;
+      else next.cancelled = true;
+      virtualNowMs = dueMs;
+      firingDepth++;
+      try {
+        next.callback.apply(window, next.args);
+      } catch (err) {
+        originalSetTimeout(function() { throw err; }, 0);
+      }
+      firingDepth--;
+    }
+    timerQueue = timerQueue.filter(function(entry) { return !entry.cancelled; });
+  }
+  window.setTimeout = function(callback, delay) {
+    if (!rendering || typeof callback !== "function") return originalSetTimeout.apply(null, arguments);
+    return addTimer(callback, delay, Array.prototype.slice.call(arguments, 2), false);
+  };
+  window.setInterval = function(callback, delay) {
+    if (!rendering || typeof callback !== "function") return originalSetInterval.apply(null, arguments);
+    return addTimer(callback, delay, Array.prototype.slice.call(arguments, 2), true);
+  };
+  window.clearTimeout = function(id) {
+    if (!cancelTimer(id)) originalClearTimeout(id);
+  };
+  window.clearInterval = function(id) {
+    if (!cancelTimer(id)) originalClearInterval(id);
+  };
+
   window.__HF_VIRTUAL_TIME__ = {
     originalSetTimeout: originalSetTimeout,
     originalClearTimeout: originalClearTimeout,
@@ -419,8 +481,10 @@ ${seededRandomBlock}
     originalCancelAnimationFrame: originalCancelAnimationFrame,
     seekToTime: function(nextTimeMs) {
       var safeTimeMs = Math.max(0, Number(nextTimeMs) || 0);
+      if (window.__renderReady === true) rendering = true;
+      ${seekToTimeReseedCall}fireDueTimers(safeTimeMs);
       virtualNowMs = safeTimeMs;
-      ${seekToTimeReseedCall}flushAnimationFrame();
+      flushAnimationFrame();
       return virtualNowMs;
     },
     getTime: function() {
@@ -18006,7 +18070,7 @@ function assertPlanSizeWithinLimit(input) {
   });
   throw new PlanTooLargeError(breakdown.totalBytes, input.limitBytes, breakdown, input.observedAt);
 }
-function resolveChunkPlan(totalFrames, configChunkSize, maxParallelChunks, targetChunkFrames) {
+function resolveChunkPlan(totalFrames, configChunkSize, maxParallelChunks, targetChunkFrames, minParallelChunks = 1) {
   assertPositiveInteger2("totalFrames", totalFrames);
   assertPositiveInteger2("maxParallelChunks", maxParallelChunks);
   if (configChunkSize !== void 0) {
@@ -18015,7 +18079,11 @@ function resolveChunkPlan(totalFrames, configChunkSize, maxParallelChunks, targe
   if (targetChunkFrames !== void 0) {
     assertPositiveInteger2("targetChunkFrames", targetChunkFrames);
   }
-  const autoSizeParallel = targetChunkFrames === void 0 ? maxParallelChunks : Math.min(maxParallelChunks, Math.max(1, Math.ceil(totalFrames / targetChunkFrames)));
+  assertPositiveInteger2("minParallelChunks", minParallelChunks);
+  const autoSizeParallel = targetChunkFrames === void 0 ? maxParallelChunks : Math.min(
+    maxParallelChunks,
+    Math.max(minParallelChunks, Math.ceil(totalFrames / targetChunkFrames))
+  );
   const resolvedChunkSize = configChunkSize ?? Math.max(MIN_CHUNK_SIZE, Math.ceil(totalFrames / autoSizeParallel));
   const naiveCount = Math.ceil(totalFrames / resolvedChunkSize);
   const chunkCount = Math.min(maxParallelChunks, Math.max(1, naiveCount));
@@ -18594,7 +18662,8 @@ async function buildLocalExecutionPlan(projectDir, config, executionPlanDir, opt
     totalFrames,
     config.chunkSize,
     maxParallel,
-    config.targetChunkFrames
+    config.targetChunkFrames,
+    config.minParallelChunks
   );
   const chunks = buildPlanChunkSlices(
     frameWeights,
@@ -20598,6 +20667,20 @@ function validateDistributedRenderConfig(config) {
       );
     }
   }
+  if (config.minParallelChunks !== void 0) {
+    if (!Number.isInteger(config.minParallelChunks) || config.minParallelChunks < 1) {
+      throw new InvalidConfigError(
+        "config.minParallelChunks",
+        `must be a positive integer; got ${config.minParallelChunks}`
+      );
+    }
+    if (config.minParallelChunks > MAX_PARALLEL_CHUNKS_CEILING) {
+      throw new InvalidConfigError(
+        "config.minParallelChunks",
+        `must be <= ${MAX_PARALLEL_CHUNKS_CEILING}; got ${config.minParallelChunks}`
+      );
+    }
+  }
   for (const field of ["workerTimeoutSeconds", "workerConcurrency"]) {
     const value = config[field];
     if (value !== void 0 && (!Number.isInteger(value) || value < 1)) {
@@ -20767,6 +20850,7 @@ function assertDistributedOptions(value) {
     "chunkSize",
     "maxParallelChunks",
     "targetChunkFrames",
+    "minParallelChunks",
     "planDirSizeLimitBytes"
   ]) {
     assertOptionalInteger(value, field, 1);
@@ -20906,6 +20990,7 @@ function distributedConfigFromRequest(request, runtime = {}) {
     chunkSize: distributed.chunkSize,
     maxParallelChunks: distributed.maxParallelChunks,
     targetChunkFrames: distributed.targetChunkFrames,
+    minParallelChunks: distributed.minParallelChunks,
     runtimeCap: distributed.runtimeCap,
     rejectOnSystemFonts: distributed.rejectOnSystemFonts,
     failClosedFontFetch: distributed.failClosedFontFetch,
@@ -20933,6 +21018,7 @@ function renderRequestFromDistributedConfig(input) {
     ...optionalProperty("chunkSize", config.chunkSize),
     ...optionalProperty("maxParallelChunks", config.maxParallelChunks),
     ...optionalProperty("targetChunkFrames", config.targetChunkFrames),
+    ...optionalProperty("minParallelChunks", config.minParallelChunks),
     ...optionalProperty("runtimeCap", config.runtimeCap),
     ...optionalProperty("rejectOnSystemFonts", config.rejectOnSystemFonts),
     ...optionalProperty("failClosedFontFetch", config.failClosedFontFetch),

package/dist/public-server.js

@@ -427,6 +427,68 @@ ${seededRandomBlock}
     }
   };
 
+  // Timers set once rendering has started run on film time: each seek fires every timer due by then, in
+  // due order. Until a seek after the page reports ready, timers keep the wall clock: setup code waits on
+  // them while the renderer may already be seeking.
+  var rendering = false;
+  var timerQueue = [];
+  var nextTimerId = 1000000000;
+  var firingDepth = 0;
+  function addTimer(callback, delay, args, repeats) {
+    // A timer set from a firing timer waits at least 1 ms, so a zero-delay chain cannot stall a seek.
+    var ms = Math.max(firingDepth > 0 ? 1 : 0, Number(delay) || 0);
+    var entry = { id: nextTimerId++, callback: callback, args: args, due: virtualNowMs + ms, every: repeats ? Math.max(1, ms) : 0, cancelled: false };
+    timerQueue.push(entry);
+    return entry.id;
+  }
+  function cancelTimer(id) {
+    for (var i = 0; i < timerQueue.length; i++) {
+      if (timerQueue[i].id === id) {
+        timerQueue[i].cancelled = true;
+        return true;
+      }
+    }
+    return false;
+  }
+  function fireDueTimers(untilMs) {
+    // Frame times are fractional, so a timer due on a frame lands a rounding error past it; it still fires on it.
+    untilMs += 0.000001;
+    while (true) {
+      var next = null;
+      for (var i = 0; i < timerQueue.length; i++) {
+        var candidate = timerQueue[i];
+        if (!candidate.cancelled && candidate.due <= untilMs && (next === null || candidate.due < next.due)) next = candidate;
+      }
+      if (next === null) break;
+      var dueMs = next.due;
+      if (next.every) next.due += next.every;
+      else next.cancelled = true;
+      virtualNowMs = dueMs;
+      firingDepth++;
+      try {
+        next.callback.apply(window, next.args);
+      } catch (err) {
+        originalSetTimeout(function() { throw err; }, 0);
+      }
+      firingDepth--;
+    }
+    timerQueue = timerQueue.filter(function(entry) { return !entry.cancelled; });
+  }
+  window.setTimeout = function(callback, delay) {
+    if (!rendering || typeof callback !== "function") return originalSetTimeout.apply(null, arguments);
+    return addTimer(callback, delay, Array.prototype.slice.call(arguments, 2), false);
+  };
+  window.setInterval = function(callback, delay) {
+    if (!rendering || typeof callback !== "function") return originalSetInterval.apply(null, arguments);
+    return addTimer(callback, delay, Array.prototype.slice.call(arguments, 2), true);
+  };
+  window.clearTimeout = function(id) {
+    if (!cancelTimer(id)) originalClearTimeout(id);
+  };
+  window.clearInterval = function(id) {
+    if (!cancelTimer(id)) originalClearInterval(id);
+  };
+
   window.__HF_VIRTUAL_TIME__ = {
     originalSetTimeout: originalSetTimeout,
     originalClearTimeout: originalClearTimeout,
@@ -436,8 +498,10 @@ ${seededRandomBlock}
     originalCancelAnimationFrame: originalCancelAnimationFrame,
     seekToTime: function(nextTimeMs) {
       var safeTimeMs = Math.max(0, Number(nextTimeMs) || 0);
+      if (window.__renderReady === true) rendering = true;
+      ${seekToTimeReseedCall}fireDueTimers(safeTimeMs);
       virtualNowMs = safeTimeMs;
-      ${seekToTimeReseedCall}flushAnimationFrame();
+      flushAnimationFrame();
       return virtualNowMs;
     },
     getTime: function() {
@@ -16537,6 +16601,7 @@ function assertDistributedOptions(value) {
     "chunkSize",
     "maxParallelChunks",
     "targetChunkFrames",
+    "minParallelChunks",
     "planDirSizeLimitBytes"
   ]) {
     assertOptionalInteger(value, field, 1);

package/dist/renderRequest.d.ts

@@ -12,6 +12,7 @@ export interface DistributedRenderOptions {
     chunkSize?: number;
     maxParallelChunks?: number;
     targetChunkFrames?: number;
+    minParallelChunks?: number;
     runtimeCap?: DistributedRenderConfig["runtimeCap"];
     rejectOnSystemFonts?: boolean;
     failClosedFontFetch?: boolean;

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

@@ -104,17 +104,19 @@ export interface DistributedRenderConfig extends Pick<RenderRequestOptions, "pag
      * chunks whose per-chunk frame count stays at or below this bound, still
      * capped by `maxParallelChunks`:
      *
-     *     chunkCount = clamp(ceil(totalFrames / targetChunkFrames), 1, maxParallelChunks)
+     *     chunkCount = clamp(ceil(totalFrames / targetChunkFrames), minParallelChunks, maxParallelChunks)
      *
      * This bounds per-chunk render *time* (which scales with frames-per-chunk) so
      * a single chunk can't exceed a downstream per-chunk timeout on a long video,
-     * while short videos still collapse to few chunks. It is a ceiling, not a
+     * while short videos drop to `minParallelChunks` (default 1). It is a ceiling, not a
      * fixed size: a video short enough to fit in fewer chunks gets fewer. Ignored
      * when `chunkSize` is set (an explicit fixed size already pins per-chunk
      * frames). Mutually exclusive with `chunkSize` in intent; if both are passed,
      * `chunkSize` wins and `targetChunkFrames` is a no-op.
      */
     targetChunkFrames?: number;
+    /** Fewest chunks a `targetChunkFrames`-sized plan uses, so a short video keeps this fan-out. */
+    minParallelChunks?: number;
     /** Runtime hint; consumed by future per-runtime budget checks. The current implementation records the value but does not enforce. */
     runtimeCap?: "lambda" | "temporal" | "cloud-run-job" | "k8s-job" | "none";
     /**
@@ -397,12 +399,12 @@ export declare function measurePlanDirBytes(planDir: string): number;
  * on tiny renders). Explicit numbers, including `240`, take precedence.
  *
  * Optional `targetChunkFrames` caps per-chunk frames in the auto-sized path:
- * the auto-sizer then targets `clamp(ceil(totalFrames / targetChunkFrames), 1,
- * maxParallelChunks)` chunks, so short videos collapse to fewer chunks and long
+ * the auto-sizer then targets `clamp(ceil(totalFrames / targetChunkFrames), minParallelChunks,
+ * maxParallelChunks)` chunks, so short videos drop to `minParallelChunks` and long
  * videos add chunks (up to the cap) to keep each one under the bound. It is a
  * no-op when omitted, and ignored when `configChunkSize` is set.
  */
-export declare function resolveChunkPlan(totalFrames: number, configChunkSize: number | undefined, maxParallelChunks: number, targetChunkFrames?: number): {
+export declare function resolveChunkPlan(totalFrames: number, configChunkSize: number | undefined, maxParallelChunks: number, targetChunkFrames?: number, minParallelChunks?: number): {
     chunkCount: number;
     effectiveChunkSize: number;
 };

package/dist/services/fileServer.d.ts

@@ -95,9 +95,9 @@ export interface VirtualTimeShimOptions {
 /**
  * Build the page-side virtual-time shim script.
  *
- * The shim freezes `Date.now`, `performance.now`, and the rAF/setTimeout
- * pipeline so a render seek can deterministically advance the page's
- * notion of "now". The renderer issues `__HF_VIRTUAL_TIME__.seekToTime(ms)`
+ * The shim freezes `Date.now`, `performance.now`, rAF, and the timers set
+ * after the first seek, so a render seek can deterministically advance the
+ * page's notion of "now". The renderer issues `__HF_VIRTUAL_TIME__.seekToTime(ms)`
  * before every frame capture; everything timing-related on the page sees
  * exactly `ms` until the next seek.
  *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hyperframes/producer",
-  "version": "0.9.20",
+  "version": "0.9.21",
   "description": "HTML-to-video rendering engine using Chrome's BeginFrame API",
   "repository": {
     "type": "git",
@@ -35,11 +35,11 @@
     "postcss": "^8.4.0",
     "puppeteer": "~25.11.0",
     "puppeteer-core": "^25.11.0",
-    "@hyperframes/lint": "0.9.20",
-    "@hyperframes/studio-server": "0.9.20",
-    "@hyperframes/core": "0.9.20",
-    "@hyperframes/parsers": "0.9.20",
-    "@hyperframes/engine": "0.9.20"
+    "@hyperframes/engine": "0.9.21",
+    "@hyperframes/parsers": "0.9.21",
+    "@hyperframes/studio-server": "0.9.21",
+    "@hyperframes/lint": "0.9.21",
+    "@hyperframes/core": "0.9.21"
   },
   "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.9.20"
+    "@hyperframes/aws-lambda": "0.9.21"
   },
   "engines": {
     "node": ">=22"