sitepong 0.2.3 → 0.2.4

package/ios/WatchtowerCore/Screenshotter.swift

@@ -0,0 +1,163 @@
+#if canImport(UIKit)
+import UIKit
+import CoreImage
+
+/// One-shot screenshot capture (§3.4) + redaction (§5).
+/// Renders the key window at 0.5× via `UIGraphicsImageRenderer`, blurs sensitive
+/// rects BEFORE hashing/upload, then hands back redacted RGBA + PNG.
+enum Screenshotter {
+
+    static let captureScale: CGFloat = 0.5
+    static let blurRadius: Double = 16 // radius >= 16 px at capture scale (§5)
+
+    struct Capture {
+        let rgba: [UInt8]
+        let width: Int
+        let height: Int
+        let pngBase64: String
+    }
+
+    /// True when the window's layout is mid-animation and a captured frame would be
+    /// a transient in-between state rather than the settled, canonical screen (§3.4).
+    /// Covers: a scroll view actively dragging or decelerating (a swipe gesture whose
+    /// `.ended` fires mid-fling), and a view-controller push/pop transition in flight.
+    /// Used to defer template storage so dedup stays stable across runs.
+    static func isLayoutInFlight(in window: UIWindow) -> Bool {
+        if scrollViewAnimating(in: window) { return true }
+        if viewControllerTransitioning(window: window) { return true }
+        return false
+    }
+
+    private static func scrollViewAnimating(in view: UIView) -> Bool {
+        if let sv = view as? UIScrollView, sv.isDragging || sv.isDecelerating || sv.isZooming {
+            return true
+        }
+        for sub in view.subviews where scrollViewAnimating(in: sub) { return true }
+        return false
+    }
+
+    private static func viewControllerTransitioning(window: UIWindow) -> Bool {
+        guard let root = window.rootViewController else { return false }
+        return viewControllerTransitioning(root)
+    }
+
+    /// Recurse the FULL view-controller tree: children as well as the presented
+    /// chain. A React Native app nests its navigation controller (RNSScreen /
+    /// react-native-screens) inside the root RCTRootViewController as a CHILD,
+    /// so walking only root.presentedViewController misses every RN push/pop
+    /// transition and mid-slide frames get stored as canonical templates.
+    private static func viewControllerTransitioning(_ vc: UIViewController) -> Bool {
+        if vc.transitionCoordinator != nil { return true }
+        if let presented = vc.presentedViewController,
+           viewControllerTransitioning(presented) { return true }
+        for child in vc.children where viewControllerTransitioning(child) {
+            return true
+        }
+        return false
+    }
+
+    /// Collect sensitive rects (window space) for a window:
+    /// secureTextEntry fields + watchtowerSensitive UIViews + SwiftUI .watchtowerSensitive().
+    static func sensitiveRects(in window: UIWindow) -> [CGRect] {
+        var rects: [CGRect] = []
+        func walk(_ view: UIView) {
+            var isSensitive = view.watchtowerSensitive
+            if let tf = view as? UITextField, tf.isSecureTextEntry { isSensitive = true }
+            if isSensitive {
+                rects.append(view.convert(view.bounds, to: window))
+            }
+            for sub in view.subviews { walk(sub) }
+        }
+        walk(window)
+        rects.append(contentsOf: WatchtowerRegistry.shared.sensitiveRects(in: window))
+        return rects
+    }
+
+    struct RawCapture {
+        let image: UIImage
+        let sensitiveRects: [CGRect]
+        let scale: CGFloat
+    }
+
+    /// Main-thread-only work: raw render (UIKit drawing) + sensitive-rect walk.
+    /// Everything downstream (blur, RGBA extraction, hashing, PNG encode) runs
+    /// off-main via `redact(_:)` — never call this inside the touch-delivery
+    /// call stack; hop to the next runloop turn first.
+    static func renderRaw(window: UIWindow) -> RawCapture? {
+        let bounds = window.bounds
+        guard bounds.width > 0, bounds.height > 0 else { return nil }
+
+        let format = UIGraphicsImageRendererFormat()
+        format.scale = captureScale
+        format.opaque = true
+        let renderer = UIGraphicsImageRenderer(bounds: bounds, format: format)
+
+        let rects = sensitiveRects(in: window)
+
+        let image = renderer.image { _ in
+            window.drawHierarchy(in: bounds, afterScreenUpdates: false)
+        }
+        return RawCapture(image: image, sensitiveRects: rects, scale: captureScale)
+    }
+
+    /// Blur the sensitive rects of a raw capture (§5). CoreImage only — safe to
+    /// run off the main thread.
+    static func redact(_ raw: RawCapture) -> UIImage {
+        guard !raw.sensitiveRects.isEmpty else { return raw.image }
+        return blur(image: raw.image, rects: raw.sensitiveRects, captureScale: raw.scale)
+    }
+
+    private static func blur(image: UIImage, rects: [CGRect], captureScale: CGFloat) -> UIImage {
+        guard let cgImage = image.cgImage else { return image }
+        let ciContext = CIContext(options: nil)
+        let pixelW = cgImage.width
+        let pixelH = cgImage.height
+        let base = CIImage(cgImage: cgImage)
+
+        // Build a fully-blurred version of the whole image once.
+        let clamped = base.clampedToExtent()
+        guard let blurFilter = CIFilter(name: "CIGaussianBlur") else { return image }
+        blurFilter.setValue(clamped, forKey: kCIInputImageKey)
+        blurFilter.setValue(blurRadius, forKey: kCIInputRadiusKey)
+        guard let blurredFull = blurFilter.outputImage?.cropped(to: base.extent) else { return image }
+
+        // Composite: start with sharp base, paste blurred patches over sensitive rects.
+        var composite = base
+        for rect in rects {
+            // Convert window-space (points) rect to pixel space (origin top-left ->
+            // CoreImage origin bottom-left).
+            let px = rect.origin.x * captureScale
+            let pyTop = rect.origin.y * captureScale
+            let pw = rect.size.width * captureScale
+            let ph = rect.size.height * captureScale
+            let pyBottomLeft = CGFloat(pixelH) - pyTop - ph
+            let pixelRect = CGRect(x: px, y: pyBottomLeft, width: pw, height: ph)
+                .intersection(CGRect(x: 0, y: 0, width: pixelW, height: pixelH))
+            guard !pixelRect.isNull, pixelRect.width > 0, pixelRect.height > 0 else { continue }
+
+            let patch = blurredFull.cropped(to: pixelRect)
+            composite = patch.composited(over: composite)
+        }
+
+        guard let outCG = ciContext.createCGImage(composite, from: base.extent) else { return image }
+        return UIImage(cgImage: outCG)
+    }
+
+    /// Extract tightly-packed RGBA bytes from a CGImage.
+    static func rgbaBytes(from image: UIImage) -> (rgba: [UInt8], width: Int, height: Int)? {
+        guard let cg = image.cgImage else { return nil }
+        let width = cg.width
+        let height = cg.height
+        var data = [UInt8](repeating: 0, count: width * height * 4)
+        let colorSpace = CGColorSpaceCreateDeviceRGB()
+        let bitmapInfo = CGImageAlphaInfo.premultipliedLast.rawValue
+        guard let ctx = CGContext(
+            data: &data, width: width, height: height,
+            bitsPerComponent: 8, bytesPerRow: width * 4,
+            space: colorSpace, bitmapInfo: bitmapInfo
+        ) else { return nil }
+        ctx.draw(cg, in: CGRect(x: 0, y: 0, width: width, height: height))
+        return (data, width, height)
+    }
+}
+#endif

