@hyperframes/producer 0.9.20 → 0.9.22

package/dist/index.js

@@ -331,7 +331,7 @@ function buildVirtualTimeShim(options) {
     } catch (e) {}
   }
 ` : "";
-  const seekToTimeReseedCall = seedRandomFromFrame ? "reseedRngFromTime(safeTimeMs);\n      " : "";
+  const seekToTimeReseedCall = seedRandomFromFrame ? "reseedRngFromTime(safeTimeMs);\n    " : "";
   return String.raw`(function() {
   if (window.__HF_VIRTUAL_TIME__) return;
 
@@ -410,6 +410,82 @@ ${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);
+  };
+
+  function seekToTime(nextTimeMs) {
+    var safeTimeMs = Math.max(0, Number(nextTimeMs) || 0);
+    if (!rendering && window.__renderReady === true) {
+      rendering = true;
+      // A worker whose first frame is past the start plays the film's first frame first, so timers the
+      // page starts there keep the schedule a one-worker render gives them.
+      if (safeTimeMs > 0) seekToTime(0);
+    }
+    ${seekToTimeReseedCall}fireDueTimers(safeTimeMs);
+    virtualNowMs = safeTimeMs;
+    flushAnimationFrame();
+    return virtualNowMs;
+  }
+
   window.__HF_VIRTUAL_TIME__ = {
     originalSetTimeout: originalSetTimeout,
     originalClearTimeout: originalClearTimeout,
@@ -417,12 +493,7 @@ ${seededRandomBlock}
     originalClearInterval: originalClearInterval,
     originalRequestAnimationFrame: originalRequestAnimationFrame,
     originalCancelAnimationFrame: originalCancelAnimationFrame,
-    seekToTime: function(nextTimeMs) {
-      var safeTimeMs = Math.max(0, Number(nextTimeMs) || 0);
-      virtualNowMs = safeTimeMs;
-      ${seekToTimeReseedCall}flushAnimationFrame();
-      return virtualNowMs;
-    },
+    seekToTime: seekToTime,
     getTime: function() {
       return virtualNowMs;
     },
@@ -16828,13 +16899,14 @@ var RenderChunkValidationError = class extends Error {
     this.code = code;
   }
 };
+var chunkFrameInjectorDependencies = { createVideoFrameInjector: createVideoFrameInjector3 };
 function createChunkVideoFrameInjectorFactory(frameLookup, options) {
   if (!(frameLookup instanceof Promise))
-    return () => createVideoFrameInjector3(frameLookup, options);
+    return () => chunkFrameInjectorDependencies.createVideoFrameInjector(frameLookup, options);
   return () => {
     let hook;
     return async (page, time, heldVideoTime) => {
-      hook ??= createVideoFrameInjector3(await frameLookup, options);
+      hook ??= chunkFrameInjectorDependencies.createVideoFrameInjector(await frameLookup, options);
       await hook?.(page, time, heldVideoTime);
     };
   };
@@ -18006,7 +18078,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 +18087,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 +18670,8 @@ async function buildLocalExecutionPlan(projectDir, config, executionPlanDir, opt
     totalFrames,
     config.chunkSize,
     maxParallel,
-    config.targetChunkFrames
+    config.targetChunkFrames,
+    config.minParallelChunks
   );
   const chunks = buildPlanChunkSlices(
     frameWeights,
@@ -20598,6 +20675,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 +20858,7 @@ function assertDistributedOptions(value) {
     "chunkSize",
     "maxParallelChunks",
     "targetChunkFrames",
+    "minParallelChunks",
     "planDirSizeLimitBytes"
   ]) {
     assertOptionalInteger(value, field, 1);
@@ -20906,6 +20998,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 +21026,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

@@ -348,7 +348,7 @@ function buildVirtualTimeShim(options) {
     } catch (e) {}
   }
 ` : "";
-  const seekToTimeReseedCall = seedRandomFromFrame ? "reseedRngFromTime(safeTimeMs);\n      " : "";
+  const seekToTimeReseedCall = seedRandomFromFrame ? "reseedRngFromTime(safeTimeMs);\n    " : "";
   return String.raw`(function() {
   if (window.__HF_VIRTUAL_TIME__) return;
 
@@ -427,6 +427,82 @@ ${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);
+  };
+
+  function seekToTime(nextTimeMs) {
+    var safeTimeMs = Math.max(0, Number(nextTimeMs) || 0);
+    if (!rendering && window.__renderReady === true) {
+      rendering = true;
+      // A worker whose first frame is past the start plays the film's first frame first, so timers the
+      // page starts there keep the schedule a one-worker render gives them.
+      if (safeTimeMs > 0) seekToTime(0);
+    }
+    ${seekToTimeReseedCall}fireDueTimers(safeTimeMs);
+    virtualNowMs = safeTimeMs;
+    flushAnimationFrame();
+    return virtualNowMs;
+  }
+
   window.__HF_VIRTUAL_TIME__ = {
     originalSetTimeout: originalSetTimeout,
     originalClearTimeout: originalClearTimeout,
@@ -434,12 +510,7 @@ ${seededRandomBlock}
     originalClearInterval: originalClearInterval,
     originalRequestAnimationFrame: originalRequestAnimationFrame,
     originalCancelAnimationFrame: originalCancelAnimationFrame,
-    seekToTime: function(nextTimeMs) {
-      var safeTimeMs = Math.max(0, Number(nextTimeMs) || 0);
-      virtualNowMs = safeTimeMs;
-      ${seekToTimeReseedCall}flushAnimationFrame();
-      return virtualNowMs;
-    },
+    seekToTime: seekToTime,
     getTime: function() {
       return virtualNowMs;
     },
@@ -16537,6 +16608,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/chunkFrames.d.ts

@@ -16,6 +16,9 @@ export declare class RenderChunkValidationError extends Error {
     readonly code: RenderChunkValidationCode;
     constructor(code: RenderChunkValidationCode, message: string);
 }
+export declare const chunkFrameInjectorDependencies: {
+    createVideoFrameInjector: typeof createVideoFrameInjector;
+};
 /** One injector per browser session: a hook reused on a fresh page can skip its first injection. */
 export declare function createChunkVideoFrameInjectorFactory(frameLookup: FrameLookupTable | Promise<FrameLookupTable> | null, options?: Parameters<typeof createVideoFrameInjector>[1]): () => BeforeCaptureHook | null;
 /**

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.22",
   "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/core": "0.9.22",
+    "@hyperframes/parsers": "0.9.22",
+    "@hyperframes/lint": "0.9.22",
+    "@hyperframes/engine": "0.9.22",
+    "@hyperframes/studio-server": "0.9.22"
   },
   "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.22"
   },
   "engines": {
     "node": ">=22"