@oneuptime/react-native-replay 14.0.11 → 14.0.13

package/dist/index.js

@@ -15,7 +15,7 @@ import {
 } from "react-native";
 
 // src/MobileReplayRecorder.ts
-import { AppState } from "react-native";
+import { AppState, Keyboard } from "react-native";
 
 // src/Contract.ts
 var SESSION_REPLAY_WIRE_VERSION = 1;
@@ -51,6 +51,7 @@ var SESSION_REPLAY_CHECKOUT_INTERVAL_MS = 6e4;
 var SESSION_REPLAY_ROLLING_BUFFER_MS = 6e4;
 var SESSION_REPLAY_ROLLING_BUFFER_BYTES = 2 * 1024 * 1024;
 var SESSION_REPLAY_IDLE_ROLLOVER_MS = 30 * 6e4;
+var SESSION_REPLAY_IDLE_PAUSE_MS = 5 * 6e4;
 var SESSION_REPLAY_MAX_SESSION_MS = 4 * 60 * 6e4;
 var SESSION_REPLAY_MAX_DECOMPRESSED_FRAME_BYTES = 8 * 1024 * 1024;
 var MAX_SESSION_REPLAY_CHUNK_BYTES = 2 * 1024 * 1024;
@@ -59,7 +60,7 @@ var SESSION_REPLAY_MAX_OFFLINE_DELAY_MS = 3 * 24 * 60 * 60 * 1e3;
 var MOBILE_CAPTURE_INTERVAL_MS = 500;
 var MOBILE_RECORDER_KIND = "rn-view-tree";
 var SYNTHETIC_RRWEB_VERSION = "synthetic-1";
-var RECORDER_VERSION = true ? "14.0.11" : "0.0.0-dev";
+var RECORDER_VERSION = true ? "14.0.13" : "0.0.0-dev";
 var SESSION_REPLAY_MOBILE_RECORDER_CAPABILITIES = [
   "mobile-view-tree",
   "mobile-touch-events",
@@ -111,6 +112,9 @@ var IDENTIFY_CUSTOM_EVENT_TAG = "oneuptime.identify";
 var TAGS_CUSTOM_EVENT_TAG = "oneuptime.tags";
 var VISIBILITY_CUSTOM_EVENT_TAG = "oneuptime.visibility";
 var TOUCH_CUSTOM_EVENT_TAG = "oneuptime.touch";
+var SESSION_ROTATED_CUSTOM_EVENT_TAG = "oneuptime.session-rotated";
+var IDLE_PAUSED_CUSTOM_EVENT_TAG = "oneuptime.idle-paused";
+var IDLE_RESUMED_CUSTOM_EVENT_TAG = "oneuptime.idle-resumed";
 
 // src/Sanitize.ts
 var MAX_TRAIT_KEYS = 20;
@@ -2486,6 +2490,18 @@ var ReplaySessionStore = class {
     };
     return { ...this.identity };
   }
