react-native-photo-video-editor 0.1.0

package/ios/Stickers/RemoteImageLoader.swift

@@ -0,0 +1,127 @@
+import UIKit
+
+/// Small async image loader for the online-sticker sheet: in-memory + on-disk thumbnail cache,
+/// plus a full-res "download and hand me a local file" path for the sticker that actually gets
+/// inserted as a layer. Plain `URLSession`, no third-party dependency (matches the rest of the
+/// codebase's zero-networking-dependency policy).
+final class RemoteImageLoader {
+  static let shared = RemoteImageLoader()
+
+  private let memoryCache = NSCache<NSString, UIImage>()
+  private let ioQueue = DispatchQueue(label: "com.photovideoeditor.remoteimageloader.io", qos: .userInitiated)
+  private let session = URLSession.shared
+
+  private init() {
+    memoryCache.countLimit = 500
+  }
+
+  private var diskCacheDirectory: URL? {
+    guard let base = FileManager.default.urls(for: .cachesDirectory, in: .userDomainMask).first else { return nil }
+    let dir = base.appendingPathComponent("openmoji", isDirectory: true)
+    if !FileManager.default.fileExists(atPath: dir.path) {
+      try? FileManager.default.createDirectory(at: dir, withIntermediateDirectories: true)
+    }
+    return dir
+  }
+
+  private func diskCacheFile(forKey key: String) -> URL? {
+    diskCacheDirectory?.appendingPathComponent(key)
+  }
+
+  // MARK: - Thumbnails (UICollectionViewCell-safe)
+
+  /// Loads a thumbnail into `imageView`, guarding against cell reuse: the URL being loaded is
+  /// stamped onto the image view via associated object, and the result is only applied if that
+  /// stamp still matches once the load completes (standard fix for the "wrong image after scroll"
+  /// bug with recycled `UICollectionViewCell`/`UITableViewCell` image views).
+  func loadThumbnail(url: URL, into imageView: UIImageView) {
+    Self.setLoadTag(url.absoluteString, on: imageView)
+    imageView.image = nil
+
+    let cacheKey = url.absoluteString as NSString
+    if let cached = memoryCache.object(forKey: cacheKey) {
+      imageView.image = cached
+      return
+    }
+
+    let diskKey = "\(url.lastPathComponent)_thumb.png"
+    ioQueue.async { [weak self] in
+      guard let self else { return }
+      if let diskURL = self.diskCacheFile(forKey: diskKey),
+         let data = try? Data(contentsOf: diskURL),
+         let image = UIImage(data: data) {
+        self.memoryCache.setObject(image, forKey: cacheKey)
+        DispatchQueue.main.async {
+          guard Self.loadTag(on: imageView) == url.absoluteString else { return }
+          imageView.image = image
+        }
+        return
+      }
+
+      self.session.dataTask(with: url) { data, response, _ in
+        guard
+          let data, let image = UIImage(data: data),
+          let http = response as? HTTPURLResponse, (200..<300).contains(http.statusCode)
+        else { return }
+        self.memoryCache.setObject(image, forKey: cacheKey)
+        if let diskURL = self.diskCacheFile(forKey: diskKey) {
+          try? data.write(to: diskURL, options: .atomic)
+        }
+        DispatchQueue.main.async {
+          guard Self.loadTag(on: imageView) == url.absoluteString else { return }
+          imageView.image = image
+        }
+      }.resume()
+    }
+  }
+
+  // MARK: - Full-res download
+
+  /// Downloads (or returns the already-cached file for) the full-res sticker image. Completion
+  /// always fires on the main thread.
+  func downloadFull(url: URL, completion: @escaping (URL?, Error?) -> Void) {
+    let diskKey = "\(url.lastPathComponent)_full.png"
+    ioQueue.async { [weak self] in
+      guard let self else { return }
+      if let diskURL = self.diskCacheFile(forKey: diskKey), FileManager.default.fileExists(atPath: diskURL.path) {
+        DispatchQueue.main.async { completion(diskURL, nil) }
+        return
+      }
+      self.session.dataTask(with: url) { data, response, error in
+        if let error {
+          DispatchQueue.main.async { completion(nil, error) }
+          return
+        }
+        guard
+          let data,
+          let http = response as? HTTPURLResponse, (200..<300).contains(http.statusCode)
+        else {
+          DispatchQueue.main.async { completion(nil, URLError(.badServerResponse)) }
+          return
+        }
+        guard let diskURL = self.diskCacheFile(forKey: diskKey) else {
+          DispatchQueue.main.async { completion(nil, URLError(.cannotCreateFile)) }
+          return
+        }
+        do {
+          try data.write(to: diskURL, options: .atomic)
+          DispatchQueue.main.async { completion(diskURL, nil) }
+        } catch {
+          DispatchQueue.main.async { completion(nil, error) }
+        }
+      }.resume()
+    }
+  }
+
+  // MARK: - Cell-reuse tagging
+
+  private static var loadTagKey: UInt8 = 0
+
+  private static func setLoadTag(_ tag: String, on imageView: UIImageView) {
+    objc_setAssociatedObject(imageView, &loadTagKey, tag, .OBJC_ASSOCIATION_RETAIN_NONATOMIC)
+  }
+
+  private static func loadTag(on imageView: UIImageView) -> String? {
+    objc_getAssociatedObject(imageView, &loadTagKey) as? String
+  }
+}

