feat: Tile compression - backtracking layers level (#137)

Implemented tile compression, which divides the screen into multiple
tiles and changes from the previous screen being detected. If possible,
only a portion of the screen is sent; otherwise, the entire screen is
sent. If it’s possible to restore the previous state by removing a
layer, the layer is removed.

Added an option `compression: overlayTiles(layers = 10)`. The `layers`
parameter specifies the number of layers that can be stacked on top of
each other.

<img width="1183" height="779" alt="image"
src="https://github.com/user-attachments/assets/128b081e-0e25-46e8-8288-7b15f7d63a70"
/>


<!-- CURSOR_SUMMARY -->
---

> [!NOTE]
> **Medium Risk**
> Changes the core capture/compression and RRWeb event-generation paths;
bugs could lead to missing/incorrect frames or increased payloads, but
the change is scoped to session replay data generation (not
auth/security).
> 
> **Overview**
> Introduces a configurable session replay compression mode
(`SessionReplayOptions.compression`) with an `overlayTiles(layers:)`
strategy that periodically emits keyframes and otherwise sends only the
changed screen region.
> 
> Refactors capture/export to produce `ExportFrame` (one or more image
tiles + rects, keyframe flag, and optional `ImageSignature`) via a new
`CaptureManager` + `TileDiffManager`, and updates the RRWeb pipeline to
apply incremental updates using a new `.mutation` `IncrementalSource`
(`MutationData` add/remove nodes with backtracking) instead of always
redrawing a single full-screen canvas.
> 
> Updates supporting RRWeb encodings (`WindowData` sizing, canvas
commands to accept rects), renames `SessionReplayEventGenerator` to
`RRWebEventGenerator`, and adjusts tests and the test app for the new
capture API.
> 
> <sup>Written by [Cursor
Bugbot](https://cursor.com/dashboard?tab=bugbot) for commit
135e672. This will update automatically
on new commits. Configure
[here](https://cursor.com/dashboard?tab=bugbot).</sup>
<!-- /CURSOR_SUMMARY -->

Author: abelonogov-ld

Sources/LaunchDarklySessionReplay/API/SessionReplayOptions.swift

@@ -44,18 +44,26 @@ public struct SessionReplayOptions {
         }
     }
 
+    public enum CompressionMethod {
+        case screenImage
+        case overlayTiles(layers: Int = 10)
+    }
+    
     public var isEnabled: Bool
+    public var compression: CompressionMethod = .overlayTiles()
     public var serviceName: String
     public var privacy = PrivacyOptions()
     public var log: OSLog
 
     public init(isEnabled: Bool = true,
                 serviceName: String = "sessionreplay-swift",
                 privacy: PrivacyOptions = PrivacyOptions(),
+                compression: CompressionMethod = .overlayTiles(),
                 log: OSLog = OSLog(subsystem: "com.launchdarkly", category: "LaunchDarklySessionReplayPlugin")) {
         self.isEnabled = isEnabled
         self.serviceName = serviceName
         self.privacy = privacy
+        self.compression = compression
         self.log = log
     }
 }

Sources/LaunchDarklySessionReplay/Exporter/ImageItemPayload.swift

@@ -7,12 +7,12 @@ struct ImageItemPayload: EventQueueItemPayload {
     }
 
     var timestamp: TimeInterval {
-        exportImage.timestamp
+        exportFrame.timestamp
     }
 
     func cost() -> Int {
-        exportImage.data.count
+        exportFrame.images.reduce(0) { $0 + $1.data.count }
     }
 
-    let exportImage: ExportImage
+    let exportFrame: ExportFrame
 }

…porter/SessionReplayEventGenerator.swift …eplay/Exporter/RRWebEventGenerator.swiftSources/LaunchDarklySessionReplay/Exporter/SessionReplayEventGenerator.swift renamed to Sources/LaunchDarklySessionReplay/Exporter/RRWebEventGenerator.swift Sources/LaunchDarklySessionReplay/Exporter/SessionReplayEventGenerator.swift renamed to Sources/LaunchDarklySessionReplay/Exporter/RRWebEventGenerator.swift

