@yabbadabbadev/pepito 0.1.0

package/dist/msw-events.js

@@ -0,0 +1,44 @@
+import { recordBypassResponse, recordMatch, recordMockedResponse, recordRequestStart, recordUnhandled, } from './traffic-registry';
+// The only file in the package that touches `worker.events` (spec risk 1:
+// the life-cycle events API is mid-migration — see
+// docs/knowledge/msw-browser-mode.md). If MSW changes that API, it gets
+// fixed here without touching the registry or the matchers.
+//
+// Only five events: `request:end` and `unhandledException` add nothing to
+// the registry (measured, see docs/knowledge/quiescencia-red-msw.md), so
+// they aren't listened to.
+/**
+ * Hooks up the traffic registry (traffic-registry.ts) to MSW's events.
+ * `setupNetwork()` calls it once per worker, before `worker.start()`.
+ */
+export function watchNetwork(events) {
+    events.on('request:start', ({ request, requestId }) => {
+        const url = new URL(request.url);
+        // Clone without giving up control: as soon as the handler starts
+        // reading the stream, request.clone() throws (gotcha 1,
+        // docs/knowledge/msw-browser-mode.md).
+        const clone = request.clone();
+        recordRequestStart(requestId, {
+            method: request.method,
+            origin: url.origin,
+            path: url.pathname,
+            searchParams: Object.fromEntries(url.searchParams),
+            body: clone.json().catch(() => undefined),
+        });
+    });
+    events.on('request:match', ({ requestId }) => {
+        recordMatch(requestId);
+    });
+    events.on('request:unhandled', ({ requestId }) => {
+        recordUnhandled(requestId);
+    });
+    events.on('response:mocked', ({ response, requestId }) => {
+        recordMockedResponse(requestId, response.status, response
+            .clone()
+            .json()
+            .catch(() => undefined));
+    });
+    events.on('response:bypass', ({ response, requestId }) => {
+        recordBypassResponse(requestId, response.status);
+    });
+}

package/dist/network-singleton.d.ts

@@ -0,0 +1,10 @@
+import type { SetupWorker } from 'msw/browser';
+/** What `mount` needs from `setupNetwork()`: the worker to register test handlers on and the original `href` to restore between tests. */
+export interface NetworkContext {
+    worker: SetupWorker;
+    initialHref: string;
+}
+/** Publishes `setupNetwork()`'s context for `mount` to read; one call per test file. */
+export declare function registerNetworkContext(nextContext: NetworkContext): void;
+/** Reads the published context or throws with a fix instruction if `setupNetwork()` wasn't called before `caller`. */
+export declare function requireNetworkContext(caller: string): NetworkContext;

package/dist/network-singleton.js

@@ -0,0 +1,16 @@
+// Module per test file in browser mode (docs/knowledge/aislamiento-tests.md):
+// this variable doesn't leak between files, so a file that never calls
+// setupNetwork always sees `undefined` here, with no need for an explicit
+// reset.
+let context;
+/** Publishes `setupNetwork()`'s context for `mount` to read; one call per test file. */
+export function registerNetworkContext(nextContext) {
+    context = nextContext;
+}
+/** Reads the published context or throws with a fix instruction if `setupNetwork()` wasn't called before `caller`. */
+export function requireNetworkContext(caller) {
+    if (!context) {
+        throw new Error(`pepito: setupNetwork(handlers) has not been initialized. Call it in your setup file (setupFiles in vitest.config) before using ${caller}.`);
+    }
+    return context;
+}

