react-native-photo-video-editor 0.1.0

package/ios/Editor/README.md

@@ -0,0 +1,5 @@
+# Planned iOS editor
+
+Milestone one contains no editing engine. A future full-screen editor will use `AVPlayer` for preview, AVFoundation composition/export APIs for timelines and final output, and Core Image/Core Graphics for photo filtering and composition. Metal will be introduced only when measured real-time rendering requirements justify it.
+
+Temporary/output URL ownership and cleanup will be explicit. Photos framework integration will occur only when gallery saving is requested; the consuming app—not this library—must provide the relevant usage descriptions.

package/ios/Editor/UI/EditorComponents.swift

@@ -0,0 +1,138 @@
+import UIKit
+
+/// Shared "Studio Violet" UI primitives (DESIGN.md), reused across the photo/video editor shell
+/// instead of hand-rolling styling per screen. Mirrors `EditorComponents.kt` on Android.
+
+/// A `UITapGestureRecognizer` that takes a closure instead of a target/action pair.
+final class ClosureTapGestureRecognizer: UITapGestureRecognizer {
+  private let action: () -> Void
+
+  init(action: @escaping () -> Void) {
+    self.action = action
+    super.init(target: nil, action: nil)
+    addTarget(self, action: #selector(handle))
+  }
+
+  @objc private func handle() { action() }
+}
+
+/// Tactile press feedback (scale 1.0 -> 0.97) matching DESIGN.md's "Tactile Instrument Feel".
+/// Only observes touch-down/up via a zero-duration long-press recognizer with
+/// `cancelsTouchesInView = false`, so it never interferes with an existing tap recognizer
+/// (e.g. the tool rail's `handleToolNodeTap`) already attached to the same view.
+private final class EditorPressFeedback: NSObject {
+  private let pressedScale: CGFloat
+  private weak var target: UIView?
+
+  init(target: UIView, pressedScale: CGFloat) {
+    self.target = target
+    self.pressedScale = pressedScale
+    super.init()
+    let recognizer = UILongPressGestureRecognizer(target: self, action: #selector(handle(_:)))
+    recognizer.minimumPressDuration = 0
+    recognizer.cancelsTouchesInView = false
+    target.addGestureRecognizer(recognizer)
+  }
+
+  @objc private func handle(_ recognizer: UILongPressGestureRecognizer) {
+    guard let target else { return }
+    switch recognizer.state {
+    case .began:
+      UIView.animate(withDuration: 0.08) { target.transform = CGAffineTransform(scaleX: self.pressedScale, y: self.pressedScale) }
+    case .ended, .cancelled, .failed:
+      UIView.animate(withDuration: 0.12) { target.transform = .identity }
+    default:
+      break
+    }
+  }
+}
+
+private var pressFeedbackAssociationKey: UInt8 = 0
+
+extension UIView {
+  /// Attaches (once) the shared press-scale feedback to this view.
+  func applyPressScale(_ scale: CGFloat = 0.97) {
+    guard objc_getAssociatedObject(self, &pressFeedbackAssociationKey) == nil else { return }
+    let feedback = EditorPressFeedback(target: self, pressedScale: scale)
+    objc_setAssociatedObject(self, &pressFeedbackAssociationKey, feedback, .OBJC_ASSOCIATION_RETAIN)
+  }
+}
+
+enum EditorComponents {
+  /// Elevated rounded container (DESIGN.md "Elevated Panels & Tiles"), used for cards/tiles/sheets.
+  static func card(
+    radius: CGFloat = DesignTokens.radiusLg,
+    backgroundColor: UIColor = DesignTokens.elevatedPanel,
+    borderColor: UIColor? = DesignTokens.interactiveNeutral
+  ) -> UIView {
+    let view = UIView()
+    view.backgroundColor = backgroundColor
+    view.layer.cornerRadius = radius
+    if let borderColor {
+      view.layer.borderColor = borderColor.cgColor
+      view.layer.borderWidth = 1
+    }
+    return view
+  }
+
+  /// Pill chip for quick actions / filter tags (DESIGN.md "Chips & Filter Presets").
+  static func chip(text: String, selected: Bool, onTap: @escaping () -> Void) -> UIView {
+    let label = UILabel()
+    label.text = text
+    label.font = .systemFont(ofSize: 12, weight: .semibold)
+    label.textColor = selected ? DesignTokens.textPrimary : DesignTokens.textSecondary
+    label.textAlignment = .center
+
+    let container = UIView()
+    container.backgroundColor = selected ? DesignTokens.accentViolet : DesignTokens.elevatedPanel
+    container.layer.cornerRadius = 16
+    if !selected {
+      container.layer.borderColor = DesignTokens.interactiveNeutral.cgColor
+      container.layer.borderWidth = 1
+    }
+    container.addSubview(label)
+    label.translatesAutoresizingMaskIntoConstraints = false
+    NSLayoutConstraint.activate([
+      label.leadingAnchor.constraint(equalTo: container.leadingAnchor, constant: DesignTokens.spaceLg),
+      label.trailingAnchor.constraint(equalTo: container.trailingAnchor, constant: -DesignTokens.spaceLg),
+      label.topAnchor.constraint(equalTo: container.topAnchor, constant: DesignTokens.spaceXs),
+      label.bottomAnchor.constraint(equalTo: container.bottomAnchor, constant: -DesignTokens.spaceXs),
+      container.heightAnchor.constraint(greaterThanOrEqualToConstant: 32),
+    ])
+    container.isUserInteractionEnabled = true
+    container.addGestureRecognizer(ClosureTapGestureRecognizer(action: onTap))
+    container.applyPressScale()
+    return container
+  }
+
+  /// Primary Export CTA (DESIGN.md "Primary Export Button"): solid violet fill, 44pt min height,
+  /// 12px radius, subtle glow shadow, 0.97 press scale.
+  static func primaryButton(
+    text: String,
+    systemImage: String? = nil,
+    fillColor: UIColor = DesignTokens.accentViolet,
+    textColor: UIColor = DesignTokens.textPrimary,
+    onTap: @escaping () -> Void
+  ) -> UIButton {
+    let button = UIButton(type: .system)
+    button.setTitle(text, for: .normal)
+    button.setTitleColor(textColor, for: .normal)
+    if let systemImage { button.setImage(UIImage(systemName: systemImage), for: .normal) }
+    button.tintColor = textColor
+    button.backgroundColor = fillColor
+    button.layer.cornerRadius = DesignTokens.radiusLg
+    button.titleLabel?.font = .systemFont(ofSize: 13, weight: .bold)
+    button.contentEdgeInsets = UIEdgeInsets(top: 0, left: DesignTokens.spaceLg, bottom: 0, right: DesignTokens.spaceLg)
+    if #available(iOS 15.0, *) {
+      button.configuration = nil // avoid UIButtonConfiguration overriding our manual styling on iOS 15+
+    }
+    button.heightAnchor.constraint(equalToConstant: DesignTokens.touchTargetMin).isActive = true
+    button.layer.shadowColor = fillColor.cgColor
+    button.layer.shadowOpacity = 0.35
+    button.layer.shadowRadius = 12
+    button.layer.shadowOffset = CGSize(width: 0, height: 4)
+    button.addAction(UIAction { _ in onTap() }, for: .touchUpInside)
+    button.applyPressScale()
+    return button
+  }
+}

package/ios/Files/SourceResolver.swift

@@ -0,0 +1,13 @@
+import Foundation
+
+/// Resolves an editor source uri (file:// or a bare path) to a local
+/// filesystem path that ImageIO can read directly. Photos-library identifiers
+/// (ph://) and remote https:// sources are not yet supported.
+enum SourceResolver {
+  static func resolvePath(sourceUri: String, tempPrefix: String) -> String? {
+    guard let url = URL(string: sourceUri) else { return nil }
+    if url.isFileURL { return url.path }
+    if url.scheme == nil { return sourceUri }
+    return nil
+  }
+}

package/ios/Models/EditorRequest.swift

@@ -0,0 +1,3 @@
+import Foundation
+
+struct EditorRequest { let uri: String; let mediaType: String; let mimeType: String? }

package/ios/Photo/Export/PhotoExporter.swift

@@ -0,0 +1,144 @@
+import ImageIO
+import UIKit
+
+struct PhotoExportResult {
+  let uri: String
+  let width: Int
+  let height: Int
+  let fileSize: Int
+  let mimeType: String
+}
+
+struct PhotoExportError: Error {
+  let code: String
+  let message: String
+}
+
+/// Applies a `PhotoTransformState` to the full-resolution source photo and
+/// writes the result to a new file under the app's temporary directory. The
+/// source file is never modified. WebP export is not implemented on iOS
+/// (no first-party encoder); JPEG and PNG are supported.
+enum PhotoExporter {
+  private static let defaultMaxDimension: CGFloat = 4096
+
+  static func export(
+    sourceUri: String,
+    transform: PhotoTransformState,
+    adjustments: PhotoAdjustments,
+    layers: [PhotoLayer],
+    exportOptions: [String: Any]?
+  ) throws -> PhotoExportResult {
+    guard let path = SourceResolver.resolvePath(sourceUri: sourceUri, tempPrefix: "pve_export") else {
+      throw PhotoExportError(code: "E_SOURCE_NOT_FOUND", message: "The selected photo could not be found.")
+    }
+    let url = URL(fileURLWithPath: path)
+    guard let source = CGImageSourceCreateWithURL(url as CFURL, nil) else {
+      throw PhotoExportError(code: "E_SOURCE_UNREADABLE", message: "The selected photo could not be decoded.")
+    }
+
+    let maxWidth = (exportOptions?["maxWidth"] as? NSNumber)?.doubleValue.map { CGFloat($0) }
+    let maxHeight = (exportOptions?["maxHeight"] as? NSNumber)?.doubleValue.map { CGFloat($0) }
+    let decodeTarget = max(maxWidth ?? defaultMaxDimension, maxHeight ?? defaultMaxDimension) * 2
+
+    let thumbnailOptions: [CFString: Any] = [
+      kCGImageSourceCreateThumbnailFromImageAlways: true,
+      kCGImageSourceThumbnailMaxPixelSize: decodeTarget,
+      kCGImageSourceCreateThumbnailWithTransform: true,
+    ]
+    guard let cgImage = CGImageSourceCreateThumbnailAtIndex(source, 0, thumbnailOptions as CFDictionary) else {
+      throw PhotoExportError(code: "E_OUT_OF_MEMORY", message: "The photo is too large to process on this device.")
+    }
+    let upright = UIImage(cgImage: cgImage)
+
+    let transformed = PhotoEditSession.applyTransform(upright, state: transform)
+    let adjusted = PhotoAdjustmentRenderer.apply(transformed, adjustments: adjustments)
+    let layered = PhotoLayerRenderer.render(adjusted, layers: layers) { uri in resolveImageLayer(uri) }
+    let cropped = crop(layered, transform: transform)
+    let resized = resize(cropped, maxWidth: maxWidth, maxHeight: maxHeight)
+
+    let format = (exportOptions?["imageFormat"] as? String)?.lowercased() ?? "jpeg"
+    let quality = qualityFor(exportOptions?["quality"] as? String ?? "high")
+
+    let outputDir = FileManager.default.temporaryDirectory.appendingPathComponent("photovideoeditor", isDirectory: true)
+    try? FileManager.default.createDirectory(at: outputDir, withIntermediateDirectories: true)
+
+    let data: Data?
+    let mimeType: String
+    let ext: String
+    switch format {
+    case "png":
+      data = resized.pngData()
+      mimeType = "image/png"
+      ext = "png"
+    default:
+      // WebP encoding is not implemented on iOS; unsupported formats fall back to JPEG.
+      data = resized.jpegData(compressionQuality: quality)
+      mimeType = "image/jpeg"
+      ext = "jpg"
+    }
+    guard let outputData = data else {
+      throw PhotoExportError(code: "E_EXPORT_FAILED", message: "Unable to encode the exported photo.")
+    }
+
+    let outputFile = outputDir.appendingPathComponent(UUID().uuidString + "." + ext)
+    do {
+      try outputData.write(to: outputFile)
+    } catch {
+      throw PhotoExportError(code: "E_EXPORT_FAILED", message: "Unable to write the exported photo.")
+    }
+
+    let attributes = try? FileManager.default.attributesOfItem(atPath: outputFile.path)
+    let fileSize = (attributes?[.size] as? Int) ?? outputData.count
+
+    return PhotoExportResult(
+      uri: outputFile.absoluteString,
+      width: Int(resized.size.width),
+      height: Int(resized.size.height),
+      fileSize: fileSize,
+      mimeType: mimeType
+    )
+  }
+
+  /// Export-time, one-shot resolver for sticker-uri and overlay-uri layers alike (no cache needed —
+  /// export runs once per invocation).
+  private static func resolveImageLayer(_ uri: String) -> UIImage? {
+    guard let path = SourceResolver.resolvePath(sourceUri: uri, tempPrefix: "pve_layer_export") else { return nil }
+    return UIImage(contentsOfFile: path)
+  }
+
+  private static func crop(_ image: UIImage, transform: PhotoTransformState) -> UIImage {
+    guard transform.cropLeft > 0 || transform.cropTop > 0 || transform.cropRight < 1 || transform.cropBottom < 1 else { return image }
+    guard let cgImage = image.cgImage else { return image }
+    let width = CGFloat(cgImage.width)
+    let height = CGFloat(cgImage.height)
+    let fullRect = CGRect(x: 0, y: 0, width: width, height: height)
+    let rect = CGRect(
+      x: transform.cropLeft * width,
+      y: transform.cropTop * height,
+      width: (transform.cropRight - transform.cropLeft) * width,
+      height: (transform.cropBottom - transform.cropTop) * height
+    ).integral.intersection(fullRect)
+    guard rect.width > 0, rect.height > 0, let croppedImage = cgImage.cropping(to: rect) else { return image }
+    return UIImage(cgImage: croppedImage)
+  }
+
+  private static func resize(_ image: UIImage, maxWidth: CGFloat?, maxHeight: CGFloat?) -> UIImage {
+    guard maxWidth != nil || maxHeight != nil else { return image }
+    let widthLimit = maxWidth ?? image.size.width
+    let heightLimit = maxHeight ?? image.size.height
+    guard image.size.width > widthLimit || image.size.height > heightLimit else { return image }
+    let scale = min(widthLimit / image.size.width, heightLimit / image.size.height)
+    let targetSize = CGSize(width: max(1, image.size.width * scale), height: max(1, image.size.height * scale))
+    let renderer = PhotoEditSession.pixelRenderer(size: targetSize)
+    return renderer.image { _ in image.draw(in: CGRect(origin: .zero, size: targetSize)) }
+  }
+
+  private static func qualityFor(_ preset: String) -> CGFloat {
+    switch preset {
+    case "low": return 0.5
+    case "medium": return 0.75
+    case "original": return 1.0
+    default: return 0.9
+    }
+  }
+}

package/ios/Photo/Rendering/OverlayGeometry.swift

@@ -0,0 +1,22 @@
+import CoreGraphics
+
+/// Pure normalized-coordinate mapping used by preview and export rendering.
+enum OverlayGeometry {
+  struct Transform {
+    let center: CGPoint
+    let scale: CGFloat
+    let rotationDegrees: CGFloat
+    let opacity: CGFloat
+    let shortSide: CGFloat
+  }
+
+  static func map(_ layer: PhotoLayer, frameSize: CGSize) -> Transform {
+    Transform(
+      center: CGPoint(x: layer.x * frameSize.width, y: layer.y * frameSize.height),
+      scale: layer.scale,
+      rotationDegrees: layer.rotationDegrees,
+      opacity: min(max(layer.opacity, 0), 1),
+      shortSide: min(frameSize.width, frameSize.height)
+    )
+  }
+}

package/ios/Photo/Rendering/PhotoAdjustmentRenderer.swift

@@ -0,0 +1,141 @@
+import UIKit
+
+/// Applies the non-destructive `PhotoAdjustments` stack to a `UIImage`. The
+/// live preview and the exporter both call this, in this exact order, so what
+/// the user sees always matches what gets exported — and the per-channel
+/// formulas mirror `PhotoAdjustmentRenderer.kt` so Android/iOS output stays
+/// visually close:
+///
+/// color adjustments (brightness/contrast/saturation/exposure/temperature)
+/// -> blur -> mirror -> preset filter blend.
+enum PhotoAdjustmentRenderer {
+  static func apply(_ source: UIImage, adjustments: PhotoAdjustments) -> UIImage {
+    guard !adjustments.isIdentity, var buffer = PixelBuffer(image: source) else { return source }
+
+    let needsColorPass = adjustments.brightness != 0 || adjustments.contrast != 0 || adjustments.saturation != 0 ||
+      adjustments.exposure != 0 || adjustments.temperature != 0
+    if needsColorPass {
+      applyColorAdjustments(&buffer, adjustments)
+    }
+    if adjustments.blurRadius >= 1 {
+      applyBoxBlur(&buffer, radius: Int(adjustments.blurRadius.rounded()))
+    }
+
+    var image = buffer.makeImage() ?? source
+    if adjustments.mirror {
+      image = applyMirror(image)
+    }
+    if let preset = adjustments.filterPreset {
+      image = applyPreset(image, preset: preset, strength: adjustments.filterStrength / 100)
+    }
+    return image
+  }
+
+  private static func applyColorAdjustments(_ buffer: inout PixelBuffer, _ adjustments: PhotoAdjustments) {
+    let exposureScale = pow(2, adjustments.exposure / 100)
+    let brightnessOffset = adjustments.brightness / 100 * 80
+    let contrastScale = (adjustments.contrast + 100) / 100
+    let contrastTranslate = 128 * (1 - contrastScale)
+    let saturationFactor = (adjustments.saturation + 100) / 100
+    let tempShift = adjustments.temperature / 100 * 40
+
+    for y in 0..<buffer.height {
+      for x in 0..<buffer.width {
+        let pixel = buffer[x, y]
+        var r = Double(pixel.r) * exposureScale + brightnessOffset
+        var g = Double(pixel.g) * exposureScale + brightnessOffset
+        var b = Double(pixel.b) * exposureScale + brightnessOffset
+        r = r * contrastScale + contrastTranslate
+        g = g * contrastScale + contrastTranslate
+        b = b * contrastScale + contrastTranslate
+        let luminance = 0.2126 * r + 0.7152 * g + 0.0722 * b
+        r = luminance + (r - luminance) * saturationFactor
+        g = luminance + (g - luminance) * saturationFactor
+        b = luminance + (b - luminance) * saturationFactor
+        r += tempShift
+        b -= tempShift
+        buffer[x, y] = (clampByte(r), clampByte(g), clampByte(b), pixel.a)
+      }
+    }
+  }
+
+  /// Approximate Gaussian blur via three passes of separable box blur.
+  private static func applyBoxBlur(_ buffer: inout PixelBuffer, radius: Int) {
+    guard radius > 0 else { return }
+    for _ in 0..<3 {
+      boxBlurPass(&buffer, radius: radius, horizontal: true)
+      boxBlurPass(&buffer, radius: radius, horizontal: false)
+    }
+  }
+
+  private static func boxBlurPass(_ buffer: inout PixelBuffer, radius: Int, horizontal: Bool) {
+    let source = buffer
+    let outerLimit = horizontal ? buffer.height : buffer.width
+    let innerLimit = horizontal ? buffer.width : buffer.height
+    for outer in 0..<outerLimit {
+      for inner in 0..<innerLimit {
+        var r = 0
+        var g = 0
+        var b = 0
+        var a = 0
+        var count = 0
+        for offset in -radius...radius {
+          let sample = min(max(inner + offset, 0), innerLimit - 1)
+          let (x, y) = horizontal ? (sample, outer) : (outer, sample)
+          let pixel = source[x, y]
+          r += Int(pixel.r); g += Int(pixel.g); b += Int(pixel.b); a += Int(pixel.a)
+          count += 1
+        }
+        let (ox, oy) = horizontal ? (inner, outer) : (outer, inner)
+        buffer[ox, oy] = (UInt8(r / count), UInt8(g / count), UInt8(b / count), UInt8(a / count))
+      }
+    }
+  }
+
+  /// Mirrors the left half of the image onto the right half.
+  private static func applyMirror(_ image: UIImage) -> UIImage {
+    guard image.size.width >= 2, let cgImage = image.cgImage else { return image }
+    let halfWidth = CGFloat(Int(image.size.width) / 2)
+    let leftRect = CGRect(x: 0, y: 0, width: halfWidth, height: image.size.height)
+    guard let leftCG = cgImage.cropping(to: leftRect) else { return image }
+    let leftImage = UIImage(cgImage: leftCG)
+    let renderer = PhotoEditSession.pixelRenderer(size: image.size)
+    return renderer.image { context in
+      leftImage.draw(in: leftRect)
+      context.cgContext.saveGState()
+      context.cgContext.translateBy(x: image.size.width, y: 0)
+      context.cgContext.scaleBy(x: -1, y: 1)
+      leftImage.draw(in: leftRect)
+      context.cgContext.restoreGState()
+    }
+  }
+
+  private static func applyPreset(_ image: UIImage, preset: String, strength: Double) -> UIImage {
+    guard let recipe = PhotoFilterPresets.recipe(for: preset), var buffer = PixelBuffer(image: image) else { return image }
+    for y in 0..<buffer.height {
+      for x in 0..<buffer.width {
+        let pixel = buffer[x, y]
+        let luminance = 0.2126 * Double(pixel.r) + 0.7152 * Double(pixel.g) + 0.0722 * Double(pixel.b)
+        var r = luminance + (Double(pixel.r) - luminance) * recipe.saturation
+        var g = luminance + (Double(pixel.g) - luminance) * recipe.saturation
+        var b = luminance + (Double(pixel.b) - luminance) * recipe.saturation
+        r = r * recipe.scale + recipe.redOffset
+        g = g * recipe.scale + recipe.greenOffset
+        b = b * recipe.scale + recipe.blueOffset
+        buffer[x, y] = (clampByte(r), clampByte(g), clampByte(b), pixel.a)
+      }
+    }
+    guard let filtered = buffer.makeImage() else { return image }
+    guard strength < 1 else { return filtered }
+
+    let renderer = PhotoEditSession.pixelRenderer(size: image.size)
+    return renderer.image { _ in
+      image.draw(in: CGRect(origin: .zero, size: image.size))
+      filtered.draw(in: CGRect(origin: .zero, size: image.size), blendMode: .normal, alpha: CGFloat(strength))
+    }
+  }
+
+  private static func clampByte(_ value: Double) -> UInt8 {
+    UInt8(min(max(value.rounded(), 0), 255))
+  }
+}

package/ios/Photo/Rendering/PhotoAdjustments.swift

@@ -0,0 +1,57 @@
+import Foundation
+
+/// Non-destructive photo adjustment stack (Milestone 3). Every numeric field
+/// has a documented range and a zero/no-op default so "reset" is always just
+/// `PhotoAdjustments()`. Mirrors `PhotoAdjustments.kt` field-for-field so the
+/// two platforms can share the same formulas in their renderers.
+struct PhotoAdjustments: Equatable {
+  var brightness: Double = 0 // -100..100
+  var contrast: Double = 0 // -100..100
+  var saturation: Double = 0 // -100..100
+  var exposure: Double = 0 // -100..100
+  var temperature: Double = 0 // -100..100
+  var blurRadius: Double = 0 // 0..25 (px)
+  var mirror: Bool = false
+  var filterPreset: String?
+  var filterStrength: Double = 100 // 0..100, only meaningful when filterPreset is set
+
+  var isIdentity: Bool { self == PhotoAdjustments() }
+
+  func value(_ key: String) -> Double {
+    switch key {
+    case "brightness": return brightness
+    case "contrast": return contrast
+    case "saturation": return saturation
+    case "exposure": return exposure
+    case "temperature": return temperature
+    case "blurRadius": return blurRadius
+    case "filterStrength": return filterStrength
+    default: return 0
+    }
+  }
+
+  mutating func setValue(_ key: String, _ newValue: Double) {
+    switch key {
+    case "brightness": brightness = newValue
+    case "contrast": contrast = newValue
+    case "saturation": saturation = newValue
+    case "exposure": exposure = newValue
+    case "temperature": temperature = newValue
+    case "blurRadius": blurRadius = newValue
+    case "filterStrength": filterStrength = newValue
+    default: break
+    }
+  }
+
+  static let sliderKeys = [
+    "brightness", "contrast", "saturation", "exposure", "temperature", "blurRadius",
+  ]
+
+  static func range(for key: String) -> (Double, Double) {
+    switch key {
+    case "blurRadius": return (0, 25)
+    case "filterStrength": return (0, 100)
+    default: return (-100, 100)
+    }
+  }
+}

package/ios/Photo/Rendering/PhotoEditSession.swift

@@ -0,0 +1,121 @@
+import ImageIO
+import UIKit
+
+/// Owns an in-memory, downsampled working copy of the source photo for fast,
+/// memory-safe live preview. The full-resolution source is decoded again,
+/// once, only at export time by `PhotoExporter`.
+final class PhotoEditSession {
+  private(set) var state = PhotoTransformState()
+  private(set) var adjustments = PhotoAdjustments()
+  let layerStack = PhotoLayerStack()
+  let baseImage: UIImage?
+
+  private var cachedBaseImage: UIImage?
+  private var cachedState: PhotoTransformState?
+  private var cachedAdjustments: PhotoAdjustments?
+  private var cachedPreviewImage: UIImage?
+  private weak var cachedPreviewBaseImage: UIImage?
+  private var cachedPreviewLayerRevision: UInt64?
+  /// Resolved images for both sticker-uri and overlay-uri layers — the lookup logic is identical
+  /// for either layer type, so one cache/resolver serves both.
+  private var imageLayerCache: [String: UIImage?] = [:]
+
+  init(sourceUri: String, maxPreviewDimension: CGFloat = 1600) {
+    baseImage = PhotoEditSession.decodeUpright(sourceUri: sourceUri, maxDimension: maxPreviewDimension)
+  }
+
+  func update(_ transform: (inout PhotoTransformState) -> Void) {
+    transform(&state)
+  }
+
+  func updateAdjustments(_ transform: (inout PhotoAdjustments) -> Void) {
+    transform(&adjustments)
+  }
+
+  /// Rotate/flip/straighten + adjustments only, cached so dragging a layer doesn't re-run the full pipeline every frame.
+  private func computeBase() -> UIImage? {
+    guard let base = baseImage else { return nil }
+    if let cached = cachedBaseImage, cachedState == state, cachedAdjustments == adjustments {
+      return cached
+    }
+    let transformed: UIImage
+    if state.rotationDegrees == 0 && state.straightenDegrees == 0 {
+      transformed = base
+    } else {
+      transformed = PhotoEditSession.applyTransform(base, state: state)
+    }
+    let adjusted = PhotoAdjustmentRenderer.apply(transformed, adjustments: adjustments)
+    cachedBaseImage = adjusted
+    cachedState = state
+    cachedAdjustments = adjustments
+    return adjusted
+  }
+
+  /// Renders rotate/flip/straighten + adjustments + layers — the crop overlay draws the crop live on top of this.
+  func renderPreview() -> UIImage? {
+    guard let base = computeBase() else { return nil }
+    if cachedPreviewBaseImage === base,
+       cachedPreviewLayerRevision == layerStack.revision,
+       let cachedPreviewImage {
+      return cachedPreviewImage
+    }
+    let rendered = PhotoLayerRenderer.render(base, layers: layerStack.layers) { [weak self] uri in self?.resolveImageLayer(uri) }
+    cachedPreviewBaseImage = base
+    cachedPreviewLayerRevision = layerStack.revision
+    cachedPreviewImage = rendered
+    return rendered
+  }
+
+  func release() {
+    cachedBaseImage = nil
+    cachedState = nil
+    cachedAdjustments = nil
+    cachedPreviewImage = nil
+    cachedPreviewBaseImage = nil
+    cachedPreviewLayerRevision = nil
+    imageLayerCache.removeAll()
+  }
+
+  private func resolveImageLayer(_ uri: String) -> UIImage? {
+    if let cached = imageLayerCache[uri] { return cached }
+    let path = SourceResolver.resolvePath(sourceUri: uri, tempPrefix: "pve_layer_image")
+    let image = path.flatMap { UIImage(contentsOfFile: $0) }
+    imageLayerCache[uri] = image
+    return image
+  }
+
+  /// A renderer whose output pixel size exactly matches its point size, so
+  /// width/height math stays consistent with `CGImage.width`/`height` elsewhere.
+  static func pixelRenderer(size: CGSize) -> UIGraphicsImageRenderer {
+    let format = UIGraphicsImageRendererFormat()
+    format.scale = 1
+    return UIGraphicsImageRenderer(size: size, format: format)
+  }
+
+  static func applyTransform(_ image: UIImage, state: PhotoTransformState) -> UIImage {
+    guard state.rotationDegrees != 0 || state.straightenDegrees != 0 else { return image }
+    let radians = state.totalRotationRadians
+    let rotatedBounds = CGRect(origin: .zero, size: image.size).applying(CGAffineTransform(rotationAngle: radians))
+    let canvasSize = CGSize(width: abs(rotatedBounds.width), height: abs(rotatedBounds.height))
+    let renderer = pixelRenderer(size: canvasSize)
+    return renderer.image { context in
+      let ctx = context.cgContext
+      ctx.translateBy(x: canvasSize.width / 2, y: canvasSize.height / 2)
+      ctx.rotate(by: radians)
+      image.draw(in: CGRect(x: -image.size.width / 2, y: -image.size.height / 2, width: image.size.width, height: image.size.height))
+    }
+  }
+
+  private static func decodeUpright(sourceUri: String, maxDimension: CGFloat) -> UIImage? {
+    guard let path = SourceResolver.resolvePath(sourceUri: sourceUri, tempPrefix: "pve_preview") else { return nil }
+    let url = URL(fileURLWithPath: path)
+    guard let source = CGImageSourceCreateWithURL(url as CFURL, nil) else { return nil }
+    let options: [CFString: Any] = [
+      kCGImageSourceCreateThumbnailFromImageAlways: true,
+      kCGImageSourceThumbnailMaxPixelSize: maxDimension,
+      kCGImageSourceCreateThumbnailWithTransform: true,
+    ]
+    guard let cgImage = CGImageSourceCreateThumbnailAtIndex(source, 0, options as CFDictionary) else { return nil }
+    return UIImage(cgImage: cgImage)
+  }
+}