package/ios/Validation/EditorRequestValidator.swift

@@ -0,0 +1,9 @@
+import Foundation
+
+enum EditorRequestValidator {
+  static func errorCode(for request: EditorRequest) -> String? {
+    if request.uri.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty { return "E_INVALID_URI" }
+    if request.mediaType != "photo" && request.mediaType != "video" { return "E_UNSUPPORTED_MEDIA_TYPE" }
+    return nil
+  }
+}

package/ios/Video/Cache/TimelineThumbnailRepository.swift

@@ -0,0 +1,148 @@
+import AVFoundation
+import CryptoKit
+import UIKit
+
+/// Bounded memory -> disk -> decoder pipeline for video timeline thumbnails.
+final class TimelineThumbnailRepository {
+  final class Request {
+    private let lock = NSLock()
+    private var cancelled = false
+
+    func cancel() {
+      lock.lock()
+      cancelled = true
+      lock.unlock()
+    }
+
+    fileprivate var isCancelled: Bool {
+      lock.lock()
+      defer { lock.unlock() }
+      return cancelled
+    }
+  }
+
+  private let memory = NSCache<NSString, UIImage>()
+  private let decodeQueue: OperationQueue = {
+    let queue = OperationQueue()
+    queue.name = "com.photovideoeditor.timeline-thumbnails"
+    queue.qualityOfService = .utility
+    queue.maxConcurrentOperationCount = 2
+    return queue
+  }()
+  private let diskQueue = DispatchQueue(label: "com.photovideoeditor.timeline-thumbnail-disk")
+  private let cacheDirectory: URL
+  private let maxDiskBytes: Int64
+
+  init(maxDiskBytes: Int64 = 96 * 1024 * 1024) {
+    self.maxDiskBytes = maxDiskBytes
+    let base = FileManager.default.urls(for: .cachesDirectory, in: .userDomainMask).first!
+    cacheDirectory = base.appendingPathComponent("pve_timeline_thumbnails", isDirectory: true)
+    try? FileManager.default.createDirectory(at: cacheDirectory, withIntermediateDirectories: true)
+    memory.totalCostLimit = min(64 * 1024 * 1024, max(16 * 1024 * 1024, Int(ProcessInfo.processInfo.physicalMemory / 16)))
+    memory.countLimit = 96
+  }
+
+  @discardableResult
+  func load(
+    mediaID: String,
+    asset: AVAsset,
+    durationMs: Int64,
+    count: Int = 12,
+    size: CGSize,
+    onThumbnail: @escaping (_ index: Int, _ image: UIImage) -> Void,
+    onComplete: @escaping () -> Void
+  ) -> Request {
+    let request = Request()
+    let safeCount = min(24, max(1, count))
+    let pixelSize = CGSize(width: max(1, size.width), height: max(1, size.height))
+    decodeQueue.addOperation { [weak self] in
+      guard let self else { return }
+      let generator = AVAssetImageGenerator(asset: asset)
+      generator.appliesPreferredTrackTransform = true
+      generator.maximumSize = pixelSize
+      generator.requestedTimeToleranceBefore = CMTime(value: 100, timescale: 1000)
+      generator.requestedTimeToleranceAfter = CMTime(value: 100, timescale: 1000)
+      let step = max(1, durationMs) / Int64(safeCount)
+
+      for index in 0..<safeCount {
+        if request.isCancelled { break }
+        autoreleasepool {
+          let timestampMs = Int64(index) * step + step / 2
+          let key = self.key(mediaID: mediaID, timestampMs: timestampMs, size: pixelSize)
+          let image = self.memory.object(forKey: key as NSString)
+            ?? self.readDisk(key: key)
+            ?? self.decode(generator: generator, timestampMs: timestampMs)
+          guard let image, !request.isCancelled else { return }
+          self.memory.setObject(image, forKey: key as NSString, cost: image.memoryCost)
+          self.writeDiskIfNeeded(key: key, image: image)
+          DispatchQueue.main.async {
+            if !request.isCancelled { onThumbnail(index, image) }
+          }
+        }
+      }
+      if !request.isCancelled { DispatchQueue.main.async { onComplete() } }
+      self.diskQueue.async { self.trimDisk() }
+    }
+    return request
+  }
+
+  func close() {
+    decodeQueue.cancelAllOperations()
+    memory.removeAllObjects()
+  }
+
+  func clearMemory() {
+    memory.removeAllObjects()
+  }
+
+  private func decode(generator: AVAssetImageGenerator, timestampMs: Int64) -> UIImage? {
+    guard let cgImage = try? generator.copyCGImage(
+      at: CMTime(value: timestampMs, timescale: 1000),
+      actualTime: nil
+    ) else { return nil }
+    return UIImage(cgImage: cgImage)
+  }
+
+  private func readDisk(key: String) -> UIImage? {
+    let url = cacheDirectory.appendingPathComponent(key).appendingPathExtension("jpg")
+    guard let data = try? Data(contentsOf: url, options: .mappedIfSafe), let image = UIImage(data: data) else { return nil }
+    try? FileManager.default.setAttributes([.modificationDate: Date()], ofItemAtPath: url.path)
+    return image
+  }
+
+  private func writeDiskIfNeeded(key: String, image: UIImage) {
+    let url = cacheDirectory.appendingPathComponent(key).appendingPathExtension("jpg")
+    guard !FileManager.default.fileExists(atPath: url.path), let data = image.jpegData(compressionQuality: 0.82) else { return }
+    try? data.write(to: url, options: .atomic)
+  }
+
+  private func trimDisk() {
+    let keys: Set<URLResourceKey> = [.contentModificationDateKey, .fileSizeKey, .isRegularFileKey]
+    guard let files = try? FileManager.default.contentsOfDirectory(
+      at: cacheDirectory,
+      includingPropertiesForKeys: Array(keys),
+      options: [.skipsHiddenFiles]
+    ) else { return }
+    let entries = files.compactMap { url -> (URL, Date, Int64)? in
+      guard let values = try? url.resourceValues(forKeys: keys), values.isRegularFile == true else { return nil }
+      return (url, values.contentModificationDate ?? .distantPast, Int64(values.fileSize ?? 0))
+    }.sorted { $0.1 < $1.1 }
+    var bytes = entries.reduce(Int64(0)) { $0 + $1.2 }
+    for entry in entries where bytes > maxDiskBytes {
+      try? FileManager.default.removeItem(at: entry.0)
+      bytes -= entry.2
+    }
+  }
+
+  private func key(mediaID: String, timestampMs: Int64, size: CGSize) -> String {
+    let digest = SHA256.hash(data: Data(mediaID.utf8)).prefix(12).map { String(format: "%02x", $0) }.joined()
+    return "timeline_\(digest)_\(timestampMs)_\(Int(size.width))x\(Int(size.height))"
+  }
+}
+
+private extension UIImage {
+  var memoryCost: Int {
+    guard let image = cgImage else { return 1 }
+    return image.bytesPerRow * image.height
+  }
+}