package/dist/network.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Opaque marker that `expect.network()` hangs off. It doesn't identify a
+ * request but the overall traffic observed by the registry: a symbol keeps
+ * any real value from the application (a string, a spec object) from
+ * accidentally slipping in where only this marker makes sense —
+ * `toHaveNoUnhandledRequests` requires it with `===` before looking at the
+ * traffic.
+ */
+export declare const NETWORK_TARGET: unique symbol;
+/**
+ * Diagnostic utilities over the observed traffic, for inspecting it outside
+ * an assertion (for example, while debugging a failing test).
+ */
+export declare const network: {
+    /**
+     * Waits for the network to settle and dumps the observed traffic via
+     * `console.log`, in the same format that appears in the network matchers'
+     * failure messages.
+     *
+     * @example
+     * ```ts
+     * await fetch('/api/products')
+     * await network.log()
+     * ```
+     */
+    log(): Promise<void>;
+    /**
+     * Waits for the network to settle, with the same double-observation
+     * mechanism the network matchers use (`snapshotAfterIdle` in
+     * matchers.ts) — it doesn't duplicate it, it only discards the snapshot it
+     * produces. Guarantees that every request seen up to the moment of the
+     * call has closed (with `response:mocked`, `response:bypass` or the 500
+     * MSW fabricates when a handler throws). It does not guarantee the
+     * absence of future traffic: the same practical blind window remains as
+     * for the rest of the mechanism — a request fired in the same tick as the
+     * call, before crossing the real round trip to the service worker (1–6 ms
+     * measured; see `.claude/docs/references/measured-foundations.md`), may
+     * not be in the registry yet when `network.idle()` resolves.
+     *
+     * Meant for visual regression: capturing right after mounting, with a
+     * slow network in the mix, produces a STABLE but wrong baseline — the
+     * native stabilizer of `toMatchScreenshot` doesn't catch it because
+     * "Loading…" is also a capture that stops changing between frames
+     * (measured: 0 failures across 17 local runs + 3 in CI waiting for calm
+     * this way — see `.claude/docs/references/measured-foundations.md`).
+     * Before this, the only public way to wait for calm on its own was to
+     * divert `expect.network().toHaveNoUnhandledRequests()` from its actual
+     * purpose (detecting traffic without a handler). It works just as well as a
+     * generic "wait for the network to settle", without asserting anything.
+     *
+     * @example
+     * ```ts
+     * const screen = await mount(<App />)
+     * await network.idle()
+     * await expect.element(screen.getByRole('main')).toMatchScreenshot('catalog')
+     * ```
+     *
+     * @throws If the network doesn't settle within the `QUIESCENCE_TIMEOUT_MS`
+     * budget, with the dump of the requests that were still in flight — the
+     * same error `waitForNetworkIdle` throws.
+     */
+    idle(): Promise<void>;
+};

package/dist/network.js