package/ios/WatchtowerCore/SwiftUIModifiers.swift

@@ -0,0 +1,78 @@
+#if canImport(SwiftUI) && canImport(UIKit)
+import SwiftUI
+import UIKit
+
+/// Internal reporter view that publishes its window-space frame into the
+/// registry whenever layout changes, then resolves cleanly on disappear.
+private struct WatchtowerReporter: UIViewRepresentable {
+    let id: String?
+    let screenName: String?
+    let sensitive: Bool
+
+    func makeUIView(context: Context) -> ReporterView {
+        let v = ReporterView()
+        v.isUserInteractionEnabled = false
+        v.backgroundColor = .clear
+        v.tagId = id
+        v.screenName = screenName
+        v.sensitive = sensitive
+        return v
+    }
+
+    func updateUIView(_ uiView: ReporterView, context: Context) {
+        uiView.tagId = id
+        uiView.screenName = screenName
+        uiView.sensitive = sensitive
+        uiView.publish()
+    }
+
+    static func dismantleUIView(_ uiView: ReporterView, coordinator: ()) {
+        WatchtowerRegistry.shared.remove(token: ObjectIdentifier(uiView))
+    }
+
+    final class ReporterView: UIView {
+        var tagId: String?
+        var screenName: String?
+        var sensitive: Bool = false
+
+        override func didMoveToWindow() {
+            super.didMoveToWindow()
+            publish()
+        }
+
+        override func layoutSubviews() {
+            super.layoutSubviews()
+            publish()
+        }
+
+        func publish() {
+            guard let window = window, let superview = superview else { return }
+            // The reporter is a zero-or-overlay view; report the *superview*'s
+            // frame in window space, which corresponds to the modified content.
+            let frame = superview.convert(superview.bounds, to: window)
+            let region = TaggedRegion(id: tagId, screenName: screenName,
+                                      sensitive: sensitive, frameInWindow: frame,
+                                      window: window)
+            WatchtowerRegistry.shared.update(token: ObjectIdentifier(self), region: region)
+        }
+    }
+}
+
+public extension View {
+    /// Declares the enclosing SwiftUI subtree as a named screen (§3.2).
+    func watchtowerScreen(_ name: String) -> some View {
+        self.background(WatchtowerReporter(id: nil, screenName: name, sensitive: false))
+    }
+
+    /// Tags this view with a stable element id used as `element_id` (§3.3).
+    func watchtowerTag(_ id: String) -> some View {
+        self.background(WatchtowerReporter(id: id, screenName: nil, sensitive: false))
+    }
+
+    /// Marks this view's region as sensitive; it is blurred before hashing /
+    /// upload (§5).
+    func watchtowerSensitive() -> some View {
+        self.background(WatchtowerReporter(id: nil, screenName: nil, sensitive: true))
+    }
+}
+#endif

