fix(engine): honor explicit render worker counts (#2439)

packages/engine/src/services/parallelCoordinator.test.ts

@@ -76,6 +76,17 @@ describe("calculateOptimalWorkers", () => {
 
     expect(workers).toBe(4);
   });
+
+  it.each([12, 16])(
+    "honors an explicit %i-worker request above the auto safe maximum",
+    (requested) => {
+      expect(calculateOptimalWorkers(900, requested, { concurrency: "auto" })).toBe(requested);
+    },
+  );
+
+  it("caps explicit worker requests at the documented 24-worker ceiling", () => {
+    expect(calculateOptimalWorkers(900, 25, { concurrency: "auto" })).toBe(24);
+  });
 });
 
 describe("shouldDisableBrowserPoolForParallelWorker", () => {

packages/engine/src/services/parallelCoordinator.ts

@@ -160,6 +160,10 @@ export function calculateOptimalWorkers(
   requested?: number,
   config?: WorkerSizingConfig,
 ): number {
+  if (requested !== undefined) {
+    return Math.max(MIN_WORKERS, Math.min(ABSOLUTE_MAX_WORKERS, requested));
+  }
+
   // Resolve effective values: config overrides → DEFAULT_CONFIG fallback.
   const effectiveMaxWorkers = (() => {
     const concurrency = config?.concurrency ?? DEFAULT_CONFIG.concurrency;
@@ -174,10 +178,6 @@ export function calculateOptimalWorkers(
     config?.largeRenderThreshold ?? DEFAULT_CONFIG.largeRenderThreshold;
   const captureCostMultiplier = Math.max(1, config?.captureCostMultiplier ?? 1);
 
-  if (requested !== undefined) {
-    return Math.max(MIN_WORKERS, Math.min(effectiveMaxWorkers, requested));
-  }
-
   if (totalFrames < MIN_FRAMES_PER_WORKER * 2) return 1;
 
   const cpuCount = cpus().length;