From 2ac5308a432d9cd1b093e9ce57fb797c0efa2ec1 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= <thymikee@gmail.com>
Date: Mon, 5 Oct 2026 20:45:04 +0200
Subject: [PATCH 1/4] feat(recording): cap the touch overlay frame rate at the
 caller's --fps

record start --fps now also caps the touch overlay's composited frame rate
(at most 30), carried as a recording fact so a recovered stop honours it.
An overlay export that runs out of its budget names that in overlayWarning.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
---
 .../RecordingScripts/recording-overlay.swift  | 30 ++++++++++++++-----
 .../src/recording/__tests__/overlay.test.ts   | 17 ++++++++++-
 packages/capture-kit/src/recording/overlay.ts | 16 ++++++++--
 .../src/recording/recording-facts.test.ts     | 11 ++++++-
 .../src/recording/recording-facts.ts          |  7 +++++
 .../src/screen-recording-runtime-host.ts      |  2 ++
 .../contracts/src/screen-recording-runtime.ts |  2 ++
 .../src/recording/finalize.ts                 |  1 +
 .../src/recording/live-snapshot.test.ts       |  2 ++
 .../src/recording/live-snapshot.ts            |  1 +
 .../src/recording/manifest.ts                 |  5 ++++
 .../src/recording/recovery.test.ts            |  2 ++
 .../src/recording/recovery.ts                 |  1 +
 .../platform-android/src/recording/runtime.ts |  1 +
 .../src/recording/completion.test.ts          | 26 ++++++++++++++++
 .../src/recording/completion.ts               |  2 ++
 .../platform-apple/src/recording/runtime.ts   |  1 +
 src/commands/recording/index.ts               |  2 +-
 ...me-screen-recording-finalizer-host.test.ts | 12 ++++++++
 ...runtime-screen-recording-finalizer-host.ts |  1 +
 website/docs/docs/commands.md                 |  3 +-
 21 files changed, 131 insertions(+), 14 deletions(-)

