@durable-streams/client 0.1.4 → 0.1.5

package/dist/index.cjs

@@ -541,6 +541,10 @@ async function* parseSSEStream(stream$1, signal) {
 //#endregion
 //#region src/response.ts
 /**
+* Constant used as abort reason when pausing the stream due to visibility change.
+*/
+const PAUSE_STREAM = `PAUSE_STREAM`;
+/**
 * Implementation of the StreamResponse interface.
 */
 var StreamResponseImpl = class {
@@ -565,6 +569,12 @@ var StreamResponseImpl = class {
 	#closed;
 	#stopAfterUpToDate = false;
 	#consumptionMethod = null;
+	#state = `active`;
+	#requestAbortController;
+	#unsubscribeFromVisibilityChanges;
+	#pausePromise;
+	#pauseResolve;
+	#justResumedFromPause = false;
 	#sseResilience;
 	#lastSSEConnectionStartTime;
 	#consecutiveShortSSEConnections = 0;
@@ -599,6 +609,59 @@ var StreamResponseImpl = class {
 			this.#closedReject = reject;
 		});
 		this.#responseStream = this.#createResponseStream(config.firstResponse);
+		this.#abortController.signal.addEventListener(`abort`, () => {
+			this.#requestAbortController?.abort(this.#abortController.signal.reason);
+			this.#pauseResolve?.();
+			this.#pausePromise = void 0;
+			this.#pauseResolve = void 0;
+		}, { once: true });
+		this.#subscribeToVisibilityChanges();
+	}
+	/**
+	* Subscribe to document visibility changes to pause/resume syncing.
+	* When the page is hidden, we pause to save battery and bandwidth.
+	* When visible again, we resume syncing.
+	*/
+	#subscribeToVisibilityChanges() {
+		if (typeof document === `object` && typeof document.hidden === `boolean` && typeof document.addEventListener === `function`) {
+			const visibilityHandler = () => {
+				if (document.hidden) this.#pause();
+				else this.#resume();
+			};
+			document.addEventListener(`visibilitychange`, visibilityHandler);
+			this.#unsubscribeFromVisibilityChanges = () => {
+				if (typeof document === `object`) document.removeEventListener(`visibilitychange`, visibilityHandler);
+			};
+			if (document.hidden) this.#pause();
+		}
+	}
+	/**
+	* Pause the stream when page becomes hidden.
+	* Aborts any in-flight request to free resources.
+	* Creates a promise that pull() will await while paused.
+	*/
+	#pause() {
+		if (this.#state === `active`) {
+			this.#state = `pause-requested`;
+			this.#pausePromise = new Promise((resolve) => {
+				this.#pauseResolve = resolve;
+			});
+			this.#requestAbortController?.abort(PAUSE_STREAM);
+		}
+	}
+	/**
+	* Resume the stream when page becomes visible.
+	* Resolves the pause promise to unblock pull().
+	*/
+	#resume() {
+		if (this.#state === `paused` || this.#state === `pause-requested`) {
+			if (this.#abortController.signal.aborted) return;
+			this.#state = `active`;
+			this.#justResumedFromPause = true;
+			this.#pauseResolve?.();
+			this.#pausePromise = void 0;
+			this.#pauseResolve = void 0;
+		}
 	}
 	get headers() {
 		return this.#headers;
@@ -619,9 +682,11 @@ var StreamResponseImpl = class {
 		if (!this.#isJsonMode) throw new DurableStreamError(`JSON methods are only valid for JSON-mode streams. Content-Type is "${this.contentType}" and json hint was not set.`, `BAD_REQUEST`);
 	}
 	#markClosed() {
+		this.#unsubscribeFromVisibilityChanges?.();
 		this.#closedResolve();
 	}
 	#markError(err) {
+		this.#unsubscribeFromVisibilityChanges?.();
 		this.#closedReject(err);
 	}
 	/**
@@ -734,8 +799,9 @@ var StreamResponseImpl = class {
 		const delayOrNull = await this.#handleSSEConnectionEnd();
 		if (delayOrNull === null) return null;
 		this.#markSSEConnectionStart();
-		const newSSEResponse = await this.#startSSE(this.offset, this.cursor, this.#abortController.signal);
-		if (newSSEResponse.body) return parseSSEStream(newSSEResponse.body, this.#abortController.signal);
+		this.#requestAbortController = new AbortController();
+		const newSSEResponse = await this.#startSSE(this.offset, this.cursor, this.#requestAbortController.signal);
+		if (newSSEResponse.body) return parseSSEStream(newSSEResponse.body, this.#requestAbortController.signal);
 		return null;
 	}
 	/**
@@ -821,7 +887,8 @@ var StreamResponseImpl = class {
 						const isSSE = firstResponse.headers.get(`content-type`)?.includes(`text/event-stream`) ?? false;
 						if (isSSE && firstResponse.body) {
 							this.#markSSEConnectionStart();
-							sseEventIterator = parseSSEStream(firstResponse.body, this.#abortController.signal);
+							this.#requestAbortController = new AbortController();
+							sseEventIterator = parseSSEStream(firstResponse.body, this.#requestAbortController.signal);
 						} else {
 							controller.enqueue(firstResponse);
 							if (this.upToDate && !this.#shouldContinueLive()) {
@@ -832,33 +899,63 @@ var StreamResponseImpl = class {
 							return;
 						}
 					}
-					if (sseEventIterator) while (true) {
-						const result = await this.#processSSEEvents(sseEventIterator);
-						switch (result.type) {
-							case `response`:
-								if (result.newIterator) sseEventIterator = result.newIterator;
-								controller.enqueue(result.response);
-								return;
-							case `closed`:
+					if (sseEventIterator) {
+						if (this.#state === `pause-requested` || this.#state === `paused`) {
+							this.#state = `paused`;
+							if (this.#pausePromise) await this.#pausePromise;
+							if (this.#abortController.signal.aborted) {
 								this.#markClosed();
 								controller.close();
 								return;
-							case `error`:
-								this.#markError(result.error);
-								controller.error(result.error);
+							}
+							const newIterator = await this.#trySSEReconnect();
+							if (newIterator) sseEventIterator = newIterator;
+							else {
+								this.#markClosed();
+								controller.close();
 								return;
-							case `continue`:
-								if (result.newIterator) sseEventIterator = result.newIterator;
-								continue;
+							}
+						}
+						while (true) {
+							const result = await this.#processSSEEvents(sseEventIterator);
+							switch (result.type) {
+								case `response`:
+									if (result.newIterator) sseEventIterator = result.newIterator;
+									controller.enqueue(result.response);
+									return;
+								case `closed`:
+									this.#markClosed();
+									controller.close();
+									return;
+								case `error`:
+									this.#markError(result.error);
+									controller.error(result.error);
+									return;
+								case `continue`:
+									if (result.newIterator) sseEventIterator = result.newIterator;
+									continue;
+							}
 						}
 					}
 					if (this.#shouldContinueLive()) {
+						if (this.#state === `pause-requested` || this.#state === `paused`) {
+							this.#state = `paused`;
+							if (this.#pausePromise) await this.#pausePromise;
+							if (this.#abortController.signal.aborted) {
+								this.#markClosed();
+								controller.close();
+								return;
+							}
+						}
 						if (this.#abortController.signal.aborted) {
 							this.#markClosed();
 							controller.close();
 							return;
 						}
-						const response = await this.#fetchNext(this.offset, this.cursor, this.#abortController.signal);
+						const resumingFromPause = this.#justResumedFromPause;
+						this.#justResumedFromPause = false;
+						this.#requestAbortController = new AbortController();
+						const response = await this.#fetchNext(this.offset, this.cursor, this.#requestAbortController.signal, resumingFromPause);
 						this.#updateStateFromResponse(response);
 						controller.enqueue(response);
 						return;
@@ -866,6 +963,10 @@ var StreamResponseImpl = class {
 					this.#markClosed();
 					controller.close();
 				} catch (err) {
+					if (this.#requestAbortController?.signal.aborted && this.#requestAbortController.signal.reason === PAUSE_STREAM) {
+						if (this.#state === `pause-requested`) this.#state = `paused`;
+						return;
+					}
 					if (this.#abortController.signal.aborted) {
 						this.#markClosed();
 						controller.close();
@@ -877,6 +978,7 @@ var StreamResponseImpl = class {
 			},
 			cancel: () => {
 				this.#abortController.abort();
+				this.#unsubscribeFromVisibilityChanges?.();
 				this.#markClosed();
 			}
 		});
@@ -1158,6 +1260,7 @@ var StreamResponseImpl = class {
 	}
 	cancel(reason) {
 		this.#abortController.abort(reason);
+		this.#unsubscribeFromVisibilityChanges?.();
 		this.#markClosed();
 	}
 	get closed() {
@@ -1372,11 +1475,13 @@ async function streamInternal(options) {
 	const initialCursor = firstResponse.headers.get(STREAM_CURSOR_HEADER) ?? void 0;
 	const initialUpToDate = firstResponse.headers.has(STREAM_UP_TO_DATE_HEADER);
 	const isJsonMode = options.json === true || (contentType?.includes(`application/json`) ?? false);
-	const fetchNext = async (offset, cursor, signal) => {
+	const fetchNext = async (offset, cursor, signal, resumingFromPause) => {
 		const nextUrl = new URL(url);
 		nextUrl.searchParams.set(OFFSET_QUERY_PARAM, offset);
-		if (live === `auto` || live === `long-poll`) nextUrl.searchParams.set(LIVE_QUERY_PARAM, `long-poll`);
-		else if (live === `sse`) nextUrl.searchParams.set(LIVE_QUERY_PARAM, `sse`);
+		if (!resumingFromPause) {
+			if (live === `auto` || live === `long-poll`) nextUrl.searchParams.set(LIVE_QUERY_PARAM, `long-poll`);
+			else if (live === `sse`) nextUrl.searchParams.set(LIVE_QUERY_PARAM, `sse`);
+		}
 		if (cursor) nextUrl.searchParams.set(`cursor`, cursor);
 		const nextParams = await resolveParams(options.params);
 		for (const [key, value] of Object.entries(nextParams)) nextUrl.searchParams.set(key, value);

package/dist/index.js

@@ -517,6 +517,10 @@ async function* parseSSEStream(stream$1, signal) {
 //#endregion
 //#region src/response.ts
 /**
+* Constant used as abort reason when pausing the stream due to visibility change.
+*/
+const PAUSE_STREAM = `PAUSE_STREAM`;
+/**
 * Implementation of the StreamResponse interface.
 */
 var StreamResponseImpl = class {
@@ -541,6 +545,12 @@ var StreamResponseImpl = class {
 	#closed;
 	#stopAfterUpToDate = false;
 	#consumptionMethod = null;
+	#state = `active`;
+	#requestAbortController;
+	#unsubscribeFromVisibilityChanges;
+	#pausePromise;
+	#pauseResolve;
+	#justResumedFromPause = false;
 	#sseResilience;
 	#lastSSEConnectionStartTime;
 	#consecutiveShortSSEConnections = 0;
@@ -575,6 +585,59 @@ var StreamResponseImpl = class {
 			this.#closedReject = reject;
 		});
 		this.#responseStream = this.#createResponseStream(config.firstResponse);
+		this.#abortController.signal.addEventListener(`abort`, () => {
+			this.#requestAbortController?.abort(this.#abortController.signal.reason);
+			this.#pauseResolve?.();
+			this.#pausePromise = void 0;
+			this.#pauseResolve = void 0;
+		}, { once: true });
+		this.#subscribeToVisibilityChanges();
+	}
+	/**
+	* Subscribe to document visibility changes to pause/resume syncing.
+	* When the page is hidden, we pause to save battery and bandwidth.
+	* When visible again, we resume syncing.
+	*/
+	#subscribeToVisibilityChanges() {
+		if (typeof document === `object` && typeof document.hidden === `boolean` && typeof document.addEventListener === `function`) {
+			const visibilityHandler = () => {
+				if (document.hidden) this.#pause();
+				else this.#resume();
+			};
+			document.addEventListener(`visibilitychange`, visibilityHandler);
+			this.#unsubscribeFromVisibilityChanges = () => {
+				if (typeof document === `object`) document.removeEventListener(`visibilitychange`, visibilityHandler);
+			};
+			if (document.hidden) this.#pause();
+		}
+	}
+	/**
+	* Pause the stream when page becomes hidden.
+	* Aborts any in-flight request to free resources.
+	* Creates a promise that pull() will await while paused.
+	*/
+	#pause() {
+		if (this.#state === `active`) {
+			this.#state = `pause-requested`;
+			this.#pausePromise = new Promise((resolve) => {
+				this.#pauseResolve = resolve;
+			});
+			this.#requestAbortController?.abort(PAUSE_STREAM);
+		}
+	}
+	/**
+	* Resume the stream when page becomes visible.
+	* Resolves the pause promise to unblock pull().
+	*/
+	#resume() {
+		if (this.#state === `paused` || this.#state === `pause-requested`) {
+			if (this.#abortController.signal.aborted) return;
+			this.#state = `active`;
+			this.#justResumedFromPause = true;
+			this.#pauseResolve?.();
+			this.#pausePromise = void 0;
+			this.#pauseResolve = void 0;
+		}
 	}
 	get headers() {
 		return this.#headers;
@@ -595,9 +658,11 @@ var StreamResponseImpl = class {
 		if (!this.#isJsonMode) throw new DurableStreamError(`JSON methods are only valid for JSON-mode streams. Content-Type is "${this.contentType}" and json hint was not set.`, `BAD_REQUEST`);
 	}
 	#markClosed() {
+		this.#unsubscribeFromVisibilityChanges?.();
 		this.#closedResolve();
 	}
 	#markError(err) {
+		this.#unsubscribeFromVisibilityChanges?.();
 		this.#closedReject(err);
 	}
 	/**
@@ -710,8 +775,9 @@ var StreamResponseImpl = class {
 		const delayOrNull = await this.#handleSSEConnectionEnd();
 		if (delayOrNull === null) return null;
 		this.#markSSEConnectionStart();
-		const newSSEResponse = await this.#startSSE(this.offset, this.cursor, this.#abortController.signal);
-		if (newSSEResponse.body) return parseSSEStream(newSSEResponse.body, this.#abortController.signal);
+		this.#requestAbortController = new AbortController();
+		const newSSEResponse = await this.#startSSE(this.offset, this.cursor, this.#requestAbortController.signal);
+		if (newSSEResponse.body) return parseSSEStream(newSSEResponse.body, this.#requestAbortController.signal);
 		return null;
 	}
 	/**
@@ -797,7 +863,8 @@ var StreamResponseImpl = class {
 						const isSSE = firstResponse.headers.get(`content-type`)?.includes(`text/event-stream`) ?? false;
 						if (isSSE && firstResponse.body) {
 							this.#markSSEConnectionStart();
-							sseEventIterator = parseSSEStream(firstResponse.body, this.#abortController.signal);
+							this.#requestAbortController = new AbortController();
+							sseEventIterator = parseSSEStream(firstResponse.body, this.#requestAbortController.signal);
 						} else {
 							controller.enqueue(firstResponse);
 							if (this.upToDate && !this.#shouldContinueLive()) {
@@ -808,33 +875,63 @@ var StreamResponseImpl = class {
 							return;
 						}
 					}
-					if (sseEventIterator) while (true) {
-						const result = await this.#processSSEEvents(sseEventIterator);
-						switch (result.type) {
-							case `response`:
-								if (result.newIterator) sseEventIterator = result.newIterator;
-								controller.enqueue(result.response);
-								return;
-							case `closed`:
+					if (sseEventIterator) {
+						if (this.#state === `pause-requested` || this.#state === `paused`) {
+							this.#state = `paused`;
+							if (this.#pausePromise) await this.#pausePromise;
+							if (this.#abortController.signal.aborted) {
 								this.#markClosed();
 								controller.close();
 								return;
-							case `error`:
-								this.#markError(result.error);
-								controller.error(result.error);
+							}
+							const newIterator = await this.#trySSEReconnect();
+							if (newIterator) sseEventIterator = newIterator;
+							else {
+								this.#markClosed();
+								controller.close();
 								return;
-							case `continue`:
-								if (result.newIterator) sseEventIterator = result.newIterator;
-								continue;
+							}
+						}
+						while (true) {
+							const result = await this.#processSSEEvents(sseEventIterator);
+							switch (result.type) {
+								case `response`:
+									if (result.newIterator) sseEventIterator = result.newIterator;
+									controller.enqueue(result.response);
+									return;
+								case `closed`:
+									this.#markClosed();
+									controller.close();
+									return;
+								case `error`:
+									this.#markError(result.error);
+									controller.error(result.error);
+									return;
+								case `continue`:
+									if (result.newIterator) sseEventIterator = result.newIterator;
+									continue;
+							}
 						}
 					}
 					if (this.#shouldContinueLive()) {
+						if (this.#state === `pause-requested` || this.#state === `paused`) {
+							this.#state = `paused`;
+							if (this.#pausePromise) await this.#pausePromise;
+							if (this.#abortController.signal.aborted) {
+								this.#markClosed();
+								controller.close();
+								return;
+							}
+						}
 						if (this.#abortController.signal.aborted) {
 							this.#markClosed();
 							controller.close();
 							return;
 						}
-						const response = await this.#fetchNext(this.offset, this.cursor, this.#abortController.signal);
+						const resumingFromPause = this.#justResumedFromPause;
+						this.#justResumedFromPause = false;
+						this.#requestAbortController = new AbortController();
+						const response = await this.#fetchNext(this.offset, this.cursor, this.#requestAbortController.signal, resumingFromPause);
 						this.#updateStateFromResponse(response);
 						controller.enqueue(response);
 						return;
@@ -842,6 +939,10 @@ var StreamResponseImpl = class {
 					this.#markClosed();
 					controller.close();
 				} catch (err) {
+					if (this.#requestAbortController?.signal.aborted && this.#requestAbortController.signal.reason === PAUSE_STREAM) {
+						if (this.#state === `pause-requested`) this.#state = `paused`;
+						return;
+					}
 					if (this.#abortController.signal.aborted) {
 						this.#markClosed();
 						controller.close();
@@ -853,6 +954,7 @@ var StreamResponseImpl = class {
 			},
 			cancel: () => {
 				this.#abortController.abort();
+				this.#unsubscribeFromVisibilityChanges?.();
 				this.#markClosed();
 			}
 		});
@@ -1134,6 +1236,7 @@ var StreamResponseImpl = class {
 	}
 	cancel(reason) {
 		this.#abortController.abort(reason);
+		this.#unsubscribeFromVisibilityChanges?.();
 		this.#markClosed();
 	}
 	get closed() {
@@ -1348,11 +1451,13 @@ async function streamInternal(options) {
 	const initialCursor = firstResponse.headers.get(STREAM_CURSOR_HEADER) ?? void 0;
 	const initialUpToDate = firstResponse.headers.has(STREAM_UP_TO_DATE_HEADER);
 	const isJsonMode = options.json === true || (contentType?.includes(`application/json`) ?? false);
-	const fetchNext = async (offset, cursor, signal) => {
+	const fetchNext = async (offset, cursor, signal, resumingFromPause) => {
 		const nextUrl = new URL(url);
 		nextUrl.searchParams.set(OFFSET_QUERY_PARAM, offset);
-		if (live === `auto` || live === `long-poll`) nextUrl.searchParams.set(LIVE_QUERY_PARAM, `long-poll`);
-		else if (live === `sse`) nextUrl.searchParams.set(LIVE_QUERY_PARAM, `sse`);
+		if (!resumingFromPause) {
+			if (live === `auto` || live === `long-poll`) nextUrl.searchParams.set(LIVE_QUERY_PARAM, `long-poll`);
+			else if (live === `sse`) nextUrl.searchParams.set(LIVE_QUERY_PARAM, `sse`);
+		}
 		if (cursor) nextUrl.searchParams.set(`cursor`, cursor);
 		const nextParams = await resolveParams(options.params);
 		for (const [key, value] of Object.entries(nextParams)) nextUrl.searchParams.set(key, value);

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@durable-streams/client",
   "description": "TypeScript client for the Durable Streams protocol",
-  "version": "0.1.4",
+  "version": "0.1.5",
   "author": "Durable Stream contributors",
   "license": "Apache-2.0",
   "repository": {
@@ -47,7 +47,7 @@
   "devDependencies": {
     "fast-check": "^4.4.0",
     "tsdown": "^0.9.0",
-    "@durable-streams/server": "0.1.5"
+    "@durable-streams/server": "0.1.6"
   },
   "engines": {
     "node": ">=18.0.0"

package/src/response.ts

@@ -25,6 +25,16 @@ import type {
   TextChunk,
 } from "./types"
 
+/**
+ * Constant used as abort reason when pausing the stream due to visibility change.
+ */
+const PAUSE_STREAM = `PAUSE_STREAM`
+
+/**
+ * State machine for visibility-based pause/resume.
+ */
+type StreamState = `active` | `pause-requested` | `paused`
+
 /**
  * Internal configuration for creating a StreamResponse.
  */