@@ -0,0 +1,76 @@
+import { formatTraffic } from './failure-messages';
+// Cycle with matchers.ts (which imports NETWORK_TARGET from this file,
+// below): safe because both uses live inside function bodies that run
+// deferred, never during module evaluation — `import`/`function` hoisting
+// resolves them at call time. Changing either side to a module-level
+// const-arrow would break the cycle, with one of the two sides seeing
+// `undefined` on load.
+import { snapshotAfterIdle } from './matchers';
+/**
+ * Opaque marker that `expect.network()` hangs off. It doesn't identify a
+ * request but the overall traffic observed by the registry: a symbol keeps
+ * any real value from the application (a string, a spec object) from
+ * accidentally slipping in where only this marker makes sense —
+ * `toHaveNoUnhandledRequests` requires it with `===` before looking at the
+ * traffic.
+ */
+export const NETWORK_TARGET = Symbol('pepito:network-target');
+/**
+ * Diagnostic utilities over the observed traffic, for inspecting it outside
+ * an assertion (for example, while debugging a failing test).
+ */
+export const network = {
+    /**
+     * Waits for the network to settle and dumps the observed traffic via
+     * `console.log`, in the same format that appears in the network matchers'
+     * failure messages.
+     *
+     * @example
+     * ```ts
+     * await fetch('/api/products')
+     * await network.log()
+     * ```
+     */
+    async log() {
+        const traffic = await snapshotAfterIdle();
+        console.log(formatTraffic(traffic));
+    },
+    /**
+     * Waits for the network to settle, with the same double-observation
+     * mechanism the network matchers use (`snapshotAfterIdle` in
+     * matchers.ts) — it doesn't duplicate it, it only discards the snapshot it
+     * produces. Guarantees that every request seen up to the moment of the
+     * call has closed (with `response:mocked`, `response:bypass` or the 500
+     * MSW fabricates when a handler throws). It does not guarantee the
+     * absence of future traffic: the same practical blind window remains as
+     * for the rest of the mechanism — a request fired in the same tick as the
+     * call, before crossing the real round trip to the service worker (1–6 ms
+     * measured; see `.claude/docs/references/measured-foundations.md`), may
+     * not be in the registry yet when `network.idle()` resolves.
+     *
+     * Meant for visual regression: capturing right after mounting, with a
+     * slow network in the mix, produces a STABLE but wrong baseline — the
+     * native stabilizer of `toMatchScreenshot` doesn't catch it because
+     * "Loading…" is also a capture that stops changing between frames
+     * (measured: 0 failures across 17 local runs + 3 in CI waiting for calm
+     * this way — see `.claude/docs/references/measured-foundations.md`).
+     * Before this, the only public way to wait for calm on its own was to
+     * divert `expect.network().toHaveNoUnhandledRequests()` from its actual
+     * purpose (detecting traffic without a handler). It works just as well as a
+     * generic "wait for the network to settle", without asserting anything.
+     *
+     * @example
+     * ```ts
+     * const screen = await mount(<App />)
+     * await network.idle()
+     * await expect.element(screen.getByRole('main')).toMatchScreenshot('catalog')
+     * ```
+     *
+     * @throws If the network doesn't settle within the `QUIESCENCE_TIMEOUT_MS`
+     * budget, with the dump of the requests that were still in flight — the
+     * same error `waitForNetworkIdle` throws.
+     */
+    async idle() {
+        await snapshotAfterIdle();
+    },
+};

package/dist/request-descriptors.d.ts

@@ -0,0 +1,79 @@
+/**
+ * How the expected request is compared against the observed one.
+ * `searchParams` and `body` match by subset of top-level keys with deep
+ * equality per key — `{ body: { productName: 'Milk' } }` matches even if
+ * the real request also carries `id` or `createdAt` — unless `exact: true`,
+ * which requires strict equality of the whole object.
+ *
+ * A repeated key in the real query (`?tag=a&tag=b`) collapses to a single
+ * value — the last one — before comparing, because the registry builds
+ * `searchParams` with `Object.fromEntries`: if your application relies on a
+ * key appearing more than once, this comparison won't detect it.
+ */
+export interface RequestSpecOptions {
+    searchParams?: Record<string, string>;
+    body?: unknown;
+    exact?: boolean;
+}
+/**
+ * Describes the request a network matcher looks for in the observed
+ * traffic. Built with `request()` or one of its shortcuts (`get`, `post`,
+ * `put`, `patch`, `del`, `query`); there's no need to build it by hand.
+ *
+ * Matching ignores `origin`: `get('/api/x')` matches both a same-origin
+ * request to `/api/x` and one to `https://other.host/api/x`, if some
+ * handler responds there. The traffic registry does keep the `origin` of
+ * each request — not used yet, but it leaves room for an assertion by host
+ * the day two hosts share the same path.
+ */
+export interface RequestSpec extends RequestSpecOptions {
+    method: string;
+    path: string;
+}
+/**
+ * Escape hatch for any HTTP method, including ones MSW 2.15 doesn't yet
+ * expose as its own helper (`QUERY`). The shortcuts (`get`, `post`, …) are
+ * `request(fixedMethod, ...)`; for any other method, or to leave the method
+ * explicit in the test itself, use this directly.
+ *
+ * @example
+ * ```ts
+ * import { request } from '@yabbadabbadev/pepito'
+ *
+ * await expect(request('QUERY', '/api/products')).toHaveBeenRequested()
+ * ```
+ */
+export declare function request(method: string, path: string, options?: RequestSpecOptions): RequestSpec;
+/**
+ * Describes an expected `GET` request.
+ *
+ * @example
+ * ```ts
+ * import { get } from '@yabbadabbadev/pepito'
+ *
+ * await expect(get('/api/products', { searchParams: { filter: 'bread' } })).toHaveBeenRequested()
+ * ```
+ */
+export declare const get: (path: string, options?: RequestSpecOptions) => RequestSpec;
+/** Describes an expected `POST` request; same shape as {@link get}. */
+export declare const post: typeof get;
+/** Describes an expected `PUT` request; same shape as {@link get}. */
+export declare const put: typeof get;
+/** Describes an expected `PATCH` request; same shape as {@link get}. */
+export declare const patch: typeof get;
+/**
+ * Describes an expected `DELETE` request; same shape as {@link get}.
+ * Named `del` because `delete` is a reserved word.
+ */
+export declare const del: typeof get;
+/**
+ * Describes an expected `QUERY` request — the method this package's spec
+ * introduces, between `GET` and `POST`. The relevant option is usually
+ * `searchParams`, not `body`: it's called `searchParams` and not `query` on
+ * purpose, because `query` is already the name of this HTTP method in the
+ * same API. MSW 2.15 doesn't expose `query` as a handler helper yet — it's
+ * declared with `http.all` and filtered by method — but pepito's traffic
+ * registry observes it just the same, because it reads `request.method` as
+ * a plain string.
+ */
+export declare const query: typeof get;