diff --git a/apple/runner/AgentDeviceRunner/RecordingScripts/recording-overlay.swift b/apple/runner/AgentDeviceRunner/RecordingScripts/recording-overlay.swift
index 0c4a1bcec7..5851e5a842 100644
--- a/apple/runner/AgentDeviceRunner/RecordingScripts/recording-overlay.swift
+++ b/apple/runner/AgentDeviceRunner/RecordingScripts/recording-overlay.swift
@@ -88,7 +88,10 @@ func run() throws {
   let renderSize = resolvedRenderSize(for: sourceVideoTrack)
   let videoComposition = AVMutableVideoComposition()
   videoComposition.renderSize = renderSize
-  videoComposition.frameDuration = resolvedFrameDuration(for: sourceVideoTrack)
+  videoComposition.frameDuration = resolvedFrameDuration(
+    for: sourceVideoTrack,
+    maximumFrameRate: parsedArgs.maximumFrameRate
+  )
 
   let instruction = AVMutableVideoCompositionInstruction()
   instruction.timeRange = fullRange
@@ -158,11 +161,15 @@ func run() throws {
 
 func parseArguments(
   _ arguments: [String]
-) throws -> (inputPath: String, outputPath: String, eventsPath: String, timeoutSeconds: Double) {
+) throws -> (
+  inputPath: String, outputPath: String, eventsPath: String, timeoutSeconds: Double,
+  maximumFrameRate: Int32
+) {
   var inputPath: String?
   var outputPath: String?
   var eventsPath: String?
   var timeoutSeconds = defaultRecordingExportTimeoutSeconds
+  var maximumFrameRate = maximumCompositedFrameRate
   var index = 0
 
   while index < arguments.count {
@@ -194,6 +201,13 @@ func parseArguments(
       }
       timeoutSeconds = milliseconds / 1000
       index += 2
+    case "--max-fps":
+      let rawValue = try recordingOptionValue(arguments, nextIndex, "--max-fps")
+      guard let framesPerSecond = Int32(rawValue), framesPerSecond > 0 else {
+        throw RecordingScriptError.invalidArgs("--max-fps must be a positive integer")
+      }
+      maximumFrameRate = min(framesPerSecond, maximumCompositedFrameRate)
+      index += 2
     default:
       throw RecordingScriptError.invalidArgs("Unknown argument: \(argument)")
     }
@@ -201,10 +215,10 @@ func parseArguments(
 
   guard let inputPath, let outputPath, let eventsPath else {
     throw RecordingScriptError.invalidArgs(
-      "Usage: recording-overlay.swift --input <video> --output <video> --events <json> [--quality <medium|high>] [--timeout-ms <ms>]"
+      "Usage: recording-overlay.swift --input <video> --output <video> --events <json> [--quality <medium|high>] [--timeout-ms <ms>] [--max-fps <n>]"
     )
   }
-  return (inputPath, outputPath, eventsPath, timeoutSeconds)
+  return (inputPath, outputPath, eventsPath, timeoutSeconds, maximumFrameRate)
 }
 
 /// The composited overlay must keep the captured track's dimensions, so it can only use a preset
@@ -339,7 +353,7 @@ func frameMeanLuma(_ image: CGImage) -> Double? {
 }
 
 /// The composited export renders at most this many frames a second, which is smooth for a touch
-/// that stays visible for 0.45s.
+/// that stays visible for 0.45s. `--max-fps` lowers it, never raises it.
 let maximumCompositedFrameRate: Int32 = 30
 
 /// A variable-frame-rate capture (simctl recordVideo, adb screenrecord) reports one tick of its
@@ -347,11 +361,11 @@ let maximumCompositedFrameRate: Int32 = 30
 /// every frame the encoder could make, 75 a second from an iOS simulator and 60 from an Android
 /// emulator, about three times the frames the capture holds; a 5-minute recording's export then
 /// outlasted the `record stop` request. So the frame duration is the capture's, but never shorter
-/// than one frame at `maximumCompositedFrameRate`. A capture that reports none renders at that
+/// than one frame at `maximumFrameRate`. A capture that reports none renders at that
 /// rate: its average (`nominalFrameRate`) can be a couple of frames a second over a still screen,
 /// which would skip a touch.
-func resolvedFrameDuration(for track: AVAssetTrack) -> CMTime {
-  let shortest = CMTime(value: 1, timescale: maximumCompositedFrameRate)
+func resolvedFrameDuration(for track: AVAssetTrack, maximumFrameRate: Int32) -> CMTime {
+  let shortest = CMTime(value: 1, timescale: maximumFrameRate)
   let minFrameDuration = track.minFrameDuration
   if minFrameDuration.isValid && !minFrameDuration.isIndefinite && minFrameDuration.seconds > 0 {
     return CMTimeMaximum(minFrameDuration, shortest)
diff --git a/packages/capture-kit/src/recording/__tests__/overlay.test.ts b/packages/capture-kit/src/recording/__tests__/overlay.test.ts
index 21d7849706..4fcd8455c0 100644
--- a/packages/capture-kit/src/recording/__tests__/overlay.test.ts
+++ b/packages/capture-kit/src/recording/__tests__/overlay.test.ts
@@ -131,6 +131,21 @@ test('overlay forwards the requested high export preset', async () => {
   );
 });
 
+test('overlay caps the helper frame rate at the caller fps only when one was asked for', async () => {
+  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({ videoPath, telemetryPath });
+  expect(helperScriptArgs()).not.toContain('--max-fps');
+
+  mockRunCmd.mockClear();
+  await overlayRecordingTouches({ videoPath, telemetryPath, fps: 15 });
+  const args = helperScriptArgs();
+  expect(args[args.indexOf('--max-fps') + 1]).toBe('15');
+});
+
 test('overlay hands the helper what is left of its budget, inside the record request', async () => {
   const videoPath = path.join(tmpDir, 'recording.mp4');
   const telemetryPath = path.join(tmpDir, 'recording.gesture-telemetry.json');
@@ -168,7 +183,7 @@ test('overlay leaves the video as recorded when compiling the helper spent its b
 
   await expect(overlayRecordingTouches({ videoPath, telemetryPath })).rejects.toMatchObject({
     code: 'COMMAND_FAILED',
-    message: 'Failed to add touch overlays to the recording',
+    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(mockRunCmd.mock.calls.filter(([cmd]) => cmd !== 'xcrun')).toHaveLength(0);
   expect(fs.readFileSync(videoPath, 'utf8')).toBe('original');
diff --git a/packages/capture-kit/src/recording/overlay.ts b/packages/capture-kit/src/recording/overlay.ts
index 7412f40ad1..59c0004eb1 100644
--- a/packages/capture-kit/src/recording/overlay.ts
+++ b/packages/capture-kit/src/recording/overlay.ts
@@ -98,6 +98,10 @@ async function exportProcessedVideo(params: {
     await waitForPlayableVideo(outputPath);
     fs.renameSync(outputPath, videoPath);
   } catch (error) {
+    const description =
+      deadline.remainingMs() <= HELPER_EXIT_GRACE_MS
+        ? `${commandDescription}: the export did not finish within its ${params.budgetMs}ms budget; a lower --fps renders faster`
+        : commandDescription;
     const cause =
       error instanceof AppError
         ? error
@@ -109,7 +113,7 @@ async function exportProcessedVideo(params: {
           );
     throw new AppError(
       'COMMAND_FAILED',
-      commandDescription,
+      description,
       {
         ...cause.details,
         videoPath,
@@ -132,6 +136,8 @@ export async function overlayRecordingTouches(params: {
   videoPath: string;
   telemetryPath: string;
   exportQuality?: RecordingExportQuality;
+  /** The caller's `--fps`; the helper renders at most this many frames a second, capped at 30. */
+  fps?: number;
   targetLabel?: string;
 }): Promise<void> {
   const {
@@ -143,7 +149,13 @@ export async function overlayRecordingTouches(params: {
   await exportProcessedVideo({
     videoPath,
     scriptPath: getOverlayScriptPath(),
-    scriptArgs: ['--events', telemetryPath, '--quality', exportQuality],
+    scriptArgs: [
+      '--events',
+      telemetryPath,
+      '--quality',
+      exportQuality,
+      ...(params.fps === undefined ? [] : ['--max-fps', String(params.fps)]),
+    ],
     commandDescription: `Failed to add touch overlays to the ${targetLabel}`,
     budgetMs: OVERLAY_BUDGET_MS,
   });
diff --git a/packages/capture-kit/src/recording/recording-facts.test.ts b/packages/capture-kit/src/recording/recording-facts.test.ts
index 51c679b483..b6d7e7819b 100644
--- a/packages/capture-kit/src/recording/recording-facts.test.ts
+++ b/packages/capture-kit/src/recording/recording-facts.test.ts
@@ -21,6 +21,7 @@ test('accepts the facts a caller asked for, with or without the optional ones',
     true,
   );
   assert.equal(recordingFactsAreValid(facet({ exportQuality: 'high' })), true);
+  assert.equal(recordingFactsAreValid(facet({ fps: 15 })), true);
 });
 
 test('refuses a facet whose recording facts no start could have produced', () => {
@@ -32,6 +33,9 @@ test('refuses a facet whose recording facts no start could have produced', () =>
 
 test('refuses an optional fact that is present but unreadable rather than dropping it', () => {
   assert.equal(recordingFactsAreValid(facet({ exportQuality: 'ultra' })), false);
+  assert.equal(recordingFactsAreValid(facet({ fps: 0 })), false);
+  assert.equal(recordingFactsAreValid(facet({ fps: 12.5 })), false);
+  assert.equal(recordingFactsAreValid(facet({ fps: '15' })), false);
   assert.equal(recordingFactsAreValid(facet({ activeSessionApp: { bundleId: '' } })), false);
   assert.equal(recordingFactsAreValid(facet({ activeSessionApp: { name: 'Example' } })), false);
   assert.equal(recordingFactsAreValid(facet({ activeSessionApp: 'com.example.app' })), false);
@@ -42,6 +46,11 @@ test('refuses an optional fact that is present but unreadable rather than droppi
 });
 
 test('names every key of the facet it validates', () => {
-  const declared = Object.keys({ ...FACTS, activeSessionApp: undefined, exportQuality: undefined });
+  const declared = Object.keys({
+    ...FACTS,
+    activeSessionApp: undefined,
+    exportQuality: undefined,
+    fps: undefined,
+  });
   assert.deepEqual([...RECORDING_FACTS_KEYS].sort(), declared.sort());
 });
diff --git a/packages/capture-kit/src/recording/recording-facts.ts b/packages/capture-kit/src/recording/recording-facts.ts
index 57cb388331..3761749c66 100644
--- a/packages/capture-kit/src/recording/recording-facts.ts
+++ b/packages/capture-kit/src/recording/recording-facts.ts
@@ -19,6 +19,7 @@ export type RecordingFacts = Readonly<{
   recordOnlySession: boolean;
   activeSessionApp?: RecordingAppIdentity;
   exportQuality?: RecordingExportQuality;
+  fps?: number;
 }>;
 
 /** The keys of {@link RecordingFacts}, so a backend carries the facet without naming it twice. */
@@ -28,6 +29,7 @@ export const RECORDING_FACTS_KEYS = [
   'recordOnlySession',
   'activeSessionApp',
   'exportQuality',
+  'fps',
 ] as const satisfies readonly (keyof RecordingFacts)[];
 
 /**
@@ -41,10 +43,15 @@ export function recordingFactsAreValid(value: Record<string, unknown>): value is
     typeof value.showTouches === 'boolean' &&
     typeof value.recordOnlySession === 'boolean' &&
     (value.exportQuality === undefined || isRecordingExportQuality(value.exportQuality)) &&
+    isOptionalFps(value.fps) &&
     isOptionalAppIdentity(value.activeSessionApp)
   );
 }
 
+function isOptionalFps(value: unknown): value is number | undefined {
+  return value === undefined || (typeof value === 'number' && Number.isInteger(value) && value > 0);
+}
+
 function isOptionalAppIdentity(value: unknown): value is RecordingAppIdentity | undefined {
   if (value === undefined) return true;
   if (!isRecord(value) || !isNonemptyText(value.bundleId)) return false;
diff --git a/packages/contracts/src/screen-recording-runtime-host.ts b/packages/contracts/src/screen-recording-runtime-host.ts
index ccbb03318b..bf9e52ac30 100644
--- a/packages/contracts/src/screen-recording-runtime-host.ts
+++ b/packages/contracts/src/screen-recording-runtime-host.ts
@@ -253,6 +253,8 @@ export type ScreenRecordingFinalizer = Readonly<{
       showTouches: boolean;
       gestureEvents: readonly RecordingGestureEvent[];
       exportQuality?: RecordingExportQuality;
+      /** The touch overlay renders at no more frames a second than this. */
+      fps?: number;
       targetLabel: string;
     }>,
     signal?: AbortSignal,
diff --git a/packages/contracts/src/screen-recording-runtime.ts b/packages/contracts/src/screen-recording-runtime.ts
index e7654614ec..66e0977bbd 100644
--- a/packages/contracts/src/screen-recording-runtime.ts
+++ b/packages/contracts/src/screen-recording-runtime.ts
@@ -72,6 +72,8 @@ export type ScreenRecordingLiveSnapshot = Readonly<{
   recordOnlySession: boolean;
   activeSessionApp?: RecordingAppIdentity;
   exportQuality?: RecordingExportQuality;
+  /** The caller's `--fps`: the capture rate where the recorder takes one, and the overlay's cap. */
+  fps?: number;
   gestureEvents: readonly RecordingGestureEvent[];
   touchReferenceFrame?: GestureReferenceFrame;
   gestureClockOriginAtMs?: number;
diff --git a/packages/platform-android/src/recording/finalize.ts b/packages/platform-android/src/recording/finalize.ts
index 6e43427e34..c598c9fce8 100644
--- a/packages/platform-android/src/recording/finalize.ts
+++ b/packages/platform-android/src/recording/finalize.ts
@@ -123,6 +123,7 @@ async function exportCollectedChunks(
       showTouches: chunked ? false : recording.showTouches,
       gestureEvents: recording.gestureEvents,
       exportQuality: recording.exportQuality ?? 'medium',
+      ...(recording.fps === undefined ? {} : { fps: recording.fps }),
       targetLabel: TARGET_LABEL,
     });
   } catch (error) {
diff --git a/packages/platform-android/src/recording/live-snapshot.test.ts b/packages/platform-android/src/recording/live-snapshot.test.ts
index e45d2d5950..9cfa8032f7 100644
--- a/packages/platform-android/src/recording/live-snapshot.test.ts
+++ b/packages/platform-android/src/recording/live-snapshot.test.ts
@@ -22,6 +22,7 @@ describe('snapshot', () => {
         ...recordingInput(),
         clientOutputPath: '/client/capture.mp4',
         exportQuality: 'high',
+        fps: 15,
         activeSessionApp: { bundleId: 'com.example.app' },
       },
       1,
@@ -30,6 +31,7 @@ describe('snapshot', () => {
     expect(started).toMatchObject({
       clientOutPath: '/client/capture.mp4',
       exportQuality: 'high',
+      fps: 15,
       activeSessionApp: { bundleId: 'com.example.app' },
     });
     expect(snapshot({ ...recordingInput(), showTouches: false }, 1).showTouches).toBe(false);
diff --git a/packages/platform-android/src/recording/live-snapshot.ts b/packages/platform-android/src/recording/live-snapshot.ts
index e7822c1c4d..778313d44a 100644
--- a/packages/platform-android/src/recording/live-snapshot.ts
+++ b/packages/platform-android/src/recording/live-snapshot.ts
@@ -18,6 +18,7 @@ export function snapshot(
     recordOnlySession: input.recordOnlySession,
     ...(input.activeSessionApp ? { activeSessionApp: input.activeSessionApp } : {}),
     ...(input.exportQuality ? { exportQuality: input.exportQuality } : {}),
+    ...(input.fps === undefined ? {} : { fps: input.fps }),
     gestureEvents: [],
   });
 }
diff --git a/packages/platform-android/src/recording/manifest.ts b/packages/platform-android/src/recording/manifest.ts
index e358062093..e93ff91e20 100644
--- a/packages/platform-android/src/recording/manifest.ts
+++ b/packages/platform-android/src/recording/manifest.ts
@@ -21,6 +21,7 @@ export type AndroidRecordingDescriptor = Readonly<{
   recordOnlySession: boolean;
   activeSessionApp?: ScreenRecordingStartInput['activeSessionApp'];
   exportQuality?: ScreenRecordingStartInput['exportQuality'];
+  fps?: number;
   transportMode: 'local' | 'transport-composed';
 }>;
 
@@ -46,6 +47,7 @@ export type NativeManifest = Readonly<{
   recordOnlySession: boolean;
   activeSessionApp?: ScreenRecordingStartInput['activeSessionApp'];
   exportQuality?: ScreenRecordingStartInput['exportQuality'];
+  fps?: number;
   transportMode: 'local' | 'transport-composed';
   chunks: readonly NativeChunk[];
   pendingRemotePath?: string;
@@ -82,6 +84,7 @@ export const androidScreenRecordingDescriptorCodec = Object.freeze({
               : {
                   exportQuality: body.exportQuality as AndroidRecordingDescriptor['exportQuality'],
                 }),
+            ...(body.fps === undefined ? {} : { fps: body.fps }),
           }),
         } as const)
       : ({ status: 'invalid', message: 'Invalid Android screen-recording descriptor' } as const),
@@ -110,6 +113,7 @@ export function createNativeManifest(
     recordOnlySession: input.recordOnlySession,
     ...(input.activeSessionApp === undefined ? {} : { activeSessionApp: input.activeSessionApp }),
     ...(input.exportQuality === undefined ? {} : { exportQuality: input.exportQuality }),
+    ...(input.fps === undefined ? {} : { fps: input.fps }),
     chunks,
     ...(pendingRemotePath === undefined ? {} : { pendingRemotePath }),
     transportMode,
@@ -163,6 +167,7 @@ export function nativeManifestMatchesDescriptor(
     manifest.recordOnlySession === descriptor.recordOnlySession &&
     JSON.stringify(manifest.activeSessionApp) === JSON.stringify(descriptor.activeSessionApp) &&
     manifest.exportQuality === descriptor.exportQuality &&
+    manifest.fps === descriptor.fps &&
     manifest.transportMode === descriptor.transportMode &&
     (manifest.completion === undefined ||
       completionMatchesDescriptor(manifest.completion, descriptor))
diff --git a/packages/platform-android/src/recording/recovery.test.ts b/packages/platform-android/src/recording/recovery.test.ts
index 7bd50a1a35..a100db49ba 100644
--- a/packages/platform-android/src/recording/recovery.test.ts
+++ b/packages/platform-android/src/recording/recovery.test.ts
@@ -28,6 +28,7 @@ test('reattaches complete matching evidence and refuses fence, session, or devic
     recordOnlySession: true,
     activeSessionApp: { bundleId: 'com.example.app', name: 'Example' },
     exportQuality: 'high',
+    fps: 15,
   });
   const active = await runtime.screenRecordingReattach({ envelope: started.envelope });
   expect(active.status).toBe('active');
@@ -38,6 +39,7 @@ test('reattaches complete matching evidence and refuses fence, session, or devic
       scope: 'system',
       recordOnlySession: true,
       exportQuality: 'high',
+      fps: 15,
     });
   for (const envelope of [
     { ...started.envelope, fence: { token: 'other', generation: 2 } },
diff --git a/packages/platform-android/src/recording/recovery.ts b/packages/platform-android/src/recording/recovery.ts
index 94b109df24..2181f397db 100644
--- a/packages/platform-android/src/recording/recovery.ts
+++ b/packages/platform-android/src/recording/recovery.ts
@@ -256,6 +256,7 @@ function inputFromDescriptor(
       ? {}
       : { activeSessionApp: descriptor.activeSessionApp }),
     ...(descriptor.exportQuality === undefined ? {} : { exportQuality: descriptor.exportQuality }),
+    ...(descriptor.fps === undefined ? {} : { fps: descriptor.fps }),
     fence,
   };
 }
diff --git a/packages/platform-android/src/recording/runtime.ts b/packages/platform-android/src/recording/runtime.ts
index 331424dfb4..cc0223858a 100644
--- a/packages/platform-android/src/recording/runtime.ts
+++ b/packages/platform-android/src/recording/runtime.ts
@@ -208,6 +208,7 @@ async function startAndroidRecording(params: {
           ? {}
           : { activeSessionApp: input.activeSessionApp }),
         ...(input.exportQuality === undefined ? {} : { exportQuality: input.exportQuality }),
+        ...(input.fps === undefined ? {} : { fps: input.fps }),
         transportMode: transport.mode,
       }),
     }),
diff --git a/packages/platform-apple/src/recording/completion.test.ts b/packages/platform-apple/src/recording/completion.test.ts
index 06d3ce05ee..e99f8ce2f9 100644
--- a/packages/platform-apple/src/recording/completion.test.ts
+++ b/packages/platform-apple/src/recording/completion.test.ts
@@ -28,3 +28,29 @@ test('projects invalidated touch-overlay state without publishing a false overla
     },
   });
 });
+
+test('hands the caller fps to the finalizer that burns the touch overlay', async () => {
+  const requests: Readonly<{ showTouches: boolean; fps?: number }>[] = [];
+  await completeAppleRecording({
+    host: appleRecordingHost({
+      complete: async (input) => {
+        requests.push(input);
+        return {};
+      },
+    }),
+    snapshot: {
+      backend: 'simctl',
+      outPath: '/tmp/capture.mp4',
+      startedAt: 1,
+      scope: 'app',
+      showTouches: true,
+      recordOnlySession: false,
+      fps: 15,
+      gestureEvents: [],
+    },
+    targetLabel: 'iOS recording',
+    stopObservation: { recorder: 'confirmed' },
+  });
+
+  expect(requests).toEqual([expect.objectContaining({ showTouches: true, fps: 15 })]);
+});
diff --git a/packages/platform-apple/src/recording/completion.ts b/packages/platform-apple/src/recording/completion.ts
index 6fc7b50120..1445a0a853 100644
--- a/packages/platform-apple/src/recording/completion.ts
+++ b/packages/platform-apple/src/recording/completion.ts
@@ -34,6 +34,7 @@ export async function completeAppleRecording(params: {
       showTouches: snapshot.invalidatedReason ? false : snapshot.showTouches,
       gestureEvents: snapshot.gestureEvents,
       exportQuality: snapshot.exportQuality ?? 'medium',
+      ...(snapshot.fps === undefined ? {} : { fps: snapshot.fps }),
       targetLabel,
     });
   } catch (error) {
@@ -95,6 +96,7 @@ export async function finalizeAppleRecordingFromCollected(
         showTouches: overlayUnavailability === undefined && snapshot.showTouches,
         gestureEvents: snapshot.gestureEvents,
         exportQuality: snapshot.exportQuality ?? 'medium',
+        ...(snapshot.fps === undefined ? {} : { fps: snapshot.fps }),
         targetLabel,
       }),
     );
diff --git a/packages/platform-apple/src/recording/runtime.ts b/packages/platform-apple/src/recording/runtime.ts
index e3e5deff41..c0fc429e2b 100644
--- a/packages/platform-apple/src/recording/runtime.ts
+++ b/packages/platform-apple/src/recording/runtime.ts
@@ -486,6 +486,7 @@ function snapshot(
     recordOnlySession: input.recordOnlySession,
     ...(input.activeSessionApp === undefined ? {} : { activeSessionApp: input.activeSessionApp }),
     ...(input.exportQuality === undefined ? {} : { exportQuality: input.exportQuality }),
+    ...(input.fps === undefined ? {} : { fps: input.fps }),
     gestureEvents: [],
     ...(clockAnchor === undefined
       ? {}
diff --git a/src/commands/recording/index.ts b/src/commands/recording/index.ts
index 62435afd63..66df2d2606 100644
--- a/src/commands/recording/index.ts
+++ b/src/commands/recording/index.ts
@@ -128,7 +128,7 @@ export const recordCommandFacet = defineCommandFacet({
   text: {
     summary: 'Start or stop screen recording',
     cliDetail:
-      'The default --scope app requires an active app session from open <app>; use --scope device/system to explicitly request whole-screen recording where the selected backend supports it. Android record start publishes a durable device manifest, recordings longer than the 180s adb screenrecord limit are returned as multiple MP4 chunks while the daemon stays alive, and daemon-restart recovery uses only manifest-owned chunks. Android screenrecord encodes a frame only when the screen changes, so a clip can end at the last frame the recorder encoded instead of at record stop; durationMs is host wall clock from record start until the export finished, and capturedDurationMs reports the video timeline when it can be measured, with a warning naming how much of the window that video covers. An Android manifest left by an unreachable recording is retired on the next start once its recorders are proven gone; one still owned refuses with non-retriable DEVICE_IN_USE and reason native_recovery_evidence_open naming the session to run record stop for, and a recorder that is still writing an artifact refuses with DEVICE_IN_USE and reason native_recording_artifact_claimed, which clears itself once that recorder ends at the 180s limit. HarmonyOS supports whole-screen recording on physical devices only: use --scope device/system; --fps, --quality, and --hide-touches are unsupported. Use --quality to choose medium or high export quality on supported backends. An iOS simulator host recording lock returns non-retriable DEVICE_IN_USE with reason apple_simulator_recording_busy. Stop the recording in its owning session; if a dead recorder left the host locked, ask the host operator to restart the CoreSimulator stream service. A record stop that cannot produce its export keeps what a retry reads back — on Android the device-side artifact and the native manifest — leaves the recording manifest of that session open, and returns its own error, so retry record stop in that session; only closing the session disposes them. Every stopped recording also reports what became of its recorder and of the file that recorder writes to: recorder is confirmed, or lost when the session holding it died, and nativePathDisposition is retirable while that file still owes a removal or retired once its removal was verified. Both are optional disclosures, not failures; ADR 0024 declares further states (unconfirmed, pending) for the steps that gain those probes, and no stop reports them yet. record contact-sheet <video.mp4> [--out <sheet.png>] is a local report over a file you already exported: it decodes frames out of that MP4 and writes one PNG holding the cells where the screen visibly changed, each labeled with its elapsed time on the clip timeline. It needs no session and no device, rebuilds any past recording, and works for every backend that exports MP4; a WebM recording is refused with reason contact_sheet_container_unsupported. The sample grid is bounded and spread across the whole clip, so it reports coverage rather than a review: a flash that opens and closes entirely between two sample times is not in the sheet, which is why the result also reports how many times it sampled and how many frames came back. Frame decoding is Apple AVFoundation tooling, so the command runs only on macOS hosts and refuses elsewhere with reason contact_sheet_unsupported_host.',
+      'The default --scope app requires an active app session from open <app>; use --scope device/system to explicitly request whole-screen recording where the selected backend supports it. Android record start publishes a durable device manifest, recordings longer than the 180s adb screenrecord limit are returned as multiple MP4 chunks while the daemon stays alive, and daemon-restart recovery uses only manifest-owned chunks. Android screenrecord encodes a frame only when the screen changes, so a clip can end at the last frame the recorder encoded instead of at record stop; durationMs is host wall clock from record start until the export finished, and capturedDurationMs reports the video timeline when it can be measured, with a warning naming how much of the window that video covers. An Android manifest left by an unreachable recording is retired on the next start once its recorders are proven gone; one still owned refuses with non-retriable DEVICE_IN_USE and reason native_recovery_evidence_open naming the session to run record stop for, and a recorder that is still writing an artifact refuses with DEVICE_IN_USE and reason native_recording_artifact_claimed, which clears itself once that recorder ends at the 180s limit. HarmonyOS supports whole-screen recording on physical devices only: use --scope device/system; --fps, --quality, and --hide-touches are unsupported. Use --quality to choose medium or high export quality on supported backends. The touch overlay renders at most 30 frames a second, or at --fps when lower; a lower --fps makes record stop faster on a long recording, and an overlay export that runs past its budget returns the raw video with an overlayWarning. An iOS simulator host recording lock returns non-retriable DEVICE_IN_USE with reason apple_simulator_recording_busy. Stop the recording in its owning session; if a dead recorder left the host locked, ask the host operator to restart the CoreSimulator stream service. A record stop that cannot produce its export keeps what a retry reads back — on Android the device-side artifact and the native manifest — leaves the recording manifest of that session open, and returns its own error, so retry record stop in that session; only closing the session disposes them. Every stopped recording also reports what became of its recorder and of the file that recorder writes to: recorder is confirmed, or lost when the session holding it died, and nativePathDisposition is retirable while that file still owes a removal or retired once its removal was verified. Both are optional disclosures, not failures; ADR 0024 declares further states (unconfirmed, pending) for the steps that gain those probes, and no stop reports them yet. record contact-sheet <video.mp4> [--out <sheet.png>] is a local report over a file you already exported: it decodes frames out of that MP4 and writes one PNG holding the cells where the screen visibly changed, each labeled with its elapsed time on the clip timeline. It needs no session and no device, rebuilds any past recording, and works for every backend that exports MP4; a WebM recording is refused with reason contact_sheet_container_unsupported. The sample grid is bounded and spread across the whole clip, so it reports coverage rather than a review: a flash that opens and closes entirely between two sample times is not in the sheet, which is why the result also reports how many times it sampled and how many frames came back. Frame decoding is Apple AVFoundation tooling, so the command runs only on macOS hosts and refuses elsewhere with reason contact_sheet_unsupported_host.',
   },
   metadata: recordCommandMetadata,
   run: (client, input) => client.recording.record(input as RecordOptions),
diff --git a/src/platform-runtime-screen-recording-finalizer-host.test.ts b/src/platform-runtime-screen-recording-finalizer-host.test.ts
index 44a9f12573..2082e5f023 100644
--- a/src/platform-runtime-screen-recording-finalizer-host.test.ts
+++ b/src/platform-runtime-screen-recording-finalizer-host.test.ts
@@ -80,6 +80,18 @@ test('burns touches into a playable recording without a warning', async () => {
   expect(result).toEqual({ telemetryPath: '/tmp/capture.telemetry.json' });
 });
 
+test('hands the caller fps to the touch overlay', async () => {
+  await createScreenRecordingFinalizer().complete({
+    outputPath: '/tmp/capture.mp4',
+    showTouches: true,
+    gestureEvents: [{ kind: 'tap', tMs: 500, x: 10, y: 20 }],
+    fps: 15,
+    targetLabel: 'test recording',
+  });
+
+  expect(overlay).toHaveBeenCalledWith(expect.objectContaining({ fps: 15 }));
+});
+
 test('#2707 reports a dropped overlay and keeps the raw when compositing throws', async () => {
   // overlay.ts verifies the composite and only renames it over the raw on success, so a compositor
   // that fails its own #2707 checks throws before any rename: the raw file survives and the caller
diff --git a/src/platform-runtime-screen-recording-finalizer-host.ts b/src/platform-runtime-screen-recording-finalizer-host.ts
index 00a4afba74..746887cf4a 100644
--- a/src/platform-runtime-screen-recording-finalizer-host.ts
+++ b/src/platform-runtime-screen-recording-finalizer-host.ts
@@ -45,6 +45,7 @@ async function overlayTouches(
       videoPath: input.outputPath,
       telemetryPath,
       exportQuality: input.exportQuality,
+      ...(input.fps === undefined ? {} : { fps: input.fps }),
       targetLabel: input.targetLabel,
     });
     if (!(await isPlayableVideo(input.outputPath))) {
diff --git a/website/docs/docs/commands.md b/website/docs/docs/commands.md
index 0c8b66c295..7adef8c7f7 100644
--- a/website/docs/docs/commands.md
+++ b/website/docs/docs/commands.md
@@ -1083,7 +1083,7 @@ agent-device diff screenshot --baseline baseline.png --out diff.png --overlay-re
 agent-device record start               # Start app-scoped recording after open <app>
 agent-device record start session.mp4   # Start app-scoped recording to explicit path
 agent-device record start session.mp4 --scope device  # Intentionally record the full simulator/device screen
-agent-device record start session.mp4 --fps 30  # Override iOS device runner FPS
+agent-device record start session.mp4 --fps 15  # Runner capture rate and touch-overlay frame cap
 agent-device record start session.mp4 --quality high # Higher-quality export (slower)
 agent-device record stop                # Stop active recording
 ```
@@ -1104,6 +1104,7 @@ agent-device record stop                # Stop active recording
 - In `--json` mode, each overlay ref also includes a screenshot-space `center` point for coordinate fallback like `press <x> <y>`.
 - Burned-in touch overlays are exported only on macOS hosts, because the overlay pipeline depends on Swift + AVFoundation helpers.
 - On Linux or other non-macOS hosts, `record stop` still succeeds and returns the raw video plus telemetry sidecar, and includes `overlayWarning` when burn-in overlays were skipped.
+- The touch overlay renders at most 30 frames a second, or at `--fps` when it is lower, so a lower `--fps` makes a long recording's `record stop` faster. The overlay has a fixed budget inside the `record stop` request; an export that runs past it returns the raw video and telemetry with an `overlayWarning` naming the budget.
 - On iOS simulators, a busy CoreSimulator host recording slot makes `record start` return non-retriable `DEVICE_IN_USE` with `details.reason: apple_simulator_recording_busy`. Use `record stop` in the session that owns the active recording. If a previous recorder died and no recording is active, ask the host operator to restart the CoreSimulator stream service before retrying.
 - When the Apple runner records (`--fps` sets its frame rate), it captures a frame only while no command is using the runner's main thread; a frame that falls during that work is skipped instead of queued behind it. A capture slower than the frame interval lowers the frame rate, and a capture still running after one second is dropped. A busy app or a long command can therefore yield fewer frames than `--fps` requests.
 - Android uses `adb shell screenrecord`, which has a 180s platform limit. `record start` publishes a durable device manifest. Longer recordings are split into MP4 chunks while the daemon stays alive; after daemon restart, `record stop` recovers only manifest-owned chunks and warns when gesture overlay telemetry was lost.

From b08d6b90e3d973f5dbca74ee0734fe01398c8251 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= <thymikee@gmail.com>
Date: Mon, 5 Oct 2026 21:21:18 +0200
Subject: [PATCH 2/4] fix(recording): name the overlay budget only when the
 export itself ran out of it

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
---
 .../src/recording/__tests__/overlay.test.ts   | 39 ++++++++++++++++++-
 packages/capture-kit/src/recording/overlay.ts | 39 +++++++++++--------
 .../contracts/src/screen-recording-runtime.ts |  5 ++-
 .../src/recording/completion.test.ts          | 26 +++++++++++++
 website/docs/docs/commands.md                 |  2 +-
 5 files changed, 91 insertions(+), 20 deletions(-)

diff --git a/packages/capture-kit/src/recording/__tests__/overlay.test.ts b/packages/capture-kit/src/recording/__tests__/overlay.test.ts
index 4fcd8455c0..0426365fb2 100644
--- a/packages/capture-kit/src/recording/__tests__/overlay.test.ts
+++ b/packages/capture-kit/src/recording/__tests__/overlay.test.ts
@@ -183,8 +183,45 @@ test('overlay leaves the video as recorded when compiling the helper spent its b
 
   await expect(overlayRecordingTouches({ videoPath, telemetryPath })).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`,
+    message: 'Failed to add touch overlays to the recording',
   });
   expect(mockRunCmd.mock.calls.filter(([cmd]) => cmd !== 'xcrun')).toHaveLength(0);
   expect(fs.readFileSync(videoPath, 'utf8')).toBe('original');
 });
+
+test('overlay names its budget when the export ran out of it', async () => {
+  vi.useFakeTimers({ toFake: ['Date'] });
+  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({ videoPath, telemetryPath });
+  fs.writeFileSync(videoPath, 'original');
+  mockRunCmd.mockImplementationOnce(async () => {
+    vi.setSystemTime(Date.now() + OVERLAY_BUDGET_MS);
+    throw new AppError('COMMAND_FAILED', 'recording-overlay exited with code 1');
+  });
+
+  await expect(overlayRecordingTouches({ videoPath, telemetryPath })).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(fs.readFileSync(videoPath, 'utf8')).toBe('original');
+});
+
+test('overlay keeps the plain failure when the export failed with budget to spare', async () => {
+  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({ videoPath, telemetryPath });
+  mockRunCmd.mockImplementationOnce(async () => {
+    throw new AppError('COMMAND_FAILED', 'recording-overlay exited with code 1');
+  });
+
+  await expect(overlayRecordingTouches({ videoPath, telemetryPath })).rejects.toMatchObject({
+    message: 'Failed to add touch overlays to the recording',
+  });
+});
diff --git a/packages/capture-kit/src/recording/overlay.ts b/packages/capture-kit/src/recording/overlay.ts
index 59c0004eb1..79806b53b9 100644
--- a/packages/capture-kit/src/recording/overlay.ts
+++ b/packages/capture-kit/src/recording/overlay.ts
@@ -67,6 +67,7 @@ async function exportProcessedVideo(params: {
   await waitForPlayableVideo(videoPath);
 
   const outputPath = temporarySiblingVideoPath(videoPath);
+  let exportOverran = false;
   try {
     const executablePath = await compileSwiftSourceFile({
       sourcePath: scriptPath,
@@ -82,26 +83,30 @@ async function exportProcessedVideo(params: {
         `No time was left for the export within the ${params.budgetMs}ms budget`,
       );
     }
-    await runCmd(
-      executablePath,
-      [
-        '--input',
-        videoPath,
-        '--output',
-        outputPath,
-        ...scriptArgs,
-        '--timeout-ms',
-        String(Math.round(exportMs)),
-      ],
-      { timeoutMs: helperMs, env: buildSwiftToolEnv() },
-    );
+    try {
+      await runCmd(
+        executablePath,
+        [
+          '--input',
+          videoPath,
+          '--output',
+          outputPath,
+          ...scriptArgs,
+          '--timeout-ms',
+          String(Math.round(exportMs)),
+        ],
+        { timeoutMs: helperMs, env: buildSwiftToolEnv() },
+      );
+    } catch (error) {
+      exportOverran = deadline.remainingMs() <= HELPER_EXIT_GRACE_MS;
+      throw error;
+    }
     await waitForPlayableVideo(outputPath);
     fs.renameSync(outputPath, videoPath);
   } catch (error) {
-    const description =
-      deadline.remainingMs() <= HELPER_EXIT_GRACE_MS
-        ? `${commandDescription}: the export did not finish within its ${params.budgetMs}ms budget; a lower --fps renders faster`
-        : commandDescription;
+    const description = exportOverran
+      ? `${commandDescription}: the export did not finish within its ${params.budgetMs}ms budget; a lower --fps renders faster`
+      : commandDescription;
     const cause =
       error instanceof AppError
         ? error
diff --git a/packages/contracts/src/screen-recording-runtime.ts b/packages/contracts/src/screen-recording-runtime.ts
index 66e0977bbd..b76582d062 100644
--- a/packages/contracts/src/screen-recording-runtime.ts
+++ b/packages/contracts/src/screen-recording-runtime.ts
@@ -72,7 +72,10 @@ export type ScreenRecordingLiveSnapshot = Readonly<{
   recordOnlySession: boolean;
   activeSessionApp?: RecordingAppIdentity;
   exportQuality?: RecordingExportQuality;
-  /** The caller's `--fps`: the capture rate where the recorder takes one, and the overlay's cap. */
+  /**
+   * The caller's `--fps`: the capture rate where the recorder takes one. The touch overlay renders
+   * at most this many frames a second, and never more than 30.
+   */
   fps?: number;
   gestureEvents: readonly RecordingGestureEvent[];
   touchReferenceFrame?: GestureReferenceFrame;
diff --git a/packages/platform-apple/src/recording/completion.test.ts b/packages/platform-apple/src/recording/completion.test.ts
index e99f8ce2f9..2e7dab7ec6 100644
--- a/packages/platform-apple/src/recording/completion.test.ts
+++ b/packages/platform-apple/src/recording/completion.test.ts
@@ -54,3 +54,29 @@ test('hands the caller fps to the finalizer that burns the touch overlay', async
 
   expect(requests).toEqual([expect.objectContaining({ showTouches: true, fps: 15 })]);
 });
+
+test('hands the finalizer no fps when the caller asked for none', async () => {
+  const requests: Readonly<{ fps?: number }>[] = [];
+  await completeAppleRecording({
+    host: appleRecordingHost({
+      complete: async (input) => {
+        requests.push(input);
+        return {};
+      },
+    }),
+    snapshot: {
+      backend: 'simctl',
+      outPath: '/tmp/capture.mp4',
+      startedAt: 1,
+      scope: 'app',
+      showTouches: true,
+      recordOnlySession: false,
+      gestureEvents: [],
+    },
+    targetLabel: 'iOS recording',
+    stopObservation: { recorder: 'confirmed' },
+  });
+
+  expect(requests).toHaveLength(1);
+  expect(requests[0]).not.toHaveProperty('fps');
+});
diff --git a/website/docs/docs/commands.md b/website/docs/docs/commands.md
index 7adef8c7f7..028c1d803f 100644
--- a/website/docs/docs/commands.md
+++ b/website/docs/docs/commands.md
@@ -1110,7 +1110,7 @@ agent-device record stop                # Stop active recording
 - Android uses `adb shell screenrecord`, which has a 180s platform limit. `record start` publishes a durable device manifest. Longer recordings are split into MP4 chunks while the daemon stays alive; after daemon restart, `record stop` recovers only manifest-owned chunks and warns when gesture overlay telemetry was lost.
 - Android `screenrecord` encodes a frame only when the screen changes, so a clip ends at the last frame the recorder encoded instead of at `record stop`: a window that ends on an unchanged screen yields a shorter video, while every on-screen change inside the window stays at its real offset in it. `record stop` reports `durationMs` as host wall clock from `record start` until the export finished, and when the video can be measured it also reports `capturedDurationMs` and warns with how much of the window that video covers.
 - Limrun iOS and Android direct sessions record the whole simulator or emulator screen through the provider's server-side recorder, so every `--scope` captures the same frame and `--fps` and `--hide-touches` are refused with `INVALID_ARGS` before any device work. `record stop` asks the instance to stop once and then downloads the served MP4 to the output path; that download is bounded to end inside the request window, so a slow or dropped transfer ends typed, leaves no file behind, and is retried by the next `record stop` from the same URL while the instance lives. Nothing survives a daemon restart: the recording is `unreattachable` and the instance disposes the file when the lease is released.
-- `record stop` is safe to repeat. When its request window ends while the daemon is still exporting — typical for a long touch-overlay burn-in, on a local or remote daemon — the export keeps running there, and a second `record stop` in the same session returns that completed recording, including the caller-side output path, without starting another recording. A finished recording whose video file is already gone reports `no active recording`.
+- `record stop` is safe to repeat. When its request window ends while the daemon is still exporting, on a local or remote daemon, the export keeps running there, and a second `record stop` in the same session returns that completed recording, including the caller-side output path, without starting another recording. A finished recording whose video file is already gone reports `no active recording`.
 - A recording answers two independent questions, and `record stop` reports both: whether a playable export exists, and whether the recorder stopped. `recorder` is `confirmed` when the recorder exited or acknowledged a stop meant for this recording, and `lost` when the session holding it died — an Apple recording invalidated by a runner restart. `nativePathDisposition` says what became of the artifact path the recorder itself writes to: `retirable` while that file still sits there owed a removal, and `retired` once its removal was verified. Both are optional disclosures — the export is served either way, a replay of a recording stopped before they existed omits them, and so does a backend whose recorder writes the served file itself. The vocabulary is deliberately wider than today's answers: `recorder: unconfirmed` (a probe that could not be read, or no exit inside the stop budget), the identity-mismatch reasons under `lost`, and `nativePathDisposition: pending` are declared by [ADR 0024](https://github.com/callstack/agent-device/blob/main/docs/adr/0024-screen-recording-provable-signal.md) for the steps that gain those probes, and no stop reports them yet.
 
 - `record contact-sheet <video.mp4> [--out <sheet.png>]` turns a recording you already exported into one PNG: the frames where the screen visibly changed, laid out in a grid and each labeled with its elapsed time (`HH:MM:SS.mmm`) on the clip timeline. It is how an agent reads a recording it cannot play. It reads the file you pass — no session, no device, no daemon — so it can rebuild an old take and the sheet can only describe screens that export contains. Any backend that exports MP4 works (Apple, Android, HarmonyOS, Limrun); a WebM recording from the web backend is refused with `details.reason: contact_sheet_container_unsupported`. The default output is `<recording>.contact-sheet.png`, and `--out` is refused when it points back at the recording itself, because a sheet is derived from a take and never replaces it. `--json` reports each cell's time and changed-pixel share alongside `sampledFrameCount`, `decodedFrameCount`, and `skippedSampleCount`.

From 43e7b74fb87970b93a18a7ad12b51b656b7a086f Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= <thymikee@gmail.com>
Date: Tue, 6 Oct 2026 07:44:25 +0200
Subject: [PATCH 3/4] test(recording): pin the caller fps through the Apple
 simulator finalize path

Cover the simulator start snapshot and finalizeAppleRecordingFromCollected, the
route simctl recordings take, and name the touch-overlay cap in --fps help.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
---
 .../src/flag-definitions-action.ts            |  3 +-
 .../src/recording/completion.test.ts          | 38 ++++++++++++++++++-
 .../src/recording/runtime.test.ts             | 35 +++++++++++++++++
 3 files changed, 74 insertions(+), 2 deletions(-)

diff --git a/packages/command-registry/src/flag-definitions-action.ts b/packages/command-registry/src/flag-definitions-action.ts
index cd697ca8c3..fde3a89da0 100644
--- a/packages/command-registry/src/flag-definitions-action.ts
+++ b/packages/command-registry/src/flag-definitions-action.ts
@@ -42,7 +42,8 @@ export const ACTION_FLAG_DEFINITIONS: readonly FlagDefinition[] = [
     min: 1,
     max: 120,
     usageLabel: '--fps <n>',
-    usageDescription: 'Record: target frames per second (iOS physical device runner)',
+    usageDescription:
+      'Record: target frames per second (iOS physical device runner) and touch-overlay frame cap',
     projectConfig: true,
     recorded: true,
   },
diff --git a/packages/platform-apple/src/recording/completion.test.ts b/packages/platform-apple/src/recording/completion.test.ts
index 2e7dab7ec6..8bff58aa8e 100644
--- a/packages/platform-apple/src/recording/completion.test.ts
+++ b/packages/platform-apple/src/recording/completion.test.ts
@@ -1,5 +1,6 @@
 import { expect, test } from 'vitest';
-import { completeAppleRecording } from './completion.ts';
+import { completeAppleRecording, finalizeAppleRecordingFromCollected } from './completion.ts';
+import { recordingFileStore } from '@agent-device/capture-kit/recording-artifact-fixtures';
 import { appleRecordingHost } from './runtime.fixtures.ts';
 
 test('projects invalidated touch-overlay state without publishing a false overlay', async () => {
@@ -80,3 +81,38 @@ test('hands the finalizer no fps when the caller asked for none', async () => {
   expect(requests).toHaveLength(1);
   expect(requests[0]).not.toHaveProperty('fps');
 });
+
+test('a collected simulator copy hands the caller fps to the finalizer, and none when unset', async () => {
+  for (const fps of [10, undefined]) {
+    const requests: Readonly<{ fps?: number }>[] = [];
+    const files = recordingFileStore();
+    files.files.set('/tmp/capture.collected.mp4', 'fake-video');
+    await finalizeAppleRecordingFromCollected({
+      host: appleRecordingHost({
+        files,
+        complete: async (input) => {
+          requests.push(input);
+          return {};
+        },
+      }),
+      snapshot: {
+        backend: 'simctl',
+        outPath: '/tmp/capture.mp4',
+        startedAt: 1,
+        scope: 'app',
+        showTouches: true,
+        recordOnlySession: false,
+        ...(fps === undefined ? {} : { fps }),
+        gestureEvents: [],
+      },
+      targetLabel: 'iOS recording',
+      collectedPath: '/tmp/capture.collected.mp4',
+      exportPath: '/tmp/capture.mp4',
+      nativePath: '/tmp/capture.native.mp4',
+    });
+
+    expect(requests).toHaveLength(1);
+    if (fps === undefined) expect(requests[0]).not.toHaveProperty('fps');
+    else expect(requests[0]).toMatchObject({ showTouches: true, fps });
+  }
+});
diff --git a/packages/platform-apple/src/recording/runtime.test.ts b/packages/platform-apple/src/recording/runtime.test.ts
index f814c82cb0..4f03744a3a 100644
--- a/packages/platform-apple/src/recording/runtime.test.ts
+++ b/packages/platform-apple/src/recording/runtime.test.ts
@@ -262,6 +262,41 @@ test('a simulator stop exports from a copy and retires the file the recorder own
   expect(files.exists(collectedPath)).toBe(false);
 });
 
+test('a simulator recording carries the caller fps from start to the finalizer', async () => {
+  for (const fps of [15, undefined]) {
+    const requests: Readonly<{ fps?: number }>[] = [];
+    const operations = createAppleScreenRecordingOperations({
+      host: appleHost({
+        apple: {
+          startSimulator: async () => ({
+            markers: [processIdentity],
+            wait: Promise.resolve({ stdout: '', stderr: '', exitCode: 0 }),
+            terminate: async () => {},
+          }),
+        },
+        complete: async (request) => {
+          requests.push(request);
+          return {};
+        },
+      }),
+      device: simulator,
+      owner: localRuntimeOwner('apple'),
+      signal: new AbortController().signal,
+    });
+
+    const started = await operations.screenRecordingStart(
+      input({ showTouches: true, ...(fps === undefined ? {} : { fps }) }),
+    );
+    const handle = started.pendingHandle.transfer();
+    expect(handle.inspect().fps).toBe(fps);
+    expect((await handle.finish()).status).toBe('completed');
+
+    expect(requests).toHaveLength(1);
+    if (fps === undefined) expect(requests[0]).not.toHaveProperty('fps');
+    else expect(requests[0]).toMatchObject({ fps });
+  }
+});
+
 test('a simulator export the finalizer refuses leaves the caller path empty and the copy for the retry', async () => {
   const exportPath = recordingOutputPath('refused.mp4');
   const nativePath = exportPath.replace(/\.mp4$/, '.native.mp4');

From 89b7f957ccae22f5438d868321eba0b1991c67ca Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= <thymikee@gmail.com>
Date: Tue, 6 Oct 2026 07:52:56 +0200
Subject: [PATCH 4/4] docs(recording): say --fps lowers the touch-overlay rate
 under its 30 fps ceiling

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
---
 packages/command-registry/src/flag-definitions-action.ts | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/packages/command-registry/src/flag-definitions-action.ts b/packages/command-registry/src/flag-definitions-action.ts
index fde3a89da0..9578e7719b 100644
--- a/packages/command-registry/src/flag-definitions-action.ts
+++ b/packages/command-registry/src/flag-definitions-action.ts
@@ -43,7 +43,7 @@ export const ACTION_FLAG_DEFINITIONS: readonly FlagDefinition[] = [
     max: 120,
     usageLabel: '--fps <n>',
     usageDescription:
-      'Record: target frames per second (iOS physical device runner) and touch-overlay frame cap',
+      'Record: target frames per second (iOS physical device runner); also lowers the touch-overlay rate, which never exceeds 30',
     projectConfig: true,
     recorded: true,
   },