package/ios/WatchtowerCore/Swizzling.swift

@@ -0,0 +1,59 @@
+#if canImport(UIKit)
+import UIKit
+import ObjectiveC
+
+/// Centralized method swizzling for UIWindow.sendEvent and
+/// UIViewController.viewDidAppear. Installed once, idempotent. All capture work
+/// is wrapped so it can never crash the host app.
+enum Swizzling {
+    private static var installed = false
+
+    static func installIfNeeded() {
+        guard !installed else { return }
+        installed = true
+        swizzle(
+            cls: UIWindow.self,
+            original: #selector(UIWindow.sendEvent(_:)),
+            swizzled: #selector(UIWindow.wt_sendEvent(_:))
+        )
+        swizzle(
+            cls: UIViewController.self,
+            original: #selector(UIViewController.viewDidAppear(_:)),
+            swizzled: #selector(UIViewController.wt_viewDidAppear(_:))
+        )
+    }
+
+    private static func swizzle(cls: AnyClass, original: Selector, swizzled: Selector) {
+        guard let orig = class_getInstanceMethod(cls, original),
+              let swiz = class_getInstanceMethod(cls, swizzled) else { return }
+        let didAdd = class_addMethod(cls, original,
+                                     method_getImplementation(swiz),
+                                     method_getTypeEncoding(swiz))
+        if didAdd {
+            class_replaceMethod(cls, swizzled,
+                                method_getImplementation(orig),
+                                method_getTypeEncoding(orig))
+        } else {
+            method_exchangeImplementations(orig, swiz)
+        }
+    }
+}
+
+extension UIWindow {
+    @objc func wt_sendEvent(_ event: UIEvent) {
+        // Call original first (this is the swizzled-in original IMP).
+        self.wt_sendEvent(event)
+        // Capture is best-effort and must never throw / crash.
+        guard WatchtowerEngine.shared.isRunning else { return }
+        WatchtowerEngine.shared.handle(event: event, in: self)
+    }
+}
+
+extension UIViewController {
+    @objc func wt_viewDidAppear(_ animated: Bool) {
+        self.wt_viewDidAppear(animated)
+        guard WatchtowerEngine.shared.isRunning else { return }
+        WatchtowerEngine.shared.didAppear(viewController: self)
+    }
+}
+#endif