package/dist/request-descriptors.js

@@ -0,0 +1,49 @@
+/**
+ * Escape hatch for any HTTP method, including ones MSW 2.15 doesn't yet
+ * expose as its own helper (`QUERY`). The shortcuts (`get`, `post`, …) are
+ * `request(fixedMethod, ...)`; for any other method, or to leave the method
+ * explicit in the test itself, use this directly.
+ *
+ * @example
+ * ```ts
+ * import { request } from '@yabbadabbadev/pepito'
+ *
+ * await expect(request('QUERY', '/api/products')).toHaveBeenRequested()
+ * ```
+ */
+export function request(method, path, options) {
+    return { method, path, ...options };
+}
+/**
+ * Describes an expected `GET` request.
+ *
+ * @example
+ * ```ts
+ * import { get } from '@yabbadabbadev/pepito'
+ *
+ * await expect(get('/api/products', { searchParams: { filter: 'bread' } })).toHaveBeenRequested()
+ * ```
+ */
+export const get = (path, options) => request('GET', path, options);
+/** Describes an expected `POST` request; same shape as {@link get}. */
+export const post = (path, options) => request('POST', path, options);
+/** Describes an expected `PUT` request; same shape as {@link get}. */
+export const put = (path, options) => request('PUT', path, options);
+/** Describes an expected `PATCH` request; same shape as {@link get}. */
+export const patch = (path, options) => request('PATCH', path, options);
+/**
+ * Describes an expected `DELETE` request; same shape as {@link get}.
+ * Named `del` because `delete` is a reserved word.
+ */
+export const del = (path, options) => request('DELETE', path, options);
+/**
+ * Describes an expected `QUERY` request — the method this package's spec
+ * introduces, between `GET` and `POST`. The relevant option is usually
+ * `searchParams`, not `body`: it's called `searchParams` and not `query` on
+ * purpose, because `query` is already the name of this HTTP method in the
+ * same API. MSW 2.15 doesn't expose `query` as a handler helper yet — it's
+ * declared with `http.all` and filtered by method — but pepito's traffic
+ * registry observes it just the same, because it reads `request.method` as
+ * a plain string.
+ */
+export const query = (path, options) => request('QUERY', path, options);

package/dist/setup-network.d.ts

