From 16e049b32035298f179b7b5e5cee4b84064dc5cf Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Miguel=20=C3=81ngel?= <miguel.sierra@heygen.com>
Date: Sun, 24 May 2026 13:27:54 -0400
Subject: [PATCH] =?UTF-8?q?fix(cli):=20address=20review=20=E2=80=94=20fps?=
 =?UTF-8?q?=20comment,=20fileServer=20cross-ref,=20duration=20note?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Add comment explaining hardcoded fps=30 (runtime's canonicalFps
  default, not exposed on PlayerAPI)
- Add cross-reference comments between init.ts and fileServer.ts
  explaining their different __renderReady timing semantics
---
 packages/cli/src/commands/snapshot.ts        | 1 +
 packages/core/src/runtime/init.ts            | 2 ++
 packages/producer/src/services/fileServer.ts | 2 ++
 3 files changed, 5 insertions(+)

diff --git a/packages/cli/src/commands/snapshot.ts b/packages/cli/src/commands/snapshot.ts
index a8f654f67..f9158f20a 100644
--- a/packages/cli/src/commands/snapshot.ts
+++ b/packages/cli/src/commands/snapshot.ts
@@ -276,6 +276,7 @@ async function captureSnapshots(
       for (let i = 0; i < positions.length; i++) {
         const time = positions[i]!;
 
+        // 30 = runtime's default canonicalFps (not exposed on PlayerAPI)
         await page.evaluate((t: number) => {
           const player = (window as any).__player;
           if (!player) return;
diff --git a/packages/core/src/runtime/init.ts b/packages/core/src/runtime/init.ts
index af7e8529b..11b84dc22 100644
--- a/packages/core/src/runtime/init.ts
+++ b/packages/core/src/runtime/init.ts
@@ -1634,6 +1634,8 @@ export function initSandboxRuntimeModular(): void {
     player._timeline = state.capturedTimeline;
   }
 
+  // __renderReady = timeline is bound, safe for deterministic seeking.
+  // fileServer.ts sets this immediately (no timeline to bind in its runtime).
   if (state.capturedTimeline) {
     (window as Window & { __renderReady?: boolean }).__renderReady = true;
   }
diff --git a/packages/producer/src/services/fileServer.ts b/packages/producer/src/services/fileServer.ts
index 262ba4308..17c383a98 100644
--- a/packages/producer/src/services/fileServer.ts
+++ b/packages/producer/src/services/fileServer.ts
@@ -390,6 +390,8 @@ const RENDER_MODE_SCRIPT = `(function() {
       },
     };
     window.__playerReady = true;
+    // Media-fallback player has no timeline to bind, so render-ready is immediate.
+    // init.ts defers __renderReady until the timeline is bound — different runtime.
     window.__renderReady = true;
     return true;
   }