sitepong 0.2.13 → 0.2.15

package/ios/ScreenRecorder/ScreenRecorderModule.swift

@@ -123,10 +123,16 @@ public class SitePongScreenRecorderModule: Module {
       let platform = config["platform"] as? String ?? "react-native-ios"
       // Idle grace before a reopen rolls a new session (default 30s).
       let sessionGraceMs = config["sessionGraceMs"] as? Double ?? 30_000
+      // Release channel + suppression list forwarded from the JS SDK config.
+      // nil channel → WatchtowerCore auto-resolves (debug→development,
+      // release→production); ignoreChannels defaults to ["development"].
+      let channel = config["channel"] as? String
+      let ignoreChannels = config["ignoreChannels"] as? [String] ?? ["development"]
       guard let endpoint = URL(string: endpointStr) else { return }
       Watchtower.start(apiKey: apiKey, projectId: projectId,
                        endpoint: endpoint, sampleRate: sampleRate,
-                       platform: platform, sessionGraceMs: sessionGraceMs)
+                       platform: platform, sessionGraceMs: sessionGraceMs,
+                       channel: channel, ignoreChannels: ignoreChannels)
     }
 
     Function("watchtowerStop") {
@@ -141,8 +147,8 @@ public class SitePongScreenRecorderModule: Module {
       Watchtower.captureScreenshot()
     }
 
-    Function("watchtowerSetUser") { (distinctId: String?) in
-      Watchtower.setUser(distinctId)
+    Function("watchtowerSetUser") { (distinctId: String?, email: String?, name: String?) in
+      Watchtower.setUser(distinctId, email: email, name: name)
     }
 
     Function("watchtowerGetSessionId") { () -> String? in

package/ios/WatchtowerCore/StructuralRecorder.swift

@@ -12,8 +12,27 @@
 //
 // One platform-neutral core, two capture adapters (fiber / UIView), one stored
 // stream, one dashboard Player.
+//
+// Parity with the RN structural SDK (all implemented here):
+//  • Sensitive masking — honors watchtowerSensitive UIViews + SwiftUI
+//    .watchtowerSensitive() regions (via WatchtowerRegistry), not just secure fields.
+//  • Scroll fidelity — native nodes carry ABSOLUTE window frames, so scroll shows
+//    up as frame deltas; we densify sampling while a UIScrollView is moving so fast
+//    scrolls aren't aliased (no SetNodeScroll — that would double-translate here).
+//  • Session follow — re-keys onto WatchtowerEngine's rolled session id (shared id,
+//    roll-in-lockstep) via .sitePongWatchtowerSessionDidRoll, the native analogue
+//    of the RN provider's watchForRoll.
+//  • Crash-flush — a best-effort synchronous flush on uncaught exception.
+//  • Adaptive sampling — a heavy tree walk backs the sampler off for a few ticks
+//    so capture never pins the main thread.
 import UIKit
 
+extension Notification.Name {
+    /// Posted by WatchtowerEngine on session start/roll so the structural recorder
+    /// can share the session id and roll in lockstep.
+    static let sitePongWatchtowerSessionDidRoll = Notification.Name("SitePongWatchtowerSessionDidRoll")
+}
+
 public final class SitePongStructuralCapture {
     public static let shared = SitePongStructuralCapture()
 
@@ -22,12 +41,12 @@ public final class SitePongStructuralCapture {
     private var projectId: String?
     private var platform = "ios"
     private var sessionId = ""
+    private var installId: String?
     private var startedAt = Date()
     private var ids: [ObjectIdentifier: Int] = [:]
     private var nextId = 1
     private var events: [[String: Any]] = []
     private var screen = ""
-    private var sampleTimer: Timer?
     private var flushTimer: Timer?
     private var running = false
 
@@ -39,6 +58,20 @@ public final class SitePongStructuralCapture {
     private var flushedEventCount = 0
     private var sending = false
 
+    // Scroll fidelity: last seen content offset per node id; while any scroll view
+    // moves we sample faster so the frame-delta capture isn't aliased.
+    private var scrollOffsets: [Int: CGPoint] = [:]
+    private var scanScrolls: [(id: Int, off: CGPoint)] = []
+    private var scrollQuietTicks = 3
+
+    // Adaptive sampling: a walk over `walkBudgetMs` backs off proportionally.
+    private let walkBudgetMs: Double = 24
+    private let maxOverloadSkip = 8
+    private var overloadSkip = 0
+
+    // Crash-flush chains any pre-existing uncaught-exception handler.
+    private static var previousExceptionHandler: (@convention(c) (NSException) -> Void)?
+
     private func now() -> Int { Int(Date().timeIntervalSince(startedAt) * 1000) }
 
     /// Start capturing. `endpoint` is the ingest base URL (e.g.
@@ -50,6 +83,7 @@ public final class SitePongStructuralCapture {
         self.projectId = projectId
         self.sessionId = sessionId
         self.platform = platform
+        self.installId = UIDevice.current.identifierForVendor?.uuidString
         self.startedAt = Date()
         self.running = true
 
@@ -63,7 +97,7 @@ public final class SitePongStructuralCapture {
             g.delegate = SPStructuralTapDelegate.shared
             w.addGestureRecognizer(g)
         }
-        sampleTimer = Timer.scheduledTimer(withTimeInterval: 0.12, repeats: true) { [weak self] _ in self?.sample() }
+        scheduleSample()
         flushTimer = Timer.scheduledTimer(withTimeInterval: 4.0, repeats: true) { [weak self] _ in self?.flush() }
 
         // Flush on background so the tail isn't stranded when timers suspend.
@@ -71,6 +105,12 @@ public final class SitePongStructuralCapture {
             self, selector: #selector(onBackground),
             name: UIApplication.didEnterBackgroundNotification, object: nil
         )
+        // Follow WatchtowerEngine's session so structural + tap streams share one id.
+        NotificationCenter.default.addObserver(
+            self, selector: #selector(onSessionRoll(_:)),
+            name: .sitePongWatchtowerSessionDidRoll, object: nil
+        )
+        installCrashFlush()
     }
 
     @objc private func onBackground() {
@@ -78,6 +118,29 @@ public final class SitePongStructuralCapture {
         flush()
     }
 
+    /// WatchtowerEngine rolled (or started) a session — re-key onto it so the
+    /// structural stream follows the same (linked) session id. Mirrors the RN
+    /// provider's stop()+begin() on a session roll.
+    @objc private func onSessionRoll(_ note: Notification) {
+        guard running, let newId = note.userInfo?["sessionId"] as? String, newId != sessionId else { return }
+        // Best-effort ship the old-session tail under the OLD id (fire-and-forget,
+        // decoupled from the flush cursor so it can't corrupt the new session).
+        if !events.isEmpty, let w = keyWindow() {
+            sendBestEffort(batch: events, seqStart: flushedEventCount, sessionId: sessionId,
+                           viewport: (Int(w.bounds.width), Int(w.bounds.height)))
+        }
+        // Reset to a clean new session and take a fresh full snapshot.
+        sessionId = newId
+        events.removeAll(keepingCapacity: true)
+        ids.removeAll(keepingCapacity: true)
+        nextId = 1
+        flushedEventCount = 0
+        scrollOffsets.removeAll(keepingCapacity: true)
+        screen = ""
+        startedAt = Date()
+        sample()
+    }
+
     public func setScreen(_ name: String) {
         guard running, name != screen else { return }
         sample()
@@ -88,11 +151,8 @@ public final class SitePongStructuralCapture {
     public func stop() {
         guard running else { return }
         running = false
-        sampleTimer?.invalidate(); sampleTimer = nil
         flushTimer?.invalidate(); flushTimer = nil
-        NotificationCenter.default.removeObserver(
-            self, name: UIApplication.didEnterBackgroundNotification, object: nil
-        )
+        NotificationCenter.default.removeObserver(self)
         flush()
     }
 
@@ -136,27 +196,39 @@ public final class SitePongStructuralCapture {
         return nil
     }
 
-    private func serialize(_ v: UIView, in window: UIWindow) -> [String: Any]? {
+    private func serialize(_ v: UIView, in window: UIWindow, sensitiveRects: [CGRect]) -> [String: Any]? {
         if v.isHidden || v.alpha < 0.02 { return nil }
         let f = v.convert(v.bounds, to: window)
+        // Sensitive if the view opts in (UIKit flag), is a secure field, or its
+        // center falls inside a SwiftUI .watchtowerSensitive() region — the same
+        // sources Screenshotter blurs, so structural replay masks them too.
+        let center = CGPoint(x: f.midX, y: f.midY)
+        let inSensitive = v.watchtowerSensitive
+            || ((v as? UITextField)?.isSecureTextEntry ?? false)
+            || sensitiveRects.contains { $0.contains(center) }
+
         var attrs: [String: String] = [:]
         if let aid = v.accessibilityIdentifier, !aid.isEmpty { attrs["testID"] = aid }
-        if let al = v.accessibilityLabel, !al.isEmpty { attrs["accessibilityLabel"] = al }
+        if let al = v.accessibilityLabel, !al.isEmpty, !inSensitive { attrs["accessibilityLabel"] = al }
         if let bg = hex(v.backgroundColor) { attrs["backgroundColor"] = bg }
         if v.layer.cornerRadius > 0 { attrs["borderRadius"] = String(Int(v.layer.cornerRadius)) }
-        if let secure = (v as? UITextField)?.isSecureTextEntry, secure { attrs["wtSensitive"] = "true" }
+        if inSensitive { attrs["wtSensitive"] = "true" }
         if let l = v as? UILabel {
             attrs["color"] = hex(l.textColor) ?? "#111111"
             attrs["fontSize"] = String(Int(l.font.pointSize))
         }
         attrs["frame"] = "\(Int(f.origin.x)),\(Int(f.origin.y)),\(Int(f.size.width)),\(Int(f.size.height))"
+
+        if let sv = v as? UIScrollView { scanScrolls.append((idFor(v), sv.contentOffset)) }
+
         let tag = tagFor(v)
         var node: [String: Any] = ["id": idFor(v), "tag": tag, "attrs": attrs]
-        if let t = textFor(v), !t.isEmpty { node["text"] = t }
+        // Never serialize text inside a sensitive region.
+        if !inSensitive, let t = textFor(v), !t.isEmpty { node["text"] = t }
         // Don't descend into text/controls' internal subviews (keeps the tree clean).
         if !(v is UILabel) && !(v is UIButton) {
             var kids: [[String: Any]] = []
-            for sub in v.subviews { if let s = serialize(sub, in: window) { kids.append(s) } }
+            for sub in v.subviews { if let s = serialize(sub, in: window, sensitiveRects: sensitiveRects) { kids.append(s) } }
             node["children"] = kids
         } else {
             node["children"] = []
@@ -165,8 +237,38 @@ public final class SitePongStructuralCapture {
     }
 
     private func sample() {
-        guard running, let w = keyWindow(), let root = serialize(w, in: w) else { return }
+        guard running, let w = keyWindow() else { return }
+        // Adaptive back-off: while recovering from a heavy walk, skip the body.
+        if overloadSkip > 0 { overloadSkip -= 1; return }
+
+        scanScrolls.removeAll(keepingCapacity: true)
+        let sensitiveRects = WatchtowerRegistry.shared.sensitiveRects(in: w)
+        let t0 = Date()
+        guard let root = serialize(w, in: w, sensitiveRects: sensitiveRects) else { return }
+        let walkMs = Date().timeIntervalSince(t0) * 1000
+        if walkMs > walkBudgetMs { overloadSkip = min(maxOverloadSkip, Int(walkMs / walkBudgetMs)) }
+
         events.append(["t": now(), "type": "snapshot", "tree": root])
+
+        // Scroll detection: did any scroll view's offset move? Densify sampling
+        // for a few ticks so fast scrolls (captured as frame deltas) aren't aliased.
+        var scrolled = false
+        for (id, off) in scanScrolls {
+            if let last = scrollOffsets[id], abs(last.x - off.x) > 0.5 || abs(last.y - off.y) > 0.5 { scrolled = true }
+            scrollOffsets[id] = off
+        }
+        scrollQuietTicks = scrolled ? 0 : scrollQuietTicks + 1
+    }
+
+    /// Self-scheduling sampler: 60ms while scrolling, 120ms at rest.
+    private func scheduleSample() {
+        guard running else { return }
+        let interval = scrollQuietTicks < 3 ? 0.06 : 0.12
+        DispatchQueue.main.asyncAfter(deadline: .now() + interval) { [weak self] in
+            guard let self = self, self.running else { return }
+            self.sample()
+            self.scheduleSample()
+        }
     }
 
     @objc private func onTap(_ g: UITapGestureRecognizer) {
@@ -207,26 +309,35 @@ public final class SitePongStructuralCapture {
              viewport: (Int(w.bounds.width), Int(w.bounds.height)), attempt: 0)
     }
 
-    private func post(batch: [[String: Any]], seqStart: Int, viewport: (Int, Int), attempt: Int) {
-        let payload: [String: Any] = [
+    private func requestBody(batch: [[String: Any]], seqStart: Int, sessionId: String, viewport: (Int, Int)) -> Data? {
+        var payload: [String: Any] = [
             "session_id": sessionId,
             "platform": platform,
             "viewport": ["w": viewport.0, "h": viewport.1],
             "seq_start": seqStart,
             "events": batch,
         ]
-        guard let body = try? JSONSerialization.data(withJSONObject: payload),
-              let url = URL(string: "\(endpoint)/api/replay-stream/native") else {
-            DispatchQueue.main.async { self.sending = false }
-            return
-        }
+        if let iid = installId { payload["install_id"] = iid }
+        return try? JSONSerialization.data(withJSONObject: payload)
+    }
+
+    private func makeRequest(body: Data) -> URLRequest? {
+        guard let url = URL(string: "\(endpoint)/api/replay-stream/native") else { return nil }
         var req = URLRequest(url: url)
         req.httpMethod = "POST"
         req.setValue("application/json", forHTTPHeaderField: "Content-Type")
         req.setValue(apiKey, forHTTPHeaderField: "X-API-Key")
         if let pid = projectId { req.setValue(pid, forHTTPHeaderField: "X-Project-ID") }
         req.httpBody = body
+        return req
+    }
 
+    private func post(batch: [[String: Any]], seqStart: Int, viewport: (Int, Int), attempt: Int) {
+        guard let body = requestBody(batch: batch, seqStart: seqStart, sessionId: sessionId, viewport: viewport),
+              let req = makeRequest(body: body) else {
+            DispatchQueue.main.async { self.sending = false }
+            return
+        }
         URLSession.shared.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
@@ -248,6 +359,39 @@ public final class SitePongStructuralCapture {
             }
         }.resume()
     }
+
+    /// Fire-and-forget send under an explicit session id — used for the old-session
+    /// tail on a roll, decoupled from the flush cursor so it can't corrupt the new
+    /// session's seq. Best-effort (no retry / no re-queue).
+    private func sendBestEffort(batch: [[String: Any]], seqStart: Int, sessionId: String, viewport: (Int, Int)) {
+        guard !endpoint.isEmpty,
+              let body = requestBody(batch: batch, seqStart: seqStart, sessionId: sessionId, viewport: viewport),
+              let req = makeRequest(body: body) else { return }
+        URLSession.shared.dataTask(with: req).resume()
+    }
+
+    // MARK: - crash flush
+    private func installCrashFlush() {
+        SitePongStructuralCapture.previousExceptionHandler = NSGetUncaughtExceptionHandler()
+        NSSetUncaughtExceptionHandler { ex in
+            SitePongStructuralCapture.shared.crashFlush()
+            SitePongStructuralCapture.previousExceptionHandler?(ex)
+        }
+    }
+
+    /// Synchronous best-effort flush from an uncaught-exception handler (the run
+    /// loop is dead, so we block briefly on URLSession's own queue). Mirrors the
+    /// JS ErrorUtils crash-flush.
+    func crashFlush() {
+        guard running, !events.isEmpty,
+              let w = keyWindow(),
+              let body = requestBody(batch: events, seqStart: flushedEventCount, sessionId: sessionId,
+                                     viewport: (Int(w.bounds.width), Int(w.bounds.height))),
+              let req = makeRequest(body: body) else { return }
+        let sem = DispatchSemaphore(value: 0)
+        URLSession.shared.dataTask(with: req) { _, _, _ in sem.signal() }.resume()
+        _ = sem.wait(timeout: .now() + 1.5)
+    }
 }
 
 /// Allow the capture recognizer to run alongside buttons/scroll gestures.

package/ios/WatchtowerCore/TapEvent.swift

@@ -14,6 +14,11 @@ public struct CaptureEvent: Codable {
     public var distinct_id: String?
     public var device_model: String?
     public var os_version: String?
+    /// Release channel / environment this event was captured in (dev | preview |
+    /// production | …). Stamped on every event so the dashboard can keep dev
+    /// noise out of prod analytics. Defaults to "production"; the engine sets it
+    /// from the resolved channel. Non-optional so it is always on the wire.
+    public var channel: String = "production"
     /// Persistent per-install id (identifierForVendor) — stamped on every event
     /// so the dashboard can stitch consecutive sessions from the same install
     /// into a journey at read time, even for anonymous users.

package/ios/WatchtowerCore/Watchtower.swift

@@ -11,25 +11,70 @@ public enum Watchtower {
     /// §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.
+    ///
+    /// `channel` tags every event with a release channel / environment so dev
+    /// traffic can be kept out of prod analytics. When omitted it is resolved
+    /// automatically: **debug builds → `"development"`, release builds →
+    /// `"production"`**. Any channel listed in `ignoreChannels` is *suppressed*
+    /// — `start` becomes a complete no-op (no swizzles, no observers, zero
+    /// network). The default `["development"]` means debug builds capture
+    /// nothing unless you opt in (pass `ignoreChannels: []` or an explicit
+    /// `channel`). Release builds send `"production"` and are never suppressed
+    /// by the default.
     public static func start(apiKey: String, projectId: String,
                              endpoint: URL, sampleRate: Double = 0.1,
-                             platform: String = "ios", sessionGraceMs: Double = 30_000) {
+                             platform: String = "ios", sessionGraceMs: Double = 30_000,
+                             channel: String? = nil,
+                             ignoreChannels: [String] = ["development"]) {
+        let resolved = resolveChannel(channel)
+        // Suppressed channel → don't start at all. This is the "ignore dev,
+        // listen to prod" gate: zero capture and zero ingest cost for dev.
+        let ignored = Set(ignoreChannels.map { $0.trimmingCharacters(in: .whitespacesAndNewlines).lowercased() })
+        if ignored.contains(resolved) { return }
+
         #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, sessionGraceMs: sessionGraceMs)
+                                          platform: platform, sessionGraceMs: sessionGraceMs,
+                                          channel: resolved)
         } else {
             DispatchQueue.main.async {
                 WatchtowerEngine.shared.start(apiKey: apiKey, projectId: projectId,
                                               endpoint: endpoint, sampleRate: sampleRate,
-                                              platform: platform, sessionGraceMs: sessionGraceMs)
+                                              platform: platform, sessionGraceMs: sessionGraceMs,
+                                              channel: resolved)
             }
         }
         #endif
     }
 
+    /// Resolve the effective channel: an explicit, non-empty override wins
+    /// (lowercased); otherwise debug builds are `"development"` and release
+    /// builds `"production"`. Exposed at module scope so tests can assert the
+    /// build-config default without a running engine.
+    static func resolveChannel(_ explicit: String?) -> String {
+        if let c = explicit?.trimmingCharacters(in: .whitespacesAndNewlines).lowercased(), !c.isEmpty {
+            return c
+        }
+        #if DEBUG
+        return "development"
+        #else
+        return "production"
+        #endif
+    }
+
+    /// The channel the engine is currently tagging events with, or nil when not
+    /// running (e.g. suppressed). Useful for diagnostics and tests.
+    public static var channel: String? {
+        #if canImport(UIKit)
+        return WatchtowerEngine.shared.currentChannel
+        #else
+        return nil
+        #endif
+    }
+
     public static func stop() {
         #if canImport(UIKit)
         WatchtowerEngine.shared.stop()

package/ios/WatchtowerCore/WatchtowerEngine.swift

@@ -37,6 +37,13 @@ final class WatchtowerEngine {
     /// overrides to "react-native-ios" via start(platform:).
     private var platform: String = "ios"
 
+    /// Release channel / environment stamped on every event (dev | preview |
+    /// production | …). Resolved by Watchtower.start (debug→"development",
+    /// release→"production", or an explicit override) and passed in here. The
+    /// suppression decision (don't run at all on an ignored channel) is made in
+    /// Watchtower.start before this engine is ever started.
+    private var channel: String = "production"
+
     /// Persistent per-install id (identifierForVendor), resolved once at start
     /// and stamped on every event so the dashboard can stitch consecutive
     /// sessions from the same install into a journey at read time.
@@ -83,13 +90,15 @@ final class WatchtowerEngine {
     // MARK: - Lifecycle
 
     func start(apiKey: String, projectId: String, endpoint: URL, sampleRate: Double,
-               platform: String = "ios", sessionGraceMs: Double = 30_000) {
+               platform: String = "ios", sessionGraceMs: Double = 30_000,
+               channel: String = "production") {
         guard !isRunning else { return }
         self.transport = Transport(apiKey: apiKey, projectId: projectId, endpoint: endpoint)
         self.sessionId = UUID().uuidString
         self.sequence = 0
         self.sampleRate = sampleRate
         self.platform = platform
+        self.channel = channel
         self.sessionGraceMs = sessionGraceMs
         self.installId = UIDevice.current.identifierForVendor?.uuidString
         self.lastBackgroundedAt = nil
@@ -113,6 +122,13 @@ final class WatchtowerEngine {
         observeBackground()
         isRunning = true
         emit(baseEvent(type: "session_start"))
+        // Announce the session so the structural recorder can share this id and
+        // roll in lockstep (the native analogue of the RN provider adopting the
+        // native session id).
+        NotificationCenter.default.post(
+            name: .sitePongWatchtowerSessionDidRoll,
+            object: nil, userInfo: ["sessionId": sessionId]
+        )
     }
 
     func stop() {
@@ -142,6 +158,9 @@ final class WatchtowerEngine {
 
     var currentSessionId: String? { isRunning ? sessionId : nil }
 
+    /// The channel events are being tagged with, or nil when not running.
+    var currentChannel: String? { isRunning ? channel : nil }
+
     private func durationMs() -> UInt64 {
         guard let started = sessionStartedAt else { return 0 }
         return UInt64(max(0, Date().timeIntervalSince(started) * 1000))
@@ -159,6 +178,7 @@ final class WatchtowerEngine {
             os_version: osVersion
         )
         event.install_id = installId
+        event.channel = channel
         // Link hints ride only the session_start of a rolled session.
         if type == "session_start" {
             event.previous_session_id = pendingPreviousSessionId
@@ -254,6 +274,11 @@ final class WatchtowerEngine {
         emit(baseEvent(type: "session_start"))
         pendingPreviousSessionId = nil
         pendingSessionGapMs = nil
+        // Structural recorder re-keys onto the rolled session id.
+        NotificationCenter.default.post(
+            name: .sitePongWatchtowerSessionDidRoll,
+            object: nil, userInfo: ["sessionId": sessionId]
+        )
     }
 
     // MARK: - Screen views (§1.1 screen_view)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sitepong",
-  "version": "0.2.13",
+  "version": "0.2.15",
   "description": "Official SitePong SDK for error tracking and monitoring",
   "main": "dist/index.js",
   "module": "dist/index.mjs",