@@ -0,0 +1,33 @@
+import type { RequestHandler } from 'msw';
+import type { SetupWorker, StartOptions } from 'msw/browser';
+/**
+ * Starts the MSW worker and hooks up the traffic registry, leaving the
+ * between-test cleanup installed in `afterEach`: registry, hot handlers,
+ * document URL and origin storage all return to their pre-test state
+ * (measured — see `.claude/docs/references/measured-foundations.md`).
+ *
+ * Called once per test file, typically from a `setupFiles` entry in
+ * `vitest.config`, never from inside a test.
+ *
+ * Known cleanup limit: a cookie set with an explicit `path` other than `/`
+ * (or with `domain`) can't be enumerated from `document.cookie`, so it
+ * survives between tests — see `clearOriginStorage` in storage-cleanup.ts.
+ * A cookie without an explicit `path` does get cleared, including one set
+ * while `mount` was simulating being on a nested route (measured — see
+ * `.claude/docs/references/measured-foundations.md`).
+ *
+ * @param handlers - Initial MSW handlers, the same ones `setupWorker` would take.
+ * @param startOptions - Passed through to `worker.start()` as-is; no wrapper of its own.
+ * @returns The MSW `SetupWorker`, so individual tests can call `worker.use()`.
+ *
+ * @example
+ * ```ts
+ * import { http, HttpResponse } from 'msw'
+ * import { setupNetwork } from '@yabbadabbadev/pepito'
+ *
+ * setupNetwork([
+ *   http.get('/api/products', () => HttpResponse.json([])),
+ * ])
+ * ```
+ */
+export declare function setupNetwork(handlers: RequestHandler[], startOptions?: StartOptions): SetupWorker;

package/dist/setup-network.js

@@ -0,0 +1,57 @@
+import { setupWorker } from 'msw/browser';
+import { afterEach, beforeAll } from 'vitest';
+import { watchNetwork } from './msw-events';
+import { registerNetworkContext, requireNetworkContext, } from './network-singleton';
+import { clearOriginStorage } from './storage-cleanup';
+import { resetTraffic } from './traffic-registry';
+/**
+ * Starts the MSW worker and hooks up the traffic registry, leaving the
+ * between-test cleanup installed in `afterEach`: registry, hot handlers,
+ * document URL and origin storage all return to their pre-test state
+ * (measured — see `.claude/docs/references/measured-foundations.md`).
+ *
+ * Called once per test file, typically from a `setupFiles` entry in
+ * `vitest.config`, never from inside a test.
+ *
+ * Known cleanup limit: a cookie set with an explicit `path` other than `/`
+ * (or with `domain`) can't be enumerated from `document.cookie`, so it
+ * survives between tests — see `clearOriginStorage` in storage-cleanup.ts.
+ * A cookie without an explicit `path` does get cleared, including one set
+ * while `mount` was simulating being on a nested route (measured — see
+ * `.claude/docs/references/measured-foundations.md`).
+ *
+ * @param handlers - Initial MSW handlers, the same ones `setupWorker` would take.
+ * @param startOptions - Passed through to `worker.start()` as-is; no wrapper of its own.
+ * @returns The MSW `SetupWorker`, so individual tests can call `worker.use()`.
+ *
+ * @example
+ * ```ts
+ * import { http, HttpResponse } from 'msw'
+ * import { setupNetwork } from '@yabbadabbadev/pepito'
+ *
+ * setupNetwork([
+ *   http.get('/api/products', () => HttpResponse.json([])),
+ * ])
+ * ```
+ */
+export function setupNetwork(handlers, startOptions) {
+    const worker = setupWorker(...handlers);
+    // The registry is hooked up BEFORE start(): start is the earliest point
+    // that can generate traffic.
+    watchNetwork(worker.events);
+    registerNetworkContext({ worker, initialHref: location.href });
+    beforeAll(async () => {
+        await worker.start({ quiet: true, ...startOptions });
+    });
+    afterEach(() => {
+        resetTraffic();
+        worker.resetHandlers();
+        // clearOriginStorage() goes BEFORE restoring the URL, not after:
+        // defensive ordering per RFC 6265, with no observable effect measured
+        // in this harness — see the TSDoc on clearOriginStorage in
+        // storage-cleanup.ts.
+        clearOriginStorage();
+        history.replaceState({}, '', requireNetworkContext('setupNetwork').initialHref);
+    });
+    return worker;
+}