package/ios/Video/Export/VideoExporter.swift

@@ -0,0 +1,275 @@
+import AVFoundation
+import QuartzCore
+import UIKit
+
+struct VideoExportResult {
+  let uri: String
+  let width: Int
+  let height: Int
+  let durationMs: Int64
+  let fileSize: Int
+  let mimeType: String
+}
+
+struct VideoExportError: Error {
+  let code: String
+  let message: String
+}
+
+/// Wraps AVFoundation to apply trim/mute/rotate/flip to the full-resolution
+/// source video and export an H.264/AAC MP4. The source file is never
+/// modified.
+///
+/// Milestone 7 (multi-clip timeline): each `VideoClip`'s trimmed range is
+/// inserted into the same export `AVMutableComposition` back-to-back via
+/// `insertTimeRange(_:of:at:)`, mirroring exactly what `VideoEditSession`
+/// already does for gapless preview — `AVMutableComposition` supports
+/// multi-segment concatenation natively, so no Media3-style multi-item
+/// `Composition`/`EditedMediaItemSequence` equivalent is needed here.
+///
+final class VideoExporter {
+  private var exportSession: AVAssetExportSession?
+  private var progressTimer: Timer?
+  private var outputURL: URL?
+
+  func export(
+    clips: [VideoClip],
+    assetProvider: (VideoClip) -> AVURLAsset,
+    state: VideoTransformState,
+    layers: [PhotoLayer],
+    exportOptions: [String: Any]?,
+    onProgress: @escaping (Float) -> Void,
+    onComplete: @escaping (VideoExportResult) -> Void,
+    onError: @escaping (VideoExportError) -> Void
+  ) {
+    guard !clips.isEmpty else {
+      onError(VideoExportError(code: "E_SOURCE_NOT_FOUND", message: "There are no clips to export."))
+      return
+    }
+
+    let composition = AVMutableComposition()
+    guard let compositionVideoTrack = composition.addMutableTrack(withMediaType: .video, preferredTrackID: kCMPersistentTrackID_Invalid) else {
+      onError(VideoExportError(code: "E_INTERNAL", message: "Unable to build the export composition."))
+      return
+    }
+    let compositionAudioTrack = composition.addMutableTrack(withMediaType: .audio, preferredTrackID: kCMPersistentTrackID_Invalid)
+
+    var sourceVideoTrack: AVAssetTrack?
+    var cursor = CMTime.zero
+    for clip in clips {
+      let clipAsset = assetProvider(clip)
+      guard let clipVideoTrack = clipAsset.tracks(withMediaType: .video).first else {
+        onError(VideoExportError(code: "E_SOURCE_UNREADABLE", message: "A clip's source video could not be decoded."))
+        return
+      }
+      if sourceVideoTrack == nil { sourceVideoTrack = clipVideoTrack }
+      let range = CMTimeRange(
+        start: CMTime(value: clip.trimStartMs, timescale: 1000),
+        end: CMTime(value: clip.effectiveTrimEndMs(), timescale: 1000)
+      )
+      do {
+        try compositionVideoTrack.insertTimeRange(range, of: clipVideoTrack, at: cursor)
+      } catch {
+        onError(VideoExportError(code: "E_EXPORT_FAILED", message: "Unable to trim the video."))
+        return
+      }
+      if let compositionAudioTrack, let clipAudioTrack = clipAsset.tracks(withMediaType: .audio).first {
+        try? compositionAudioTrack.insertTimeRange(range, of: clipAudioTrack, at: cursor)
+      }
+      cursor = CMTimeAdd(cursor, range.duration)
+    }
+    let timeRange = CMTimeRange(start: .zero, duration: cursor)
+    let durationMs = clips.reduce(Int64(0)) { $0 + $1.trimmedDurationMs() }
+
+    guard let sourceVideoTrack else {
+      onError(VideoExportError(code: "E_SOURCE_UNREADABLE", message: "The selected video could not be decoded."))
+      return
+    }
+
+    let naturalSize = sourceVideoTrack.naturalSize
+    let baseTransform = sourceVideoTrack.preferredTransform
+    let uprightSize = naturalSize.applying(baseTransform)
+    let uprightWidth = abs(uprightSize.width)
+    let uprightHeight = abs(uprightSize.height)
+
+    var transform = baseTransform
+
+    let normalizedRotation = ((state.rotationDegrees % 360) + 360) % 360
+    var renderWidth = uprightWidth
+    var renderHeight = uprightHeight
+    if normalizedRotation != 0 {
+      let radians = CGFloat(normalizedRotation) * .pi / 180
+      transform = transform.concatenating(CGAffineTransform(rotationAngle: radians))
+      switch normalizedRotation {
+      case 90:
+        transform = transform.concatenating(CGAffineTransform(translationX: uprightHeight, y: 0))
+        renderWidth = uprightHeight
+        renderHeight = uprightWidth
+      case 180:
+        transform = transform.concatenating(CGAffineTransform(translationX: uprightWidth, y: uprightHeight))
+      case 270:
+        transform = transform.concatenating(CGAffineTransform(translationX: 0, y: uprightWidth))
+        renderWidth = uprightHeight
+        renderHeight = uprightWidth
+      default:
+        break
+      }
+    }
+
+    // Crop around the transformed video's center. The same normalized layer
+    // coordinates are then evaluated against this final output rectangle.
+    if let targetRatio = state.aspectRatio, targetRatio > 0 {
+      let currentRatio = renderWidth / renderHeight
+      if currentRatio > targetRatio {
+        let croppedWidth = renderHeight * targetRatio
+        transform = transform.concatenating(CGAffineTransform(translationX: -(renderWidth - croppedWidth) / 2, y: 0))
+        renderWidth = croppedWidth
+      } else if currentRatio < targetRatio {
+        let croppedHeight = renderWidth / targetRatio
+        transform = transform.concatenating(CGAffineTransform(translationX: 0, y: -(renderHeight - croppedHeight) / 2))
+        renderHeight = croppedHeight
+      }
+    }
+
+    let videoComposition = AVMutableVideoComposition()
+    videoComposition.renderSize = CGSize(width: renderWidth, height: renderHeight)
+    videoComposition.frameDuration = CMTime(value: 1, timescale: 30)
+
+    let instruction = AVMutableVideoCompositionInstruction()
+    instruction.timeRange = CMTimeRange(start: .zero, duration: timeRange.duration)
+    let layerInstruction = AVMutableVideoCompositionLayerInstruction(assetTrack: compositionVideoTrack)
+    layerInstruction.setTransform(transform, at: .zero)
+    instruction.layerInstructions = [layerInstruction]
+    videoComposition.instructions = [instruction]
+
+    if !layers.isEmpty {
+      let renderSize = CGSize(width: renderWidth, height: renderHeight)
+      let longestEdge = max(renderSize.width, renderSize.height)
+      let overlayScale = min(1, 1280 / max(longestEdge, 1))
+      let overlayRenderSize = CGSize(
+        width: max(2, floor(renderSize.width * overlayScale)),
+        height: max(2, floor(renderSize.height * overlayScale))
+      )
+      let renderer = PhotoEditSession.pixelRenderer(size: overlayRenderSize)
+      let transparentBase = renderer.image { _ in }
+      let videoLayer = CALayer()
+      videoLayer.frame = CGRect(origin: .zero, size: renderSize)
+      let parentLayer = CALayer()
+      parentLayer.frame = videoLayer.frame
+      parentLayer.addSublayer(videoLayer)
+      let durationSeconds = max(CMTimeGetSeconds(timeRange.duration), 0.001)
+      let visibleLayers = layers.filter(\.visible)
+      // Merge only adjacent layers with identical timing. This collapses the
+      // common full-duration stack to one bitmap without changing z-order.
+      var timingGroups: [(key: String, layers: [PhotoLayer])] = []
+      for layer in visibleLayers {
+        let key = "\(max(0, layer.startMs)):\(layer.effectiveEndMs(durationMs: durationMs))"
+        if timingGroups.last?.key == key {
+          timingGroups[timingGroups.count - 1].layers.append(layer)
+        } else {
+          timingGroups.append((key, [layer]))
+        }
+      }
+      for entry in timingGroups {
+        let group = entry.layers
+        guard let representative = group.first else { continue }
+        autoreleasepool {
+        let image = PhotoLayerRenderer.render(transparentBase, layers: group) { uri in
+          SourceResolver.resolvePath(sourceUri: uri, tempPrefix: "pve_video_layer_export").flatMap { UIImage(contentsOfFile: $0) }
+        }
+        let surface = CALayer()
+        surface.frame = parentLayer.bounds
+        surface.contents = image.cgImage
+        surface.contentsGravity = .resizeAspect
+        applyVisibilityTiming(to: surface, layer: representative, durationMs: durationMs, durationSeconds: durationSeconds)
+        parentLayer.addSublayer(surface)
+        }
+      }
+      videoComposition.animationTool = AVVideoCompositionCoreAnimationTool(postProcessingAsVideoLayer: videoLayer, in: parentLayer)
+    }
+
+    let outputDir = FileManager.default.temporaryDirectory.appendingPathComponent("photovideoeditor", isDirectory: true)
+    try? FileManager.default.createDirectory(at: outputDir, withIntermediateDirectories: true)
+    let output = outputDir.appendingPathComponent(UUID().uuidString + ".mp4")
+    outputURL = output
+
+    guard let session = AVAssetExportSession(asset: composition, presetName: AVAssetExportPresetHighestQuality) else {
+      onError(VideoExportError(code: "E_INTERNAL", message: "Unable to create the export session."))
+      return
+    }
+    session.outputURL = output
+    session.outputFileType = .mp4
+    session.videoComposition = videoComposition
+    exportSession = session
+
+    let timer = Timer.scheduledTimer(withTimeInterval: 0.3, repeats: true) { [weak session] _ in
+      guard let session else { return }
+      onProgress(session.progress)
+    }
+    progressTimer = timer
+
+    session.exportAsynchronously { [weak self] in
+      guard let self else { return }
+      self.progressTimer?.invalidate()
+      switch session.status {
+      case .completed:
+        self.outputURL = nil
+        let attributes = try? FileManager.default.attributesOfItem(atPath: output.path)
+        let fileSize = (attributes?[.size] as? Int) ?? 0
+        onComplete(
+          VideoExportResult(
+            uri: output.absoluteString,
+            width: Int(renderWidth),
+            height: Int(renderHeight),
+            durationMs: durationMs,
+            fileSize: fileSize,
+            mimeType: "video/mp4"
+          )
+        )
+      case .cancelled:
+        try? FileManager.default.removeItem(at: output)
+        onError(VideoExportError(code: "E_EXPORT_CANCELLED", message: "Export was cancelled."))
+      default:
+        try? FileManager.default.removeItem(at: output)
+        onError(VideoExportError(code: "E_EXPORT_FAILED", message: session.error?.localizedDescription ?? "Unable to export the video."))
+      }
+    }
+  }
+
+  private func applyVisibilityTiming(to surface: CALayer, layer: PhotoLayer, durationMs: Int64, durationSeconds: Double) {
+    let start = min(max(layer.startMs, 0), durationMs)
+    let end = layer.effectiveEndMs(durationMs: durationMs)
+    if start == 0 && end >= durationMs {
+      surface.opacity = 1
+      return
+    }
+    let animation = CAKeyframeAnimation(keyPath: "opacity")
+    var values: [NSNumber] = []
+    var times: [NSNumber] = []
+    if start > 0 {
+      values.append(0); times.append(0)
+      values.append(1); times.append(NSNumber(value: Double(start) / Double(max(durationMs, 1))))
+    } else {
+      values.append(1); times.append(0)
+    }
+    if end < durationMs {
+      values.append(0); times.append(NSNumber(value: Double(end) / Double(max(durationMs, 1))))
+    } else {
+      values.append(1); times.append(1)
+    }
+    animation.values = values
+    animation.keyTimes = times
+    animation.calculationMode = .discrete
+    animation.beginTime = AVCoreAnimationBeginTimeAtZero
+    animation.duration = durationSeconds
+    animation.fillMode = .both
+    animation.isRemovedOnCompletion = false
+    surface.add(animation, forKey: "overlayVisibility")
+  }
+
+  func cancel() {
+    exportSession?.cancelExport()
+    progressTimer?.invalidate()
+    if let outputURL { try? FileManager.default.removeItem(at: outputURL) }
+  }
+}