@@ -11,7 +11,7 @@ actor SessionReplayExporter: EventExporting {
     private let context: SessionReplayContext
     private let sessionManager: SessionManaging
     private var isInitializing = false
-    private var eventGenerator: SessionReplayEventGenerator
+    private var eventGenerator: RRWebEventGenerator
     private var log: OSLog
     private var initializedSession: InitializeSessionResponse?
     private var sessionInfo: SessionInfo?
@@ -32,7 +32,7 @@ actor SessionReplayExporter: EventExporting {
         self.replayApiService = replayApiService
         self.sessionManager = context.observabilityContext.sessionManager
         self.title = title
-        self.eventGenerator = SessionReplayEventGenerator(log: context.log, title: title)
+        self.eventGenerator = RRWebEventGenerator(log: context.log, title: title)
         self.log = context.log
         self.sessionInfo = sessionManager.sessionInfo
 
@@ -47,7 +47,7 @@ actor SessionReplayExporter: EventExporting {
 
     private func updateSessionInfo(_ sessionInfo: SessionInfo) async {
         self.sessionInfo = sessionInfo
-        self.eventGenerator = SessionReplayEventGenerator(log: log, title: title)
+        self.eventGenerator = RRWebEventGenerator(log: log, title: title)
         self.initializedSession = nil
     }
 

Sources/LaunchDarklySessionReplay/Exporter/SessionReplayExporter.swift

@@ -20,11 +20,11 @@ final class SessionReplayStats {
         return Double(images) / elapsedTime
     }
 
-    func addExportImage(_ exportImage: ExportImage) {
+    func addExportFrame(_ exportFrame: ExportFrame) {
         images += 1
-        imagesSize += Int64(exportImage.data.count)
-        firstImageTimestamp = firstImageTimestamp ?? exportImage.timestamp
-        lastImageTimestamp = exportImage.timestamp
+        imagesSize += Int64(exportFrame.images.reduce(0) { $0 + $1.data.count })
+        firstImageTimestamp = firstImageTimestamp ?? exportFrame.timestamp
+        lastImageTimestamp = exportFrame.timestamp
 
         logIfNeeded()
     }

Sources/LaunchDarklySessionReplay/Exporter/SessionReplayStats.swift

@@ -69,8 +69,11 @@ struct ClearRect: CommandPayload {
 
     private enum K: String, CodingKey { case property, args }
 
-    init(x: Int, y: Int, width: Int, height: Int) {
-        self.x = x; self.y = y; self.width = width; self.height = height
+    init(rect: CGRect) {
+        self.x = Int(rect.minX)
+        self.y = Int(rect.minY)
+        self.width = Int(rect.size.width)
+        self.height = Int(rect.size.height)
     }
 
     init(from decoder: Decoder) throws {
@@ -104,8 +107,12 @@ struct DrawImage: CommandPayload {
 
     private enum K: String, CodingKey { case property, args }
 
-    init(image: AnyRRNode, dx: Int, dy: Int, dw: Int, dh: Int) {
-        self.image = image; self.dx = dx; self.dy = dy; self.dw = dw; self.dh = dh
+    init(image: AnyRRNode, rect: CGRect) {
+        self.image = image
+        self.dx = Int(rect.minX)
+        self.dy = Int(rect.minY)
+        self.dw = Int(rect.size.width)
+        self.dh = Int(rect.size.height)
     }
 
     init(from decoder: Decoder) throws {
@@ -126,8 +133,11 @@ struct DrawImage: CommandPayload {
         try a.encode(image)
         try a.encode(dx)
         try a.encode(dy)
-        try a.encode(dw)
-        try a.encode(dh)
+        
+        if (dx > 0 || dy > 0) {
+            try a.encode(dw)
+            try a.encode(dh)
+        }
     }
 }
 

Sources/LaunchDarklySessionReplay/RRWeb/CanvasDrawData.swift

@@ -26,6 +26,76 @@ struct DomData: EventDataProtocol {
     }
 }
 
+// MARK: - DOM Mutation Data (for incremental DOM updates)
+
+struct MutationData: EventDataProtocol {
+    var source: IncrementalSource
+    var adds: [AddedNode]
+    var removes: [RemovedNode]
+    var texts: [TextMutation]
+    var attributes: [AttributeMutation]
+    
+    // Transitional
+    var canvasSize: Int
+    
+    init(adds: [AddedNode] = [],
+         removes: [RemovedNode] = [],
+         texts: [TextMutation] = [],
+         attributes: [AttributeMutation] = [],
+         canvasSize: Int = 0) {
+        self.source = .mutation
+        self.adds = adds
+        self.removes = removes
+        self.texts = texts
+        self.attributes = attributes
+        self.canvasSize = canvasSize
+    }
+    
+    private enum CodingKeys: String, CodingKey {
+        case source, adds, removes, texts, attributes
+    }
+    
+    init(from decoder: Decoder) throws {
+        let container = try decoder.container(keyedBy: CodingKeys.self)
+        self.source = try container.decode(IncrementalSource.self, forKey: .source)
+        self.adds = try container.decode([AddedNode].self, forKey: .adds)
+        self.removes = try container.decode([RemovedNode].self, forKey: .removes)
+        self.texts = try container.decode([TextMutation].self, forKey: .texts)
+        self.attributes = try container.decode([AttributeMutation].self, forKey: .attributes)
+        self.canvasSize = 0
+    }
+    
+    func encode(to encoder: Encoder) throws {
+        var container = encoder.container(keyedBy: CodingKeys.self)
+        try container.encode(source, forKey: .source)
+        try container.encode(adds, forKey: .adds)
+        try container.encode(removes, forKey: .removes)
+        try container.encode(texts, forKey: .texts)
+        try container.encode(attributes, forKey: .attributes)
+    }
+}
+
+struct AddedNode: Codable {
+    var parentId: Int
+    var nextId: Int?
+    var node: EventNode
+}
+
+struct RemovedNode: Codable {
+    var parentId: Int
+    var id: Int
+}
+
+struct TextMutation: Codable {
+    var id: Int
+    var value: String
+}
+
+struct AttributeMutation: Codable {
+    var id: Int
+    var attributes: [String: String?]
+}
+
 struct EventNode: Codable {
     var type: NodeType
     var name: String?

Sources/LaunchDarklySessionReplay/RRWeb/DomData.swift

@@ -33,6 +33,8 @@ struct AnyEventData: Codable {
                 self.value = try CanvasDrawData(from: decoder)
             } else if src == .mouseMove {
                 self.value = try MouseMoveEventData(from: decoder)
+            } else if src == .mutation {
+                self.value = try MutationData(from: decoder)
             } else {
                 self.value = try MouseInteractionData(from: decoder)
             }

Sources/LaunchDarklySessionReplay/RRWeb/Event.swift

@@ -5,9 +5,9 @@ struct WindowData: EventDataProtocol {
     var width: Int?
     var height: Int?
 
-    init(href: String? = nil, width: Int? = nil, height: Int? = nil) {
+    init(href: String? = nil, size: CGSize) {
         self.href = href
-        self.width = width
-        self.height = height
+        self.width = Int(size.width)
+        self.height = Int(size.height)
     }
 }

Sources/LaunchDarklySessionReplay/RRWeb/WindowData.swift

@@ -3,8 +3,9 @@ import Combine
 import LaunchDarklyObservability
 import UIKit
 
-final class SnapshotTaker: EventSource {
-    private let captureService: ScreenCaptureService
+final class CaptureManager: EventSource {
+    private let captureService: ImageCaptureService
+    private let tileDiffManager: TileDiffManager
     private let appLifecycleManager: AppLifecycleManaging
     @MainActor
     private var displayLink: CADisplayLink?
@@ -29,10 +30,12 @@ final class SnapshotTaker: EventSource {
         }
     }
 
-    init(captureService: ScreenCaptureService,
+    init(captureService: ImageCaptureService,
+         compression: SessionReplayOptions.CompressionMethod,
          appLifecycleManager: AppLifecycleManaging,
          eventQueue: EventQueue) {
         self.captureService = captureService
+        self.tileDiffManager = TileDiffManager(compression: compression, scale: 1.0)
         self.eventQueue = eventQueue
         self.appLifecycleManager = appLifecycleManager
 
@@ -115,21 +118,44 @@ final class SnapshotTaker: EventSource {
         let lastFrameDispatchTime = DispatchTime.now()
         self.lastFrameDispatchTime = lastFrameDispatchTime
 
-        captureService.captureUIImage { capturedImage in
-            guard let capturedImage else {
+        captureService.captureRawFrame { rawFrame in
+            guard let rawFrame else {
+                // dropped frame
+                return
+            }
+
+            guard let capturedFrame = self.tileDiffManager.computeDiffCapture(frame: rawFrame) else {
                 // dropped frame
                 return
             }
 
-            guard let exportImage = capturedImage.image.exportImage(format: .jpeg(quality: 0.3),
-                                                                    originalSize: capturedImage.renderSize,
-                                                                    scale: capturedImage.scale,
-                                                                    timestamp: capturedImage.timestamp,
-                                                                    orientation: capturedImage.orientation) else {
+            guard let exportFrame = self.exportFrame(from: capturedFrame) else {
+                // dropped frame
                 return
             }
 
-            await self.eventQueue.send(ImageItemPayload(exportImage: exportImage))
+            await self.eventQueue.send(ImageItemPayload(exportFrame: exportFrame))
         }
     }
+    
+    private func exportFrame(from capturedFrame: TiledFrame) -> ExportFrame? {
+        let format = ExportFormat.jpeg(quality: 0.3)
+        var exportedFrames = [ExportFrame.ExportImage]()
+        for tile in capturedFrame.tiles {
+            guard let exportedFrame = tile.image.asExportedImage(format: format, rect: tile.rect) else {
+                return nil
+            }
+            exportedFrames.append(exportedFrame)
+        }
+        guard !exportedFrames.isEmpty else { return nil }
+        
+        return ExportFrame(images: exportedFrames,
+                           originalSize: capturedFrame.originalSize,
+                           scale: capturedFrame.scale,
+                           format: format,
+                           timestamp: capturedFrame.timestamp,
+                           orientation: capturedFrame.orientation,
+                           isKeyframe: capturedFrame.isKeyframe,
+                           imageSignature: capturedFrame.imageSignature)
+    }
 }