package/dist/spec-matching.d.ts

@@ -0,0 +1,18 @@
+import type { RequestSpec } from './request-descriptors';
+import type { ResolvedRequest } from './traffic-registry';
+/**
+ * Compares an observed value against an expected one by subset of
+ * top-level keys with deep equality per key (or direct deep equality if
+ * `expected` isn't a plain object), unless `exact: true`, which requires
+ * strict equality of the whole object. Used both by `matchesSpec` over the
+ * request's `body` and by `toHaveRespondedWith` over the `responseBody`:
+ * same subset semantics, two different places it's applied.
+ */
+export declare function matchesBody(observed: unknown, expected: unknown, exact: boolean | undefined): boolean;
+/**
+ * Compares an observed request against a `RequestSpec`: method and path by
+ * strict equality; `body` and `searchParams` by subset of top-level keys
+ * with deep equality per key, unless `{ exact: true }`, which requires
+ * strict equality of the whole object.
+ */
+export declare function matchesSpec(observed: ResolvedRequest, spec: RequestSpec): boolean;

package/dist/spec-matching.js

@@ -0,0 +1,66 @@
+function deepEqual(a, b) {
+    if (a === b)
+        return true;
+    if (typeof a !== 'object' ||
+        typeof b !== 'object' ||
+        a === null ||
+        b === null) {
+        return false;
+    }
+    if (Array.isArray(a) !== Array.isArray(b))
+        return false;
+    const keysA = Object.keys(a);
+    const keysB = Object.keys(b);
+    if (keysA.length !== keysB.length)
+        return false;
+    return keysA.every((key) => deepEqual(a[key], b[key]));
+}
+// Excludes null (typeof null === 'object') and arrays: both match by direct
+// deep equality, not by subset of keys.
+function isPlainObject(candidate) {
+    return (typeof candidate === 'object' &&
+        candidate !== null &&
+        !Array.isArray(candidate));
+}
+function matchesSubset(observed, expected, exact) {
+    if (exact)
+        return deepEqual(observed, expected);
+    return Object.keys(expected).every((key) => deepEqual(observed[key], expected[key]));
+}
+/**
+ * Compares an observed value against an expected one by subset of
+ * top-level keys with deep equality per key (or direct deep equality if
+ * `expected` isn't a plain object), unless `exact: true`, which requires
+ * strict equality of the whole object. Used both by `matchesSpec` over the
+ * request's `body` and by `toHaveRespondedWith` over the `responseBody`:
+ * same subset semantics, two different places it's applied.
+ */
+export function matchesBody(observed, expected, exact) {
+    if (!isPlainObject(expected))
+        return deepEqual(observed, expected);
+    return isPlainObject(observed) && matchesSubset(observed, expected, exact);
+}
+/**
+ * Compares an observed request against a `RequestSpec`: method and path by
+ * strict equality; `body` and `searchParams` by subset of top-level keys
+ * with deep equality per key, unless `{ exact: true }`, which requires
+ * strict equality of the whole object.
+ */
+export function matchesSpec(observed, spec) {
+    if (observed.method !== spec.method || observed.path !== spec.path) {
+        return false;
+    }
+    if (spec.searchParams !== undefined &&
+        // observed.searchParams comes from Object.fromEntries(url.searchParams):
+        // with a repeated key (`?tag=a&tag=b`) only the last value survives. The
+        // subset comparison checks that single value without being able to
+        // detect the loss.
+        !matchesSubset(observed.searchParams, spec.searchParams, spec.exact)) {
+        return false;
+    }
+    if (spec.body !== undefined &&
+        !matchesBody(observed.body, spec.body, spec.exact)) {
+        return false;
+    }
+    return true;
+}