@@ -53,7 +63,8 @@ export interface StreamResponseConfig {
   fetchNext: (
     offset: Offset,
     cursor: string | undefined,
-    signal: AbortSignal
+    signal: AbortSignal,
+    resumingFromPause?: boolean
   ) => Promise<Response>
   /** Function to start SSE connection and return a Response with SSE body */
   startSSE?: (
@@ -100,6 +111,14 @@ export class StreamResponseImpl<
   #stopAfterUpToDate = false
   #consumptionMethod: string | null = null
 
+  // --- Visibility/Pause State ---
+  #state: StreamState = `active`
+  #requestAbortController?: AbortController
+  #unsubscribeFromVisibilityChanges?: () => void
+  #pausePromise?: Promise<void>
+  #pauseResolve?: () => void
+  #justResumedFromPause = false
+
   // --- SSE Resilience State ---
   #sseResilience: Required<SSEResilienceOptions>
   #lastSSEConnectionStartTime?: number
@@ -150,6 +169,97 @@ export class StreamResponseImpl<
 
     // Create the core response stream
     this.#responseStream = this.#createResponseStream(config.firstResponse)
+
+    // Install single abort listener that propagates to current request controller
+    // and unblocks any paused pull() (avoids accumulating one listener per request)
+    this.#abortController.signal.addEventListener(
+      `abort`,
+      () => {
+        this.#requestAbortController?.abort(this.#abortController.signal.reason)
+        // Unblock pull() if paused, so it can see the abort and close
+        this.#pauseResolve?.()
+        this.#pausePromise = undefined
+        this.#pauseResolve = undefined
+      },
+      { once: true }
+    )
+
+    // Subscribe to visibility changes for pause/resume (browser only)
+    this.#subscribeToVisibilityChanges()
+  }
+
+  /**
+   * Subscribe to document visibility changes to pause/resume syncing.
+   * When the page is hidden, we pause to save battery and bandwidth.
+   * When visible again, we resume syncing.
+   */
+  #subscribeToVisibilityChanges(): void {
+    // Only subscribe in browser environments
+    if (
+      typeof document === `object` &&
+      typeof document.hidden === `boolean` &&
+      typeof document.addEventListener === `function`
+    ) {
+      const visibilityHandler = (): void => {
+        if (document.hidden) {
+          this.#pause()
+        } else {
+          this.#resume()
+        }
+      }
+
+      document.addEventListener(`visibilitychange`, visibilityHandler)
+
+      // Store cleanup function to remove the event listener
+      // Check document still exists (may be undefined in tests after cleanup)
+      this.#unsubscribeFromVisibilityChanges = () => {
+        if (typeof document === `object`) {
+          document.removeEventListener(`visibilitychange`, visibilityHandler)
+        }
+      }
+
+      // Check initial state - page might already be hidden when stream starts
+      if (document.hidden) {
+        this.#pause()
+      }
+    }
+  }
+
+  /**
+   * Pause the stream when page becomes hidden.
+   * Aborts any in-flight request to free resources.
+   * Creates a promise that pull() will await while paused.
+   */
+  #pause(): void {
+    if (this.#state === `active`) {
+      this.#state = `pause-requested`
+      // Create promise that pull() will await
+      this.#pausePromise = new Promise((resolve) => {
+        this.#pauseResolve = resolve
+      })
+      // Abort current request if any
+      this.#requestAbortController?.abort(PAUSE_STREAM)
+    }
+  }
+
+  /**
+   * Resume the stream when page becomes visible.
+   * Resolves the pause promise to unblock pull().
+   */
+  #resume(): void {
+    if (this.#state === `paused` || this.#state === `pause-requested`) {
+      // Don't resume if the user's signal is already aborted
+      if (this.#abortController.signal.aborted) {
+        return
+      }
+
+      // Transition to active and resolve the pause promise
+      this.#state = `active`
+      this.#justResumedFromPause = true // Flag for single-shot skip of live param
+      this.#pauseResolve?.()
+      this.#pausePromise = undefined
+      this.#pauseResolve = undefined
+    }
   }
 
   // --- Response metadata getters ---
