From bed5866de3e0fdeeff2df196ea7379092e236b89 Mon Sep 17 00:00:00 2001
From: ryanda9910 <ryandaaldo@gmail.com>
Date: Fri, 19 Jun 2026 13:01:14 +0700
Subject: [PATCH 1/2] feat(recording): make iOS export quality configurable

Wire the existing recording-export-quality enum through the record command
down to the Swift export preset. Adds a `--export-quality <medium|high>`
option for iOS recordings that controls the AVAssetExportSession preset used
when a recording is re-encoded.

`medium` stays the default and selects AVAssetExportPresetMediumQuality, which
preserves the fast simulator-friendly export. `high` opts into
AVAssetExportPresetHighestQuality for evidence-grade output. This is separate
from the existing integer `--quality <5-10>` capture flag that scales render
resolution.

Closes #568
---
 .../RecordingScripts/recording-resize.swift   | 45 ++++++++++-
 src/client-normalizers.ts                     |  1 +
 src/client-types.ts                           |  3 +
 src/commands/recording/index.test.ts          | 16 ++++
 src/commands/recording/index.ts               |  9 ++-
 .../recording-export-quality.test.ts          | 33 ++++++++
 src/core/recording-export-quality.ts          | 23 ++++++
 .../handlers/__tests__/record-trace.test.ts   | 75 ++++++++++++++++++-
 src/daemon/handlers/record-trace-recording.ts | 16 ++++
 src/daemon/handlers/record-trace-types.ts     |  2 +
 src/daemon/types.ts                           |  2 +
 src/recording/__tests__/overlay.test.ts       | 29 ++++++-
 src/recording/overlay.ts                      | 14 +++-
 src/utils/__tests__/args.test.ts              |  3 +-
 src/utils/cli-flags.ts                        | 14 ++++
 website/docs/docs/commands.md                 |  2 +
 16 files changed, 275 insertions(+), 12 deletions(-)
 create mode 100644 src/core/__tests__/recording-export-quality.test.ts
 create mode 100644 src/core/recording-export-quality.ts

