msw 3.0.2 → 3.0.4

package/lib/mockServiceWorker.js

@@ -7,9 +7,13 @@
  * - Please do NOT modify this file.
  */
 
-const PACKAGE_VERSION = '3.0.2'
-const INTEGRITY_CHECKSUM = '5cd5cf8b54c3a90f82960cedcd637772'
+const PACKAGE_VERSION = '3.0.4'
+const INTEGRITY_CHECKSUM = '0bd5af64c8dc112df5e0c5e9c8a2b15a'
 const IS_MOCKED_RESPONSE = Symbol('isMockedResponse')
+// Cache Storage is shared by the whole origin. Scope the cache name
+// to this registration so multiple workers do not overwrite each other.
+const ACTIVE_CLIENTS_CACHE_NAME = `msw:active-clients:${self.registration.scope}`
+const ACTIVE_CLIENTS_CACHE_KEY = '/__msw__/active-clients'
 
 const activeClientIds = new Set()
 /**
@@ -17,6 +21,23 @@ const activeClientIds = new Set()
  */
 const pendingRequests = new Map()
 
+/**
+ * The browser may terminate this worker at any point (idle timeout,
+ * hidden page throttling, event timeout) and evaluate it again on the
+ * next event, losing all in-memory state. Restore the active client IDs
+ * from the storage so the worker keeps handling requests after that.
+ */
+let hasRestoredActiveClientIds = false
+let isStoredActiveClientIdsOutdated = false
+let activeClientIdsStorePromise = Promise.resolve()
+const activeClientIdsRestorePromise = restoreActiveClientIds()
+  .catch((error) => {
+    console.error('[MSW] Failed to restore the active clients:', error)
+  })
+  .finally(() => {
+    hasRestoredActiveClientIds = true
+  })
+
 addEventListener('install', function () {
   self.skipWaiting()
 })