@@ -189,10 +299,12 @@ export class StreamResponseImpl<
   }
 
   #markClosed(): void {
+    this.#unsubscribeFromVisibilityChanges?.()
     this.#closedResolve()
   }
 
   #markError(err: Error): void {
+    this.#unsubscribeFromVisibilityChanges?.()
     this.#closedReject(err)
   }
 
@@ -388,13 +500,19 @@ export class StreamResponseImpl<
     // Track new connection start
     this.#markSSEConnectionStart()
 
+    // Create new per-request abort controller for this SSE connection
+    this.#requestAbortController = new AbortController()
+
     const newSSEResponse = await this.#startSSE(
       this.offset,
       this.cursor,
-      this.#abortController.signal
+      this.#requestAbortController.signal
     )
     if (newSSEResponse.body) {
-      return parseSSEStream(newSSEResponse.body, this.#abortController.signal)
+      return parseSSEStream(
+        newSSEResponse.body,
+        this.#requestAbortController.signal
+      )
     }
     return null
   }
@@ -548,10 +666,12 @@ export class StreamResponseImpl<
             if (isSSE && firstResponse.body) {
               // Track SSE connection start for resilience monitoring
               this.#markSSEConnectionStart()
+              // Create per-request abort controller for SSE connection
+              this.#requestAbortController = new AbortController()
               // Start parsing SSE events
               sseEventIterator = parseSSEStream(
                 firstResponse.body,
-                this.#abortController.signal
+                this.#requestAbortController.signal
               )
               // Fall through to SSE processing below
             } else {
@@ -570,6 +690,30 @@ export class StreamResponseImpl<
 
           // SSE mode: process events from the SSE stream
           if (sseEventIterator) {
+            // Check for pause state before processing SSE events
+            if (this.#state === `pause-requested` || this.#state === `paused`) {
+              this.#state = `paused`
+              if (this.#pausePromise) {
+                await this.#pausePromise
+              }
+              // After resume, check if we should still continue
+              if (this.#abortController.signal.aborted) {
+                this.#markClosed()
+                controller.close()
+                return
+              }
+              // Reconnect SSE after resume
+              const newIterator = await this.#trySSEReconnect()
+              if (newIterator) {
+                sseEventIterator = newIterator
+              } else {
+                // Could not reconnect - close the stream
+                this.#markClosed()
+                controller.close()
+                return
+              }
+            }
+
             // Keep reading events until we get data or stream ends
             // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
             while (true) {
@@ -604,16 +748,39 @@ export class StreamResponseImpl<
 
           // Long-poll mode: continue with live updates if needed
           if (this.#shouldContinueLive()) {
+            // If paused or pause-requested, await the pause promise
+            // This blocks pull() until resume() is called, avoiding deadlock
+            if (this.#state === `pause-requested` || this.#state === `paused`) {
+              this.#state = `paused`
+              if (this.#pausePromise) {
+                await this.#pausePromise
+              }
+              // After resume, check if we should still continue
+              if (this.#abortController.signal.aborted) {
+                this.#markClosed()
+                controller.close()
+                return
+              }
+            }
+
             if (this.#abortController.signal.aborted) {
               this.#markClosed()
               controller.close()
               return
             }
 
+            // Consume the single-shot resume flag (only first fetch after resume skips live param)
+            const resumingFromPause = this.#justResumedFromPause
+            this.#justResumedFromPause = false
+
+            // Create a new AbortController for this request (so we can abort on pause)
+            this.#requestAbortController = new AbortController()
+
             const response = await this.#fetchNext(
               this.offset,
               this.cursor,
-              this.#abortController.signal
+              this.#requestAbortController.signal,
+              resumingFromPause
             )
 
             this.#updateStateFromResponse(response)
@@ -626,6 +793,21 @@ export class StreamResponseImpl<
           this.#markClosed()
           controller.close()
         } catch (err) {
+          // Check if this was a pause-triggered abort
+          // Treat PAUSE_STREAM aborts as benign regardless of current state
+          // (handles race where resume() was called before abort completed)
+          if (
+            this.#requestAbortController?.signal.aborted &&
+            this.#requestAbortController.signal.reason === PAUSE_STREAM
+          ) {
+            // Only transition to paused if we're still in pause-requested state
+            if (this.#state === `pause-requested`) {
+              this.#state = `paused`
+            }
+            // Return - either we're paused, or already resumed and next pull will proceed
+            return
+          }
+
           if (this.#abortController.signal.aborted) {
             this.#markClosed()
             controller.close()
@@ -638,6 +820,7 @@ export class StreamResponseImpl<
 
       cancel: () => {
         this.#abortController.abort()
+        this.#unsubscribeFromVisibilityChanges?.()
         this.#markClosed()
       },
     })
@@ -1044,6 +1227,7 @@ export class StreamResponseImpl<
 
   cancel(reason?: unknown): void {
     this.#abortController.abort(reason)
+    this.#unsubscribeFromVisibilityChanges?.()
     this.#markClosed()
   }
 

package/src/stream-api.ts

@@ -191,16 +191,22 @@ async function streamInternal<TJson = unknown>(
   const fetchNext = async (
     offset: Offset,
     cursor: string | undefined,
-    signal: AbortSignal
+    signal: AbortSignal,
+    resumingFromPause?: boolean
   ): Promise<Response> => {
     const nextUrl = new URL(url)
     nextUrl.searchParams.set(OFFSET_QUERY_PARAM, offset)
 
     // For subsequent requests in auto mode, use long-poll
-    if (live === `auto` || live === `long-poll`) {
-      nextUrl.searchParams.set(LIVE_QUERY_PARAM, `long-poll`)
-    } else if (live === `sse`) {
-      nextUrl.searchParams.set(LIVE_QUERY_PARAM, `sse`)
+    // BUT: if we're resuming from a paused state, don't set live mode
+    // to avoid a long-poll that holds for 20sec - we want an immediate response
+    // so the UI can show "connected" status quickly
+    if (!resumingFromPause) {
+      if (live === `auto` || live === `long-poll`) {
+        nextUrl.searchParams.set(LIVE_QUERY_PARAM, `long-poll`)
+      } else if (live === `sse`) {
+        nextUrl.searchParams.set(LIVE_QUERY_PARAM, `sse`)
+      }
     }
 
     if (cursor) {