refactor(recording): share the AVFoundation export pipeline between overlay and trim (#1943)

* wip: shared recording export support

* refactor(recording): share the AVFoundation export pipeline between overlay and trim

Extracts RecordingExportSupport.swift (error vocabulary, flag-value reading,
composition assembly, bounded export wait) so recording-overlay and
recording-trim stop carrying three near-identical copies of the same
mechanics. Entry points move to @main because multi-file swiftc reserves
top-level statements for main.swift.

compileSwiftSourceFile gains extraSourcePaths: extra units join the cache key
and reach swiftc, and overlay.ts passes the shared support file for both
scripts. Error messages and per-script stderr prefixes are unchanged; trim's
error-precedence order (missing video track before invalid range) is
preserved by resolving the track before the range guards.

Author: thymikee

apple/runner/AgentDeviceRunner/RecordingScripts/RecordingExportSupport.swift

@@ -0,0 +1,111 @@
+import AVFoundation
+import Foundation
+
+/// Shared mechanics for the recording post-processing scripts (overlay burn-in, start trim).
+/// Each script keeps its own argument grammar and export-quality policy; this file owns the
+/// error vocabulary, flag-value reading, composition assembly, and the bounded export wait.
+
+enum RecordingScriptError: Error, CustomStringConvertible {
+  case invalidArgs(String)
+  case invalidTrimRange
+  case missingVideoTrack
+  case exportFailed(String)
+
+  var description: String {
+    switch self {
+    case .invalidArgs(let message):
+      return message
+    case .invalidTrimRange:
+      return "Trim start must be before the end of the recording."
+    case .missingVideoTrack:
+      return "Input video does not contain a video track."
+    case .exportFailed(let message):
+      return message
+    }
+  }
+}
+
+func recordingOptionValue(_ arguments: [String], _ nextIndex: Int, _ flag: String) throws -> String {
+  guard nextIndex < arguments.count else {
+    throw RecordingScriptError.invalidArgs("\(flag) requires a value")
+  }
+  return arguments[nextIndex]
+}
+
+func removeStaleOutput(_ outputURL: URL) throws {
+  if FileManager.default.fileExists(atPath: outputURL.path) {
+    try FileManager.default.removeItem(at: outputURL)
+  }
+}
+
+func sourceVideoTrack(of asset: AVURLAsset) throws -> AVAssetTrack {
+  guard let track = asset.tracks(withMediaType: .video).first else {
+    throw RecordingScriptError.missingVideoTrack
+  }
+  return track
+}
+
+/// Copies `videoTrack` for `timeRange` into a fresh composition, carrying the optional audio track
+/// along when present. The caller owns any `preferredTransform` policy: trim propagates the source
+/// transform directly, while overlay re-applies it through a video-composition layer instruction
+/// instead.
+func makeRecordingComposition(
+  asset: AVURLAsset,
+  videoTrack: AVAssetTrack,
+  timeRange: CMTimeRange
+) throws -> AVMutableComposition {
+  let composition = AVMutableComposition()
+  guard let compositionVideoTrack = composition.addMutableTrack(
+    withMediaType: .video,
+    preferredTrackID: kCMPersistentTrackID_Invalid
+  ) else {
+    throw RecordingScriptError.exportFailed("Failed to create composition video track.")
+  }
+  try compositionVideoTrack.insertTimeRange(timeRange, of: videoTrack, at: .zero)
+
+  if let sourceAudioTrack = asset.tracks(withMediaType: .audio).first,
+     let compositionAudioTrack = composition.addMutableTrack(
+       withMediaType: .audio,
+       preferredTrackID: kCMPersistentTrackID_Invalid
+     ) {
+    try? compositionAudioTrack.insertTimeRange(timeRange, of: sourceAudioTrack, at: .zero)
+  }
+  return composition
+}
+
+func makeRecordingExporter(
+  _ composition: AVAsset,
+  presetName: String,
+  outputURL: URL,
+  videoComposition: AVMutableVideoComposition? = nil
+) throws -> AVAssetExportSession {
+  guard let exporter = AVAssetExportSession(asset: composition, presetName: presetName) else {
+    throw RecordingScriptError.exportFailed("Failed to create export session.")
+  }
+  exporter.outputURL = outputURL
+  exporter.outputFileType = .mp4
+  exporter.videoComposition = videoComposition
+  exporter.shouldOptimizeForNetworkUse = true
+  return exporter
+}
+
+/// Bounded asynchronous export: signals completion through a semaphore and cancels after 120s so a
+/// wedged encoder cannot hang the recording pipeline past the caller's own timeout budget.
+func runRecordingExport(
+  _ exporter: AVAssetExportSession,
+  timeoutMessage: String,
+  failureMessage: String
+) throws {
+  let semaphore = DispatchSemaphore(value: 0)
+  exporter.exportAsynchronously {
+    semaphore.signal()
+  }
+  if semaphore.wait(timeout: .now() + 120) == .timedOut {
+    exporter.cancelExport()
+    throw RecordingScriptError.exportFailed(timeoutMessage)
+  }
+
+  if exporter.status != .completed {
+    throw RecordingScriptError.exportFailed(exporter.error?.localizedDescription ?? failureMessage)
+  }
+}

apple/runner/AgentDeviceRunner/RecordingScripts/recording-overlay.swift

@@ -30,40 +30,33 @@ struct GestureEvent: Decodable {
   let edge: String?
 }
 
-enum OverlayError: Error, CustomStringConvertible {
-  case invalidArgs(String)
-  case missingVideoTrack
-  case exportFailed(String)
+enum ExportQuality: String {
+  case medium
+  case high
+}
 
-  var description: String {
-    switch self {
-    case .invalidArgs(let message):
-      return message
-    case .missingVideoTrack:
-      return "Input video does not contain a video track."
-    case .exportFailed(let message):
-      return message
+/// Entry point: `@main` because multi-file swiftc compilation reserves top-level statements for
+/// `main.swift`, which cannot be shared per-script.
+@main
+enum RecordingOverlay {
+  static func main() {
+    do {
+      try run()
+    } catch {
+      fputs("recording-overlay: \(error)\n", stderr)
+      exit(1)
     }
   }
 }
 
-do {
-  try run()
-} catch {
-  fputs("recording-overlay: \(error)\n", stderr)
-  exit(1)
-}
-
 func run() throws {
   let arguments = Array(CommandLine.arguments.dropFirst())
   let parsedArgs = try parseArguments(arguments)
   let inputURL = URL(fileURLWithPath: parsedArgs.inputPath)
   let outputURL = URL(fileURLWithPath: parsedArgs.outputPath)
   let eventsURL = URL(fileURLWithPath: parsedArgs.eventsPath)
 
-  if FileManager.default.fileExists(atPath: outputURL.path) {
-    try FileManager.default.removeItem(at: outputURL)
-  }
+  try removeStaleOutput(outputURL)
 
   let payload = try Data(contentsOf: eventsURL)
   let envelope = try JSONDecoder().decode(GestureEnvelope.self, from: payload)
@@ -74,27 +67,15 @@ func run() throws {
   }
 
   let asset = AVURLAsset(url: inputURL)
-  guard let sourceVideoTrack = asset.tracks(withMediaType: .video).first else {
-    throw OverlayError.missingVideoTrack
-  }
-
-  let composition = AVMutableComposition()
-  guard let compositionVideoTrack = composition.addMutableTrack(
-    withMediaType: .video,
-    preferredTrackID: kCMPersistentTrackID_Invalid
-  ) else {
-    throw OverlayError.exportFailed("Failed to create composition video track.")
-  }
-
+  let sourceVideoTrack = try sourceVideoTrack(of: asset)
   let fullRange = CMTimeRange(start: .zero, duration: asset.duration)
-  try compositionVideoTrack.insertTimeRange(fullRange, of: sourceVideoTrack, at: .zero)
-
-  if let sourceAudioTrack = asset.tracks(withMediaType: .audio).first,
-     let compositionAudioTrack = composition.addMutableTrack(
-       withMediaType: .audio,
-       preferredTrackID: kCMPersistentTrackID_Invalid
-     ) {
-    try? compositionAudioTrack.insertTimeRange(fullRange, of: sourceAudioTrack, at: .zero)
+  let composition = try makeRecordingComposition(
+    asset: asset,
+    videoTrack: sourceVideoTrack,
+    timeRange: fullRange
+  )
+  guard let compositionVideoTrack = composition.tracks(withMediaType: .video).first else {
+    throw RecordingScriptError.exportFailed("Failed to create composition video track.")
   }
 
   let renderSize = resolvedRenderSize(for: sourceVideoTrack)
@@ -149,32 +130,17 @@ func run() throws {
   // while avoiding very slow highest-quality exports. Pass --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.")
-  }
-
-  exporter.outputURL = outputURL
-  exporter.outputFileType = .mp4
-  exporter.videoComposition = videoComposition
-  exporter.shouldOptimizeForNetworkUse = true
-
-  let semaphore = DispatchSemaphore(value: 0)
-  exporter.exportAsynchronously {
-    semaphore.signal()
-  }
-  if semaphore.wait(timeout: .now() + 120) == .timedOut {
-    exporter.cancelExport()
-    throw OverlayError.exportFailed("Touch overlay export timed out.")
-  }
-
-  if exporter.status != .completed {
-    throw OverlayError.exportFailed(exporter.error?.localizedDescription ?? "Touch overlay export failed.")
-  }
-}
-
-enum ExportQuality: String {
-  case medium
-  case high
+  let exporter = try makeRecordingExporter(
+    composition,
+    presetName: presetName,
+    outputURL: outputURL,
+    videoComposition: videoComposition
+  )
+  try runRecordingExport(
+    exporter,
+    timeoutMessage: "Touch overlay export timed out.",
+    failureMessage: "Touch overlay export failed."
+  )
 }
 
 func parseArguments(
@@ -193,33 +159,28 @@ func parseArguments(
     let nextIndex = index + 1
     switch argument {
     case "--input":
-      guard nextIndex < arguments.count else { throw OverlayError.invalidArgs("--input requires a value") }
-      inputPath = arguments[nextIndex]
+      inputPath = try recordingOptionValue(arguments, nextIndex, "--input")
       index += 2
     case "--output":
-      guard nextIndex < arguments.count else { throw OverlayError.invalidArgs("--output requires a value") }
-      outputPath = arguments[nextIndex]
+      outputPath = try recordingOptionValue(arguments, nextIndex, "--output")
       index += 2
     case "--events":
-      guard nextIndex < arguments.count else { throw OverlayError.invalidArgs("--events requires a value") }
-      eventsPath = arguments[nextIndex]
+      eventsPath = try recordingOptionValue(arguments, nextIndex, "--events")
       index += 2
     case "--quality":
-      guard nextIndex < arguments.count else {
-        throw OverlayError.invalidArgs("--quality requires a value")
-      }
-      guard let parsed = ExportQuality(rawValue: arguments[nextIndex]) else {
-        throw OverlayError.invalidArgs("--quality must be one of: medium, high")
+      let rawValue = try recordingOptionValue(arguments, nextIndex, "--quality")
+      guard let parsed = ExportQuality(rawValue: rawValue) else {
+        throw RecordingScriptError.invalidArgs("--quality must be one of: medium, high")
       }
       exportQuality = parsed
       index += 2
     default:
-      throw OverlayError.invalidArgs("Unknown argument: \(argument)")
+      throw RecordingScriptError.invalidArgs("Unknown argument: \(argument)")
     }
   }
 
   guard let inputPath, let outputPath, let eventsPath else {
-    throw OverlayError.invalidArgs(
+    throw RecordingScriptError.invalidArgs(
       "Usage: recording-overlay.swift --input <video> --output <video> --events <json> [--quality <medium|high>]"
     )
   }