MonitorScope: pause()/resume() so background tabs don't keep an open WS

Adds pause()/resume() alongside existing start()/stop():
- pause(): stops the underlying pryv.Monitor (closes socket.io transport)
  but preserves accumulated state (events, streamsByID, oldestLoadedTime,
  maxModified). No-op if already paused or stopped.
- resume(): rebuilds the live monitor with the current maxModified so the
  catch-up events.get returns only what changed during the pause. No-op
  if not paused or already stopped.
- Extracts the existing live-monitor-build path into attachLiveMonitor()
  so start() and resume() share the same code.

Driven by the 2026-04-29 hds-prod-open-pryv-io incident where a single
backgrounded tab held a socket.io reconnect loop for ~5 days. v3.0.2 +
v3.0.3 of @pryv/socket.io already cap the loop; this is the third belt
— browser-tab visibility now severs the WS entirely, so backgrounded
sessions don't even attempt to keep one open. See
_macro/_plans/_TEMP/SESSION-2026-05-04.md.

Author: perki

ts/MonitorScope.ts

@@ -44,6 +44,7 @@ export class MonitorScope {
   private _hasMoreOlder: boolean = false;
   private maxModified: number = 0;
   private stopped: boolean = false;
+  private paused: boolean = false;
 
   constructor (connection: Connection, config: MonitorScopeConfig, callbacks: MonitorScopeCallbacks) {
     this.connection = connection;
@@ -130,7 +131,18 @@ export class MonitorScope {
     if (this.stopped) return;
 
     // Step 3: Start Monitor for real-time updates
-    // modifiedSince trick — initial fetch returns ~nothing
+    await this.attachLiveMonitor();
+  }
+
+  /**
+   * Build + start the live Monitor with the latest `maxModified` so any
+   * events created since the last seen update are caught up via the
+   * `modifiedSince` trick. Used both during initial start() and on
+   * resume() after a pause/visibilitychange cycle.
+   */
+  private async attachLiveMonitor (): Promise<void> {
+    if (this.stopped) return;
+    const toTime = this.config.toTime ?? (Date.now() / 1000);
     const eventsGetScope: any = {
       fromTime: this.config.fromTime,
       toTime,
@@ -162,6 +174,35 @@ export class MonitorScope {
     this.monitor.addUpdateMethod(new (pryv as any).Monitor.UpdateMethod.Socket());
   }
 
+  /**
+   * Pause the live monitor: closes the socket.io transport but preserves
+   * accumulated state (events, streams, oldestLoadedTime, maxModified).
+   * Use when the consumer's view becomes inactive (e.g. browser tab
+   * hidden) so a backgrounded session doesn't keep an open WebSocket.
+   *
+   * Cheap to call repeatedly — no-op if already paused or stopped.
+   */
+  pause (): void {
+    if (this.stopped || this.paused) return;
+    if (this.monitor) {
+      try { this.monitor.stop(); } catch (_) { /* ignore */ }
+      this.monitor = null;
+    }
+    this.paused = true;
+  }
+
+  /**
+   * Resume after a pause: rebuilds the Monitor with the current
+   * `maxModified` so the catch-up `events.get` returns only events
+   * created/changed during the pause. No-op if not paused or already
+   * stopped.
+   */
+  async resume (): Promise<void> {
+    if (this.stopped || !this.paused) return;
+    this.paused = false;
+    await this.attachLiveMonitor();
+  }
+
   /**
    * Load older events beyond current scope (triggered by scroll-up).
    * Loads pageSize events older than the oldest currently loaded.