package/ios/WatchtowerCore/TapEvent.swift

@@ -0,0 +1,61 @@
+import Foundation
+
+/// A single capture event — the tagged union from spec §1.1. `type` selects
+/// which optional fields are populated ("tap" | "screen_view" | "session_start"
+/// | "session_end"). Synthesized Codable omits nil optionals on the wire.
+public struct CaptureEvent: Codable {
+    // Common fields (every type)
+    public var type: String
+    public var session_id: String
+    public var sequence: UInt64
+    public var timestamp: String
+    public var platform: String
+    public var app_version: String?
+    public var distinct_id: String?
+    public var device_model: String?
+    public var os_version: String?
+
+    // screen_view
+    public var screen_name: String?
+    public var prev_screen_name: String?
+
+    // session_end
+    public var duration_ms: UInt64?
+    public var reason: String?
+
+    // tap
+    public var screen_fp: String?
+    public var element_id: String?
+    public var element_label: String?
+    public var element_role: String?
+    public var x: Double?
+    public var y: Double?
+    public var viewport_w: UInt?
+    public var viewport_h: UInt?
+    public var frame_hash: String?
+    /// Client-side heuristic (§1.1): tap produced no observable response.
+    /// nil when false or undetermined — never sent as false.
+    public var dead: Bool?
+}
+
+struct TapsBatch: Codable {
+    let events: [CaptureEvent]
+}
+
+struct TemplateUpload: Codable {
+    let route_name: String
+    let p_hash: String
+    let width: Int
+    let height: Int
+    let image_base64: String
+}
+
+struct FrameUpload: Codable {
+    let session_id: String
+    let timestamp: String
+    let screen_name: String
+    let frame_hash: String
+    let width: Int
+    let height: Int
+    let image_base64: String
+}

package/ios/WatchtowerCore/Transport.swift