diff --git a/ios-runner/AgentDeviceRunner/RecordingScripts/recording-resize.swift b/ios-runner/AgentDeviceRunner/RecordingScripts/recording-resize.swift
index de489539d..a4a748255 100644
--- a/ios-runner/AgentDeviceRunner/RecordingScripts/recording-resize.swift
+++ b/ios-runner/AgentDeviceRunner/RecordingScripts/recording-resize.swift
@@ -74,7 +74,8 @@ func run() throws {
   instruction.layerInstructions = [layerInstruction]
   videoComposition.instructions = [instruction]
 
-  guard let exporter = AVAssetExportSession(asset: composition, presetName: AVAssetExportPresetHighestQuality) else {
+  let presetName = exportPresetName(for: parsedArgs.exportQuality, compatibleWith: composition)
+  guard let exporter = AVAssetExportSession(asset: composition, presetName: presetName) else {
     throw ResizeError.exportFailed("Failed to create export session.")
   }
 
@@ -97,10 +98,20 @@ func run() throws {
   }
 }
 
-func parseArguments(_ arguments: [String]) throws -> (inputPath: String, outputPath: String, quality: Int) {
+enum ExportQuality: String {
+  case medium
+  case high
+}
+
+func parseArguments(
+  _ arguments: [String]
+) throws -> (inputPath: String, outputPath: String, quality: Int, exportQuality: ExportQuality) {
   var inputPath: String?
   var outputPath: String?
   var quality: Int?
+  // Export quality defaults to medium so existing callers keep the fast, simulator-friendly
+  // export. Pass --export-quality high to opt into a slower highest-quality export.
+  var exportQuality: ExportQuality = .medium
   var index = 0
 
   while index < arguments.count {
@@ -122,6 +133,15 @@ func parseArguments(_ arguments: [String]) throws -> (inputPath: String, outputP
       }
       quality = parsed
       index += 2
+    case "--export-quality":
+      guard nextIndex < arguments.count else {
+        throw ResizeError.invalidArgs("--export-quality requires a value")
+      }
+      guard let parsed = ExportQuality(rawValue: arguments[nextIndex]) else {
+        throw ResizeError.invalidArgs("--export-quality must be one of: medium, high")
+      }
+      exportQuality = parsed
+      index += 2
     default:
       throw ResizeError.invalidArgs("Unknown argument: \(argument)")
     }
@@ -129,10 +149,27 @@ func parseArguments(_ arguments: [String]) throws -> (inputPath: String, outputP
 
   guard let inputPath, let outputPath, let quality else {
     throw ResizeError.invalidArgs(
-      "Usage: recording-resize.swift --input <video> --output <video> --quality <5-10>"
+      "Usage: recording-resize.swift --input <video> --output <video> --quality <5-10> [--export-quality <medium|high>]"
     )
   }
-  return (inputPath, outputPath, quality)
+  return (inputPath, outputPath, quality, exportQuality)
+}
+
+func exportPresetName(
+  for exportQuality: ExportQuality,
+  compatibleWith asset: AVAsset
+) -> String {
+  switch exportQuality {
+  case .high:
+    return AVAssetExportPresetHighestQuality
+  case .medium:
+    // Mirror the touch-overlay export: prefer the faster medium preset, falling back to
+    // highest quality only when medium is not available for this composition.
+    let compatible = AVAssetExportSession.exportPresets(compatibleWith: asset)
+    return compatible.contains(AVAssetExportPresetMediumQuality)
+      ? AVAssetExportPresetMediumQuality
+      : AVAssetExportPresetHighestQuality
+  }
 }
 
 func resolvedRenderSize(for track: AVAssetTrack) -> CGSize {
diff --git a/src/client-normalizers.ts b/src/client-normalizers.ts
index 7310b5c42..aed8b5764 100644
--- a/src/client-normalizers.ts
+++ b/src/client-normalizers.ts
@@ -304,6 +304,7 @@ export function buildFlags(options: InternalRequestOptions): CommandFlags {
     count: options.count,
     fps: options.fps,
     quality: options.quality,
+    exportQuality: options.exportQuality,
     hideTouches: options.hideTouches,
     intervalMs: options.intervalMs,
     delayMs: options.delayMs,
diff --git a/src/client-types.ts b/src/client-types.ts
index 3ec23320d..022e0be65 100644
--- a/src/client-types.ts
+++ b/src/client-types.ts
@@ -16,6 +16,7 @@ import type {
 import type { DeviceKind, DeviceTarget, Platform, PlatformSelector } from './utils/device.ts';
 import type { BackMode } from './core/back-mode.ts';
 import type { ClickButton } from './core/click-button.ts';
+import type { RecordingExportQuality } from './core/recording-export-quality.ts';
 import type { DeviceRotation } from './core/device-rotation.ts';
 import type {
   ScrollDirection,
@@ -775,6 +776,7 @@ export type RecordOptions = AgentDeviceRequestOverrides & {
   path?: string;
   fps?: number;
   quality?: RecordingQuality;
+  exportQuality?: RecordingExportQuality;
   hideTouches?: boolean;
 };
 
@@ -855,6 +857,7 @@ type CommandExecutionOptions = Partial<ScreenshotRequestFlags> & {
   count?: number;
   fps?: number;
   quality?: RecordingQuality;
+  exportQuality?: RecordingExportQuality;
   hideTouches?: boolean;
   intervalMs?: number;
   delayMs?: number;
diff --git a/src/commands/recording/index.test.ts b/src/commands/recording/index.test.ts
index 8b7f39dba..04e19cdde 100644
--- a/src/commands/recording/index.test.ts
+++ b/src/commands/recording/index.test.ts
@@ -46,6 +46,22 @@ describe('recording command interface', () => {
     });
   });
 
+  test('reads the export-quality flag into record input', () => {
+    expect(
+      recordCliReader(['start', './capture.mp4'], {
+        exportQuality: 'high',
+      } as CliFlags),
+    ).toMatchObject({
+      action: 'start',
+      path: './capture.mp4',
+      exportQuality: 'high',
+    });
+  });
+
+  test('leaves export quality unset when the flag is omitted', () => {
+    expect(recordCliReader(['start'], NO_FLAGS).exportQuality).toBeUndefined();
+  });
+
   test('reads trace CLI input', () => {
     expect(traceCliReader(['stop', './diagnostics.trace'], NO_FLAGS)).toEqual({
       action: 'stop',
diff --git a/src/commands/recording/index.ts b/src/commands/recording/index.ts
index 538c264d0..f15385286 100644
--- a/src/commands/recording/index.ts
+++ b/src/commands/recording/index.ts
@@ -1,4 +1,5 @@
 import type { RecordOptions } from '../../client-types.ts';
+import { RECORDING_EXPORT_QUALITIES } from '../../core/recording-export-quality.ts';
 import { AppError } from '../../utils/errors.ts';
 import type { CommandSchemaOverride } from '../../utils/cli-command-schema-types.ts';
 import { defineExecutableCommand } from '../command-contract.ts';
@@ -30,6 +31,7 @@ export const recordCommandMetadata = defineFieldCommandMetadata(
     path: stringField(),
     fps: integerField(),
     quality: jsonSchemaField<RecordOptions['quality']>(integerSchema()),
+    exportQuality: enumField(RECORDING_EXPORT_QUALITIES),
     hideTouches: booleanField(),
   },
 );
@@ -62,13 +64,13 @@ export const recordingCommandDefinitions = [
 
 const recordCliSchema = {
   usageOverride:
-    'record start [path] [--fps <n>] [--quality <5-10>] [--hide-touches] | record stop',
+    'record start [path] [--fps <n>] [--quality <5-10>] [--export-quality <medium|high>] [--hide-touches] | record stop',
   listUsageOverride: 'record start [path] | record stop',
   helpDescription:
-    'Start/stop screen recording; Android recordings longer than the 180s adb screenrecord limit are returned as multiple MP4 chunks',
+    'Start/stop screen recording; Android recordings longer than the 180s adb screenrecord limit are returned as multiple MP4 chunks. On iOS, --export-quality trades export speed (medium, default) for higher-quality output (high)',
   summary: 'Start or stop screen recording',
   positionalArgs: ['start|stop', 'path?'],
-  allowedFlags: ['fps', 'quality', 'hideTouches'],
+  allowedFlags: ['fps', 'quality', 'exportQuality', 'hideTouches'],
 } as const satisfies CommandSchemaOverride;
 
 const traceCliSchema = {
@@ -91,6 +93,7 @@ export const recordCliReader: CliReader = (positionals, flags) => ({
   path: positionals[1],
   fps: flags.fps,
   quality: flags.quality as RecordOptions['quality'],
+  exportQuality: flags.exportQuality,
   hideTouches: flags.hideTouches,
 });
 
diff --git a/src/core/__tests__/recording-export-quality.test.ts b/src/core/__tests__/recording-export-quality.test.ts
new file mode 100644
index 000000000..4124ebb05
--- /dev/null
+++ b/src/core/__tests__/recording-export-quality.test.ts
@@ -0,0 +1,33 @@
+import { describe, expect, test } from 'vitest';
+import {
+  DEFAULT_RECORDING_EXPORT_QUALITY,
+  RECORDING_EXPORT_QUALITIES,
+  isRecordingExportQuality,
+  recordingExportQualityToPreset,
+} from '../recording-export-quality.ts';
+
+describe('recording export quality', () => {
+  test('defaults to the fast medium export to preserve existing behavior', () => {
+    expect(DEFAULT_RECORDING_EXPORT_QUALITY).toBe('medium');
+    expect(RECORDING_EXPORT_QUALITIES).toEqual(['medium', 'high']);
+  });
+
+  test('maps each quality to its AVAssetExportPreset constant', () => {
+    expect(recordingExportQualityToPreset('medium')).toBe('AVAssetExportPresetMediumQuality');
+    expect(recordingExportQualityToPreset('high')).toBe('AVAssetExportPresetHighestQuality');
+  });
+
+  test('default quality maps to the medium-quality preset', () => {
+    expect(recordingExportQualityToPreset(DEFAULT_RECORDING_EXPORT_QUALITY)).toBe(
+      'AVAssetExportPresetMediumQuality',
+    );
+  });
+
+  test('guards recognize valid values and reject everything else', () => {
+    expect(isRecordingExportQuality('medium')).toBe(true);
+    expect(isRecordingExportQuality('high')).toBe(true);
+    expect(isRecordingExportQuality('highest')).toBe(false);
+    expect(isRecordingExportQuality(undefined)).toBe(false);
+    expect(isRecordingExportQuality(10)).toBe(false);
+  });
+});
diff --git a/src/core/recording-export-quality.ts b/src/core/recording-export-quality.ts
new file mode 100644
index 000000000..109b23b1d
--- /dev/null
+++ b/src/core/recording-export-quality.ts
@@ -0,0 +1,23 @@
+export const RECORDING_EXPORT_QUALITIES = ['medium', 'high'] as const;
+export type RecordingExportQuality = (typeof RECORDING_EXPORT_QUALITIES)[number];
+
+export const DEFAULT_RECORDING_EXPORT_QUALITY: RecordingExportQuality = 'medium';
+
+/**
+ * Maps an export-quality preset to the matching `AVAssetExportPreset` constant
+ * consumed by `recording-resize.swift`. `medium` keeps the fast, simulator-friendly
+ * export that is the default; `high` opts into the slower highest-quality export for
+ * evidence or artifact-grade recordings.
+ */
+const RECORDING_EXPORT_QUALITY_PRESETS: Record<RecordingExportQuality, string> = {
+  medium: 'AVAssetExportPresetMediumQuality',
+  high: 'AVAssetExportPresetHighestQuality',
+};
+
+export function recordingExportQualityToPreset(quality: RecordingExportQuality): string {
+  return RECORDING_EXPORT_QUALITY_PRESETS[quality];
+}
+
+export function isRecordingExportQuality(value: unknown): value is RecordingExportQuality {
+  return (RECORDING_EXPORT_QUALITIES as readonly unknown[]).includes(value);
+}
diff --git a/src/daemon/handlers/__tests__/record-trace.test.ts b/src/daemon/handlers/__tests__/record-trace.test.ts
index 98ab5e877..d2e8b3cc8 100644
--- a/src/daemon/handlers/__tests__/record-trace.test.ts
+++ b/src/daemon/handlers/__tests__/record-trace.test.ts
@@ -56,6 +56,7 @@ import { handleRecordTraceCommands } from '../record-trace.ts';
 import { deriveRecordingTelemetryPath } from '../../recording-telemetry.ts';
 import { SessionStore } from '../../session-store.ts';
 import type { SessionState } from '../../types.ts';
+import type { RecordingExportQuality } from '../../../core/recording-export-quality.ts';
 import { runIosRunnerCommand } from '../../../platforms/ios/runner-client.ts';
 import {
   getRecordingOverlaySupportWarning,
@@ -159,7 +160,12 @@ async function runRecordCommand(params: {
   positionals: string[];
   logPath?: string;
   cwd?: string;
-  flags?: { fps?: number; quality?: number; hideTouches?: boolean };
+  flags?: {
+    fps?: number;
+    quality?: number;
+    exportQuality?: RecordingExportQuality;
+    hideTouches?: boolean;
+  };
   clientArtifactPaths?: Record<string, string>;
 }) {
   return handleRecordTraceCommands({
@@ -639,10 +645,77 @@ test('record stop resizes iOS simulator recording when quality is explicit', asy
   expect(mockResizeRecording).toHaveBeenCalledWith({
     videoPath: path.resolve('./sim-quality.mp4'),
     quality: 6,
+    exportQuality: 'medium',
+    targetLabel: 'iOS recording',
+  });
+});
+
+test('record stop forwards the requested export quality to the resize step', async () => {
+  const sessionStore = makeSessionStore();
+  const sessionName = 'ios-sim-export-quality';
+  sessionStore.set(
+    sessionName,
+    makeSession(sessionName, {
+      platform: 'ios',
+      id: 'sim-1',
+      name: 'Simulator',
+      kind: 'simulator',
+      booted: true,
+    }),
+  );
+
+  mockRunCmdBackground.mockImplementation(() => ({
+    child: { kill: () => {} } as any,
+    wait: Promise.resolve({ stdout: '', stderr: '', exitCode: 0 }),
+  }));
+
+  await runRecordCommand({
+    sessionStore,
+    sessionName,
+    positionals: ['start', './sim-export-quality.mp4'],
+    flags: { quality: 6, exportQuality: 'high' },
+  });
+
+  const responseStop = await runRecordCommand({
+    sessionStore,
+    sessionName,
+    positionals: ['stop'],
+  });
+
+  expect(responseStop?.ok).toBe(true);
+  expect(mockResizeRecording).toHaveBeenCalledWith({
+    videoPath: path.resolve('./sim-export-quality.mp4'),
+    quality: 6,
+    exportQuality: 'high',
     targetLabel: 'iOS recording',
   });
 });
 
+test('record start rejects an invalid export-quality value', async () => {
+  const sessionStore = makeSessionStore();
+  const sessionName = 'ios-sim-export-quality-invalid';
+  sessionStore.set(
+    sessionName,
+    makeSession(sessionName, {
+      platform: 'ios',
+      id: 'sim-1',
+      name: 'Simulator',
+      kind: 'simulator',
+      booted: true,
+    }),
+  );
+
+  const response = await runRecordCommand({
+    sessionStore,
+    sessionName,
+    positionals: ['start', './sim-export-quality-invalid.mp4'],
+    flags: { exportQuality: 'ultra' as never },
+  });
+
+  expect((response as any).error?.code).toBe('INVALID_ARGS');
+  expect((response as any).error?.message).toMatch(/export-quality must be one of: medium, high/);
+});
+
 test('record stop leaves a short visual tail after iOS simulator gestures', async () => {
   vi.useFakeTimers();
   const sessionStore = makeSessionStore();
diff --git a/src/daemon/handlers/record-trace-recording.ts b/src/daemon/handlers/record-trace-recording.ts
index 52aec14f4..9d01153d6 100644
--- a/src/daemon/handlers/record-trace-recording.ts
+++ b/src/daemon/handlers/record-trace-recording.ts
@@ -16,6 +16,11 @@ import {
   resizeRecording,
   trimRecordingStart,
 } from '../../recording/overlay.ts';
+import {
+  DEFAULT_RECORDING_EXPORT_QUALITY,
+  RECORDING_EXPORT_QUALITIES,
+  isRecordingExportQuality,
+} from '../../core/recording-export-quality.ts';
 import {
   buildRecordStopFailure,
   formatRecordTraceError,
@@ -86,6 +91,9 @@ function buildRecordingBase(req: DaemonRequest, outPath: string): RecordingBase
     clientOutPath: req.meta?.clientArtifactPaths?.outPath,
     startedAt: Date.now(),
     quality: req.flags?.quality,
+    exportQuality: isRecordingExportQuality(req.flags?.exportQuality)
+      ? req.flags.exportQuality
+      : DEFAULT_RECORDING_EXPORT_QUALITY,
     showTouches: req.flags?.hideTouches !== true,
     gestureEvents: [],
   };
@@ -220,6 +228,13 @@ async function startRecording(params: {
       `quality must be an integer between ${RECORDING_MIN_QUALITY} and ${RECORDING_MAX_QUALITY}`,
     );
   }
+  const exportQualityFlag = req.flags?.exportQuality;
+  if (exportQualityFlag !== undefined && !isRecordingExportQuality(exportQualityFlag)) {
+    return errorResponse(
+      'INVALID_ARGS',
+      `export-quality must be one of: ${RECORDING_EXPORT_QUALITIES.join(', ')}`,
+    );
+  }
 
   if (!isCommandSupportedOnDevice('record', device)) {
     return errorResponse('UNSUPPORTED_OPERATION', 'record is not supported on this device');
@@ -382,6 +397,7 @@ async function stopNonRunnerRecording(params: {
           deps.resizeRecording({
             videoPath: recording.outPath,
             quality,
+            exportQuality: recording.exportQuality,
             targetLabel: 'iOS recording',
           }),
         {
diff --git a/src/daemon/handlers/record-trace-types.ts b/src/daemon/handlers/record-trace-types.ts
index d92c160ae..438cd5096 100644
--- a/src/daemon/handlers/record-trace-types.ts
+++ b/src/daemon/handlers/record-trace-types.ts
@@ -8,6 +8,7 @@ import type {
   trimRecordingStart,
 } from '../../recording/overlay.ts';
 import type { RecordingGestureEvent } from '../types.ts';
+import type { RecordingExportQuality } from '../../core/recording-export-quality.ts';
 
 export type RecordTraceDeps = {
   runCmd: typeof runCmd;
@@ -28,6 +29,7 @@ export type RecordingBase = {
   clientOutPath?: string;
   startedAt: number;
   quality?: number;
+  exportQuality?: RecordingExportQuality;
   showTouches: boolean;
   gestureEvents: RecordingGestureEvent[];
 };
diff --git a/src/daemon/types.ts b/src/daemon/types.ts
index bf8ff6b5a..6e6791632 100644
--- a/src/daemon/types.ts
+++ b/src/daemon/types.ts
@@ -14,6 +14,7 @@ import type { CommandFlags } from '../core/dispatch.ts';
 import type { GestureReferenceFrame, ScrollDirection } from '../core/scroll-gesture.ts';
 import type { LogBackend } from './network-log.ts';
 import type { SessionSurface } from '../core/session-surface.ts';
+import type { RecordingExportQuality } from '../core/recording-export-quality.ts';
 import type { DeviceInfo, Platform, PlatformSelector } from '../utils/device.ts';
 import type { ExecBackgroundResult, ExecResult } from '../utils/exec.ts';
 import type { SnapshotState } from '../utils/snapshot.ts';
@@ -202,6 +203,7 @@ type SessionRecordingBase = {
   overlayWarning?: string;
   startedAt: number;
   quality?: number;
+  exportQuality?: RecordingExportQuality;
   showTouches: boolean;
   gestureEvents: RecordingGestureEvent[];
   touchReferenceFrame?: GestureReferenceFrame;
diff --git a/src/recording/__tests__/overlay.test.ts b/src/recording/__tests__/overlay.test.ts
index fadf08aa1..f4104cd6d 100644
--- a/src/recording/__tests__/overlay.test.ts
+++ b/src/recording/__tests__/overlay.test.ts
@@ -27,10 +27,15 @@ vi.mock('../../utils/video.ts', () => ({
   waitForPlayableVideo: vi.fn(async () => {}),
 }));
 
-import { overlayRecordingTouches } from '../overlay.ts';
+import { overlayRecordingTouches, resizeRecording } from '../overlay.ts';
 import { AppError } from '../../utils/errors.ts';
 import { runCmd } from '../../utils/exec.ts';
 
+function helperScriptArgs(): string[] {
+  const helperCall = mockRunCmd.mock.calls.find(([cmd]) => cmd !== 'xcrun');
+  return (helperCall?.[1] as string[] | undefined) ?? [];
+}
+
 const mockRunCmd = vi.mocked(runCmd);
 
 let tmpDir: string;
@@ -98,3 +103,25 @@ test('overlay preserves Swift helper compile hints', async () => {
     },
   });
 });
+
+test('resize defaults to the fast medium export preset', async () => {
+  const videoPath = path.join(tmpDir, 'recording.mp4');
+  fs.writeFileSync(videoPath, 'original');
+
+  await resizeRecording({ videoPath, quality: 7 });
+
+  expect(helperScriptArgs()).toEqual(
+    expect.arrayContaining(['--quality', '7', '--export-quality', 'medium']),
+  );
+});
+
+test('resize forwards the requested high export preset', async () => {
+  const videoPath = path.join(tmpDir, 'recording.mp4');
+  fs.writeFileSync(videoPath, 'original');
+
+  await resizeRecording({ videoPath, quality: 8, exportQuality: 'high' });
+
+  expect(helperScriptArgs()).toEqual(
+    expect.arrayContaining(['--quality', '8', '--export-quality', 'high']),
+  );
+});
diff --git a/src/recording/overlay.ts b/src/recording/overlay.ts
index a5cd6c666..7bb12d68e 100644
--- a/src/recording/overlay.ts
+++ b/src/recording/overlay.ts
@@ -5,6 +5,10 @@ import { runCmd } from '../utils/exec.ts';
 import { AppError } from '../utils/errors.ts';
 import { buildSwiftToolEnv, compileSwiftSourceFile } from '../utils/swift-cache.ts';
 import { waitForPlayableVideo, waitForStableFile } from '../utils/video.ts';
+import {
+  DEFAULT_RECORDING_EXPORT_QUALITY,
+  type RecordingExportQuality,
+} from '../core/recording-export-quality.ts';
 
 function resolveScriptPath(scriptName: string): string {
   const moduleDir = path.dirname(fileURLToPath(import.meta.url));
@@ -138,13 +142,19 @@ export async function overlayRecordingTouches(params: {
 export async function resizeRecording(params: {
   videoPath: string;
   quality: number;
+  exportQuality?: RecordingExportQuality;
   targetLabel?: string;
 }): Promise<void> {
-  const { videoPath, quality, targetLabel = 'recording' } = params;
+  const {
+    videoPath,
+    quality,
+    exportQuality = DEFAULT_RECORDING_EXPORT_QUALITY,
+    targetLabel = 'recording',
+  } = params;
   await exportProcessedVideo({
     videoPath,
     scriptPath: getResizeScriptPath(),
-    scriptArgs: ['--quality', String(quality)],
+    scriptArgs: ['--quality', String(quality), '--export-quality', exportQuality],
     commandDescription: `Failed to resize the ${targetLabel}`,
   });
 }
diff --git a/src/utils/__tests__/args.test.ts b/src/utils/__tests__/args.test.ts
index 2d41d1a90..ad0e3a515 100644
--- a/src/utils/__tests__/args.test.ts
+++ b/src/utils/__tests__/args.test.ts
@@ -1663,9 +1663,10 @@ test('command usage shows record touch-overlay opt-out flag', () => {
   if (help === null) throw new Error('Expected command help text');
   assert.match(
     help,
-    /record start \[path\] \[--fps <n>\] \[--quality <5-10>\] \[--hide-touches\] \| record stop/,
+    /record start \[path\] \[--fps <n>\] \[--quality <5-10>\] \[--export-quality <medium\|high>\] \[--hide-touches\] \| record stop/,
   );
   assert.match(help, /--quality <5-10>/);
+  assert.match(help, /--export-quality <medium\|high>/);
   assert.match(help, /--hide-touches/);
   assert.match(help, /skip touch-overlay post-processing/);
   assert.match(help, /multiple MP4 chunks/);
diff --git a/src/utils/cli-flags.ts b/src/utils/cli-flags.ts
index 8050f43ee..3f9c14157 100644
--- a/src/utils/cli-flags.ts
+++ b/src/utils/cli-flags.ts
@@ -1,4 +1,8 @@
 import { SESSION_SURFACES, type SessionSurface } from '../core/session-surface.ts';
+import {
+  RECORDING_EXPORT_QUALITIES,
+  type RecordingExportQuality,
+} from '../core/recording-export-quality.ts';
 import type { BackMode } from '../core/back-mode.ts';
 import type { ClickButton } from '../core/click-button.ts';
 import type { SwipePattern } from '../core/scroll-gesture.ts';
@@ -77,6 +81,7 @@ export type CliFlags = RemoteConfigMetroOptions &
     count?: number;
     fps?: number;
     quality?: number;
+    exportQuality?: RecordingExportQuality;
     hideTouches?: boolean;
     intervalMs?: number;
     delayMs?: number;
@@ -634,6 +639,15 @@ const FLAG_DEFINITIONS: readonly FlagDefinition[] = [
     usageDescription:
       'Record: scale recording resolution from 5 (50%) through 10 (native resolution)',
   },
+  {
+    key: 'exportQuality',
+    names: ['--export-quality'],
+    type: 'enum',
+    enumValues: RECORDING_EXPORT_QUALITIES,
+    usageLabel: '--export-quality <medium|high>',
+    usageDescription:
+      'Record: iOS export preset tradeoff. medium (default) favors fast simulator exports; high produces a slower, higher-quality export for evidence',
+  },
   {
     key: 'hideTouches',
     names: ['--hide-touches'],
diff --git a/website/docs/docs/commands.md b/website/docs/docs/commands.md
index 52d78ffdb..a1c60df4d 100644
--- a/website/docs/docs/commands.md
+++ b/website/docs/docs/commands.md
@@ -705,6 +705,7 @@ agent-device record start               # Start screen recording to auto filenam
 agent-device record start session.mp4   # Start recording to explicit path
 agent-device record start session.mp4 --fps 30  # Override iOS device runner FPS
 agent-device record start session.mp4 --quality 7 # Scale recording resolution to 70%
+agent-device record start session.mp4 --export-quality high # Higher-quality iOS export (slower)
 agent-device record stop                # Stop active recording
 ```
 
@@ -791,6 +792,7 @@ tail -50 ~/.agent-device/sessions/default/app.log
 - Physical-device capture defaults to 15 FPS.
 - `--fps <n>` (1-120) applies to physical iOS device recording as an explicit FPS cap.
 - `--quality <5-10>` scales recording resolution from 50% through native resolution without changing FPS. Omitting it preserves the platform's current/native recording resolution.
+- `--export-quality <medium|high>` controls the iOS export preset used when a recording is re-encoded (for example when `--quality` downscales it). `medium` is the default and favors fast, simulator-friendly exports; `high` produces a slower, higher-quality export better suited to evidence, release notes, or debugging visual artifacts. This is independent of the `--quality` resolution scale: `--quality` decides how large the video is, `--export-quality` decides how hard the exporter works to preserve it.
 
 ## Tracing
 

From 8f6eb35babc77b02945cf219dd761ffda3b79efa Mon Sep 17 00:00:00 2001
From: ryanda9910 <ryandaaldo@gmail.com>
Date: Fri, 19 Jun 2026 15:03:01 +0700
Subject: [PATCH 2/2] fix(recording): apply export quality to touch-overlay
 export path

The --export-quality flag was only wired into the resize export path. The
touch-overlay re-encode (finalizeRecordingOverlay -> overlayRecordingTouches ->
recording-overlay.swift) ignored it and always picked AVAssetExportPresetMediumQuality,
so record stop with --export-quality high had no effect when the stop path
re-encodes only to burn in touch overlays.

Thread the recording's exportQuality through finalizeRecordingOverlay and
overlayRecordingTouches, pass it as --export-quality to recording-overlay.swift,
and resolve the preset there via the same exportPresetName() helper used by
recording-resize.swift. Medium stays the default when the arg is absent, so
behavior is unchanged for callers that do not set it.
---
 .../RecordingScripts/recording-overlay.swift  | 52 ++++++++++++++++---
 src/daemon/handlers/record-trace-finalize.ts  |  2 +
 src/recording/__tests__/overlay.test.ts       | 26 ++++++++++
 src/recording/overlay.ts                      | 10 +++-
 website/docs/docs/commands.md                 |  2 +-
 5 files changed, 81 insertions(+), 11 deletions(-)

diff --git a/ios-runner/AgentDeviceRunner/RecordingScripts/recording-overlay.swift b/ios-runner/AgentDeviceRunner/RecordingScripts/recording-overlay.swift
index 99866f534..aa0dbefda 100644
--- a/ios-runner/AgentDeviceRunner/RecordingScripts/recording-overlay.swift
+++ b/ios-runner/AgentDeviceRunner/RecordingScripts/recording-overlay.swift
@@ -146,11 +146,9 @@ func run() throws {
   )
 
   // Overlay burn-in forces a full re-encode; medium quality keeps simulator videos readable
-  // while avoiding very slow highest-quality exports.
-  let presetName = AVAssetExportSession.exportPresets(compatibleWith: composition)
-    .contains(AVAssetExportPresetMediumQuality)
-    ? AVAssetExportPresetMediumQuality
-    : AVAssetExportPresetHighestQuality
+  // while avoiding very slow highest-quality exports. Pass --export-quality high to opt into
+  // the slower highest-quality export.
+  let presetName = exportPresetName(for: parsedArgs.exportQuality, compatibleWith: composition)
   guard let exporter = AVAssetExportSession(asset: composition, presetName: presetName) else {
     throw OverlayError.exportFailed("Failed to create export session.")
   }
@@ -174,10 +172,20 @@ func run() throws {
   }
 }
 
-func parseArguments(_ arguments: [String]) throws -> (inputPath: String, outputPath: String, eventsPath: String) {
+enum ExportQuality: String {
+  case medium
+  case high
+}
+
+func parseArguments(
+  _ arguments: [String]
+) throws -> (inputPath: String, outputPath: String, eventsPath: String, exportQuality: ExportQuality) {
   var inputPath: String?
   var outputPath: String?
   var eventsPath: String?
+  // Export quality defaults to medium so existing callers keep the fast, simulator-friendly
+  // export. Pass --export-quality high to opt into a slower highest-quality export.
+  var exportQuality: ExportQuality = .medium
   var index = 0
 
   while index < arguments.count {
@@ -196,15 +204,43 @@ func parseArguments(_ arguments: [String]) throws -> (inputPath: String, outputP
       guard nextIndex < arguments.count else { throw OverlayError.invalidArgs("--events requires a value") }
       eventsPath = arguments[nextIndex]
       index += 2
+    case "--export-quality":
+      guard nextIndex < arguments.count else {
+        throw OverlayError.invalidArgs("--export-quality requires a value")
+      }
+      guard let parsed = ExportQuality(rawValue: arguments[nextIndex]) else {
+        throw OverlayError.invalidArgs("--export-quality must be one of: medium, high")
+      }
+      exportQuality = parsed
+      index += 2
     default:
       throw OverlayError.invalidArgs("Unknown argument: \(argument)")
     }
   }
 
   guard let inputPath, let outputPath, let eventsPath else {
-    throw OverlayError.invalidArgs("Usage: recording-overlay.swift --input <video> --output <video> --events <json>")
+    throw OverlayError.invalidArgs(
+      "Usage: recording-overlay.swift --input <video> --output <video> --events <json> [--export-quality <medium|high>]"
+    )
+  }
+  return (inputPath, outputPath, eventsPath, exportQuality)
+}
+
+func exportPresetName(
+  for exportQuality: ExportQuality,
+  compatibleWith asset: AVAsset
+) -> String {
+  switch exportQuality {
+  case .high:
+    return AVAssetExportPresetHighestQuality
+  case .medium:
+    // Prefer the faster medium preset, falling back to highest quality only when medium is
+    // not available for this composition.
+    let compatible = AVAssetExportSession.exportPresets(compatibleWith: asset)
+    return compatible.contains(AVAssetExportPresetMediumQuality)
+      ? AVAssetExportPresetMediumQuality
+      : AVAssetExportPresetHighestQuality
   }
-  return (inputPath, outputPath, eventsPath)
 }
 
 func resolvedRenderSize(for track: AVAssetTrack) -> CGSize {
diff --git a/src/daemon/handlers/record-trace-finalize.ts b/src/daemon/handlers/record-trace-finalize.ts
index e461cc69c..33457ff46 100644
--- a/src/daemon/handlers/record-trace-finalize.ts
+++ b/src/daemon/handlers/record-trace-finalize.ts
@@ -10,6 +10,7 @@ type FinalizeRecordingOverlayParams = {
     gestureEvents: import('../types.ts').RecordingGestureEvent[];
     telemetryPath?: string;
     showTouches: boolean;
+    exportQuality?: import('../../core/recording-export-quality.ts').RecordingExportQuality;
     overlayWarning?: string;
   };
   deps: Pick<RecordTraceDeps, 'overlayRecordingTouches'>;
@@ -58,6 +59,7 @@ export async function finalizeRecordingOverlay(
         deps.overlayRecordingTouches({
           videoPath: recording.outPath,
           telemetryPath,
+          exportQuality: recording.exportQuality,
           targetLabel,
         }),
       {
diff --git a/src/recording/__tests__/overlay.test.ts b/src/recording/__tests__/overlay.test.ts
index f4104cd6d..e8866975c 100644
--- a/src/recording/__tests__/overlay.test.ts
+++ b/src/recording/__tests__/overlay.test.ts
@@ -104,6 +104,32 @@ test('overlay preserves Swift helper compile hints', async () => {
   });
 });
 
+test('overlay defaults to the fast medium export preset', 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()).toEqual(
+    expect.arrayContaining(['--events', telemetryPath, '--export-quality', 'medium']),
+  );
+});
+
+test('overlay forwards the requested high export preset', 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, exportQuality: 'high' });
+
+  expect(helperScriptArgs()).toEqual(
+    expect.arrayContaining(['--events', telemetryPath, '--export-quality', 'high']),
+  );
+});
+
 test('resize defaults to the fast medium export preset', async () => {
   const videoPath = path.join(tmpDir, 'recording.mp4');
   fs.writeFileSync(videoPath, 'original');
diff --git a/src/recording/overlay.ts b/src/recording/overlay.ts
index 7bb12d68e..9c7f30848 100644
--- a/src/recording/overlay.ts
+++ b/src/recording/overlay.ts
@@ -128,13 +128,19 @@ export async function trimRecordingStart(params: {
 export async function overlayRecordingTouches(params: {
   videoPath: string;
   telemetryPath: string;
+  exportQuality?: RecordingExportQuality;
   targetLabel?: string;
 }): Promise<void> {
-  const { videoPath, telemetryPath, targetLabel = 'recording' } = params;
+  const {
+    videoPath,
+    telemetryPath,
+    exportQuality = DEFAULT_RECORDING_EXPORT_QUALITY,
+    targetLabel = 'recording',
+  } = params;
   await exportProcessedVideo({
     videoPath,
     scriptPath: getOverlayScriptPath(),
-    scriptArgs: ['--events', telemetryPath],
+    scriptArgs: ['--events', telemetryPath, '--export-quality', exportQuality],
     commandDescription: `Failed to add touch overlays to the ${targetLabel}`,
   });
 }
diff --git a/website/docs/docs/commands.md b/website/docs/docs/commands.md
index a1c60df4d..7cb867d32 100644
--- a/website/docs/docs/commands.md
+++ b/website/docs/docs/commands.md
@@ -792,7 +792,7 @@ tail -50 ~/.agent-device/sessions/default/app.log
 - Physical-device capture defaults to 15 FPS.
 - `--fps <n>` (1-120) applies to physical iOS device recording as an explicit FPS cap.
 - `--quality <5-10>` scales recording resolution from 50% through native resolution without changing FPS. Omitting it preserves the platform's current/native recording resolution.
-- `--export-quality <medium|high>` controls the iOS export preset used when a recording is re-encoded (for example when `--quality` downscales it). `medium` is the default and favors fast, simulator-friendly exports; `high` produces a slower, higher-quality export better suited to evidence, release notes, or debugging visual artifacts. This is independent of the `--quality` resolution scale: `--quality` decides how large the video is, `--export-quality` decides how hard the exporter works to preserve it.
+- `--export-quality <medium|high>` controls the iOS export preset used whenever a recording is re-encoded, whether that is `--quality` downscaling it or burning in touch overlays on `record stop`. `medium` is the default and favors fast, simulator-friendly exports; `high` produces a slower, higher-quality export better suited to evidence, release notes, or debugging visual artifacts. This is independent of the `--quality` resolution scale: `--quality` decides how large the video is, `--export-quality` decides how hard the exporter works to preserve it.
 
 ## Tracing