package/ios/Video/Render/VideoClip.swift

@@ -0,0 +1,21 @@
+import Foundation
+
+/// One segment in the multi-clip timeline (Milestone 7). Mirrors `VideoClip.kt`.
+/// Every clip in this milestone shares the same source file (created via
+/// Split/Duplicate of one input) — importing separate additional source files
+/// from a system picker is a follow-up, not attempted here.
+struct VideoClip: Equatable {
+  var id: String = UUID().uuidString
+  let sourceUri: String
+  let originalDurationMs: Int64
+  var trimStartMs: Int64 = 0
+  var trimEndMs: Int64 = 0
+
+  func effectiveTrimEndMs() -> Int64 {
+    (trimEndMs > 0 && trimEndMs <= originalDurationMs) ? trimEndMs : originalDurationMs
+  }
+
+  func trimmedDurationMs() -> Int64 {
+    max(0, effectiveTrimEndMs() - trimStartMs)
+  }
+}

package/ios/Video/Render/VideoEditSession.swift

@@ -0,0 +1,99 @@
+import AVFoundation
+import UIKit
+
+/// Owns the AVPlayer preview instance, the ordered `VideoClip` list (the
+/// multi-clip timeline, Milestone 7), and the `VideoTransformState` that
+/// applies globally across the whole composed sequence. The source is never
+/// modified — `VideoExporter` reads the clip list again to produce the
+/// exported file.
+///
+/// Unlike Android (which plays a multi-item ExoPlayer playlist and has to
+/// track a separate "global" position distinct from the player's own
+/// per-item position), the preview here concatenates every clip's trimmed
+/// range into a single `AVMutableComposition` and plays that one asset — so
+/// `player.currentTime()`/`player.seek(to:)` already ARE the composed-timeline
+/// position, with no extra bookkeeping needed. This is a deliberate,
+/// architecture-appropriate difference from the Android session, not an
+/// oversight.
+final class VideoEditSession {
+  let player = AVPlayer()
+  /// Text/sticker/shape overlays. Reuses the photo layer model/stack — see `PhotoLayer.startMs`/`endMs` for timing.
+  let layerStack = PhotoLayerStack()
+  private(set) var clips: [VideoClip] = []
+  private(set) var state = VideoTransformState()
+  /// Fires once the source is probed and the initial single-clip timeline is ready.
+  var onClipsReady: (() -> Void)?
+
+  private var statusObservation: NSKeyValueObservation?
+
+  init(sourceUri: String) {
+    let url = URL(fileURLWithPath: SourceResolver.resolvePath(sourceUri: sourceUri, tempPrefix: "pve_video_preview") ?? sourceUri)
+    let asset = AVURLAsset(url: url)
+    let probeItem = AVPlayerItem(asset: asset)
+    statusObservation = probeItem.observe(\.status, options: [.new]) { [weak self] observedItem, _ in
+      guard let self, observedItem.status == .readyToPlay, self.clips.isEmpty else { return }
+      let durationSeconds = CMTimeGetSeconds(asset.duration)
+      guard durationSeconds.isFinite, durationSeconds > 0 else { return }
+      self.clips = [VideoClip(sourceUri: sourceUri, originalDurationMs: Int64(durationSeconds * 1000))]
+      self.rebuildPlayerComposition()
+      self.onClipsReady?()
+    }
+    player.replaceCurrentItem(with: probeItem)
+  }
+
+  /// Sum of every clip's trimmed duration — the length of the composed timeline.
+  var durationMs: Int64 { clips.reduce(0) { $0 + $1.trimmedDurationMs() } }
+
+  func update(_ transform: (inout VideoTransformState) -> Void) {
+    transform(&state)
+  }
+
+  /// Applies `transform` to the clip list and rebuilds the preview composition to match,
+  /// preserving the playhead's position on the composed timeline as closely as possible.
+  func updateClips(_ transform: ([VideoClip]) -> [VideoClip]) {
+    let previousPositionMs = Int64(CMTimeGetSeconds(player.currentTime()) * 1000)
+    clips = transform(clips)
+    rebuildPlayerComposition()
+    player.seek(to: CMTime(value: previousPositionMs.clamped(to: 0...max(0, durationMs)), timescale: 1000))
+  }
+
+  /// The `AVURLAsset` for one clip's own source file (all clips share one source this milestone).
+  func asset(for clip: VideoClip) -> AVURLAsset {
+    let url = URL(fileURLWithPath: SourceResolver.resolvePath(sourceUri: clip.sourceUri, tempPrefix: "pve_video_preview") ?? clip.sourceUri)
+    return AVURLAsset(url: url)
+  }
+
+  private func rebuildPlayerComposition() {
+    guard !clips.isEmpty else { return }
+    let composition = AVMutableComposition()
+    let videoTrack = composition.addMutableTrack(withMediaType: .video, preferredTrackID: kCMPersistentTrackID_Invalid)
+    let audioTrack = composition.addMutableTrack(withMediaType: .audio, preferredTrackID: kCMPersistentTrackID_Invalid)
+    var cursor = CMTime.zero
+    for clip in clips {
+      let clipAsset = asset(for: clip)
+      let range = CMTimeRange(
+        start: CMTime(value: clip.trimStartMs, timescale: 1000),
+        end: CMTime(value: clip.effectiveTrimEndMs(), timescale: 1000)
+      )
+      if let sourceVideoTrack = clipAsset.tracks(withMediaType: .video).first {
+        try? videoTrack?.insertTimeRange(range, of: sourceVideoTrack, at: cursor)
+        videoTrack?.preferredTransform = sourceVideoTrack.preferredTransform
+      }
+      if let sourceAudioTrack = clipAsset.tracks(withMediaType: .audio).first {
+        try? audioTrack?.insertTimeRange(range, of: sourceAudioTrack, at: cursor)
+      }
+      cursor = CMTimeAdd(cursor, range.duration)
+    }
+    let item = AVPlayerItem(asset: composition)
+    player.replaceCurrentItem(with: item)
+  }
+
+  func release() {
+    statusObservation?.invalidate()
+    player.pause()
+  }
+}
+
+private extension Int64 {
+  func clamped(to range: ClosedRange<Int64>) -> Int64 { min(max(self, range.lowerBound), range.upperBound) }
+}