@@ -0,0 +1,136 @@
+import Foundation
+
+/// URLSession-based transport: batches tap events (§1.3) and uploads screenshot
+/// templates on a miss (§1.2). All work is dispatched onto a private serial
+/// queue; failures retry with backoff and drop after N attempts. Never throws to
+/// the host app.
+final class Transport {
+    private let apiKey: String
+    private let projectId: String
+    private let endpoint: URL
+    private let session: URLSession
+    private let queue = DispatchQueue(label: "com.watchtower.transport")
+
+    private var buffer: [CaptureEvent] = []
+    private var flushTimer: DispatchSourceTimer?
+
+    private let batchSize = 50
+    private let flushInterval: TimeInterval = 10
+    private let maxRetries = 3
+
+    init(apiKey: String, projectId: String, endpoint: URL) {
+        self.apiKey = apiKey
+        self.projectId = projectId
+        self.endpoint = endpoint
+        let config = URLSessionConfiguration.default
+        config.timeoutIntervalForRequest = 15
+        self.session = URLSession(configuration: config)
+        startTimer()
+    }
+
+    private func startTimer() {
+        let t = DispatchSource.makeTimerSource(queue: queue)
+        t.schedule(deadline: .now() + flushInterval, repeating: flushInterval)
+        t.setEventHandler { [weak self] in self?.flushLocked() }
+        t.resume()
+        flushTimer = t
+    }
+
+    func enqueue(_ event: CaptureEvent) {
+        queue.async { [weak self] in
+            guard let self = self else { return }
+            self.buffer.append(event)
+            if self.buffer.count >= self.batchSize {
+                self.flushLocked()
+            }
+        }
+    }
+
+    /// Flush remaining events (called on background / teardown).
+    func flush() {
+        queue.async { [weak self] in self?.flushLocked() }
+    }
+
+    /// Synchronous flush used at teardown to give pending events a chance to send.
+    func flushAndWait(timeout: TimeInterval = 3) {
+        let sem = DispatchSemaphore(value: 0)
+        queue.async { [weak self] in
+            self?.flushLocked()
+            sem.signal()
+        }
+        _ = sem.wait(timeout: .now() + timeout)
+    }
+
+    private func flushLocked() {
+        guard !buffer.isEmpty else { return }
+        let batch = buffer
+        buffer.removeAll(keepingCapacity: true)
+        postTaps(batch, attempt: 0)
+    }
+
+    private func headers(for request: inout URLRequest) {
+        request.setValue(projectId, forHTTPHeaderField: "X-Project-ID")
+        request.setValue(apiKey, forHTTPHeaderField: "X-API-Key")
+        request.setValue("application/json", forHTTPHeaderField: "Content-Type")
+    }
+
+    private func postTaps(_ events: [CaptureEvent], attempt: Int) {
+        guard let data = try? JSONEncoder().encode(TapsBatch(events: events)) else { return }
+        var req = URLRequest(url: endpoint.appendingPathComponent("api/taps"))
+        req.httpMethod = "POST"
+        headers(for: &req)
+        req.httpBody = data
+
+        session.dataTask(with: req) { [weak self] _, resp, err in
+            guard let self = self else { return }
+            let ok = (resp as? HTTPURLResponse).map { (200..<300).contains($0.statusCode) } ?? false
+            if !ok || err != nil {
+                if attempt < self.maxRetries {
+                    let delay = pow(2.0, Double(attempt)) // 1,2,4s
+                    self.queue.asyncAfter(deadline: .now() + delay) {
+                        self.postTaps(events, attempt: attempt + 1)
+                    }
+                }
+                // else: drop silently (never crash the host).
+            }
+        }.resume()
+    }
+
+    /// Upload a redacted screenshot template. Calls `completion(isNew)` on success.
+    func postTemplate(routeName: String, pHash: String, width: Int, height: Int,
+                      pngBase64: String, completion: ((Bool) -> Void)? = nil) {
+        let payload = TemplateUpload(route_name: routeName, p_hash: pHash,
+                                     width: width, height: height, image_base64: pngBase64)
+        guard let data = try? JSONEncoder().encode(payload) else { completion?(false); return }
+        var req = URLRequest(url: endpoint.appendingPathComponent("api/taps/template"))
+        req.httpMethod = "POST"
+        headers(for: &req)
+        req.httpBody = data
+
+        session.dataTask(with: req) { data, resp, _ in
+            let ok = (resp as? HTTPURLResponse).map { (200..<300).contains($0.statusCode) } ?? false
+            var isNew = false
+            if ok, let data = data,
+               let obj = try? JSONSerialization.jsonObject(with: data) as? [String: Any] {
+                isNew = (obj["isNew"] as? Bool) ?? false
+            }
+            completion?(ok ? isNew : false)
+        }.resume()
+    }
+
+    /// Upload a Layer-3 sampled session frame (§1.4). Fire-and-forget: frames
+    /// are best-effort and never retried (they are replay enrichment, not the
+    /// canonical record).
+    func postFrame(sessionId: String, timestamp: String, screenName: String,
+                   frameHash: String, width: Int, height: Int, pngBase64: String) {
+        let payload = FrameUpload(session_id: sessionId, timestamp: timestamp,
+                                  screen_name: screenName, frame_hash: frameHash,
+                                  width: width, height: height, image_base64: pngBase64)
+        guard let data = try? JSONEncoder().encode(payload) else { return }
+        var req = URLRequest(url: endpoint.appendingPathComponent("api/frames"))
+        req.httpMethod = "POST"
+        headers(for: &req)
+        req.httpBody = data
+        session.dataTask(with: req).resume()
+    }
+}

package/ios/WatchtowerCore/UIViewExtensions.swift