+  /*
+   * Forget the stored session without starting the next one. A session
+   * that ends while the recorder is paused for idle has no successor until
+   * the person comes back, and its record - last written by its own final
+   * chunk, so it looks recent - would otherwise let a relaunch in the
+   * meantime carry on a session that is already over. The visitor id stays,
+   * and so does the in-memory identity: nothing more is sent under it, and
+   * the next rotate() writes the new session.
+   */
+  async end() {
+    await this.safeRemove(this.sessionKey);
+  }
   async clear() {
     this.identity = null;
     await Promise.all([
@@ -2944,6 +2960,7 @@ function isTouchPrivate(privacyMap, x2, y) {
 var MAX_DIAGNOSTIC_EVENTS = 100;
 var TOUCH_MOVE_SAMPLE_MS = 50;
 var MOBILE_POLICY_REFRESH_INTERVAL_MS = 5 * 6e4;
+var MAX_EVENTS_HELD_FOR_RESUME = 500;
 var SAFE_ERROR_NAMES = /* @__PURE__ */ new Set([
   "AggregateError",
   "Error",
@@ -3015,6 +3032,7 @@ var MobileReplayRecorder = class {
     __publicField(this, "storage");
     __publicField(this, "nativeViewTree");
     __publicField(this, "appState");
+    __publicField(this, "keyboard");
     __publicField(this, "now");
     __publicField(this, "serializer", new ViewTreeSerializer());
     __publicField(this, "chunkBuffer", new ReplayChunkBuffer());
@@ -3081,6 +3099,21 @@ var MobileReplayRecorder = class {
     __publicField(this, "pendingStartCancellation", null);
     __publicField(this, "identityPersisted", false);
     __publicField(this, "sessionLastActivityUnixMs", 0);
+    /*
+     * The session went the idle window without activity, was sealed where it
+     * ended, and nobody has come back since.
+     *
+     * Rotating on the spot instead (the old behaviour) started a session
+     * nobody was in: an app left open in the foreground with the screen on
+     * re-snapshots every minute, so it filed a new session every half hour
+     * for as long as it stayed open. Now nothing is captured, uploaded or
+     * handed to the host as a session id until the user is back - a touch,
+     * the soft keyboard, the app returning to the foreground, or an explicit
+     * captureSession() - and that starts the next session (see
+     * maybeRotateSession). In the foreground the session was almost always
+     * paused for idle first (idlePause), so its footage already ended there.
+     */
+    __publicField(this, "sealedForIdle", false);
     __publicField(this, "rotatingSession", false);
     __publicField(this, "rotationPromise", null);
     __publicField(this, "appStateQueue", Promise.resolve());
@@ -3097,9 +3130,58 @@ var MobileReplayRecorder = class {
     __publicField(this, "suppressedTouchPointers", /* @__PURE__ */ new Set());
     __publicField(this, "unidentifiedTouchCount", 0);
     __publicField(this, "unidentifiedTouchPrivate", false);
+    /*
+     * When the person last did something: a touch (any touch - one inside a
+     * ReplayMask is still someone using the app, even though it is never
+     * recorded), the app coming back to the foreground, or the app starting.
+     * Not sessionLastActivityUnixMs, which every recorded event moves: a
+     * route change, a track() call or a JS error the app raises by itself is
+     * the app, not the person, and a polling screen would otherwise never
+     * look idle.
+     */
+    __publicField(this, "lastInputUnixMs", 0);
+    /*
+     * The idle pause (SESSION_REPLAY_IDLE_PAUSE_MS, #4208). Set when the
+     * capture tick finds nobody has touched the app for that long: the open
+     * chunk closes with an idle-paused marker as its last event, the capture
+     * timer stops, and from then on nothing is recorded - no view-tree
+     * sample, no checkout, no chunk, and every event the app emits is
+     * dropped rather than queued. The 15-second flush timer is the only one
+     * left, and all it does is end the session (sealForIdle, #4207) if nobody
+     * comes back inside SESSION_REPLAY_IDLE_ROLLOVER_MS.
+     *
+     * It exists because the recorder used to go on sampling the view tree
+     * every 500 ms, with a full checkout every minute, for the whole half
+     * hour before the idle rollover - the phone's CPU and battery and the
+     * customer's upload and storage, all spent on footage of nobody.
+     *
+     * Input inside that window - a touch, the soft keyboard, the app
+     * returning to the foreground - resumes the same session and tab on a
+     * fresh full snapshot with an idle-resumed marker directly behind it
+     * (idleResumeBacklog), at the next chunk index.
+     */
+    __publicField(this, "idlePause", null);
+    /*
+     * Non-null from the input that ends an idle pause until the snapshot it
+     * resumes on is in the buffer. What is recorded meanwhile - the touch
+     * that woke the recorder, the screen it opened, a track() it caused - is
+     * held here and appended behind that snapshot and the idle-resumed
+     * marker, so the chunk after a pause always opens on its snapshot.
+     */
+    __publicField(this, "idleResumeBacklog", null);
+    /*
+     * The soft keyboard is up. Keystrokes reach no view the recorder can see,
+     * so someone writing a long message - a chat, a form, a review - would
+     * otherwise look exactly like nobody touching the app. While it is up the
+     * idle pause waits, and its showing and hiding are input
+     * (onKeyboardChange). The 30-minute rollover does not look at it.
+     */
+    __publicField(this, "softKeyboardVisible", false);
+    __publicField(this, "keyboardSubscriptions", []);
     this.storage = dependencies.storage ?? defaultReplayStorage;
     this.nativeViewTree = dependencies.nativeViewTree ?? defaultNativeViewTreeAdapter;
     this.appState = dependencies.appState ?? AppState;
+    this.keyboard = dependencies.keyboard ?? Keyboard ?? null;
     this.now = dependencies.now ?? defaultNow;
   }
   start(options) {
@@ -3168,6 +3250,7 @@ var MobileReplayRecorder = class {
     this.appStateQueue = Promise.resolve();
     this.rotationPromise = null;
     this.rotatingSession = false;
+    this.sealedForIdle = false;
     this.policyRefreshPromise = null;
     this.lastPolicyRefreshAtUnixMs = 0;
     this.forceFullSnapshot = true;
@@ -3175,6 +3258,8 @@ var MobileReplayRecorder = class {
     this.touchPrivacyMap = CONSERVATIVE_TOUCH_PRIVACY_MAP;
     this.touchQueue = Promise.resolve();
     this.resetTouchSequences();
+    this.idlePause = null;
+    this.idleResumeBacklog = null;
     const validated = validateStartOptions(options);
     if (!validated) {
       this.disable("invalid-start-options");
@@ -3254,6 +3339,7 @@ var MobileReplayRecorder = class {
       );
     }
     this.sessionLastActivityUnixMs = nowUnixMs;
+    this.lastInputUnixMs = nowUnixMs;
     if (!awaitingConsent && config.captureTrigger === "Always" /* Always */ && !this.sampled && !config.isTargeted) {
       this.disable("not-sampled");
       return false;
@@ -3340,12 +3426,23 @@ var MobileReplayRecorder = class {
       this.diagnosticsStatus = "stopped";
       return;
     }
-    this.appendCustom(
-      VISIBILITY_CUSTOM_EVENT_TAG,
-      { state: "stopped" },
-      void 0,
-      true
-    );
+    const endedIdle = this.sealedForIdle || this.rotationReason(this.now()) === "idle";
+    const pause = this.idlePause;
+    if (!endedIdle && pause === null) {
+      this.appendCustom(
+        VISIBILITY_CUSTOM_EVENT_TAG,
+        { state: "stopped" },
+        void 0,
+        true
+      );
+    } else if (!endedIdle && pause !== null && this.isPauseInStream(pause)) {
+      this.idleResumeBacklog = null;
+      this.appendMarker(
+        VISIBILITY_CUSTOM_EVENT_TAG,
+        { state: "stopped" },
+        pause.pausedAtUnixMs
+      );
+    }
     this.haltCapture();
     await this.closeCurrent(true);
     if (this.uploadActive) {
@@ -3493,7 +3590,7 @@ var MobileReplayRecorder = class {
   }
   async setRoute(route) {
     await this.identityQueue;
-    if (this.running && !this.acceptingEvents) {
+    if (this.running && (!this.acceptingEvents || this.isIdlePaused())) {
       this.route = sanitizeRoute(route);
       return;
     }
@@ -3508,6 +3605,9 @@ var MobileReplayRecorder = class {
       return;
     }
     this.route = next;
+    if (this.sealedForIdle) {
+      return;
+    }
     this.appendCustom(
       ROUTE_CUSTOM_EVENT_TAG,
       {
@@ -3526,7 +3626,15 @@ var MobileReplayRecorder = class {
     if (!this.running || !this.acceptingEvents) {
       return;
     }
-    await this.maybeRotateSession(this.now());
+    const resume = this.foreground ? this.endIdlePause(this.now()) : "none";
+    await this.maybeRotateForUser(this.now());
+    if (resume === "resumed") {
+      this.startTimers();
+      await this.captureTick(true, false);
+      if (!this.running || !this.acceptingEvents) {
+        return;
+      }
+    }
     const safeReason2 = truncate(
       (typeof reason === "string" ? reason.trim() : "") || "manual",
       MAX_CAPTURE_REASON_LENGTH
@@ -3542,7 +3650,13 @@ var MobileReplayRecorder = class {
     if (!this.running || !this.acceptingEvents) {
       return;
     }
+    if (this.isIdlePaused()) {
+      return;
+    }
     await this.maybeRotateSession(this.now());
+    if (this.sealedForIdle) {
+      return;
+    }
     const rawName = error instanceof Error && typeof error.name === "string" ? error.name.trim() : "";
     const name = SAFE_ERROR_NAMES.has(rawName) ? rawName : "Error";
     this.appendCustom(
@@ -3564,9 +3678,18 @@ var MobileReplayRecorder = class {
     if (!this.running || !this.acceptingEvents || !this.foreground) {
       return;
     }
+    const input = this.noteUserInput(this.now());
+    let resumeCapture = null;
+    if (input === "resumed") {
+      this.startTimers();
+      resumeCapture = this.captureTick(true);
+    }
     const generation = this.lifecycleGeneration;
     const operation = this.touchQueue.then(
       async () => {
+        if (resumeCapture) {
+          await resumeCapture;
+        }
         await this.recordTouchAfterPrivacyCheck(sanitizedTouch, generation);
       }
     );
@@ -3593,9 +3716,9 @@ var MobileReplayRecorder = class {
       this.lastTouchMoveAtUnixMs = touch.timestamp;
     }
     const nowUnixMs = this.now();
-    if (this.rotatingSession || this.rotationReason(nowUnixMs)) {
+    if (this.rotatingSession || this.sealedForIdle || this.rotationReason(nowUnixMs)) {
       this.diagnostic("touch-dropped-session-rotation");
-      void this.maybeRotateSession(nowUnixMs);
+      void this.maybeRotateForUser(nowUnixMs);
       return;
     }
     this.appendEvent(
@@ -3620,8 +3743,9 @@ var MobileReplayRecorder = class {
     }
   }
   getDiagnostics() {
+    const status = this.diagnosticsStatus === "recording" && this.running && this.foreground && (this.isIdlePaused() || this.sealedForIdle) ? "paused" : this.diagnosticsStatus;
     return {
-      status: this.diagnosticsStatus,
+      status,
       sessionId: this.identity?.sessionId ?? null,
       recorderKind: MOBILE_RECORDER_KIND,
       configEpoch: this.config?.configEpoch ?? 0,
@@ -3643,9 +3767,14 @@ var MobileReplayRecorder = class {
       )
     };
   }
-  /** Current consented replay session for host trace/log correlation. */
+  /**
+   * Current consented replay session for host trace/log correlation. None
+   * while the session has ended idle and nobody is back: a background poll
+   * on an idle app is no part of a recording that ended at the user's last
+   * activity.
+   */
   getSessionId() {
-    return this.running && this.identityPersisted ? this.identity?.sessionId ?? null : null;
+    return this.running && this.identityPersisted && !this.sealedForIdle ? this.identity?.sessionId ?? null : null;
   }
   /** Fires immediately when a session exists and again on rotate/clear. */
   onSessionChange(listener) {
@@ -3698,9 +3827,16 @@ var MobileReplayRecorder = class {
     }
     await this.transport?.restore();
   }
-  async captureTick(force = false) {
+  /*
+   * mayPauseForIdle is false only for the snapshot captureSession() takes
+   * while paused, whose marker must be in before the pause check runs.
+   */
+  async captureTick(force = false, mayPauseForIdle = true) {
     const generation = this.lifecycleGeneration;
-    if (!this.running || !this.acceptingEvents || !this.foreground || !this.rootTag || this.captureGeneration === generation || !this.options) {
+    if (!this.running || !this.acceptingEvents || !this.foreground || !this.rootTag || this.sealedForIdle || this.captureGeneration === generation || !this.options) {
+      return;
+    }
+    if (this.isIdlePaused()) {
       return;
     }
     this.captureGeneration = generation;
@@ -3715,7 +3851,10 @@ var MobileReplayRecorder = class {
         return;
       }
       await this.maybeRotateSession(nowUnixMs);
-      if (!this.running || !this.acceptingEvents || !this.foreground || !this.isCurrentGeneration(generation)) {
+      if (!this.running || !this.acceptingEvents || !this.foreground || !this.isCurrentGeneration(generation) || this.sealedForIdle) {
+        return;
+      }
+      if (this.isIdlePaused() || this.idlePause !== null && this.rotationReason(nowUnixMs) !== null) {
         return;
       }
       const capturedSessionId = this.identity?.sessionId;
@@ -3724,7 +3863,6 @@ var MobileReplayRecorder = class {
         return;
       }
       this.touchPrivacyMap = deriveTouchPrivacyMap(tree);
-      const size = getViewport();
       const shouldForce = force || this.forceFullSnapshot || nowUnixMs - this.lastFullSnapshotAtUnixMs >= SESSION_REPLAY_CHECKOUT_INTERVAL_MS;
       if (shouldForce && !this.chunkBuffer.isEmpty()) {
         await this.closeCurrent(false);
@@ -3732,25 +3870,13 @@ var MobileReplayRecorder = class {
       if (!this.running || !this.acceptingEvents || !this.foreground || !this.isCurrentGeneration(generation) || this.identity?.sessionId !== capturedSessionId) {
         return;
       }
-      const capture = this.serializer.capture(tree, {
-        timestamp: nowUnixMs,
-        url: toAppUrl(this.options.mobileAppIdentifier, this.route),
-        viewportWidth: size.width,
-        viewportHeight: size.height,
-        forceFullSnapshot: shouldForce
-      });
-      this.droppedEvents += capture.droppedNodes;
-      this.chunkBuffer.appendMany(capture.events, {
-        route: toAppUrl(this.options.mobileAppIdentifier, this.route),
-        fidelityNotices: capture.fidelityNotices
-      });
-      if (capture.hasFullSnapshot) {
-        this.lastFullSnapshotAtUnixMs = nowUnixMs;
-        this.forceFullSnapshot = false;
-      }
+      this.appendCapture(tree, this.options, nowUnixMs, shouldForce);
       if (this.chunkBuffer.shouldFlush()) {
         await this.closeCurrent(false);
       }
+      if (mayPauseForIdle && !this.softKeyboardVisible && nowUnixMs - this.lastInputUnixMs >= SESSION_REPLAY_IDLE_PAUSE_MS) {
+        await this.pauseForIdle(nowUnixMs, generation);
+      }
     } catch (error) {
       if (this.running && this.isCurrentGeneration(generation)) {
         this.disable("native-capture-failed", {
@@ -3764,6 +3890,183 @@ var MobileReplayRecorder = class {
       }
     }
   }
+  appendCapture(tree, options, nowUnixMs, forceFullSnapshot) {
+    const size = getViewport();
+    const url = toAppUrl(options.mobileAppIdentifier, this.route);
+    const capture = this.serializer.capture(tree, {
+      timestamp: nowUnixMs,
+      url,
+      viewportWidth: size.width,
+      viewportHeight: size.height,
+      forceFullSnapshot
+    });
+    this.droppedEvents += capture.droppedNodes;
+    this.chunkBuffer.appendMany(capture.events, {
+      route: url,
+      fidelityNotices: capture.fidelityNotices
+    });
+    if (capture.hasFullSnapshot) {
+      this.lastFullSnapshotAtUnixMs = nowUnixMs;
+      this.forceFullSnapshot = false;
+      this.completeIdleResume(nowUnixMs);
+    }
+  }
+  /*
+   * The person did something: a touch, the soft keyboard showing or
+   * hiding, or the app coming back to the foreground. It ends an idle
+   * pause (see endIdlePause).
+   */
+  noteUserInput(nowUnixMs) {
+    this.lastInputUnixMs = Math.max(this.lastInputUnixMs, nowUnixMs);
+    return this.endIdlePause(nowUnixMs);
+  }
+  /*
+   * What someone being back does to an idle pause, on its own for
+   * captureSession(), which acts on the pause without being input.
+   *
+   * Inside the session's idle window the same session resumes, on the
+   * snapshot of the next capture; the caller starts that capture. Once
+   * the window has run out - or the session already ended idle - the
+   * session is over, and the caller starts the next one through
+   * maybeRotateForUser, as on any idle session; nothing changes here.
+   */
+  endIdlePause(nowUnixMs) {
+    if (this.sealedForIdle) {
+      return "session-ended";
+    }
+    if (!this.isIdlePaused()) {
+      return "none";
+    }
+    if (this.rotationReason(nowUnixMs) !== null) {
+      return "session-ended";
+    }
+    this.idleResumeBacklog = [];
+    this.forceFullSnapshot = true;
+    this.sessionLastActivityUnixMs = Math.max(
+      this.sessionLastActivityUnixMs,
+      nowUnixMs
+    );
+    return "resumed";
+  }
+  /* Paused for idle with nobody back yet: nothing is captured or recorded. */
+  isIdlePaused() {
+    return this.idlePause !== null && this.idleResumeBacklog === null;
+  }
+  /*
+   * Whether the pause's marker is in the stream being recorded now, which
+   * is what owes it the idle-resumed marker and dates a stop at it.
+   */
+  isPauseInStream(pause) {
+    return pause.marked && this.identity?.sessionId === pause.sessionId && this.identity?.tabId === pause.tabId;
+  }
+  /*
+   * Stop capturing: nobody has touched the app for the pause window.
+   *
+   * In this order: the idle-paused marker goes in as the last event of the
+   * open chunk, that chunk goes out through the ordinary path, and the
+   * sampler stops. So the last thing the recording holds before the
+   * stretch nobody recorded says so - and a session the person never comes
+   * back to has already ended there when its idle window runs out, so the
+   * idle seal (sealForIdle) has nothing left to send.
+   *
+   * A recorder holding its pre-roll in memory (error-triggered, or waiting
+   * for consent) has nothing to mark and nothing to send. Its pre-roll is
+   * dropped instead: a trigger once the person is back must not upload a
+   * minute of nobody in front of a snapshot taken after an unrecorded gap.
+   */
+  async pauseForIdle(nowUnixMs, generation) {
+    if (!this.running || !this.acceptingEvents || !this.foreground || !this.isCurrentGeneration(generation) || this.idlePause !== null || this.sealedForIdle || !this.identity) {
+      return;
+    }
+    const paused = {
+      /*
+       * Never before the session began: one that started with nobody there
+       * (the chunk cap rolled it over) was not idle before it existed.
+       */
+      idleSinceUnixMs: Math.min(
+        nowUnixMs,
+        Math.max(this.lastInputUnixMs, this.identity.sessionStartUnixMs)
+      ),
+      pausedAtUnixMs: nowUnixMs
+    };
+    const marked = this.uploadActive;
+    this.idlePause = {
+      sessionId: this.identity.sessionId,
+      tabId: this.identity.tabId,
+      idleSinceUnixMs: paused.idleSinceUnixMs,
+      pausedAtUnixMs: paused.pausedAtUnixMs,
+      marked
+    };
+    this.stopCaptureTimer();
+    this.diagnostic("idle-paused", {
+      idleForMs: nowUnixMs - paused.idleSinceUnixMs
+    });
+    if (!marked) {
+      this.chunkBuffer.clear();
+      this.rollingBuffer.clear();
+      return;
+    }
+    this.appendMarker(IDLE_PAUSED_CUSTOM_EVENT_TAG, paused, nowUnixMs);
+    await this.closeCurrent(false);
+  }
+  /*
+   * The snapshot the session resumes on is in the buffer: the idle-resumed
+   * marker goes directly behind it, then whatever was recorded since the
+   * input that woke the recorder. Same session, same tab and - the pause
+   * having closed its chunk - the next chunk index.
+   */
+  completeIdleResume(nowUnixMs) {
+    const pause = this.idlePause;
+    const held = this.idleResumeBacklog;
+    if (pause === null || held === null) {
+      return;
+    }
+    this.idlePause = null;
+    this.idleResumeBacklog = null;
+    const resumedAtUnixMs = Math.max(pause.pausedAtUnixMs, nowUnixMs);
+    if (this.isPauseInStream(pause)) {
+      const resumed = {
+        pausedAtUnixMs: pause.pausedAtUnixMs,
+        resumedAtUnixMs
+      };
+      this.appendMarker(
+        IDLE_RESUMED_CUSTOM_EVENT_TAG,
+        resumed,
+        resumedAtUnixMs
+      );
+    }
+    this.releaseHeldEvents(held);
+    this.diagnostic("idle-resumed", {
+      pausedForMs: resumedAtUnixMs - pause.pausedAtUnixMs
+    });
+  }
+  /*
+   * A marker the recorder writes about itself - the idle pause and resume,
+   * and a stop while paused - straight into the open chunk, stamped with
+   * the moment it stands for. None of them is activity (the idle rollover
+   * must not move for them), and none is "now": a stop while paused is
+   * dated at the pause.
+   */
+  appendMarker(tag, payload, timestamp) {
+    const options = {};
+    if (this.options) {
+      options.route = toAppUrl(this.options.mobileAppIdentifier, this.route);
+    }
+    if (!this.chunkBuffer.append(
+      createCustomEvent(tag, payload, timestamp),
+      options
+    )) {
+      this.droppedEvents += 1;
+    }
+  }
+  /* What was held for a resume, in the order it was recorded. */
+  releaseHeldEvents(held) {
+    for (const entry of held) {
+      if (!this.chunkBuffer.append(entry.event, entry.options)) {
+        this.droppedEvents += 1;
+      }
+    }
+  }
   appendCustom(tag, payload, signal, allowWhenQuiesced = false) {
     this.appendEvent(
       createCustomEvent(tag, payload, this.now()),
@@ -3775,15 +4078,17 @@ var MobileReplayRecorder = class {
     if (!this.running || !this.acceptingEvents && !allowWhenQuiesced) {
       return;
     }
+    if (this.sealedForIdle) {
+      return;
+    }
     if (!Number.isFinite(event.timestamp)) {
       this.droppedEvents += 1;
       this.diagnostic("invalid-event-timestamp");
       return;
     }
-    this.sessionLastActivityUnixMs = Math.max(
-      this.sessionLastActivityUnixMs,
-      event.timestamp
-    );
+    if (this.isIdlePaused()) {
+      return;
+    }
     const appendOptions = {};
     if (this.options) {
       appendOptions.route = toAppUrl(
@@ -3794,6 +4099,18 @@ var MobileReplayRecorder = class {
     if (signal) {
       appendOptions.signal = signal;
     }
+    if (this.idleResumeBacklog !== null) {
+      if (this.idleResumeBacklog.length < MAX_EVENTS_HELD_FOR_RESUME) {
+        this.idleResumeBacklog.push({ event, options: appendOptions });
+      } else {
+        this.droppedEvents += 1;
+      }
+      return;
+    }
+    this.sessionLastActivityUnixMs = Math.max(
+      this.sessionLastActivityUnixMs,
+      event.timestamp
+    );
     const accepted = this.chunkBuffer.append(event, appendOptions);
     if (!accepted) {
       this.droppedEvents += 1;
@@ -3803,7 +4120,7 @@ var MobileReplayRecorder = class {
     }
   }
   async closeCurrent(isFinal) {
-    const closesFinalChunkSlot = !isFinal && !this.rotatingSession && this.uploadActive && this.sessionStore?.getNextChunkIndex() === MAX_SESSION_REPLAY_CHUNKS_PER_SESSION - 1;
+    const closesFinalChunkSlot = !isFinal && !this.rotatingSession && !this.sealedForIdle && this.uploadActive && this.sessionStore?.getNextChunkIndex() === MAX_SESSION_REPLAY_CHUNKS_PER_SESSION - 1;
     if (closesFinalChunkSlot) {
       this.rotatingSession = true;
       const rotationOptions = {};
@@ -3815,7 +4132,7 @@ var MobileReplayRecorder = class {
       }
       this.chunkBuffer.append(
         createCustomEvent(
-          "oneuptime.session-rotated",
+          SESSION_ROTATED_CUSTOM_EVENT_TAG,
           { reason: "chunk-cap" },
           this.now()
         ),
@@ -3979,6 +4296,63 @@ var MobileReplayRecorder = class {
         });
       }
     );
+    this.installKeyboardListeners();
+  }
+  installKeyboardListeners() {
+    this.removeKeyboardListeners();
+    const keyboard = this.keyboard;
+    this.softKeyboardVisible = false;
+    if (!keyboard || typeof keyboard.addListener !== "function") {
+      return;
+    }
+    try {
+      this.softKeyboardVisible = keyboard.isVisible?.() === true;
+    } catch {
+      this.softKeyboardVisible = false;
+    }
+    try {
+      this.keyboardSubscriptions.push(
+        keyboard.addListener("keyboardDidShow", () => {
+          this.onKeyboardChange(true);
+        }),
+        keyboard.addListener("keyboardDidHide", () => {
+          this.onKeyboardChange(false);
+        })
+      );
+    } catch {
+      this.removeKeyboardListeners();
+      this.softKeyboardVisible = false;
+      this.diagnostic("keyboard-subscribe-failed");
+    }
+  }
+  removeKeyboardListeners() {
+    const subscriptions = this.keyboardSubscriptions;
+    this.keyboardSubscriptions = [];
+    for (const subscription of subscriptions) {
+      try {
+        subscription.remove();
+      } catch {
+      }
+    }
+  }
+  /*
+   * The soft keyboard came up or went away. That is the person - a field
+   * tapped, a message sent - so it counts as input and resumes a paused
+   * recording the way a touch does; and while it is up the idle pause
+   * waits, since what is typed on it reaches no view the recorder sees.
+   */
+  onKeyboardChange(visible) {
+    this.softKeyboardVisible = visible;
+    if (!this.running || !this.acceptingEvents || !this.foreground) {
+      return;
+    }
+    const input = this.noteUserInput(this.now());
+    if (input === "resumed") {
+      this.startTimers();
+      void this.captureTick(true);
+    } else if (input === "session-ended") {
+      void this.maybeRotateForUser(this.now());
+    }
   }
   async onAppStateChange(state, generation) {
     if (!this.running || !this.isCurrentGeneration(generation)) {
@@ -3998,6 +4372,13 @@ var MobileReplayRecorder = class {
       if (!this.running || !this.isCurrentGeneration(generation)) {
         return;
       }
+      if (this.idlePause !== null || this.sealedForIdle) {
+        this.idleResumeBacklog = null;
+        if (this.uploadActive) {
+          await this.transport?.drain();
+        }
+        return;
+      }
       this.appendCustom(VISIBILITY_CUSTOM_EVENT_TAG, { state: "hidden" });
       await this.closeCurrent(false);
       if (this.uploadActive) {
@@ -4007,6 +4388,7 @@ var MobileReplayRecorder = class {
     }
     if (isActive && !this.foreground) {
       this.foreground = true;
+      const input = this.noteUserInput(this.now());
       const policyReady = await this.refreshRuntimePolicy(
         generation,
         true,
@@ -4015,15 +4397,22 @@ var MobileReplayRecorder = class {
       if (!policyReady) {
         return;
       }
-      await this.maybeRotateSession(this.now());
+      const sessionIdBeforeResume = this.identity?.sessionId;
+      await this.maybeRotateSession(this.now(), true);
       if (!this.running || !this.isCurrentGeneration(generation)) {
         return;
       }
-      this.appendCustom(VISIBILITY_CUSTOM_EVENT_TAG, { state: "visible" });
-      this.forceFullSnapshot = true;
+      const resumedPausedSession = input === "resumed" && this.identity?.sessionId === sessionIdBeforeResume;
+      if (!resumedPausedSession) {
+        this.appendCustom(VISIBILITY_CUSTOM_EVENT_TAG, { state: "visible" });
+      }
+      const openedOnSnapshot = this.identity?.sessionId !== sessionIdBeforeResume && this.lastFullSnapshotAtUnixMs > 0;
+      if (!openedOnSnapshot) {
+        this.forceFullSnapshot = true;
+      }
       this.startTimers();
       this.diagnosticsStatus = this.consentState() === "Unknown" ? "consent-required" : "recording";
-      await this.captureTick(true);
+      await this.captureTick(!openedOnSnapshot);
       if (this.uploadActive && this.running) {
         this.transport?.resume();
       }
@@ -4042,16 +4431,31 @@ var MobileReplayRecorder = class {
       void this.captureTick();
     }, intervalMs);
     this.flushTimer = setInterval(() => {
+      if (this.isIdlePaused()) {
+        if (this.acceptingEvents) {
+          void this.maybeRotateSession(this.now());
+        }
+        return;
+      }
       if (this.acceptingEvents) {
         void this.closeCurrent(false);
       }
     }, SESSION_REPLAY_FLUSH_INTERVAL_MS);
   }
-  clearTimers() {
+  /*
+   * The sampler alone. An idle pause stops it - every tick is a native
+   * traversal of the whole view tree, which is what a pause is for not
+   * paying - and keeps the 15-second flush timer as its heartbeat, rather
+   * than waking the JS thread twice a second to find nothing to do.
+   */
+  stopCaptureTimer() {
     if (this.captureTimer) {
       clearInterval(this.captureTimer);
       this.captureTimer = null;
     }
+  }
+  clearTimers() {
+    this.stopCaptureTimer();
     if (this.flushTimer) {
       clearInterval(this.flushTimer);
       this.flushTimer = null;
@@ -4143,6 +4547,7 @@ var MobileReplayRecorder = class {
     this.clearTimers();
     this.appStateSubscription?.remove();
     this.appStateSubscription = null;
+    this.removeKeyboardListeners();
     this.stopConnectivity();
     this.restoreGlobalErrorHandler();
   }
@@ -4303,9 +4708,16 @@ var MobileReplayRecorder = class {
       if (!this.running || identityEpoch !== this.identityCancellationEpoch) {
         return;
       }
+      if (!this.rotationPromise && !this.sealedForIdle) {
+        if (this.isIdlePaused()) {
+          await this.sealForIdleNow();
+        } else if (this.rotationReason(this.now()) === "idle") {
+          await this.maybeRotateSession(this.now());
+        }
+      }
       if (this.rotationPromise) {
         await this.rotationPromise;
-      } else {
+      } else if (!this.sealedForIdle) {
         this.rotatingSession = true;
         const rotation = this.performSessionRotation(
           this.now(),
@@ -4640,16 +5052,24 @@ var MobileReplayRecorder = class {
       chunkIndex: 0
     };
   }
+  /*
+   * Idle before the duration cap, the order Common's SessionIdentity decides
+   * them in. A session left for the idle window ended where it was left,
+   * even when it has outlived the cap by the time anything notices, and
+   * only an idle rotation dates its end there (see performSessionRotation):
+   * called "duration", a session three hours old put in the background for
+   * two more was sealed two hours after its footage.
+   */
   rotationReason(nowUnixMs) {
     if (!this.identity) {
       return null;
     }
-    if (nowUnixMs - this.identity.sessionStartUnixMs >= SESSION_REPLAY_MAX_SESSION_MS) {
-      return "duration";
-    }
     if (nowUnixMs - this.sessionLastActivityUnixMs >= SESSION_REPLAY_IDLE_ROLLOVER_MS) {
       return "idle";
     }
+    if (nowUnixMs - this.identity.sessionStartUnixMs >= SESSION_REPLAY_MAX_SESSION_MS) {
+      return "duration";
+    }
     return null;
   }
   runExternalActivity(nowUnixMs, action) {
@@ -4684,23 +5104,61 @@ var MobileReplayRecorder = class {
       }
     });
   }
-  async maybeRotateSession(nowUnixMs) {
-    if (this.rotationPromise) {
+  /*
+   * isUserBack: the caller knows the user is here - a touch, the app
+   * returning to the foreground, an explicit captureSession(). An idle
+   * session then rotates at once. Anything else (a capture tick, a route
+   * change, a developer event) only finds out the session went idle, and
+   * seals it to wait for them (see sealedForIdle).
+   */
+  async maybeRotateSession(nowUnixMs, isUserBack = false) {
+    while (this.rotationPromise) {
       await this.rotationPromise;
-      return;
+      if (!isUserBack || !this.sealedForIdle) {
+        return;
+      }
     }
     if (!this.running || this.rotatingSession || !this.identity || !this.config || !this.sessionStore || !this.options) {
       return;
     }
-    const reason = this.rotationReason(nowUnixMs);
+    let reason;
+    if (this.sealedForIdle) {
+      if (!isUserBack) {
+        return;
+      }
+      reason = "idle";
+    } else {
+      reason = this.rotationReason(nowUnixMs);
+      if (reason !== null && this.isIdlePaused()) {
+        reason = "idle";
+      }
+    }
     if (!reason) {
       return;
     }
     this.rotatingSession = true;
-    const operation = this.performSessionRotation(
-      nowUnixMs,
-      reason
-    );
+    const operation = reason === "idle" && !isUserBack ? this.sealForIdle() : this.performSessionRotation(nowUnixMs, reason);
+    this.rotationPromise = operation;
+    try {
+      await operation;
+    } finally {
+      if (this.rotationPromise === operation) {
+        this.rotationPromise = null;
+      }
+      this.rotatingSession = false;
+    }
+  }
+  /*
+   * The idle seal on demand, under the lock every rotation takes: for an
+   * identity change on a session paused for idle, which no clock has ended
+   * yet but nobody is in.
+   */
+  async sealForIdleNow() {
+    if (this.rotationPromise || this.rotatingSession || this.sealedForIdle) {
+      return;
+    }
+    this.rotatingSession = true;
+    const operation = this.sealForIdle();
     this.rotationPromise = operation;
     try {
       await operation;
@@ -4711,8 +5169,68 @@ var MobileReplayRecorder = class {
       this.rotatingSession = false;
     }
   }
+  /*
+   * maybeRotateSession for a user who is here. On an app whose session
+   * ended idle - or was paused for idle, which stops the capture tick too
+   * (#4208) - the policy is brought up to date first: no capture tick has
+   * refreshed it while the app sat idle, and the next session must not open
+   * under one that has since changed (or turned replay off).
+   */
+  async maybeRotateForUser(nowUnixMs) {
+    if ((this.sealedForIdle || this.idlePause !== null) && !this.rotatingSession) {
+      const policyReady = await this.refreshRuntimePolicy(
+        this.lifecycleGeneration,
+        false,
+        "periodic"
+      );
+      if (!policyReady) {
+        return;
+      }
+    }
+    await this.maybeRotateSession(nowUnixMs, true);
+  }
+  /*
+   * End the session as idle, where it really ended, and wait for the user.
+   *
+   * Sealed with whatever footage is still buffered - dated by that footage,
+   * never by now - and with no marker of its own: a marker stamped now
+   * would date the session's end half an hour or more after anything the
+   * player can show. With nothing buffered nothing is sent, and the server
+   * ends the session at its last chunk - for a session paused for idle
+   * (#4208), the chunk its idle-paused marker closed.
+   */
+  async sealForIdle() {
+    this.sealedForIdle = true;
+    this.idlePause = null;
+    this.idleResumeBacklog = null;
+    this.clearTimers();
+    this.diagnostic("session-ended-idle", {
+      idleForMs: Math.max(0, this.now() - this.sessionLastActivityUnixMs)
+    });
+    this.notifySessionChange();
+    await this.closeCurrent(true);
+    await this.closeQueue;
+    if (!this.running) {
+      return;
+    }
+    if (this.uploadActive) {
+      await this.transport?.drain();
+    } else {
+      this.rollingBuffer.clear();
+    }
+    if (this.running && this.identityPersisted) {
+      await this.sessionStore?.end();
+    }
+  }
   async performSessionRotation(nowUnixMs, reason) {
-    this.appendCustom("oneuptime.session-rotated", { reason }, void 0, true);
+    if (reason !== "idle") {
+      this.appendCustom(
+        SESSION_ROTATED_CUSTOM_EVENT_TAG,
+        { reason },
+        void 0,
+        true
+      );
+    }
     await this.closeCurrent(true);
     await this.closeQueue;
     if (!this.running) {
@@ -4727,12 +5245,66 @@ var MobileReplayRecorder = class {
       return;
     }
     await this.completeSessionIdentityRotation(nowUnixMs, reason);
+    if (reason === "idle" && this.running) {
+      await this.openSessionAfterIdle();
+    }
+  }
+  /*
+   * The first things a session after an idle one records: a full snapshot
+   * of the screen the user came back to, then the rotation marker - the
+   * snapshot first, so chunk 0 is a seek anchor rather than a lone marker.
+   *
+   * Taken here, inside the rotation, rather than left to the next capture
+   * tick: until the rotation settles, touches are dropped and every other
+   * event waits for it (rotatingSession), so nothing can land ahead of the
+   * snapshot. A user who has just come back is touching the screen, and
+   * half a second of that was otherwise a chunk 0 with no screen in it.
+   *
+   * In the background or without a registered root there is no screen to
+   * capture yet; the marker opens the session alone.
+   */
+  async openSessionAfterIdle() {
+    const generation = this.lifecycleGeneration;
+    const rootTag = this.rootTag;
+    const options = this.options;
+    const sessionId = this.identity?.sessionId;
+    if (this.foreground && rootTag && options && sessionId) {
+      const capturedAtUnixMs = this.now();
+      let tree;
+      try {
+        tree = await this.nativeViewTree.captureViewTree(rootTag);
+      } catch (error) {
+        if (this.running && this.isCurrentGeneration(generation)) {
+          this.disable("native-capture-failed", {
+            name: error instanceof Error ? error.name : "Error"
+          });
+          this.haltCapture();
+        }
+        return;
+      }
+      if (!this.running || !this.isCurrentGeneration(generation) || this.identity?.sessionId !== sessionId) {
+        return;
+      }
+      if (this.foreground) {
+        this.touchPrivacyMap = deriveTouchPrivacyMap(tree);
+        this.appendCapture(tree, options, capturedAtUnixMs, true);
+      }
+    }
+    this.appendCustom(
+      SESSION_ROTATED_CUSTOM_EVENT_TAG,
+      { reason: "idle" },
+      void 0,
+      true
+    );
   }
   async completeSessionIdentityRotation(nowUnixMs, reason) {
     if (!this.sessionStore || !this.config || !this.options) {
       return;
     }
     this.identity = this.identityPersisted ? await this.sessionStore.rotate(nowUnixMs) : this.ephemeralIdentity(nowUnixMs);
+    this.sealedForIdle = false;
+    this.idlePause = null;
+    this.idleResumeBacklog = null;
     this.notifySessionChange();
     this.sampled = this.identityPersisted ? deterministicSample(
       this.identity.sessionId,
@@ -4753,6 +5325,10 @@ var MobileReplayRecorder = class {
     if (this.config.captureTrigger === "Always" /* Always */ && this.identityPersisted && !this.sampled && !this.config.isTargeted) {
       this.disable("not-sampled");
       this.haltCapture();
+      return;
+    }
+    if (this.captureTimer === null && this.running && this.foreground) {
+      this.startTimers();
     }
   }
   disable(code, details) {