fix: prepare video validation without delaying capture

packages/capture-kit/src/recording/__tests__/overlay-script-paths.test.ts

@@ -32,6 +32,7 @@ test('a helper script path is resolved per host working directory, not once per
   const overlay = async (cwd: string) => {
     fs.writeFileSync(videoPath, 'original');
     await overlayRecordingTouches({
+      validator: undefined,
       host: { env: {}, cwd },
       videoPath,
       telemetryPath,

packages/capture-kit/src/recording/__tests__/overlay.test.ts

@@ -58,19 +58,26 @@ afterEach(() => {
 });
 
 test('overlay burns touches through a cached helper and same-directory temp output', async () => {
+  const validator = {
+    kind: 'avfoundation' as const,
+    executablePath: '/prepared/video-validator',
+    env: {},
+  };
   const videoPath = path.join(tmpDir, 'recording.mp4');
   const telemetryPath = path.join(tmpDir, 'recording.gesture-telemetry.json');
   fs.writeFileSync(videoPath, 'original');
   fs.writeFileSync(telemetryPath, '{"events":[]}');
 
   await overlayRecordingTouches({
+    validator,
     host: createTestHost(),
     videoPath,
     telemetryPath,
     deadline: startRecordingOverlayBudget(),
   });
   fs.writeFileSync(videoPath, 'second original');
   await overlayRecordingTouches({
+    validator,
     host: createTestHost(),
     videoPath,
     telemetryPath,
@@ -84,6 +91,7 @@ test('overlay burns touches through a cached helper and same-directory temp outp
 
   expect(compileCalls).toHaveLength(1);
   expect(helperCalls).toHaveLength(2);
+  expect(vi.mocked(waitForPlayableVideo).mock.calls[0]?.[1].validator).toBe(validator);
 
   const [helperCmd, helperArgs, helperOptions] = helperCalls[0]!;
   const inputPath = helperArgs[helperArgs.indexOf('--input') + 1]!;
@@ -113,6 +121,7 @@ test('overlay preserves Swift helper compile hints', async () => {
 
   await expect(
     overlayRecordingTouches({
+      validator: undefined,
       host: createTestHost(),
       videoPath,
       telemetryPath,
@@ -134,6 +143,7 @@ test('overlay defaults to the fast medium export preset', async () => {
   fs.writeFileSync(telemetryPath, '{"events":[]}');
 
   await overlayRecordingTouches({
+    validator: undefined,
     host: createTestHost(),
     videoPath,
     telemetryPath,
@@ -152,6 +162,7 @@ test('overlay forwards the requested high export preset', async () => {
   fs.writeFileSync(telemetryPath, '{"events":[]}');
 
   await overlayRecordingTouches({
+    validator: undefined,
     host: createTestHost(),
     videoPath,
     telemetryPath,
@@ -171,6 +182,7 @@ test('overlay caps the helper frame rate at the caller fps only when one was ask
   fs.writeFileSync(telemetryPath, '{"events":[]}');
 
   await overlayRecordingTouches({
+    validator: undefined,
     host: createTestHost(),
     videoPath,
     telemetryPath,
@@ -180,6 +192,7 @@ test('overlay caps the helper frame rate at the caller fps only when one was ask
 
   mockRunCmd.mockClear();
   await overlayRecordingTouches({
+    validator: undefined,
     host: createTestHost(),
     videoPath,
     telemetryPath,
@@ -197,6 +210,7 @@ test('overlay hands the helper what is left of its budget, inside the record req
   fs.writeFileSync(telemetryPath, '{"events":[]}');
 
   await overlayRecordingTouches({
+    validator: undefined,
     host: createTestHost(),
     videoPath,
     telemetryPath,
@@ -225,7 +239,13 @@ test('overlay hands the helper only what the finalization left of the budget', a
   const deadline = startRecordingOverlayBudget();
   vi.setSystemTime(Date.now() + spentMs);
 
-  await overlayRecordingTouches({ host: createTestHost(), videoPath, telemetryPath, deadline });
+  await overlayRecordingTouches({
+    validator: undefined,
+    host: createTestHost(),
+    videoPath,
+    telemetryPath,
+    deadline,
+  });
 
   const helperCall = mockRunCmd.mock.calls.find(([cmd]) => cmd !== 'xcrun');
   expect(helperCall?.[2]?.timeoutMs).toBe(OVERLAY_BUDGET_MS - spentMs);
@@ -248,6 +268,7 @@ test('overlay leaves the video as recorded when compiling the helper spent its b
 
   await expect(
     overlayRecordingTouches({
+      validator: undefined,
       host: createTestHost(),
       videoPath,
       telemetryPath,
@@ -269,6 +290,7 @@ test('overlay names its budget when the export ran out of it', async () => {
   fs.writeFileSync(telemetryPath, '{"events":[]}');
 
   await overlayRecordingTouches({
+    validator: undefined,
     host: createTestHost(),
     videoPath,
     telemetryPath,
@@ -282,6 +304,7 @@ test('overlay names its budget when the export ran out of it', async () => {
 
   await expect(
     overlayRecordingTouches({
+      validator: undefined,
       host: createTestHost(),
       videoPath,
       telemetryPath,
@@ -301,6 +324,7 @@ test('overlay keeps the plain failure when the export failed with budget to spar
   fs.writeFileSync(telemetryPath, '{"events":[]}');
 
   await overlayRecordingTouches({
+    validator: undefined,
     host: createTestHost(),
     videoPath,
     telemetryPath,
@@ -312,6 +336,7 @@ test('overlay keeps the plain failure when the export failed with budget to spar
 
   await expect(
     overlayRecordingTouches({
+      validator: undefined,
       host: createTestHost(),
       videoPath,
       telemetryPath,
@@ -331,6 +356,7 @@ test('overlay keeps the video as recorded when the export never plays within its
 
   await expect(
     overlayRecordingTouches({
+      validator: undefined,
       host: createTestHost(),
       videoPath,
       telemetryPath,
@@ -356,13 +382,19 @@ test('overlay keeps the video as recorded when verifying the export spent its bu
   });
 
   await expect(
-    overlayRecordingTouches({ host: createTestHost(), videoPath, telemetryPath, deadline }),
+    overlayRecordingTouches({
+      validator: undefined,
+      host: createTestHost(),
+      videoPath,
+      telemetryPath,
+      deadline,
+    }),
   ).rejects.toMatchObject({
     code: 'COMMAND_FAILED',
     message: `Failed to add touch overlays to the recording: the export did not finish within its ${OVERLAY_BUDGET_MS}ms budget; a lower --fps renders faster`,
   });
   expect(vi.mocked(waitForPlayableVideo)).toHaveBeenCalledWith(expect.any(String), {
-    host: expect.objectContaining({ cwd: process.cwd() }),
+    validator: undefined,
     deadline,
   });
   expect(fs.readFileSync(videoPath, 'utf8')).toBe('original');

packages/capture-kit/src/recording/overlay.ts

@@ -10,7 +10,7 @@ import {
   compileSwiftSourceFile,
   resolveRecordingScriptPath,
 } from './swift-cache.ts';
-import { waitForPlayableVideo } from './video.ts';
+import { waitForPlayableVideo, type VideoValidator } from './video.ts';
 import {
   DEFAULT_RECORDING_EXPORT_QUALITY,
   type RecordingExportQuality,
@@ -29,9 +29,9 @@ export function getRecordingOverlaySupportWarning(
  * `record stop` is one daemon request, which the client abandons after `record`'s 90 s envelope:
  * the caller gets "Daemon request timed out" while the daemon finishes the stop. So the overlay must
  * end well inside it. The budget starts with the stop's finalization, so the playability checks
- * before the overlay (on a cold host they compile their validator first) come out of it, as do
- * compiling the helper, its export, its exit and verifying its output; past it the stop keeps the raw video and its
- * gesture telemetry, with a warning.
+ * before the overlay come out of it, as do compiling the overlay helper, exporting, exiting and
+ * verifying its output. Past the budget, the stop keeps the raw video and gesture telemetry, with
+ * a warning.
  */
 export const OVERLAY_BUDGET_MS = 70_000;
 
@@ -79,6 +79,7 @@ async function exportProcessedVideo(params: {
   scriptArgs: string[];
   commandDescription: string;
   deadline: Deadline;
+  validator: VideoValidator | undefined;
 }): Promise<void> {
   const { host, videoPath, scriptPath, scriptArgs, commandDescription, deadline } = params;
   const outputPath = temporarySiblingVideoPath(videoPath);
@@ -117,7 +118,7 @@ async function exportProcessedVideo(params: {
       exportOverran = deadline.remainingMs() <= HELPER_EXIT_GRACE_MS;
       throw error;
     }
-    if (!(await waitForPlayableVideo(outputPath, { host, deadline }))) {
+    if (!(await waitForPlayableVideo(outputPath, { validator: params.validator, deadline }))) {
       exportOverran = deadline.isExpired();
       throw new AppError('COMMAND_FAILED', 'The composited video was not verified as playable');
     }
@@ -158,6 +159,7 @@ function temporarySiblingVideoPath(videoPath: string): string {
 
 export async function overlayRecordingTouches(params: {
   host: HostEnvironment;
+  validator: VideoValidator | undefined;
   videoPath: string;
   telemetryPath: string;
   exportQuality?: RecordingExportQuality;
@@ -186,5 +188,6 @@ export async function overlayRecordingTouches(params: {
     ],
     commandDescription: `Failed to add touch overlays to the ${targetLabel}`,
     deadline: params.deadline,
+    validator: params.validator,
   });
 }