@@ -34,12 +55,17 @@ addEventListener('message', function (event) {
 
   event.waitUntil(
     (async () => {
+      // Never mutate the active clients before they are restored,
+      // otherwise storing them would persist an incomplete set.
+      await activeClientIdsRestorePromise
+
       if (event.data === 'CLIENT_CLOSE') {
         const allClients = await self.clients.matchAll({
           type: 'window',
         })
 
         activeClientIds.delete(clientId)
+        await storeActiveClientIds()
 
         // Await any pending requests from the closing client.
         // This makes sure that those requests are handled and not passthrough.
@@ -55,13 +81,14 @@ addEventListener('message', function (event) {
 
         // Unregister itself when there are no more clients
         if (remainingClients.length === 0) {
+          await clearStoredActiveClientIds()
           await self.registration.unregister()
         }
 
         const client = await self.clients.get(clientId)
 
         if (client != null) {
-          await sendToClient(client, {
+          notifyClient(client, {
             type: 'CLIENT_CLOSED',
           })
         }
@@ -83,14 +110,20 @@ addEventListener('message', function (event) {
 
       switch (event.data) {
         case 'KEEPALIVE_REQUEST': {
-          await sendToClient(client, {
+          // Retry a failed store on the next keepalive so the storage
+          // catches up with the in-memory state before the worker restarts.
+          if (isStoredActiveClientIdsOutdated) {
+            await storeActiveClientIds()
+          }
+
+          notifyClient(client, {
             type: 'KEEPALIVE_RESPONSE',
           })
           break
         }
 
         case 'INTEGRITY_CHECK_REQUEST': {
-          await sendToClient(client, {
+          notifyClient(client, {
             type: 'INTEGRITY_CHECK_RESPONSE',
             payload: {
               packageVersion: PACKAGE_VERSION,
@@ -102,8 +135,9 @@ addEventListener('message', function (event) {
 
         case 'MOCK_ACTIVATE': {
           activeClientIds.add(clientId)
+          await storeActiveClientIds()
 
-          await sendToClient(client, {
+          notifyClient(client, {
             type: 'MOCKING_ENABLED',
             payload: {
               client: {
@@ -129,6 +163,22 @@ addEventListener('fetch', function (event) {
     return
   }
 
+  // This request may be the one waking the worker up after the browser
+  // has terminated it. Wait for the active clients to be restored
+  // before deciding whether to handle the request.
+  if (!hasRestoredActiveClientIds) {
+    event.respondWith(
+      activeClientIdsRestorePromise.then(() => {
+        if (activeClientIds.size === 0) {
+          return fetch(event.request)
+        }
+
+        return handleRequest(event)
+      }),
+    )
+    return
+  }
+
   // Bypass all requests when there are no active clients.
   // Prevents the self-unregistered worked from handling requests
   // after it's been terminated (still remains active until the next reload).
@@ -136,15 +186,85 @@ addEventListener('fetch', function (event) {
     return
   }
 
-  const requestId = crypto.randomUUID()
-  event.respondWith(handleRequest(event, requestId))
+  event.respondWith(handleRequest(event))
 })
 
+/**
+ * Populate the active client IDs from the storage,
+ * ignoring the clients that no longer exist.
+ */
+async function restoreActiveClientIds() {
+  const storedClientIds = await readStoredActiveClientIds()
+
+  if (storedClientIds.length === 0) {
+    return
+  }
+
+  const windowClients = await self.clients.matchAll({
+    type: 'window',
+  })
+  const windowClientIds = new Set(windowClients.map((client) => client.id))
+
+  for (const clientId of storedClientIds) {
+    if (windowClientIds.has(clientId)) {
+      activeClientIds.add(clientId)
+    }
+  }
+}
+
+/**
+ * @returns {Promise<Array<string>>}
+ */
+async function readStoredActiveClientIds() {
+  const cache = await caches.open(ACTIVE_CLIENTS_CACHE_NAME)
+  const response = await cache.match(ACTIVE_CLIENTS_CACHE_KEY)
+
+  if (!response) {
+    return []
+  }
+
+  return response.json()
+}
+
+/**
+ * Storing is best-effort: a failure must never prevent the client
+ * from being activated or closed, in-memory state is still correct.
+ * Stores are serialized so each write persists the latest state
+ * and an earlier success cannot clear the flag of a later failure.
+ */
+function storeActiveClientIds() {
+  activeClientIdsStorePromise =
+    activeClientIdsStorePromise.then(writeActiveClientIds)
+  return activeClientIdsStorePromise
+}
+
+async function writeActiveClientIds() {
+  try {
+    const cache = await caches.open(ACTIVE_CLIENTS_CACHE_NAME)
+    await cache.put(
+      ACTIVE_CLIENTS_CACHE_KEY,
+      new Response(JSON.stringify(Array.from(activeClientIds))),
+    )
+    isStoredActiveClientIdsOutdated = false
+  } catch (error) {
+    isStoredActiveClientIdsOutdated = true
+    console.error('[MSW] Failed to store the active clients:', error)
+  }
+}
+
+async function clearStoredActiveClientIds() {
+  try {
+    await caches.delete(ACTIVE_CLIENTS_CACHE_NAME)
+  } catch (error) {
+    console.error('[MSW] Failed to clear the stored active clients:', error)
+  }
+}
+
 /**
  * @param {FetchEvent} event
- * @param {string} requestId
  */
-async function handleRequest(event, requestId) {
+async function handleRequest(event) {
+  const requestId = crypto.randomUUID()
   const client = await resolveMainClient(event)
   const requestCloneForEvents = event.request.clone()
 
@@ -172,7 +292,7 @@ async function handleRequest(event, requestId) {
     // request failed with a network error). Notify the client so it
     // can release the resources associated with this request.
     if (client && activeClientIds.has(client.id)) {
-      sendToClient(client, {
+      notifyClient(client, {
         type: 'REQUEST_ERROR',
         payload: {
           request: {
@@ -205,7 +325,7 @@ async function handleRequest(event, requestId) {
     // Clone the response so both the client and the library could consume it.
     const responseClone = isEventStreamResponse ? null : response.clone()
 
-    sendToClient(
+    notifyClient(
       client,
       {
         type: 'RESPONSE',
@@ -402,6 +522,26 @@ function sendToClient(client, message, transferrables = []) {
   })
 }
 
+/**
+ * Post a one-way message to the client.
+ * Unlike `sendToClient`, this does not open a MessageChannel or wait
+ * for a reply. The client never acknowledges these messages, so awaiting
+ * them keeps the extended event pending until the browser terminates
+ * the worker on its event timeout (5 minutes in Chromium), wiping its state.
+ * @param {Client} client
+ * @param {any} message
+ * @param {Array<Transferable>} transferrables
+ */
+function notifyClient(client, message, transferrables = []) {
+  try {
+    client.postMessage(message, transferrables.filter(Boolean))
+  } catch (error) {
+    // A one-way message must never fail its caller (e.g. a transferable
+    // that has already been detached must not reject a resolved request).
+    console.error('[MSW] Failed to notify the client:', error)
+  }
+}
+
 /**
  * @param {Response} response
  * @param {FetchEvent} event

package/lib/utils/is-common-asset-request.js

@@ -23,7 +23,7 @@ function isCommonAssetRequest(request) {
 	if (/(fonts\.googleapis\.com)/.test(url.hostname)) return true;
 	if (/node_modules/.test(url.pathname)) return true;
 	if (url.pathname.includes("@vite")) return true;
-	return /\.(s?css|less|m?jsx?|m?tsx?|html|ttf|otf|woff|woff2|eot|gif|jpe?g|png|avif|webp|svg|mp4|webm|ogg|mov|mp3|wav|ogg|flac|aac|pdf|txt|csv|json|xml|md|zip|tar|gz|rar|7z)$/i.test(url.pathname);
+	return /\.(s?css|less|m?jsx?|m?tsx?|html|ttf|otf|woff|woff2|eot|gif|jpe?g|png|avif|webp|ico|svg|mp4|webm|ogg|mov|mp3|wav|ogg|flac|aac|pdf|txt|csv|json|xml|md|zip|tar|gz|rar|7z)$/i.test(url.pathname);
 }
 //#endregion
 export { isCommonAssetRequest };

package/lib/utils/is-common-asset-request.js.map

@@ -1 +1 @@
-{"version":3,"file":"is-common-asset-request.js","names":[],"sources":["../../src/utils/is-common-asset-request.ts"],"sourcesContent":["/**\n * Determines if the given request is a static asset request.\n * Useful when deciding which unhandled requests to ignore.\n * @note Despite being ignored, you can still intercept and mock\n * static assets by creating request handlers for them.\n *\n * @example\n * import { isCommonAssetRequest } from 'msw'\n * import { HttpNetworkFrame } from 'msw/experimental'\n *\n * await worker.start({\n *   onUnhandledFrame({ frame, defaults }) {\n *     if (frame instanceof HttpNetworkFrame && !isCommonAssetRequest(frame.data.request)) {\n *       defaults.warn()\n *     }\n *   }\n * })\n */\nexport function isCommonAssetRequest(request: Request): boolean {\n  const url = new URL(request.url)\n\n  // Ignore certain protocols.\n  if (url.protocol === 'file:') {\n    return true\n  }\n\n  // Ignore static assets hosts.\n  if (/(fonts\\.googleapis\\.com)/.test(url.hostname)) {\n    return true\n  }\n\n  // Ignore node modules served over HTTP.\n  if (/node_modules/.test(url.pathname)) {\n    return true\n  }\n\n  // Ignore internal Vite requests, like \"/@vite/client\".\n  if (url.pathname.includes('@vite')) {\n    return true\n  }\n\n  // Ignore common static assets.\n  return /\\.(s?css|less|m?jsx?|m?tsx?|html|ttf|otf|woff|woff2|eot|gif|jpe?g|png|avif|webp|svg|mp4|webm|ogg|mov|mp3|wav|ogg|flac|aac|pdf|txt|csv|json|xml|md|zip|tar|gz|rar|7z)$/i.test(\n    url.pathname,\n  )\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;AAkBA,SAAgB,qBAAqB,SAA2B;CAC9D,MAAM,MAAM,IAAI,IAAI,QAAQ,GAAG;CAG/B,IAAI,IAAI,aAAa,SACnB,OAAO;CAIT,IAAI,2BAA2B,KAAK,IAAI,QAAQ,GAC9C,OAAO;CAIT,IAAI,eAAe,KAAK,IAAI,QAAQ,GAClC,OAAO;CAIT,IAAI,IAAI,SAAS,SAAS,OAAO,GAC/B,OAAO;CAIT,OAAO,yKAAyK,KAC9K,IAAI,QACN;AACF"}
+{"version":3,"file":"is-common-asset-request.js","names":[],"sources":["../../src/utils/is-common-asset-request.ts"],"sourcesContent":["/**\n * Determines if the given request is a static asset request.\n * Useful when deciding which unhandled requests to ignore.\n * @note Despite being ignored, you can still intercept and mock\n * static assets by creating request handlers for them.\n *\n * @example\n * import { isCommonAssetRequest } from 'msw'\n * import { HttpNetworkFrame } from 'msw/experimental'\n *\n * await worker.start({\n *   onUnhandledFrame({ frame, defaults }) {\n *     if (frame instanceof HttpNetworkFrame && !isCommonAssetRequest(frame.data.request)) {\n *       defaults.warn()\n *     }\n *   }\n * })\n */\nexport function isCommonAssetRequest(request: Request): boolean {\n  const url = new URL(request.url)\n\n  // Ignore certain protocols.\n  if (url.protocol === 'file:') {\n    return true\n  }\n\n  // Ignore static assets hosts.\n  if (/(fonts\\.googleapis\\.com)/.test(url.hostname)) {\n    return true\n  }\n\n  // Ignore node modules served over HTTP.\n  if (/node_modules/.test(url.pathname)) {\n    return true\n  }\n\n  // Ignore internal Vite requests, like \"/@vite/client\".\n  if (url.pathname.includes('@vite')) {\n    return true\n  }\n\n  // Ignore common static assets.\n  return /\\.(s?css|less|m?jsx?|m?tsx?|html|ttf|otf|woff|woff2|eot|gif|jpe?g|png|avif|webp|ico|svg|mp4|webm|ogg|mov|mp3|wav|ogg|flac|aac|pdf|txt|csv|json|xml|md|zip|tar|gz|rar|7z)$/i.test(\n    url.pathname,\n  )\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;AAkBA,SAAgB,qBAAqB,SAA2B;CAC9D,MAAM,MAAM,IAAI,IAAI,QAAQ,GAAG;CAG/B,IAAI,IAAI,aAAa,SACnB,OAAO;CAIT,IAAI,2BAA2B,KAAK,IAAI,QAAQ,GAC9C,OAAO;CAIT,IAAI,eAAe,KAAK,IAAI,QAAQ,GAClC,OAAO;CAIT,IAAI,IAAI,SAAS,SAAS,OAAO,GAC/B,OAAO;CAIT,OAAO,6KAA6K,KAClL,IAAI,QACN;AACF"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "msw",
-  "version": "3.0.2",
+  "version": "3.0.4",
   "description": "The industry standard for API mocking in JavaScript.",
   "type": "module",
   "main": "./lib/core/index.js",
@@ -94,7 +94,6 @@
   "funding": "https://github.com/sponsors/mswjs",
   "files": [
     "config/constants.js",
-    "config/scripts/postinstall.js",
     "cli",
     "lib",
     "src",
@@ -160,7 +159,7 @@
     "json-bigint": "^1.0.0",
     "knip": "^6.34.0",
     "lint-staged": "^17.1.1",
-    "msw": "^3.0.2",
+    "msw": "^3.0.4",
     "oxlint": "^1.75.0",
     "page-with": "^0.6.1",
     "prettier": "^3.9.6",

package/src/browser/default-network-options.ts

@@ -17,7 +17,7 @@ export function createDefaultNetworkOptions(
     sources: [
       supportsServiceWorker()
         ? new ServiceWorkerSource({ serviceWorker: { url: workerUrl } })
-        : new FallbackHttpSource({}),
+        : new FallbackHttpSource(),
       new InterceptorSource({
         interceptors: [
           new WebSocketInterceptor() as InterceptorSourceOptions['interceptors'][number],

package/src/browser/setup-worker.ts

@@ -56,11 +56,8 @@ export function setupWorker(...handlers: Array<AnyHandler>): SetupWorker {
               options: options?.serviceWorker?.options,
             },
             findWorker: options?.findWorker,
-            quiet: options?.quiet,
-          })
-        : new FallbackHttpSource({
-            quiet: options?.quiet,
           })
+        : new FallbackHttpSource()
 
       network.configure({
         sources: [

package/src/browser/sources/fallback-http-source.ts

@@ -1,23 +1,26 @@
 import { FetchInterceptor } from '@mswjs/interceptors/fetch'
 import { XMLHttpRequestInterceptor } from '@mswjs/interceptors/XMLHttpRequest'
 import { InterceptorSource } from '#core/experimental/sources/interceptor-source'
+import type { NetworkFrameResolutionContext } from '#core/experimental/frames/network-frame'
 import { devUtils } from '#core/utils/internal/dev-utils'
 
-interface FallbackHttpSourceOptions {
-  quiet?: boolean
-}
-
 export class FallbackHttpSource extends InterceptorSource {
-  constructor(private readonly options: FallbackHttpSourceOptions) {
+  /**
+   * The resolved context of the network this source was last enabled with.
+   */
+  #context?: NetworkFrameResolutionContext
+
+  constructor() {
     super({
       interceptors: [new XMLHttpRequestInterceptor(), new FetchInterceptor()],
     })
   }
 
-  public enable(): void {
+  public enable(context?: NetworkFrameResolutionContext): void {
+    this.#context = context
     super.enable()
 
-    if (!this.options.quiet) {
+    if (!this.#context?.quiet) {
       this.#printStartMessage()
     }
   }
@@ -25,7 +28,7 @@ export class FallbackHttpSource extends InterceptorSource {
   public disable(): void {
     super.disable()
 
-    if (!this.options.quiet) {
+    if (!this.#context?.quiet) {
       this.#printStopMessage()
     }
   }

package/src/browser/sources/service-worker-source.ts

@@ -2,6 +2,7 @@ import { invariant } from 'outvariant'
 import type { Emitter } from 'rettime'
 import { FetchResponse } from '@mswjs/interceptors'
 import { NetworkSource } from '#core/experimental/sources/network-source'
+import type { NetworkFrameResolutionContext } from '#core/experimental/frames/network-frame'
 import { RequestHandler } from '#core/handlers/request-handler'
 import {
   HttpNetworkFrame,
@@ -23,7 +24,6 @@ import { validateWorkerScope } from '../utils/validate-worker-scope'
 import { shouldInvalidateWorker } from '../utils/should-invalidate-worker'
 
 export interface ServiceWorkerSourceOptions {
-  quiet?: boolean
   serviceWorker: {
     url: string
     options?: RegistrationOptions
@@ -75,6 +75,10 @@ export class ServiceWorkerSource extends NetworkSource<ServiceWorkerHttpNetworkF
   }
 
   #options: ServiceWorkerSourceOptions
+  /**
+   * The resolved context of the network this source was last enabled with.
+   */
+  #context?: NetworkFrameResolutionContext
   /**
    * @note We cannot use `WeakMap` here as request/response
    * identity cannot be preserved through the client-worker channel.
@@ -109,7 +113,10 @@ export class ServiceWorkerSource extends NetworkSource<ServiceWorkerHttpNetworkF
     })
   }
 
-  public async enable(): Promise<ServiceWorkerRegistration> {
+  public async enable(
+    context?: NetworkFrameResolutionContext,
+  ): Promise<ServiceWorkerRegistration> {
+    this.#context = context
     this.#channel.removeAllListeners()
     this.#frames.clear()
 
@@ -147,7 +154,7 @@ export class ServiceWorkerSource extends NetworkSource<ServiceWorkerHttpNetworkF
     })
     await clientConfirmationPromise.promise
 
-    if (!this.#options.quiet) {
+    if (!this.#context?.quiet) {
       this.#printStartMessage()
     }
 
@@ -178,7 +185,7 @@ export class ServiceWorkerSource extends NetworkSource<ServiceWorkerHttpNetworkF
      * `#handleRequest`. `#startWorker` swaps in a fresh deferred on re-enable.
      */
 
-    if (!this.#options.quiet) {
+    if (!this.#context?.quiet) {
       this.#printStopMessage()
     }
   }
@@ -294,7 +301,7 @@ Please consider using a custom "serviceWorker.url" option to point to the actual
       this.#channel.postMessage('KEEPALIVE_REQUEST')
     }, 5000)
 
-    if (!this.#options.quiet) {
+    if (!this.#context?.quiet) {
       validateWorkerScope(registration)
     }
 

package/src/browser/utils/should-invalidate-worker.test.ts

@@ -104,19 +104,3 @@ test('returns false when findWorker is the same reference', () => {
     ),
   ).toBe(false)
 })
-
-test('returns false regardless of the "quiet" option', () => {
-  expect(
-    shouldInvalidateWorker(
-      createOptions({ quiet: true }),
-      createOptions({ quiet: true }),
-    ),
-  ).toBe(false)
-
-  expect(
-    shouldInvalidateWorker(
-      createOptions({ quiet: false }),
-      createOptions({ quiet: true }),
-    ),
-  ).toBe(false)
-})

package/src/core/experimental/define-network.ts

@@ -203,7 +203,7 @@ export function defineNetwork<Sources extends Array<NetworkSource<any>>>(
           )
         })
 
-        return source.enable()
+        return source.enable(resolvedOptions.context)
       })
 
       return colorlessPromiseAll(result) as MaybePromise<

package/src/core/experimental/handlers-controller.test.ts

@@ -308,6 +308,67 @@ describe(InMemoryHandlersController.prototype.reset, () => {
     expect(controller.getHandlersByKind('websocket')).toEqual([wsOne, wsTwo])
     expect(controller.getHandlersByKind('request')).toEqual([upgradeHandler])
   })
+
+  test('resets the kept handlers and disposes of the removed ones', () => {
+    const initialHandler = http.get('/initial', () => {})
+    initialHandler.reset = vi.fn()
+    initialHandler.dispose = vi.fn()
+    const runtimeHandler = http.get('/runtime', () => {})
+    runtimeHandler.reset = vi.fn()
+    runtimeHandler.dispose = vi.fn()
+
+    const controller = new InMemoryHandlersController([initialHandler])
+    controller.use([runtimeHandler])
+    controller.reset([])
+
+    expect.soft(initialHandler.reset).toHaveBeenCalledOnce()
+    expect.soft(initialHandler.dispose).not.toHaveBeenCalled()
+    expect.soft(runtimeHandler.reset).not.toHaveBeenCalled()
+    expect(runtimeHandler.dispose).toHaveBeenCalledOnce()
+  })
+
+  test('reports a rejected disposal of a removed handler', async () => {
+    vi.spyOn(console, 'error').mockImplementation(() => {})
+    onTestFinished(() => vi.restoreAllMocks())
+
+    const runtimeHandler = http.get('/runtime', () => {})
+    runtimeHandler.dispose = () =>
+      Promise.reject(new Error('Handler disposal error'))
+
+    const controller = new InMemoryHandlersController([])
+    controller.use([runtimeHandler])
+    controller.reset([])
+
+    await expect
+      .poll(() => console.error)
+      .toHaveBeenCalledWith(
+        `[MSW] Failed to dispose of "request" handler removed during reset. Please see the original error below.\nError: Handler disposal error`,
+      )
+  })
+
+  test('removes the remaining handlers when a disposal throws', () => {
+    vi.spyOn(console, 'error').mockImplementation(() => {})
+    onTestFinished(() => vi.restoreAllMocks())
+
+    const throwingHandler = http.get('/throwing', () => {})
+    throwingHandler.dispose = () => {
+      throw new Error('Handler disposal error')
+    }
+    const runtimeHandler = http.get('/runtime', () => {})
+    runtimeHandler.dispose = vi.fn()
+
+    const controller = new InMemoryHandlersController([])
+    controller.use([throwingHandler, runtimeHandler])
+    controller.reset([])
+
+    expect
+      .soft(console.error)
+      .toHaveBeenCalledWith(
+        `[MSW] Failed to dispose of "request" handler removed during reset. Please see the original error below.\nError: Handler disposal error`,
+      )
+    expect.soft(runtimeHandler.dispose).toHaveBeenCalledOnce()
+    expect(controller.currentHandlers()).toEqual([])
+  })
 })
 
 describe(InMemoryHandlersController.prototype.listHandlers, () => {

package/src/core/experimental/handlers-controller.ts

@@ -168,11 +168,38 @@ export abstract class HandlersController {
       ),
     )
 
-    for (const handler of this.currentHandlers()) {
+    const { initialHandlers } = this.getState()
+    const nextInitialHandlers =
+      nextHandlers.length > 0
+        ? groupHandlersByKind(nextHandlers)
+        : initialHandlers
+    const currentHandlers = new Set(this.currentHandlers())
+    const nextHandlersSet = new Set(
+      Object.values(nextInitialHandlers).flat().filter(Boolean),
+    )
+
+    for (const handler of currentHandlers.intersection(nextHandlersSet)) {
       handler.reset()
     }
 
-    const { initialHandlers } = this.getState()
+    // The handlers that leave the network with this reset release
+    // whatever they hold (e.g. live connection bindings).
+    // Resetting is synchronous, so their disposal is not awaited.
+    for (const handler of currentHandlers.difference(nextHandlersSet)) {
+      try {
+        const disposal = handler.dispose()
+
+        if (disposal instanceof Promise) {
+          disposal.catch((error) => {
+            this.#printDisposalError(handler, error)
+          })
+        }
+      } catch (error) {
+        // A failing disposal must not prevent the remaining handlers
+        // from being disposed of, nor the removed handlers from being cleared.
+        this.#printDisposalError(handler, error)
+      }
+    }
 
     if (nextHandlers.length === 0) {
       this.setState({
@@ -182,11 +209,9 @@ export abstract class HandlersController {
       return
     }
 
-    const normalizedNextHandlers = groupHandlersByKind(nextHandlers)
-
     this.setState({
-      initialHandlers: normalizedNextHandlers,
-      handlers: { ...normalizedNextHandlers },
+      initialHandlers: nextInitialHandlers,
+      handlers: { ...nextInitialHandlers },
     })
   }
 
@@ -217,6 +242,14 @@ export abstract class HandlersController {
   #validateHandlers(handlers: Array<AnyHandler>): boolean {
     return handlers.every((handler) => !Array.isArray(handler))
   }
+
+  #printDisposalError(handler: AnyHandler, error: unknown): void {
+    devUtils.error(
+      'Failed to dispose of "%s" handler removed during reset. Please see the original error below.\n%s',
+      handler.kind,
+      error,
+    )
+  }
 }
 
 export class InMemoryHandlersController extends HandlersController {

package/src/core/experimental/sources/network-source.ts

@@ -2,6 +2,7 @@ import { Emitter, TypedEvent, type TypedListenerOptions } from 'rettime'
 import type {
   AnyNetworkFrame,
   ExtractFrameEvents,
+  NetworkFrameResolutionContext,
 } from '../frames/network-frame'
 
 class NetworkFrameEvent<
@@ -33,7 +34,13 @@ export abstract class NetworkSource<
     this.emitter = new Emitter()
   }
 
-  public abstract enable(): unknown | Promise<unknown>
+  /**
+   * Enable this network source.
+   * @param context The resolved context of the network this source belongs to.
+   */
+  public abstract enable(
+    context?: NetworkFrameResolutionContext,
+  ): unknown | Promise<unknown>
 
   public async queue(frame: Frame): Promise<void> {
     await this.emitter.emitAsPromise(

package/src/core/handlers/handler.ts

@@ -32,8 +32,9 @@ export abstract class Handler {
   /**
    * Release the resources held by this handler.
    *
-   * @note This method is invoked automatically when the network is
-   * disabled (e.g. `server.close()`). Override it in the handlers that
+   * @note This method is invoked automatically when the handler leaves
+   * the network: when the network is disabled (e.g. `server.close()`)
+   * or when a reset removes it (e.g. `server.resetHandlers()`). Override it in the handlers that
    * hold onto anything beyond a single frame, like timers, connections,
    * or event listeners. Returning a promise makes the network await
    * this handler's disposal before it tears itself down.