@electric-sql/client 1.5.1 → 1.5.3

package/dist/index.mjs

@@ -467,6 +467,7 @@ var EXPERIMENTAL_LIVE_SSE_QUERY_PARAM = `experimental_live_sse`;
 var LIVE_SSE_QUERY_PARAM = `live_sse`;
 var FORCE_DISCONNECT_AND_REFRESH = `force-disconnect-and-refresh`;
 var PAUSE_STREAM = `pause-stream`;
+var SYSTEM_WAKE = `system-wake`;
 var LOG_MODE_QUERY_PARAM = `log`;
 var SUBSET_PARAM_WHERE = `subset__where`;
 var SUBSET_PARAM_LIMIT = `subset__limit`;
@@ -1094,6 +1095,544 @@ var SnapshotTracker = class {
   }
 };
 
+// src/shape-stream-state.ts
+var ShapeStreamState = class {
+  // --- Derived booleans ---
+  get isUpToDate() {
+    return false;
+  }
+  // --- Per-state field defaults ---
+  get staleCacheBuster() {
+    return void 0;
+  }
+  get staleCacheRetryCount() {
+    return 0;
+  }
+  get sseFallbackToLongPolling() {
+    return false;
+  }
+  get consecutiveShortSseConnections() {
+    return 0;
+  }
+  get replayCursor() {
+    return void 0;
+  }
+  // --- Default no-op methods ---
+  canEnterReplayMode() {
+    return false;
+  }
+  enterReplayMode(_cursor) {
+    return this;
+  }
+  shouldUseSse(_opts) {
+    return false;
+  }
+  handleSseConnectionClosed(_input) {
+    return {
+      state: this,
+      fellBackToLongPolling: false,
+      wasShortConnection: false
+    };
+  }
+  // --- URL param application ---
+  /** Adds state-specific query parameters to the fetch URL. */
+  applyUrlParams(_url, _context) {
+  }
+  // --- Default response/message handlers (Paused/Error never receive these) ---
+  handleResponseMetadata(_input) {
+    return { action: `ignored`, state: this };
+  }
+  handleMessageBatch(_input) {
+    return { state: this, suppressBatch: false, becameUpToDate: false };
+  }
+  pause() {
+    return new PausedState(this);
+  }
+  toErrorState(error) {
+    return new ErrorState(this, error);
+  }
+  markMustRefetch(handle) {
+    return new InitialState({
+      handle,
+      offset: `-1`,
+      liveCacheBuster: ``,
+      lastSyncedAt: this.lastSyncedAt,
+      schema: void 0
+    });
+  }
+};
+var _shared;
+var ActiveState = class extends ShapeStreamState {
+  constructor(shared) {
+    super();
+    __privateAdd(this, _shared);
+    __privateSet(this, _shared, shared);
+  }
+  get handle() {
+    return __privateGet(this, _shared).handle;
+  }
+  get offset() {
+    return __privateGet(this, _shared).offset;
+  }
+  get schema() {
+    return __privateGet(this, _shared).schema;
+  }
+  get liveCacheBuster() {
+    return __privateGet(this, _shared).liveCacheBuster;
+  }
+  get lastSyncedAt() {
+    return __privateGet(this, _shared).lastSyncedAt;
+  }
+  /** Expose shared fields to subclasses for spreading into new instances. */
+  get currentFields() {
+    return __privateGet(this, _shared);
+  }
+  // --- URL param application ---
+  applyUrlParams(url, _context) {
+    url.searchParams.set(OFFSET_QUERY_PARAM, __privateGet(this, _shared).offset);
+    if (__privateGet(this, _shared).handle) {
+      url.searchParams.set(SHAPE_HANDLE_QUERY_PARAM, __privateGet(this, _shared).handle);
+    }
+  }
+  // --- Helpers for subclass handleResponseMetadata implementations ---
+  /** Extracts updated SharedStateFields from response headers. */
+  parseResponseFields(input) {
+    var _a, _b, _c;
+    const responseHandle = input.responseHandle;
+    const handle = responseHandle && responseHandle !== input.expiredHandle ? responseHandle : __privateGet(this, _shared).handle;
+    const offset = (_a = input.responseOffset) != null ? _a : __privateGet(this, _shared).offset;
+    const liveCacheBuster = (_b = input.responseCursor) != null ? _b : __privateGet(this, _shared).liveCacheBuster;
+    const schema = (_c = __privateGet(this, _shared).schema) != null ? _c : input.responseSchema;
+    const lastSyncedAt = input.status === 204 ? input.now : __privateGet(this, _shared).lastSyncedAt;
+    return { handle, offset, schema, liveCacheBuster, lastSyncedAt };
+  }
+  /**
+   * Stale detection. Returns a transition if the response is stale,
+   * or null if it is not stale and the caller should proceed normally.
+   */
+  checkStaleResponse(input) {
+    const responseHandle = input.responseHandle;
+    const expiredHandle = input.expiredHandle;
+    if (!responseHandle || responseHandle !== expiredHandle) {
+      return null;
+    }
+    if (__privateGet(this, _shared).handle === void 0 || __privateGet(this, _shared).handle === expiredHandle) {
+      const retryCount = this.staleCacheRetryCount + 1;
+      return {
+        action: `stale-retry`,
+        state: new StaleRetryState(__spreadProps(__spreadValues({}, this.currentFields), {
+          staleCacheBuster: input.createCacheBuster(),
+          staleCacheRetryCount: retryCount
+        })),
+        exceededMaxRetries: retryCount > input.maxStaleCacheRetries
+      };
+    }
+    return { action: `ignored`, state: this };
+  }
+  // --- handleMessageBatch: template method with onUpToDate override point ---
+  handleMessageBatch(input) {
+    if (!input.hasMessages || !input.hasUpToDateMessage) {
+      return { state: this, suppressBatch: false, becameUpToDate: false };
+    }
+    let offset = __privateGet(this, _shared).offset;
+    if (input.isSse && input.upToDateOffset) {
+      offset = input.upToDateOffset;
+    }
+    const shared = {
+      handle: __privateGet(this, _shared).handle,
+      offset,
+      schema: __privateGet(this, _shared).schema,
+      liveCacheBuster: __privateGet(this, _shared).liveCacheBuster,
+      lastSyncedAt: input.now
+    };
+    return this.onUpToDate(shared, input);
+  }
+  /** Override point for up-to-date handling. Default → LiveState. */
+  onUpToDate(shared, _input) {
+    return {
+      state: new LiveState(shared),
+      suppressBatch: false,
+      becameUpToDate: true
+    };
+  }
+};
+_shared = new WeakMap();
+var FetchingState = class extends ActiveState {
+  handleResponseMetadata(input) {
+    const staleResult = this.checkStaleResponse(input);
+    if (staleResult) return staleResult;
+    const shared = this.parseResponseFields(input);
+    return { action: `accepted`, state: new SyncingState(shared) };
+  }
+  canEnterReplayMode() {
+    return true;
+  }
+  enterReplayMode(cursor) {
+    return new ReplayingState(__spreadProps(__spreadValues({}, this.currentFields), {
+      replayCursor: cursor
+    }));
+  }
+};
+var InitialState = class _InitialState extends FetchingState {
+  constructor(shared) {
+    super(shared);
+    this.kind = `initial`;
+  }
+  withHandle(handle) {
+    return new _InitialState(__spreadProps(__spreadValues({}, this.currentFields), { handle }));
+  }
+};
+var SyncingState = class _SyncingState extends FetchingState {
+  constructor(shared) {
+    super(shared);
+    this.kind = `syncing`;
+  }
+  withHandle(handle) {
+    return new _SyncingState(__spreadProps(__spreadValues({}, this.currentFields), { handle }));
+  }
+};
+var _staleCacheBuster, _staleCacheRetryCount;
+var _StaleRetryState = class _StaleRetryState extends FetchingState {
+  constructor(fields) {
+    const _a = fields, { staleCacheBuster, staleCacheRetryCount } = _a, shared = __objRest(_a, ["staleCacheBuster", "staleCacheRetryCount"]);
+    super(shared);
+    this.kind = `stale-retry`;
+    __privateAdd(this, _staleCacheBuster);
+    __privateAdd(this, _staleCacheRetryCount);
+    __privateSet(this, _staleCacheBuster, staleCacheBuster);
+    __privateSet(this, _staleCacheRetryCount, staleCacheRetryCount);
+  }
+  get staleCacheBuster() {
+    return __privateGet(this, _staleCacheBuster);
+  }
+  get staleCacheRetryCount() {
+    return __privateGet(this, _staleCacheRetryCount);
+  }
+  // StaleRetryState must not enter replay mode — it would lose the retry count
+  canEnterReplayMode() {
+    return false;
+  }
+  withHandle(handle) {
+    return new _StaleRetryState(__spreadProps(__spreadValues({}, this.currentFields), {
+      handle,
+      staleCacheBuster: __privateGet(this, _staleCacheBuster),
+      staleCacheRetryCount: __privateGet(this, _staleCacheRetryCount)
+    }));
+  }
+  applyUrlParams(url, context) {
+    super.applyUrlParams(url, context);
+    url.searchParams.set(CACHE_BUSTER_QUERY_PARAM, __privateGet(this, _staleCacheBuster));
+  }
+};
+_staleCacheBuster = new WeakMap();
+_staleCacheRetryCount = new WeakMap();
+var StaleRetryState = _StaleRetryState;
+var _consecutiveShortSseConnections, _sseFallbackToLongPolling;
+var _LiveState = class _LiveState extends ActiveState {
+  constructor(shared, sseState) {
+    var _a, _b;
+    super(shared);
+    this.kind = `live`;
+    __privateAdd(this, _consecutiveShortSseConnections);
+    __privateAdd(this, _sseFallbackToLongPolling);
+    __privateSet(this, _consecutiveShortSseConnections, (_a = sseState == null ? void 0 : sseState.consecutiveShortSseConnections) != null ? _a : 0);
+    __privateSet(this, _sseFallbackToLongPolling, (_b = sseState == null ? void 0 : sseState.sseFallbackToLongPolling) != null ? _b : false);
+  }
+  get isUpToDate() {
+    return true;
+  }
+  get consecutiveShortSseConnections() {
+    return __privateGet(this, _consecutiveShortSseConnections);
+  }
+  get sseFallbackToLongPolling() {
+    return __privateGet(this, _sseFallbackToLongPolling);
+  }
+  withHandle(handle) {
+    return new _LiveState(__spreadProps(__spreadValues({}, this.currentFields), { handle }), this.sseState);
+  }
+  applyUrlParams(url, context) {
+    super.applyUrlParams(url, context);
+    if (!context.isSnapshotRequest) {
+      url.searchParams.set(LIVE_CACHE_BUSTER_QUERY_PARAM, this.liveCacheBuster);
+      if (context.canLongPoll) {
+        url.searchParams.set(LIVE_QUERY_PARAM, `true`);
+      }
+    }
+  }
+  get sseState() {
+    return {
+      consecutiveShortSseConnections: __privateGet(this, _consecutiveShortSseConnections),
+      sseFallbackToLongPolling: __privateGet(this, _sseFallbackToLongPolling)
+    };
+  }
+  handleResponseMetadata(input) {
+    const staleResult = this.checkStaleResponse(input);
+    if (staleResult) return staleResult;
+    const shared = this.parseResponseFields(input);
+    return {
+      action: `accepted`,
+      state: new _LiveState(shared, this.sseState)
+    };
+  }
+  onUpToDate(shared, _input) {
+    return {
+      state: new _LiveState(shared, this.sseState),
+      suppressBatch: false,
+      becameUpToDate: true
+    };
+  }
+  shouldUseSse(opts) {
+    return opts.liveSseEnabled && !opts.isRefreshing && !opts.resumingFromPause && !__privateGet(this, _sseFallbackToLongPolling);
+  }
+  handleSseConnectionClosed(input) {
+    let nextConsecutiveShort = __privateGet(this, _consecutiveShortSseConnections);
+    let nextFallback = __privateGet(this, _sseFallbackToLongPolling);
+    let fellBackToLongPolling = false;
+    let wasShortConnection = false;
+    if (input.connectionDuration < input.minConnectionDuration && !input.wasAborted) {
+      wasShortConnection = true;
+      nextConsecutiveShort = nextConsecutiveShort + 1;
+      if (nextConsecutiveShort >= input.maxShortConnections) {
+        nextFallback = true;
+        fellBackToLongPolling = true;
+      }
+    } else if (input.connectionDuration >= input.minConnectionDuration) {
+      nextConsecutiveShort = 0;
+    }
+    return {
+      state: new _LiveState(this.currentFields, {
+        consecutiveShortSseConnections: nextConsecutiveShort,
+        sseFallbackToLongPolling: nextFallback
+      }),
+      fellBackToLongPolling,
+      wasShortConnection
+    };
+  }
+};
+_consecutiveShortSseConnections = new WeakMap();
+_sseFallbackToLongPolling = new WeakMap();
+var LiveState = _LiveState;
+var _replayCursor;
+var _ReplayingState = class _ReplayingState extends ActiveState {
+  constructor(fields) {
+    const _a = fields, { replayCursor } = _a, shared = __objRest(_a, ["replayCursor"]);
+    super(shared);
+    this.kind = `replaying`;
+    __privateAdd(this, _replayCursor);
+    __privateSet(this, _replayCursor, replayCursor);
+  }
+  get replayCursor() {
+    return __privateGet(this, _replayCursor);
+  }
+  withHandle(handle) {
+    return new _ReplayingState(__spreadProps(__spreadValues({}, this.currentFields), {
+      handle,
+      replayCursor: __privateGet(this, _replayCursor)
+    }));
+  }
+  handleResponseMetadata(input) {
+    const staleResult = this.checkStaleResponse(input);
+    if (staleResult) return staleResult;
+    const shared = this.parseResponseFields(input);
+    return {
+      action: `accepted`,
+      state: new _ReplayingState(__spreadProps(__spreadValues({}, shared), {
+        replayCursor: __privateGet(this, _replayCursor)
+      }))
+    };
+  }
+  onUpToDate(shared, input) {
+    const suppressBatch = !input.isSse && __privateGet(this, _replayCursor) === input.currentCursor;
+    return {
+      state: new LiveState(shared),
+      suppressBatch,
+      becameUpToDate: true
+    };
+  }
+};
+_replayCursor = new WeakMap();
+var ReplayingState = _ReplayingState;
+var PausedState = class _PausedState extends ShapeStreamState {
+  constructor(previousState) {
+    super();
+    this.kind = `paused`;
+    this.previousState = previousState;
+  }
+  get handle() {
+    return this.previousState.handle;
+  }
+  get offset() {
+    return this.previousState.offset;
+  }
+  get schema() {
+    return this.previousState.schema;
+  }
+  get liveCacheBuster() {
+    return this.previousState.liveCacheBuster;
+  }
+  get lastSyncedAt() {
+    return this.previousState.lastSyncedAt;
+  }
+  get isUpToDate() {
+    return this.previousState.isUpToDate;
+  }
+  get staleCacheBuster() {
+    return this.previousState.staleCacheBuster;
+  }
+  get staleCacheRetryCount() {
+    return this.previousState.staleCacheRetryCount;
+  }
+  get sseFallbackToLongPolling() {
+    return this.previousState.sseFallbackToLongPolling;
+  }
+  get consecutiveShortSseConnections() {
+    return this.previousState.consecutiveShortSseConnections;
+  }
+  get replayCursor() {
+    return this.previousState.replayCursor;
+  }
+  withHandle(handle) {
+    return new _PausedState(this.previousState.withHandle(handle));
+  }
+  applyUrlParams(url, context) {
+    this.previousState.applyUrlParams(url, context);
+  }
+  pause() {
+    return this;
+  }
+  resume() {
+    return this.previousState;
+  }
+};
+var ErrorState = class _ErrorState extends ShapeStreamState {
+  constructor(previousState, error) {
+    super();
+    this.kind = `error`;
+    this.previousState = previousState;
+    this.error = error;
+  }
+  get handle() {
+    return this.previousState.handle;
+  }
+  get offset() {
+    return this.previousState.offset;
+  }
+  get schema() {
+    return this.previousState.schema;
+  }
+  get liveCacheBuster() {
+    return this.previousState.liveCacheBuster;
+  }
+  get lastSyncedAt() {
+    return this.previousState.lastSyncedAt;
+  }
+  get isUpToDate() {
+    return this.previousState.isUpToDate;
+  }
+  withHandle(handle) {
+    return new _ErrorState(this.previousState.withHandle(handle), this.error);
+  }
+  applyUrlParams(url, context) {
+    this.previousState.applyUrlParams(url, context);
+  }
+  retry() {
+    return this.previousState;
+  }
+  reset(handle) {
+    return this.previousState.markMustRefetch(handle);
+  }
+};
+function createInitialState(opts) {
+  return new InitialState({
+    handle: opts.handle,
+    offset: opts.offset,
+    liveCacheBuster: ``,
+    lastSyncedAt: void 0,
+    schema: void 0
+  });
+}
+
+// src/pause-lock.ts
+var _holders, _onAcquired, _onReleased;
+var PauseLock = class {
+  constructor(callbacks) {
+    __privateAdd(this, _holders, /* @__PURE__ */ new Set());
+    __privateAdd(this, _onAcquired);
+    __privateAdd(this, _onReleased);
+    __privateSet(this, _onAcquired, callbacks.onAcquired);
+    __privateSet(this, _onReleased, callbacks.onReleased);
+  }
+  /**
+   * Acquire the lock for a given reason. Idempotent — acquiring the same
+   * reason twice is a no-op (but logs a warning since it likely indicates
+   * a caller bug).
+   *
+   * Fires `onAcquired` when the first reason is acquired (transition from
+   * unlocked to locked).
+   */
+  acquire(reason) {
+    if (__privateGet(this, _holders).has(reason)) {
+      console.warn(
+        `[Electric] PauseLock: "${reason}" already held \u2014 ignoring duplicate acquire`
+      );
+      return;
+    }
+    const wasUnlocked = __privateGet(this, _holders).size === 0;
+    __privateGet(this, _holders).add(reason);
+    if (wasUnlocked) {
+      __privateGet(this, _onAcquired).call(this);
+    }
+  }
+  /**
+   * Release the lock for a given reason. Releasing a reason that isn't
+   * held logs a warning (likely indicates an acquire/release mismatch).
+   *
+   * Fires `onReleased` when the last reason is released (transition from
+   * locked to unlocked).
+   */
+  release(reason) {
+    if (!__privateGet(this, _holders).delete(reason)) {
+      console.warn(
+        `[Electric] PauseLock: "${reason}" not held \u2014 ignoring release (possible acquire/release mismatch)`
+      );
+      return;
+    }
+    if (__privateGet(this, _holders).size === 0) {
+      __privateGet(this, _onReleased).call(this);
+    }
+  }
+  /**
+   * Whether the lock is currently held by any reason.
+   */
+  get isPaused() {
+    return __privateGet(this, _holders).size > 0;
+  }
+  /**
+   * Check if a specific reason is holding the lock.
+   */
+  isHeldBy(reason) {
+    return __privateGet(this, _holders).has(reason);
+  }
+  /**
+   * Release all reasons matching a prefix. Does NOT fire `onReleased` —
+   * this is for cleanup/reset paths where the stream state is being
+   * managed separately.
+   *
+   * This preserves reasons with different prefixes (e.g., 'visibility'
+   * is preserved when clearing 'snapshot-*' reasons).
+   */
+  releaseAllMatching(prefix) {
+    for (const reason of __privateGet(this, _holders)) {
+      if (reason.startsWith(prefix)) {
+        __privateGet(this, _holders).delete(reason);
+      }
+    }
+  }
+};
+_holders = new WeakMap();
+_onAcquired = new WeakMap();
+_onReleased = new WeakMap();
+
 // src/client.ts
 var RESERVED_PARAMS = /* @__PURE__ */ new Set([
   LIVE_CACHE_BUSTER_QUERY_PARAM,
@@ -1142,7 +1681,7 @@ function canonicalShapeKey(url) {
   cleanUrl.searchParams.sort();
   return cleanUrl.toString();
 }
-var _error, _fetchClient2, _sseFetchClient, _messageParser, _subscribers, _started, _state, _lastOffset, _liveCacheBuster, _lastSyncedAt, _isUpToDate, _isMidStream, _connected, _shapeHandle, _mode, _schema, _onError, _requestAbortController, _isRefreshing, _tickPromise, _tickPromiseResolver, _tickPromiseRejecter, _messageChain, _snapshotTracker, _activeSnapshotRequests, _midStreamPromise, _midStreamPromiseResolver, _lastSeenCursor, _currentFetchUrl, _lastSseConnectionStartTime, _minSseConnectionDuration, _consecutiveShortSseConnections, _maxShortSseConnections, _sseFallbackToLongPolling, _sseBackoffBaseDelay, _sseBackoffMaxDelay, _unsubscribeFromVisibilityChanges, _staleCacheBuster, _staleCacheRetryCount, _maxStaleCacheRetries, _ShapeStream_instances, replayMode_get, start_fn, requestShape_fn, constructUrl_fn, createAbortListener_fn, onInitialResponse_fn, onMessages_fn, fetchShape_fn, requestShapeLongPoll_fn, requestShapeSSE_fn, pause_fn, resume_fn, nextTick_fn, waitForStreamEnd_fn, publish_fn, sendErrorToSubscribers_fn, subscribeToVisibilityChanges_fn, reset_fn, buildSubsetBody_fn;
+var _error, _fetchClient2, _sseFetchClient, _messageParser, _subscribers, _started, _syncState, _connected, _mode, _onError, _requestAbortController, _refreshCount, _snapshotCounter, _ShapeStream_instances, isRefreshing_get, _tickPromise, _tickPromiseResolver, _tickPromiseRejecter, _messageChain, _snapshotTracker, _pauseLock, _currentFetchUrl, _lastSseConnectionStartTime, _minSseConnectionDuration, _maxShortSseConnections, _sseBackoffBaseDelay, _sseBackoffMaxDelay, _unsubscribeFromVisibilityChanges, _unsubscribeFromWakeDetection, _maxStaleCacheRetries, start_fn, teardown_fn, requestShape_fn, constructUrl_fn, createAbortListener_fn, onInitialResponse_fn, onMessages_fn, fetchShape_fn, requestShapeLongPoll_fn, requestShapeSSE_fn, nextTick_fn, publish_fn, sendErrorToSubscribers_fn, hasBrowserVisibilityAPI_fn, subscribeToVisibilityChanges_fn, subscribeToWakeDetection_fn, reset_fn, buildSubsetBody_fn;
 var ShapeStream = class {
   constructor(options) {
     __privateAdd(this, _ShapeStream_instances);
@@ -1152,57 +1691,57 @@ var ShapeStream = class {
     __privateAdd(this, _messageParser);
     __privateAdd(this, _subscribers, /* @__PURE__ */ new Map());
     __privateAdd(this, _started, false);
-    __privateAdd(this, _state, `active`);
-    __privateAdd(this, _lastOffset);
-    __privateAdd(this, _liveCacheBuster);
-    // Seconds since our Electric Epoch 😎
-    __privateAdd(this, _lastSyncedAt);
-    // unix time
-    __privateAdd(this, _isUpToDate, false);
-    __privateAdd(this, _isMidStream, true);
+    __privateAdd(this, _syncState);
     __privateAdd(this, _connected, false);
-    __privateAdd(this, _shapeHandle);
     __privateAdd(this, _mode);
-    __privateAdd(this, _schema);
     __privateAdd(this, _onError);
     __privateAdd(this, _requestAbortController);
-    __privateAdd(this, _isRefreshing, false);
+    __privateAdd(this, _refreshCount, 0);
+    __privateAdd(this, _snapshotCounter, 0);
     __privateAdd(this, _tickPromise);
     __privateAdd(this, _tickPromiseResolver);
     __privateAdd(this, _tickPromiseRejecter);
     __privateAdd(this, _messageChain, Promise.resolve([]));
     // promise chain for incoming messages
     __privateAdd(this, _snapshotTracker, new SnapshotTracker());
-    __privateAdd(this, _activeSnapshotRequests, 0);
-    // counter for concurrent snapshot requests
-    __privateAdd(this, _midStreamPromise);
-    __privateAdd(this, _midStreamPromiseResolver);
-    __privateAdd(this, _lastSeenCursor);
-    // Last seen cursor from previous session (used to detect cached responses)
+    __privateAdd(this, _pauseLock);
     __privateAdd(this, _currentFetchUrl);
     // Current fetch URL for computing shape key
     __privateAdd(this, _lastSseConnectionStartTime);
     __privateAdd(this, _minSseConnectionDuration, 1e3);
     // Minimum expected SSE connection duration (1 second)
-    __privateAdd(this, _consecutiveShortSseConnections, 0);
     __privateAdd(this, _maxShortSseConnections, 3);
     // Fall back to long polling after this many short connections
-    __privateAdd(this, _sseFallbackToLongPolling, false);
     __privateAdd(this, _sseBackoffBaseDelay, 100);
     // Base delay for exponential backoff (ms)
     __privateAdd(this, _sseBackoffMaxDelay, 5e3);
     // Maximum delay cap (ms)
     __privateAdd(this, _unsubscribeFromVisibilityChanges);
-    __privateAdd(this, _staleCacheBuster);
-    // Cache buster set when stale CDN response detected, used on retry requests to bypass cache
-    __privateAdd(this, _staleCacheRetryCount, 0);
+    __privateAdd(this, _unsubscribeFromWakeDetection);
     __privateAdd(this, _maxStaleCacheRetries, 3);
     var _a, _b, _c, _d;
     this.options = __spreadValues({ subscribe: true }, options);
     validateOptions(this.options);
-    __privateSet(this, _lastOffset, (_a = this.options.offset) != null ? _a : `-1`);
-    __privateSet(this, _liveCacheBuster, ``);
-    __privateSet(this, _shapeHandle, this.options.handle);
+    __privateSet(this, _syncState, createInitialState({
+      offset: (_a = this.options.offset) != null ? _a : `-1`,
+      handle: this.options.handle
+    }));
+    __privateSet(this, _pauseLock, new PauseLock({
+      onAcquired: () => {
+        var _a2;
+        __privateSet(this, _syncState, __privateGet(this, _syncState).pause());
+        if (__privateGet(this, _started)) {
+          (_a2 = __privateGet(this, _requestAbortController)) == null ? void 0 : _a2.abort(PAUSE_STREAM);
+        }
+      },
+      onReleased: () => {
+        var _a2;
+        if (!__privateGet(this, _started)) return;
+        if ((_a2 = this.options.signal) == null ? void 0 : _a2.aborted) return;
+        __privateMethod(this, _ShapeStream_instances, start_fn).call(this).catch(() => {
+        });
+      }
+    }));
     let transformer;
     if (options.columnMapper) {
       const applyColumnMapper = (row) => {
@@ -1237,18 +1776,19 @@ var ShapeStream = class {
     ));
     __privateSet(this, _fetchClient2, createFetchWithConsumedMessages(__privateGet(this, _sseFetchClient)));
     __privateMethod(this, _ShapeStream_instances, subscribeToVisibilityChanges_fn).call(this);
+    __privateMethod(this, _ShapeStream_instances, subscribeToWakeDetection_fn).call(this);
   }
   get shapeHandle() {
-    return __privateGet(this, _shapeHandle);
+    return __privateGet(this, _syncState).handle;
   }
   get error() {
     return __privateGet(this, _error);
   }
   get isUpToDate() {
-    return __privateGet(this, _isUpToDate);
+    return __privateGet(this, _syncState).isUpToDate;
   }
   get lastOffset() {
-    return __privateGet(this, _lastOffset);
+    return __privateGet(this, _syncState).offset;
   }
   get mode() {
     return __privateGet(this, _mode);
@@ -1263,32 +1803,33 @@ var ShapeStream = class {
     };
   }
   unsubscribeAll() {
-    var _a;
+    var _a, _b;
     __privateGet(this, _subscribers).clear();
     (_a = __privateGet(this, _unsubscribeFromVisibilityChanges)) == null ? void 0 : _a.call(this);
+    (_b = __privateGet(this, _unsubscribeFromWakeDetection)) == null ? void 0 : _b.call(this);
   }
-  /** Unix time at which we last synced. Undefined when `isLoading` is true. */
+  /** Unix time at which we last synced. Undefined until first successful up-to-date. */
   lastSyncedAt() {
-    return __privateGet(this, _lastSyncedAt);
+    return __privateGet(this, _syncState).lastSyncedAt;
   }
   /** Time elapsed since last sync (in ms). Infinity if we did not yet sync. */
   lastSynced() {
-    if (__privateGet(this, _lastSyncedAt) === void 0) return Infinity;
-    return Date.now() - __privateGet(this, _lastSyncedAt);
+    if (__privateGet(this, _syncState).lastSyncedAt === void 0) return Infinity;
+    return Date.now() - __privateGet(this, _syncState).lastSyncedAt;
   }
   /** Indicates if we are connected to the Electric sync service. */
   isConnected() {
     return __privateGet(this, _connected);
   }
-  /** True during initial fetch. False afterwise.  */
+  /** True during initial fetch. False afterwards.  */
   isLoading() {
-    return !__privateGet(this, _isUpToDate);
+    return !__privateGet(this, _syncState).isUpToDate;
   }
   hasStarted() {
     return __privateGet(this, _started);
   }
   isPaused() {
-    return __privateGet(this, _state) === `paused`;
+    return __privateGet(this, _pauseLock).isPaused;
   }
   /**
    * Refreshes the shape stream.
@@ -1298,12 +1839,15 @@ var ShapeStream = class {
    */
   async forceDisconnectAndRefresh() {
     var _a, _b;
-    __privateSet(this, _isRefreshing, true);
-    if (__privateGet(this, _isUpToDate) && !((_a = __privateGet(this, _requestAbortController)) == null ? void 0 : _a.signal.aborted)) {
-      (_b = __privateGet(this, _requestAbortController)) == null ? void 0 : _b.abort(FORCE_DISCONNECT_AND_REFRESH);
+    __privateWrapper(this, _refreshCount)._++;
+    try {
+      if (__privateGet(this, _syncState).isUpToDate && !((_a = __privateGet(this, _requestAbortController)) == null ? void 0 : _a.signal.aborted)) {
+        (_b = __privateGet(this, _requestAbortController)) == null ? void 0 : _b.abort(FORCE_DISCONNECT_AND_REFRESH);
+      }
+      await __privateMethod(this, _ShapeStream_instances, nextTick_fn).call(this);
+    } finally {
+      __privateWrapper(this, _refreshCount)._--;
     }
-    await __privateMethod(this, _ShapeStream_instances, nextTick_fn).call(this);
-    __privateSet(this, _isRefreshing, false);
   }
   /**
    * Request a snapshot for subset of data and inject it into the subscribed data stream.
@@ -1325,13 +1869,18 @@ var ShapeStream = class {
         `Snapshot requests are not supported in ${__privateGet(this, _mode)} mode, as the consumer is guaranteed to observe all data`
       );
     }
-    if (!__privateGet(this, _started)) await __privateMethod(this, _ShapeStream_instances, start_fn).call(this);
-    await __privateMethod(this, _ShapeStream_instances, waitForStreamEnd_fn).call(this);
-    __privateWrapper(this, _activeSnapshotRequests)._++;
+    if (!__privateGet(this, _started)) {
+      __privateMethod(this, _ShapeStream_instances, start_fn).call(this).catch(() => {
+      });
+    }
+    const snapshotReason = `snapshot-${++__privateWrapper(this, _snapshotCounter)._}`;
+    __privateGet(this, _pauseLock).acquire(snapshotReason);
+    const snapshotWarnTimer = setTimeout(() => {
+      console.warn(
+        `[Electric] Snapshot "${snapshotReason}" has held the pause lock for 30s \u2014 possible hung request or leaked lock. Current holders: ${[.../* @__PURE__ */ new Set([snapshotReason])].join(`, `)}`
+      );
+    }, 3e4);
     try {
-      if (__privateGet(this, _activeSnapshotRequests) === 1) {
-        __privateMethod(this, _ShapeStream_instances, pause_fn).call(this);
-      }
       const { metadata, data } = await this.fetchSnapshot(opts);
       const dataWithEndBoundary = data.concat([
         { headers: __spreadValues({ control: `snapshot-end` }, metadata) },
@@ -1347,10 +1896,8 @@ var ShapeStream = class {
         data
       };
     } finally {
-      __privateWrapper(this, _activeSnapshotRequests)._--;
-      if (__privateGet(this, _activeSnapshotRequests) === 0) {
-        __privateMethod(this, _ShapeStream_instances, resume_fn).call(this);
-      }
+      clearTimeout(snapshotWarnTimer);
+      __privateGet(this, _pauseLock).release(snapshotReason);
     }
   }
   /**
@@ -1385,7 +1932,7 @@ var ShapeStream = class {
       fetchUrl = result.fetchUrl;
       fetchOptions = { headers: result.requestHeaders };
     }
-    const usedHandle = __privateGet(this, _shapeHandle);
+    const usedHandle = __privateGet(this, _syncState).handle;
     let response;
     try {
       response = await __privateGet(this, _fetchClient2).call(this, fetchUrl.toString(), fetchOptions);
@@ -1395,7 +1942,8 @@ var ShapeStream = class {
           const shapeKey = canonicalShapeKey(fetchUrl);
           expiredShapesCache.markExpired(shapeKey, usedHandle);
         }
-        __privateSet(this, _shapeHandle, e.headers[SHAPE_HANDLE_HEADER] || `${usedHandle != null ? usedHandle : `handle`}-next`);
+        const nextHandle = e.headers[SHAPE_HANDLE_HEADER] || `${usedHandle != null ? usedHandle : `handle`}-next`;
+        __privateSet(this, _syncState, __privateGet(this, _syncState).withHandle(nextHandle));
         return this.fetchSnapshot(opts);
       }
       throw e;
@@ -1403,7 +1951,7 @@ var ShapeStream = class {
     if (!response.ok) {
       throw await FetchError.fromResponse(response, fetchUrl.toString());
     }
-    const schema = (_c = __privateGet(this, _schema)) != null ? _c : getSchemaFromHeaders(response.headers, {
+    const schema = (_c = __privateGet(this, _syncState).schema) != null ? _c : getSchemaFromHeaders(response.headers, {
       required: true,
       url: fetchUrl.toString()
     });
@@ -1421,51 +1969,42 @@ _sseFetchClient = new WeakMap();
 _messageParser = new WeakMap();
 _subscribers = new WeakMap();
 _started = new WeakMap();
-_state = new WeakMap();
-_lastOffset = new WeakMap();
-_liveCacheBuster = new WeakMap();
-_lastSyncedAt = new WeakMap();
-_isUpToDate = new WeakMap();
-_isMidStream = new WeakMap();
+_syncState = new WeakMap();
 _connected = new WeakMap();
-_shapeHandle = new WeakMap();
 _mode = new WeakMap();
-_schema = new WeakMap();
 _onError = new WeakMap();
 _requestAbortController = new WeakMap();
-_isRefreshing = new WeakMap();
+_refreshCount = new WeakMap();
+_snapshotCounter = new WeakMap();
+_ShapeStream_instances = new WeakSet();
+isRefreshing_get = function() {
+  return __privateGet(this, _refreshCount) > 0;
+};
 _tickPromise = new WeakMap();
 _tickPromiseResolver = new WeakMap();
 _tickPromiseRejecter = new WeakMap();
 _messageChain = new WeakMap();
 _snapshotTracker = new WeakMap();
-_activeSnapshotRequests = new WeakMap();
-_midStreamPromise = new WeakMap();
-_midStreamPromiseResolver = new WeakMap();
-_lastSeenCursor = new WeakMap();
+_pauseLock = new WeakMap();
 _currentFetchUrl = new WeakMap();
 _lastSseConnectionStartTime = new WeakMap();
 _minSseConnectionDuration = new WeakMap();
-_consecutiveShortSseConnections = new WeakMap();
 _maxShortSseConnections = new WeakMap();
-_sseFallbackToLongPolling = new WeakMap();
 _sseBackoffBaseDelay = new WeakMap();
 _sseBackoffMaxDelay = new WeakMap();
 _unsubscribeFromVisibilityChanges = new WeakMap();
-_staleCacheBuster = new WeakMap();
-_staleCacheRetryCount = new WeakMap();
+_unsubscribeFromWakeDetection = new WeakMap();
 _maxStaleCacheRetries = new WeakMap();
-_ShapeStream_instances = new WeakSet();
-replayMode_get = function() {
-  return __privateGet(this, _lastSeenCursor) !== void 0;
-};
 start_fn = async function() {
-  var _a, _b, _c, _d, _e;
+  var _a, _b;
   __privateSet(this, _started, true);
   try {
     await __privateMethod(this, _ShapeStream_instances, requestShape_fn).call(this);
   } catch (err) {
     __privateSet(this, _error, err);
+    if (err instanceof Error) {
+      __privateSet(this, _syncState, __privateGet(this, _syncState).toErrorState(err));
+    }
     if (__privateGet(this, _onError)) {
       const retryOpts = await __privateGet(this, _onError).call(this, err);
       const isRetryable = !(err instanceof MissingHeadersError);
@@ -1477,6 +2016,9 @@ start_fn = async function() {
           this.options.headers = __spreadValues(__spreadValues({}, (_b = this.options.headers) != null ? _b : {}), retryOpts.headers);
         }
         __privateSet(this, _error, null);
+        if (__privateGet(this, _syncState) instanceof ErrorState) {
+          __privateSet(this, _syncState, __privateGet(this, _syncState).retry());
+        }
         __privateSet(this, _started, false);
         await __privateMethod(this, _ShapeStream_instances, start_fn).call(this);
         return;
@@ -1484,35 +2026,45 @@ start_fn = async function() {
       if (err instanceof Error) {
         __privateMethod(this, _ShapeStream_instances, sendErrorToSubscribers_fn).call(this, err);
       }
-      __privateSet(this, _connected, false);
-      (_c = __privateGet(this, _tickPromiseRejecter)) == null ? void 0 : _c.call(this);
+      __privateMethod(this, _ShapeStream_instances, teardown_fn).call(this);
       return;
     }
     if (err instanceof Error) {
       __privateMethod(this, _ShapeStream_instances, sendErrorToSubscribers_fn).call(this, err);
     }
-    __privateSet(this, _connected, false);
-    (_d = __privateGet(this, _tickPromiseRejecter)) == null ? void 0 : _d.call(this);
+    __privateMethod(this, _ShapeStream_instances, teardown_fn).call(this);
     throw err;
   }
+  __privateMethod(this, _ShapeStream_instances, teardown_fn).call(this);
+};
+teardown_fn = function() {
+  var _a, _b;
   __privateSet(this, _connected, false);
-  (_e = __privateGet(this, _tickPromiseRejecter)) == null ? void 0 : _e.call(this);
+  (_a = __privateGet(this, _tickPromiseRejecter)) == null ? void 0 : _a.call(this);
+  (_b = __privateGet(this, _unsubscribeFromWakeDetection)) == null ? void 0 : _b.call(this);
 };
 requestShape_fn = async function() {
   var _a, _b;
-  if (__privateGet(this, _state) === `pause-requested`) {
-    __privateSet(this, _state, `paused`);
+  if (__privateGet(this, _pauseLock).isPaused) return;
+  if (!this.options.subscribe && (((_a = this.options.signal) == null ? void 0 : _a.aborted) || __privateGet(this, _syncState).isUpToDate)) {
     return;
   }
-  if (!this.options.subscribe && (((_a = this.options.signal) == null ? void 0 : _a.aborted) || __privateGet(this, _isUpToDate))) {
-    return;
+  let resumingFromPause = false;
+  if (__privateGet(this, _syncState) instanceof PausedState) {
+    resumingFromPause = true;
+    __privateSet(this, _syncState, __privateGet(this, _syncState).resume());
   }
-  const resumingFromPause = __privateGet(this, _state) === `paused`;
-  __privateSet(this, _state, `active`);
   const { url, signal } = this.options;
   const { fetchUrl, requestHeaders } = await __privateMethod(this, _ShapeStream_instances, constructUrl_fn).call(this, url, resumingFromPause);
   const abortListener = await __privateMethod(this, _ShapeStream_instances, createAbortListener_fn).call(this, signal);
   const requestAbortController = __privateGet(this, _requestAbortController);
+  if (__privateGet(this, _pauseLock).isPaused) {
+    if (abortListener && signal) {
+      signal.removeEventListener(`abort`, abortListener);
+    }
+    __privateSet(this, _requestAbortController, void 0);
+    return;
+  }
   try {
     await __privateMethod(this, _ShapeStream_instances, fetchShape_fn).call(this, {
       fetchUrl,
@@ -1521,14 +2073,12 @@ requestShape_fn = async function() {
       resumingFromPause
     });
   } catch (e) {
-    if ((e instanceof FetchError || e instanceof FetchBackoffAbortError) && requestAbortController.signal.aborted && requestAbortController.signal.reason === FORCE_DISCONNECT_AND_REFRESH) {
+    const abortReason = requestAbortController.signal.reason;
+    const isRestartAbort = requestAbortController.signal.aborted && (abortReason === FORCE_DISCONNECT_AND_REFRESH || abortReason === SYSTEM_WAKE);
+    if ((e instanceof FetchError || e instanceof FetchBackoffAbortError) && isRestartAbort) {
       return __privateMethod(this, _ShapeStream_instances, requestShape_fn).call(this);
     }
     if (e instanceof FetchBackoffAbortError) {
-      const currentState = __privateGet(this, _state);
-      if (requestAbortController.signal.aborted && requestAbortController.signal.reason === PAUSE_STREAM && currentState === `pause-requested`) {
-        __privateSet(this, _state, `paused`);
-      }
       return;
     }
     if (e instanceof StaleCacheError) {
@@ -1536,11 +2086,11 @@ requestShape_fn = async function() {
     }
     if (!(e instanceof FetchError)) throw e;
     if (e.status == 409) {
-      if (__privateGet(this, _shapeHandle)) {
+      if (__privateGet(this, _syncState).handle) {
         const shapeKey = canonicalShapeKey(fetchUrl);
-        expiredShapesCache.markExpired(shapeKey, __privateGet(this, _shapeHandle));
+        expiredShapesCache.markExpired(shapeKey, __privateGet(this, _syncState).handle);
       }
-      const newShapeHandle = e.headers[SHAPE_HANDLE_HEADER] || `${__privateGet(this, _shapeHandle)}-next`;
+      const newShapeHandle = e.headers[SHAPE_HANDLE_HEADER] || `${__privateGet(this, _syncState).handle}-next`;
       __privateMethod(this, _ShapeStream_instances, reset_fn).call(this, newShapeHandle);
       await __privateMethod(this, _ShapeStream_instances, publish_fn).call(this, Array.isArray(e.json) ? e.json : [e.json]);
       return __privateMethod(this, _ShapeStream_instances, requestShape_fn).call(this);
@@ -1646,32 +2196,18 @@ constructUrl_fn = async function(url, resumingFromPause, subsetParams) {
       setQueryParam(fetchUrl, SUBSET_PARAM_ORDER_BY, encodedOrderBy);
     }
   }
-  fetchUrl.searchParams.set(OFFSET_QUERY_PARAM, __privateGet(this, _lastOffset));
+  __privateGet(this, _syncState).applyUrlParams(fetchUrl, {
+    isSnapshotRequest: subsetParams !== void 0,
+    // Don't long-poll when resuming from pause or refreshing — avoids
+    // a 20s hold during which `isConnected` would be false
+    canLongPoll: !__privateGet(this, _ShapeStream_instances, isRefreshing_get) && !resumingFromPause
+  });
   fetchUrl.searchParams.set(LOG_MODE_QUERY_PARAM, __privateGet(this, _mode));
-  const isSnapshotRequest = subsetParams !== void 0;
-  if (__privateGet(this, _isUpToDate) && !isSnapshotRequest) {
-    if (!__privateGet(this, _isRefreshing) && !resumingFromPause) {
-      fetchUrl.searchParams.set(LIVE_QUERY_PARAM, `true`);
-    }
-    fetchUrl.searchParams.set(
-      LIVE_CACHE_BUSTER_QUERY_PARAM,
-      __privateGet(this, _liveCacheBuster)
-    );
-  }
-  if (__privateGet(this, _shapeHandle)) {
-    fetchUrl.searchParams.set(SHAPE_HANDLE_QUERY_PARAM, __privateGet(this, _shapeHandle));
-  }
   const shapeKey = canonicalShapeKey(fetchUrl);
   const expiredHandle = expiredShapesCache.getExpiredHandle(shapeKey);
   if (expiredHandle) {
     fetchUrl.searchParams.set(EXPIRED_HANDLE_QUERY_PARAM, expiredHandle);
   }
-  if (__privateGet(this, _staleCacheBuster)) {
-    fetchUrl.searchParams.set(
-      CACHE_BUSTER_QUERY_PARAM,
-      __privateGet(this, _staleCacheBuster)
-    );
-  }
   fetchUrl.searchParams.sort();
   return {
     fetchUrl,
@@ -1694,108 +2230,100 @@ createAbortListener_fn = async function(signal) {
   }
 };
 onInitialResponse_fn = async function(response) {
-  var _a, _b, _c, _d;
+  var _a, _b, _c;
   const { headers, status } = response;
   const shapeHandle = headers.get(SHAPE_HANDLE_HEADER);
-  if (shapeHandle) {
-    const shapeKey = __privateGet(this, _currentFetchUrl) ? canonicalShapeKey(__privateGet(this, _currentFetchUrl)) : null;
-    const expiredHandle = shapeKey ? expiredShapesCache.getExpiredHandle(shapeKey) : null;
-    if (shapeHandle !== expiredHandle) {
-      __privateSet(this, _shapeHandle, shapeHandle);
-      if (__privateGet(this, _staleCacheBuster)) {
-        __privateSet(this, _staleCacheBuster, void 0);
-        __privateSet(this, _staleCacheRetryCount, 0);
-      }
-    } else if (__privateGet(this, _shapeHandle) === void 0) {
-      __privateWrapper(this, _staleCacheRetryCount)._++;
-      await ((_a = response.body) == null ? void 0 : _a.cancel());
-      if (__privateGet(this, _staleCacheRetryCount) > __privateGet(this, _maxStaleCacheRetries)) {
-        throw new FetchError(
-          502,
-          void 0,
-          void 0,
-          {},
-          (_c = (_b = __privateGet(this, _currentFetchUrl)) == null ? void 0 : _b.toString()) != null ? _c : ``,
-          `CDN continues serving stale cached responses after ${__privateGet(this, _maxStaleCacheRetries)} retry attempts. This indicates a severe proxy/CDN misconfiguration. Check that your proxy includes all query parameters (especially 'handle' and 'offset') in its cache key. For more information visit the troubleshooting guide: https://electric-sql.com/docs/guides/troubleshooting`
-        );
-      }
-      console.warn(
-        `[Electric] Received stale cached response with expired shape handle. This should not happen and indicates a proxy/CDN caching misconfiguration. The response contained handle "${shapeHandle}" which was previously marked as expired. Check that your proxy includes all query parameters (especially 'handle' and 'offset') in its cache key. For more information visit the troubleshooting guide: https://electric-sql.com/docs/guides/troubleshooting Retrying with a random cache buster to bypass the stale cache (attempt ${__privateGet(this, _staleCacheRetryCount)}/${__privateGet(this, _maxStaleCacheRetries)}).`
-      );
-      __privateSet(this, _staleCacheBuster, `${Date.now()}-${Math.random().toString(36).substring(2, 9)}`);
-      throw new StaleCacheError(
-        `Received stale cached response with expired handle "${shapeHandle}". This indicates a proxy/CDN caching misconfiguration. Check that your proxy includes all query parameters (especially 'handle' and 'offset') in its cache key.`
-      );
-    } else {
-      console.warn(
-        `[Electric] Received stale cached response with expired shape handle. This should not happen and indicates a proxy/CDN caching misconfiguration. The response contained handle "${shapeHandle}" which was previously marked as expired. Check that your proxy includes all query parameters (especially 'handle' and 'offset') in its cache key. Ignoring the stale response and continuing with handle "${__privateGet(this, _shapeHandle)}".`
+  const shapeKey = __privateGet(this, _currentFetchUrl) ? canonicalShapeKey(__privateGet(this, _currentFetchUrl)) : null;
+  const expiredHandle = shapeKey ? expiredShapesCache.getExpiredHandle(shapeKey) : null;
+  const transition = __privateGet(this, _syncState).handleResponseMetadata({
+    status,
+    responseHandle: shapeHandle,
+    responseOffset: headers.get(CHUNK_LAST_OFFSET_HEADER),
+    responseCursor: headers.get(LIVE_CACHE_BUSTER_HEADER),
+    responseSchema: getSchemaFromHeaders(headers),
+    expiredHandle,
+    now: Date.now(),
+    maxStaleCacheRetries: __privateGet(this, _maxStaleCacheRetries),
+    createCacheBuster: () => `${Date.now()}-${Math.random().toString(36).substring(2, 9)}`
+  });
+  __privateSet(this, _syncState, transition.state);
+  if (transition.action === `stale-retry`) {
+    await ((_a = response.body) == null ? void 0 : _a.cancel());
+    if (transition.exceededMaxRetries) {
+      throw new FetchError(
+        502,
+        void 0,
+        void 0,
+        {},
+        (_c = (_b = __privateGet(this, _currentFetchUrl)) == null ? void 0 : _b.toString()) != null ? _c : ``,
+        `CDN continues serving stale cached responses after ${__privateGet(this, _maxStaleCacheRetries)} retry attempts. This indicates a severe proxy/CDN misconfiguration. Check that your proxy includes all query parameters (especially 'handle' and 'offset') in its cache key. For more information visit the troubleshooting guide: https://electric-sql.com/docs/guides/troubleshooting`
       );
-      return;
     }
+    console.warn(
+      `[Electric] Received stale cached response with expired shape handle. This should not happen and indicates a proxy/CDN caching misconfiguration. The response contained handle "${shapeHandle}" which was previously marked as expired. Check that your proxy includes all query parameters (especially 'handle' and 'offset') in its cache key. For more information visit the troubleshooting guide: https://electric-sql.com/docs/guides/troubleshooting Retrying with a random cache buster to bypass the stale cache (attempt ${__privateGet(this, _syncState).staleCacheRetryCount}/${__privateGet(this, _maxStaleCacheRetries)}).`
+    );
+    throw new StaleCacheError(
+      `Received stale cached response with expired handle "${shapeHandle}". This indicates a proxy/CDN caching misconfiguration. Check that your proxy includes all query parameters (especially 'handle' and 'offset') in its cache key.`
+    );
   }
-  const lastOffset = headers.get(CHUNK_LAST_OFFSET_HEADER);
-  if (lastOffset) {
-    __privateSet(this, _lastOffset, lastOffset);
-  }
-  const liveCacheBuster = headers.get(LIVE_CACHE_BUSTER_HEADER);
-  if (liveCacheBuster) {
-    __privateSet(this, _liveCacheBuster, liveCacheBuster);
-  }
-  __privateSet(this, _schema, (_d = __privateGet(this, _schema)) != null ? _d : getSchemaFromHeaders(headers));
-  if (status === 204) {
-    __privateSet(this, _lastSyncedAt, Date.now());
+  if (transition.action === `ignored`) {
+    console.warn(
+      `[Electric] Received stale cached response with expired shape handle. This should not happen and indicates a proxy/CDN caching misconfiguration. The response contained handle "${shapeHandle}" which was previously marked as expired. Check that your proxy includes all query parameters (especially 'handle' and 'offset') in its cache key. Ignoring the stale response and continuing with handle "${__privateGet(this, _syncState).handle}".`
+    );
+    return false;
   }
+  return true;
 };
 onMessages_fn = async function(batch, isSseMessage = false) {
-  var _a;
-  if (batch.length > 0) {
-    __privateSet(this, _isMidStream, true);
-    const lastMessage = batch[batch.length - 1];
-    if (isUpToDateMessage(lastMessage)) {
-      if (isSseMessage) {
-        const offset = getOffset(lastMessage);
-        if (offset) {
-          __privateSet(this, _lastOffset, offset);
-        }
-      }
-      __privateSet(this, _lastSyncedAt, Date.now());
-      __privateSet(this, _isUpToDate, true);
-      __privateSet(this, _isMidStream, false);
-      (_a = __privateGet(this, _midStreamPromiseResolver)) == null ? void 0 : _a.call(this);
-      if (__privateGet(this, _ShapeStream_instances, replayMode_get) && !isSseMessage) {
-        const currentCursor = __privateGet(this, _liveCacheBuster);
-        if (currentCursor === __privateGet(this, _lastSeenCursor)) {
-          __privateSet(this, _lastSeenCursor, void 0);
-          return;
-        }
-      }
-      __privateSet(this, _lastSeenCursor, void 0);
-      if (__privateGet(this, _currentFetchUrl)) {
-        const shapeKey = canonicalShapeKey(__privateGet(this, _currentFetchUrl));
-        upToDateTracker.recordUpToDate(shapeKey, __privateGet(this, _liveCacheBuster));
-      }
+  if (batch.length === 0) return;
+  const lastMessage = batch[batch.length - 1];
+  const hasUpToDateMessage = isUpToDateMessage(lastMessage);
+  const upToDateOffset = hasUpToDateMessage ? getOffset(lastMessage) : void 0;
+  const transition = __privateGet(this, _syncState).handleMessageBatch({
+    hasMessages: true,
+    hasUpToDateMessage,
+    isSse: isSseMessage,
+    upToDateOffset,
+    now: Date.now(),
+    currentCursor: __privateGet(this, _syncState).liveCacheBuster
+  });
+  __privateSet(this, _syncState, transition.state);
+  if (hasUpToDateMessage) {
+    if (transition.suppressBatch) {
+      return;
+    }
+    if (__privateGet(this, _currentFetchUrl)) {
+      const shapeKey = canonicalShapeKey(__privateGet(this, _currentFetchUrl));
+      upToDateTracker.recordUpToDate(
+        shapeKey,
+        __privateGet(this, _syncState).liveCacheBuster
+      );
     }
-    const messagesToProcess = batch.filter((message) => {
-      if (isChangeMessage(message)) {
-        return !__privateGet(this, _snapshotTracker).shouldRejectMessage(message);
-      }
-      return true;
-    });
-    await __privateMethod(this, _ShapeStream_instances, publish_fn).call(this, messagesToProcess);
   }
+  const messagesToProcess = batch.filter((message) => {
+    if (isChangeMessage(message)) {
+      return !__privateGet(this, _snapshotTracker).shouldRejectMessage(message);
+    }
+    return true;
+  });
+  await __privateMethod(this, _ShapeStream_instances, publish_fn).call(this, messagesToProcess);
 };
 fetchShape_fn = async function(opts) {
   var _a;
   __privateSet(this, _currentFetchUrl, opts.fetchUrl);
-  if (!__privateGet(this, _isUpToDate) && !__privateGet(this, _ShapeStream_instances, replayMode_get)) {
+  if (!__privateGet(this, _syncState).isUpToDate && __privateGet(this, _syncState).canEnterReplayMode()) {
     const shapeKey = canonicalShapeKey(opts.fetchUrl);
     const lastSeenCursor = upToDateTracker.shouldEnterReplayMode(shapeKey);
     if (lastSeenCursor) {
-      __privateSet(this, _lastSeenCursor, lastSeenCursor);
+      __privateSet(this, _syncState, __privateGet(this, _syncState).enterReplayMode(lastSeenCursor));
     }
   }
   const useSse = (_a = this.options.liveSse) != null ? _a : this.options.experimentalLiveSse;
-  if (__privateGet(this, _isUpToDate) && useSse && !__privateGet(this, _isRefreshing) && !opts.resumingFromPause && !__privateGet(this, _sseFallbackToLongPolling)) {
+  if (__privateGet(this, _syncState).shouldUseSse({
+    liveSseEnabled: !!useSse,
+    isRefreshing: __privateGet(this, _ShapeStream_instances, isRefreshing_get),
+    resumingFromPause: !!opts.resumingFromPause
+  })) {
     opts.fetchUrl.searchParams.set(EXPERIMENTAL_LIVE_SSE_QUERY_PARAM, `true`);
     opts.fetchUrl.searchParams.set(LIVE_SSE_QUERY_PARAM, `true`);
     return __privateMethod(this, _ShapeStream_instances, requestShapeSSE_fn).call(this, opts);
@@ -1809,8 +2337,9 @@ requestShapeLongPoll_fn = async function(opts) {
     headers
   });
   __privateSet(this, _connected, true);
-  await __privateMethod(this, _ShapeStream_instances, onInitialResponse_fn).call(this, response);
-  const schema = __privateGet(this, _schema);
+  const shouldProcessBody = await __privateMethod(this, _ShapeStream_instances, onInitialResponse_fn).call(this, response);
+  if (!shouldProcessBody) return;
+  const schema = __privateGet(this, _syncState).schema;
   const res = await response.text();
   const messages = res || `[]`;
   const batch = __privateGet(this, _messageParser).parse(messages, schema);
@@ -1823,6 +2352,7 @@ requestShapeSSE_fn = async function(opts) {
   const sseHeaders = __spreadProps(__spreadValues({}, headers), {
     Accept: `text/event-stream`
   });
+  let ignoredStaleResponse = false;
   try {
     let buffer = [];
     await fetchEventSource(fetchUrl.toString(), {
@@ -1830,11 +2360,15 @@ requestShapeSSE_fn = async function(opts) {
       fetch: fetch2,
       onopen: async (response) => {
         __privateSet(this, _connected, true);
-        await __privateMethod(this, _ShapeStream_instances, onInitialResponse_fn).call(this, response);
+        const shouldProcessBody = await __privateMethod(this, _ShapeStream_instances, onInitialResponse_fn).call(this, response);
+        if (!shouldProcessBody) {
+          ignoredStaleResponse = true;
+          throw new Error(`stale response ignored`);
+        }
       },
       onmessage: (event) => {
         if (event.data) {
-          const schema = __privateGet(this, _schema);
+          const schema = __privateGet(this, _syncState).schema;
           const message = __privateGet(this, _messageParser).parse(
             event.data,
             schema
@@ -1852,6 +2386,9 @@ requestShapeSSE_fn = async function(opts) {
       signal: requestAbortController.signal
     });
   } catch (error) {
+    if (ignoredStaleResponse) {
+      return;
+    }
     if (requestAbortController.signal.aborted) {
       throw new FetchBackoffAbortError();
     }
@@ -1859,46 +2396,33 @@ requestShapeSSE_fn = async function(opts) {
   } finally {
     const connectionDuration = Date.now() - __privateGet(this, _lastSseConnectionStartTime);
     const wasAborted = requestAbortController.signal.aborted;
-    if (connectionDuration < __privateGet(this, _minSseConnectionDuration) && !wasAborted) {
-      __privateWrapper(this, _consecutiveShortSseConnections)._++;
-      if (__privateGet(this, _consecutiveShortSseConnections) >= __privateGet(this, _maxShortSseConnections)) {
-        __privateSet(this, _sseFallbackToLongPolling, true);
-        console.warn(
-          `[Electric] SSE connections are closing immediately (possibly due to proxy buffering or misconfiguration). Falling back to long polling. Your proxy must support streaming SSE responses (not buffer the complete response). Configuration: Nginx add 'X-Accel-Buffering: no', Caddy add 'flush_interval -1' to reverse_proxy. Note: Do NOT disable caching entirely - Electric uses cache headers to enable request collapsing for efficiency.`
-        );
-      } else {
-        const maxDelay = Math.min(
-          __privateGet(this, _sseBackoffMaxDelay),
-          __privateGet(this, _sseBackoffBaseDelay) * Math.pow(2, __privateGet(this, _consecutiveShortSseConnections))
-        );
-        const delayMs = Math.floor(Math.random() * maxDelay);
-        await new Promise((resolve) => setTimeout(resolve, delayMs));
-      }
-    } else if (connectionDuration >= __privateGet(this, _minSseConnectionDuration)) {
-      __privateSet(this, _consecutiveShortSseConnections, 0);
-    }
-  }
-};
-pause_fn = function() {
-  var _a;
-  if (__privateGet(this, _started) && __privateGet(this, _state) === `active`) {
-    __privateSet(this, _state, `pause-requested`);
-    (_a = __privateGet(this, _requestAbortController)) == null ? void 0 : _a.abort(PAUSE_STREAM);
-  }
-};
-resume_fn = function() {
-  var _a;
-  if (__privateGet(this, _started) && (__privateGet(this, _state) === `paused` || __privateGet(this, _state) === `pause-requested`)) {
-    if ((_a = this.options.signal) == null ? void 0 : _a.aborted) {
-      return;
-    }
-    if (__privateGet(this, _state) === `pause-requested`) {
-      __privateSet(this, _state, `active`);
+    const transition = __privateGet(this, _syncState).handleSseConnectionClosed({
+      connectionDuration,
+      wasAborted,
+      minConnectionDuration: __privateGet(this, _minSseConnectionDuration),
+      maxShortConnections: __privateGet(this, _maxShortSseConnections)
+    });
+    __privateSet(this, _syncState, transition.state);
+    if (transition.fellBackToLongPolling) {
+      console.warn(
+        `[Electric] SSE connections are closing immediately (possibly due to proxy buffering or misconfiguration). Falling back to long polling. Your proxy must support streaming SSE responses (not buffer the complete response). Configuration: Nginx add 'X-Accel-Buffering: no', Caddy add 'flush_interval -1' to reverse_proxy. Note: Do NOT disable caching entirely - Electric uses cache headers to enable request collapsing for efficiency.`
+      );
+    } else if (transition.wasShortConnection) {
+      const maxDelay = Math.min(
+        __privateGet(this, _sseBackoffMaxDelay),
+        __privateGet(this, _sseBackoffBaseDelay) * Math.pow(2, __privateGet(this, _syncState).consecutiveShortSseConnections)
+      );
+      const delayMs = Math.floor(Math.random() * maxDelay);
+      await new Promise((resolve) => setTimeout(resolve, delayMs));
     }
-    __privateMethod(this, _ShapeStream_instances, start_fn).call(this);
   }
 };
 nextTick_fn = async function() {
+  if (__privateGet(this, _pauseLock).isPaused) {
+    throw new Error(
+      `Cannot wait for next tick while PauseLock is held \u2014 this would deadlock because the request loop is paused`
+    );
+  }
   if (__privateGet(this, _tickPromise)) {
     return __privateGet(this, _tickPromise);
   }
@@ -1913,22 +2437,6 @@ nextTick_fn = async function() {
   });
   return __privateGet(this, _tickPromise);
 };
-waitForStreamEnd_fn = async function() {
-  if (!__privateGet(this, _isMidStream)) {
-    return;
-  }
-  if (__privateGet(this, _midStreamPromise)) {
-    return __privateGet(this, _midStreamPromise);
-  }
-  __privateSet(this, _midStreamPromise, new Promise((resolve) => {
-    __privateSet(this, _midStreamPromiseResolver, resolve);
-  }));
-  __privateGet(this, _midStreamPromise).finally(() => {
-    __privateSet(this, _midStreamPromise, void 0);
-    __privateSet(this, _midStreamPromiseResolver, void 0);
-  });
-  return __privateGet(this, _midStreamPromise);
-};
 publish_fn = async function(messages) {
   __privateSet(this, _messageChain, __privateGet(this, _messageChain).then(
     () => Promise.all(
@@ -1950,13 +2458,16 @@ sendErrorToSubscribers_fn = function(error) {
     errorFn == null ? void 0 : errorFn(error);
   });
 };
+hasBrowserVisibilityAPI_fn = function() {
+  return typeof document === `object` && typeof document.hidden === `boolean` && typeof document.addEventListener === `function`;
+};
 subscribeToVisibilityChanges_fn = function() {
-  if (typeof document === `object` && typeof document.hidden === `boolean` && typeof document.addEventListener === `function`) {
+  if (__privateMethod(this, _ShapeStream_instances, hasBrowserVisibilityAPI_fn).call(this)) {
     const visibilityHandler = () => {
       if (document.hidden) {
-        __privateMethod(this, _ShapeStream_instances, pause_fn).call(this);
+        __privateGet(this, _pauseLock).acquire(`visibility`);
       } else {
-        __privateMethod(this, _ShapeStream_instances, resume_fn).call(this);
+        __privateGet(this, _pauseLock).release(`visibility`);
       }
     };
     document.addEventListener(`visibilitychange`, visibilityHandler);
@@ -1965,23 +2476,52 @@ subscribeToVisibilityChanges_fn = function() {
     });
   }
 };
+/**
+ * Detects system wake from sleep using timer gap detection.
+ * When the system sleeps, setInterval timers are paused. On wake,
+ * the elapsed wall-clock time since the last tick will be much larger
+ * than the interval period, indicating the system was asleep.
+ *
+ * Only active in non-browser environments (Bun, Node.js) where
+ * `document.visibilitychange` is not available. In browsers,
+ * `#subscribeToVisibilityChanges` handles this instead. Without wake
+ * detection, in-flight HTTP requests (long-poll or SSE) may hang until
+ * the OS TCP timeout.
+ */
+subscribeToWakeDetection_fn = function() {
+  if (__privateMethod(this, _ShapeStream_instances, hasBrowserVisibilityAPI_fn).call(this)) return;
+  const INTERVAL_MS = 2e3;
+  const WAKE_THRESHOLD_MS = 4e3;
+  let lastTickTime = Date.now();
+  const timer = setInterval(() => {
+    const now = Date.now();
+    const elapsed = now - lastTickTime;
+    lastTickTime = now;
+    if (elapsed > INTERVAL_MS + WAKE_THRESHOLD_MS) {
+      if (!__privateGet(this, _pauseLock).isPaused && __privateGet(this, _requestAbortController)) {
+        __privateWrapper(this, _refreshCount)._++;
+        __privateGet(this, _requestAbortController).abort(SYSTEM_WAKE);
+        queueMicrotask(() => {
+          __privateWrapper(this, _refreshCount)._--;
+        });
+      }
+    }
+  }, INTERVAL_MS);
+  if (typeof timer === `object` && `unref` in timer) {
+    timer.unref();
+  }
+  __privateSet(this, _unsubscribeFromWakeDetection, () => {
+    clearInterval(timer);
+  });
+};
 /**
  * Resets the state of the stream, optionally with a provided
  * shape handle
  */
 reset_fn = function(handle) {
-  __privateSet(this, _lastOffset, `-1`);
-  __privateSet(this, _liveCacheBuster, ``);
-  __privateSet(this, _shapeHandle, handle);
-  __privateSet(this, _isUpToDate, false);
-  __privateSet(this, _isMidStream, true);
+  __privateSet(this, _syncState, __privateGet(this, _syncState).markMustRefetch(handle));
   __privateSet(this, _connected, false);
-  __privateSet(this, _schema, void 0);
-  __privateSet(this, _activeSnapshotRequests, 0);
-  __privateSet(this, _consecutiveShortSseConnections, 0);
-  __privateSet(this, _sseFallbackToLongPolling, false);
-  __privateSet(this, _staleCacheBuster, void 0);
-  __privateSet(this, _staleCacheRetryCount, 0);
+  __privateGet(this, _pauseLock).releaseAllMatching(`snapshot`);
 };
 buildSubsetBody_fn = function(opts) {
   var _a, _b, _c, _d;