fix: respect user timeouts on low-memory systems (#1221)

Closes #1219

## Problem

On 8GB RAM machines, renders time out at 5% with `Runtime.callFunctionOn timed out` during the duration probe. User-set timeout env vars (`PRODUCER_PUPPETEER_PROTOCOL_TIMEOUT_MS`) are silently ignored by the calibration path, and there are no CLI flags to control timeouts directly.

## Root causes

1. **Calibration timeout cap overrides user settings** — `createCaptureCalibrationConfig` used `Math.min(cfg.protocolTimeout, 30_000)`, meaning even if the user set 300s, calibration still capped at 30s. On slow hardware this causes unnecessary timeouts.

2. **8GB systems get no low-memory treatment** — `getLowMemoryFlags()`, `getGpuMemBudgetMb()`, `memoryAdaptiveCacheLimit()`, and `memoryAdaptiveCacheBytesMb()` all used `< 8192` as the threshold. Systems reporting exactly 8192 MB (common for 8GB machines) fell through to the "plenty of memory" path, getting no Chrome heap reduction or cache limits.

3. **No CLI flags for key timeouts** — Users had to discover the correct env var names (`PRODUCER_PUPPETEER_PROTOCOL_TIMEOUT_MS`, `PRODUCER_PLAYER_READY_TIMEOUT_MS`) by reading source. The non-existent `PUPPETEER_PROTOCOL_TIMEOUT` and `--browser-timeout` were common guesses that did nothing.

## Changes

- `captureCost.ts`: `Math.min` → `Math.max` so the 30s calibration default is a floor, not a ceiling. User-set higher timeouts are now respected.
- `browserManager.ts`: `>= 8192` → `> 8192` in `getLowMemoryFlags()` and `<= 8192` in `getGpuMemBudgetMb()` so 8GB systems get reduced Chrome heap and GPU memory budget.
- `config.ts`: `< 8192` → `<= 8192` in `memoryAdaptiveCacheLimit()` and `memoryAdaptiveCacheBytesMb()` so 8GB systems get reduced frame cache limits.
- `render.ts`: Added `--protocol-timeout <ms>` and `--player-ready-timeout <ms>` CLI flags, wired through `resolveConfig` overrides.
- Updated calibration tests to match the new floor-not-ceiling behavior.
- Added fallow suppressions for pre-existing unused exports in `captureCost.ts`.

## Test plan

- [x] Engine config tests pass (`vitest run src/config.test.ts`)
- [x] Browser manager tests pass (`vitest run src/services/browserManager.test.ts`)
- [x] Calibration safeguard tests pass (4/4 in `renderOrchestrator.test.ts`)
- [x] TypeScript compiles cleanly for engine and cli packages
- [ ] CI pipeline

packages/cli/src/commands/render.ts

@@ -249,6 +249,20 @@ export default defineCommand({
         "readiness poll has its own 45s budget). " +
         "Env fallback: PRODUCER_PAGE_NAVIGATION_TIMEOUT_MS (MILLISECONDS).",
     },
+    "protocol-timeout": {
+      type: "string",
+      description:
+        "CDP protocol timeout in ms. Increase on slow/low-memory machines " +
+        "where Chrome operations time out. Default: 300000 (5 min). " +
+        "Env: PRODUCER_PUPPETEER_PROTOCOL_TIMEOUT_MS.",
+    },
+    "player-ready-timeout": {
+      type: "string",
+      description:
+        "Timeout in ms for the composition player to become ready. " +
+        "Increase for complex compositions on slow hardware. Default: 45000 (45 s). " +
+        "Env: PRODUCER_PLAYER_READY_TIMEOUT_MS.",
+    },
   },
   // `run` is the citty handler for `hyperframes render` — sequential flag
   // validation + render dispatch. Inherited CRITICAL on main (CRAP 1290);
@@ -326,6 +340,32 @@ export default defineCommand({
       workers = parsed;
     }
 
+    // ── Validate timeout overrides ─────────────────────────────────────
+    let protocolTimeout: number | undefined;
+    if (args["protocol-timeout"] != null) {
+      const parsed = parseInt(args["protocol-timeout"], 10);
+      if (isNaN(parsed) || parsed < 1000) {
+        errorBox(
+          "Invalid protocol-timeout",
+          `Got "${args["protocol-timeout"]}". Must be a number >= 1000 (ms).`,
+        );
+        process.exit(1);
+      }
+      protocolTimeout = parsed;
+    }
+    let playerReadyTimeout: number | undefined;
+    if (args["player-ready-timeout"] != null) {
+      const parsed = parseInt(args["player-ready-timeout"], 10);
+      if (isNaN(parsed) || parsed < 1000) {
+        errorBox(
+          "Invalid player-ready-timeout",
+          `Got "${args["player-ready-timeout"]}". Must be a number >= 1000 (ms).`,
+        );
+        process.exit(1);
+      }
+      playerReadyTimeout = parsed;
+    }
+
     // ── Wire opt-in: page-side compositing ───────────────────────────────
     if (args["page-side-compositing"] === false) {
       process.env.HF_PAGE_SIDE_COMPOSITING = "false";
@@ -347,6 +387,7 @@ export default defineCommand({
     // ── Resolve output path ───────────────────────────────────────────────
     const rendersDir = resolve("renders");
     const ext = FORMAT_EXT[format] ?? ".mp4";
+    // fallow-ignore-next-line code-duplication
     const now = new Date();
     const datePart = now.toISOString().slice(0, 10);
     const timePart = now.toTimeString().slice(0, 8).replace(/:/g, "-");
@@ -528,6 +569,8 @@ export default defineCommand({
         outputResolution,
         pageSideCompositing: args["page-side-compositing"] !== false,
         pageNavigationTimeoutMs,
+        protocolTimeout,
+        playerReadyTimeout,
         exitAfterComplete: true,
       });
     } else {
@@ -547,6 +590,8 @@ export default defineCommand({
         entryFile,
         outputResolution,
         pageNavigationTimeoutMs,
+        protocolTimeout,
+        playerReadyTimeout,
         exitAfterComplete: true,
       });
     }
@@ -583,6 +628,10 @@ interface RenderOptions {
    * producer's EngineConfig override.
    */
   pageNavigationTimeoutMs?: number;
+  /** CDP protocol timeout override (ms). */
+  protocolTimeout?: number;
+  /** Player-ready timeout override (ms). */
+  playerReadyTimeout?: number;
 }
 
 /**
@@ -848,6 +897,7 @@ async function renderDocker(
   if (options.exitAfterComplete) scheduleRenderProcessExit();
 }
 
+// fallow-ignore-next-line complexity
 export async function renderLocal(
   projectDir: string,
   outputPath: string,
@@ -885,6 +935,8 @@ export async function renderLocal(
       ...(options.pageNavigationTimeoutMs != null
         ? { pageNavigationTimeout: options.pageNavigationTimeoutMs }
         : {}),
+      ...(options.protocolTimeout != null && { protocolTimeout: options.protocolTimeout }),
+      ...(options.playerReadyTimeout != null && { playerReadyTimeout: options.playerReadyTimeout }),
     }),
     hdrMode: options.hdrMode,
     crf: options.crf,