@@ -0,0 +1,31 @@
+#if canImport(UIKit)
+import UIKit
+import ObjectiveC
+
+private var watchtowerTagKey: UInt8 = 0
+private var watchtowerSensitiveKey: UInt8 = 0
+
+public extension UIView {
+    /// A stable element id for tap attribution (§3.3, resolution order #2).
+    var watchtowerTag: String? {
+        get { objc_getAssociatedObject(self, &watchtowerTagKey) as? String }
+        set { objc_setAssociatedObject(self, &watchtowerTagKey, newValue, .OBJC_ASSOCIATION_COPY_NONATOMIC) }
+    }
+
+    /// Marks this UIKit view as sensitive; blurred before hashing / upload (§5).
+    var watchtowerSensitive: Bool {
+        get { (objc_getAssociatedObject(self, &watchtowerSensitiveKey) as? NSNumber)?.boolValue ?? false }
+        set { objc_setAssociatedObject(self, &watchtowerSensitiveKey, NSNumber(value: newValue), .OBJC_ASSOCIATION_RETAIN_NONATOMIC) }
+    }
+}
+
+private var watchtowerScreenNameKey: UInt8 = 0
+
+public extension UIViewController {
+    /// Explicit screen identity override (§3.2, highest precedence).
+    var watchtowerScreenName: String? {
+        get { objc_getAssociatedObject(self, &watchtowerScreenNameKey) as? String }
+        set { objc_setAssociatedObject(self, &watchtowerScreenNameKey, newValue, .OBJC_ASSOCIATION_COPY_NONATOMIC) }
+    }
+}
+#endif

package/ios/WatchtowerCore/Watchtower.swift

@@ -0,0 +1,80 @@
+import Foundation
+
+/// Public entrypoint for the Watchtower capture engine (spec §3).
+/// Bridge-free: zero React/RN imports. All methods are exception-safe and a
+/// no-op if `start` was not called (except `start` itself).
+public enum Watchtower {
+
+    /// Begin capturing taps + gated screenshots and uploading to `endpoint`.
+    ///
+    /// `platform` stamps the `platform` field on every emitted TapEvent (spec
+    /// §1.1). It defaults to `"ios"` for native hosts; the React Native bridge
+    /// (§4) passes `"react-native-ios"`. This is the only host-overridable
+    /// identity knob — capture logic is identical regardless of platform.
+    public static func start(apiKey: String, projectId: String,
+                             endpoint: URL, sampleRate: Double = 0.1,
+                             platform: String = "ios") {
+        #if canImport(UIKit)
+        // Ensure UIKit work happens on the main thread.
+        if Thread.isMainThread {
+            WatchtowerEngine.shared.start(apiKey: apiKey, projectId: projectId,
+                                          endpoint: endpoint, sampleRate: sampleRate,
+                                          platform: platform)
+        } else {
+            DispatchQueue.main.async {
+                WatchtowerEngine.shared.start(apiKey: apiKey, projectId: projectId,
+                                              endpoint: endpoint, sampleRate: sampleRate,
+                                              platform: platform)
+            }
+        }
+        #endif
+    }
+
+    public static func stop() {
+        #if canImport(UIKit)
+        WatchtowerEngine.shared.stop()
+        #endif
+    }
+
+    /// Explicit screen identity, overrides auto-detection until the next call
+    /// (or the next UIKit screen appearance).
+    public static func setScreen(_ name: String) {
+        #if canImport(UIKit)
+        WatchtowerEngine.shared.setScreen(name)
+        #endif
+    }
+
+    /// Force a one-shot capture of the current screen (gated on dedup).
+    public static func captureScreenshot() {
+        #if canImport(UIKit)
+        if Thread.isMainThread {
+            WatchtowerEngine.shared.captureScreenshot()
+        } else {
+            DispatchQueue.main.async { WatchtowerEngine.shared.captureScreenshot() }
+        }
+        #endif
+    }
+
+    /// Identity (§1.1 distinct_id): stamped on every subsequent event. Pass nil
+    /// to return to anonymous. The RN layer feeds the SDK's identify() through
+    /// this; native hosts call it directly.
+    public static func setUser(_ distinctId: String?) {
+        #if canImport(UIKit)
+        if Thread.isMainThread {
+            WatchtowerEngine.shared.setUser(distinctId)
+        } else {
+            DispatchQueue.main.async { WatchtowerEngine.shared.setUser(distinctId) }
+        }
+        #endif
+    }
+
+    /// The engine's current session id, or nil when not running. Attach this to
+    /// the host SDK's error/analytics events — it is the replay/error join key.
+    public static var sessionId: String? {
+        #if canImport(UIKit)
+        return WatchtowerEngine.shared.currentSessionId
+        #else
+        return nil
+        #endif
+    }
+}