package/dist/storage-cleanup.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Clears the origin storage that browser mode leaks between test files that
+ * land on the same worker: `localStorage`, `sessionStorage` and cookies
+ * belong to the origin, not the document, so they survive per-file
+ * isolation (measured — see
+ * `.claude/docs/references/measured-foundations.md`).
+ *
+ * Each cookie is expired twice per name: once with `path=/` (the one most
+ * application code sets) and once with no `path` attribute, in case one was
+ * set without it. `setupNetwork()` calls this function BEFORE restoring the
+ * URL in its `afterEach`, as a defensive ordering: per RFC 6265, the
+ * default `path` of a cookie without the attribute is, in theory, computed
+ * from the active URL both when it's set and when it's deleted, so clearing
+ * before restoring the URL would be the correct order IF that computation
+ * followed the routes `setupNetwork()` simulates with `history.pushState`.
+ *
+ * Measured that it doesn't, in this harness (Chromium via Playwright,
+ * `vitest@4.1.10`): the order has no observable effect today — full
+ * evidence in `.claude/docs/references/measured-foundations.md`. The order
+ * is kept anyway, at no cost, in case some future runner or browser does
+ * follow the simulated URL.
+ *
+ * Known and actually verified limit: a cookie set with an explicit `path`
+ * or with `domain` can't even be enumerated from `document.cookie` — it
+ * stays alive after this call.
+ *
+ * @example
+ * ```ts
+ * afterEach(() => {
+ *   clearOriginStorage()
+ * })
+ * ```
+ */
+export declare function clearOriginStorage(): void;

package/dist/storage-cleanup.js

@@ -0,0 +1,44 @@
+/**
+ * Clears the origin storage that browser mode leaks between test files that
+ * land on the same worker: `localStorage`, `sessionStorage` and cookies
+ * belong to the origin, not the document, so they survive per-file
+ * isolation (measured — see
+ * `.claude/docs/references/measured-foundations.md`).
+ *
+ * Each cookie is expired twice per name: once with `path=/` (the one most
+ * application code sets) and once with no `path` attribute, in case one was
+ * set without it. `setupNetwork()` calls this function BEFORE restoring the
+ * URL in its `afterEach`, as a defensive ordering: per RFC 6265, the
+ * default `path` of a cookie without the attribute is, in theory, computed
+ * from the active URL both when it's set and when it's deleted, so clearing
+ * before restoring the URL would be the correct order IF that computation
+ * followed the routes `setupNetwork()` simulates with `history.pushState`.
+ *
+ * Measured that it doesn't, in this harness (Chromium via Playwright,
+ * `vitest@4.1.10`): the order has no observable effect today — full
+ * evidence in `.claude/docs/references/measured-foundations.md`. The order
+ * is kept anyway, at no cost, in case some future runner or browser does
+ * follow the simulated URL.
+ *
+ * Known and actually verified limit: a cookie set with an explicit `path`
+ * or with `domain` can't even be enumerated from `document.cookie` — it
+ * stays alive after this call.
+ *
+ * @example
+ * ```ts
+ * afterEach(() => {
+ *   clearOriginStorage()
+ * })
+ * ```
+ */
+export function clearOriginStorage() {
+    localStorage.clear();
+    sessionStorage.clear();
+    for (const cookie of document.cookie.split(';')) {
+        const name = cookie.split('=')[0]?.trim();
+        if (!name)
+            continue;
+        document.cookie = `${name}=;expires=${new Date(0).toUTCString()};path=/`;
+        document.cookie = `${name}=;expires=${new Date(0).toUTCString()}`;
+    }
+}