@capybara-devtools/web 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 lhphuc99
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,27 @@
-# Temporary Holding Version
+# @capybara-devtools/web
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Browser SDK for [Capybara](https://github.com/lhphuc99/capybara#readme): sends your app's logs, network requests (including WebSockets) and storage to the Capybara UI on your computer. Works with React, Vite and the client side of Next.js.
+
+```bash
+npm install @capybara-devtools/web
+```
+
+Import it before the rest of your app so early logs and requests are captured:
+
+```ts
+import { init } from '@capybara-devtools/web';
+
+if (import.meta.env.DEV) init({ appName: 'My web app' });
+```
+
+In Next.js 15.3 or later, put it in `instrumentation-client.ts` at the project root:
+
+```ts
+import { init } from '@capybara-devtools/web';
+
+if (process.env.NODE_ENV === 'development') init({ appName: 'My Next.js app' });
+```
+
+Then run `npx capybara-devtools` (or open the desktop app) to see the data.
+
+Documentation: [github.com/lhphuc99/capybara](https://github.com/lhphuc99/capybara#web-react-vite-nextjs-client)

package/dist/errors.d.ts

@@ -0,0 +1,3 @@
+import type { Plugin } from '@capybara-devtools/core';
+export declare function windowErrorsPlugin(): Plugin;
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,yBAAyB,CAAC;AAEtD,wBAAgB,kBAAkB,IAAI,MAAM,CAuB3C"}

package/dist/errors.js

@@ -0,0 +1,24 @@
+export function windowErrorsPlugin() {
+    return {
+        name: 'errors',
+        setup(ctx) {
+            // Bubbling listener only: resource load failures (broken <img>) don't bubble and stay out.
+            const onError = (event) => {
+                const args = event.error !== undefined && event.error !== null
+                    ? [event.error]
+                    : [event.message, `at ${event.filename}:${event.lineno}:${event.colno}`];
+                ctx.emit('log', { level: 'error', source: 'uncaught', args: args.map((arg) => ctx.serialize(arg)) });
+            };
+            const onRejection = (event) => {
+                ctx.emit('log', { level: 'error', source: 'unhandledrejection', args: [ctx.serialize(event.reason)] });
+            };
+            window.addEventListener('error', onError);
+            window.addEventListener('unhandledrejection', onRejection);
+            return () => {
+                window.removeEventListener('error', onError);
+                window.removeEventListener('unhandledrejection', onRejection);
+            };
+        },
+    };
+}
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAEA,MAAM,UAAU,kBAAkB;IAChC,OAAO;QACL,IAAI,EAAE,QAAQ;QACd,KAAK,CAAC,GAAG;YACP,2FAA2F;YAC3F,MAAM,OAAO,GAAG,CAAC,KAAiB,EAAE,EAAE;gBACpC,MAAM,IAAI,GACR,KAAK,CAAC,KAAK,KAAK,SAAS,IAAI,KAAK,CAAC,KAAK,KAAK,IAAI;oBAC/C,CAAC,CAAC,CAAC,KAAK,CAAC,KAAK,CAAC;oBACf,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,EAAE,MAAM,KAAK,CAAC,QAAQ,IAAI,KAAK,CAAC,MAAM,IAAI,KAAK,CAAC,KAAK,EAAE,CAAC,CAAC;gBAC7E,GAAG,CAAC,IAAI,CAAC,KAAK,EAAE,EAAE,KAAK,EAAE,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,IAAI,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC,CAAC;YACvG,CAAC,CAAC;YACF,MAAM,WAAW,GAAG,CAAC,KAA4B,EAAE,EAAE;gBACnD,GAAG,CAAC,IAAI,CAAC,KAAK,EAAE,EAAE,KAAK,EAAE,OAAO,EAAE,MAAM,EAAE,oBAAoB,EAAE,IAAI,EAAE,CAAC,GAAG,CAAC,SAAS,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC;YACzG,CAAC,CAAC;YACF,MAAM,CAAC,gBAAgB,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;YAC1C,MAAM,CAAC,gBAAgB,CAAC,oBAAoB,EAAE,WAAW,CAAC,CAAC;YAC3D,OAAO,GAAG,EAAE;gBACV,MAAM,CAAC,mBAAmB,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;gBAC7C,MAAM,CAAC,mBAAmB,CAAC,oBAAoB,EAAE,WAAW,CAAC,CAAC;YAChE,CAAC,CAAC;QACJ,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,22 @@
+import { type CapybaraClient, type NetworkPluginOptions, type Plugin, type StorageAdapter } from '@capybara-devtools/core';
+export declare const SDK_VERSION = "0.2.0";
+export interface InitOptions {
+    /** Shown in the session picker. Defaults to the page title. */
+    appName?: string;
+    /** Machine running `capybara`. Defaults to the hostname the page was loaded from. */
+    host?: string;
+    port?: number;
+    /** Pass false to skip setup, e.g. `enabled: import.meta.env.DEV`. */
+    enabled?: boolean;
+    /** Capture console output and uncaught errors. Default true. */
+    logs?: boolean;
+    network?: boolean | NetworkPluginOptions;
+    /** `false` turns storage off; an array adds adapters next to localStorage, sessionStorage and cookies. */
+    storage?: boolean | StorageAdapter[];
+    plugins?: Plugin[];
+}
+export declare function init(options?: InitOptions): CapybaraClient | undefined;
+export { getActiveClient } from '@capybara-devtools/core';
+export type { CapybaraClient, NetworkPluginOptions, Plugin, StorageAdapter } from '@capybara-devtools/core';
+export { cookieStorage, webStorage } from './storage.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAML,KAAK,cAAc,EACnB,KAAK,oBAAoB,EACzB,KAAK,MAAM,EACX,KAAK,cAAc,EACpB,MAAM,yBAAyB,CAAC;AAKjC,eAAO,MAAM,WAAW,UAAU,CAAC;AAOnC,MAAM,WAAW,WAAW;IAC1B,+DAA+D;IAC/D,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,qFAAqF;IACrF,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,qEAAqE;IACrE,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,gEAAgE;IAChE,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,OAAO,CAAC,EAAE,OAAO,GAAG,oBAAoB,CAAC;IACzC,0GAA0G;IAC1G,OAAO,CAAC,EAAE,OAAO,GAAG,cAAc,EAAE,CAAC;IACrC,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;CACpB;AAED,wBAAgB,IAAI,CAAC,OAAO,GAAE,WAAgB,GAAG,cAAc,GAAG,SAAS,CAiC1E;AA6BD,OAAO,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAC;AAC1D,YAAY,EAAE,cAAc,EAAE,oBAAoB,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,yBAAyB,CAAC;AAC5G,OAAO,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC"}

package/dist/index.js

@@ -0,0 +1,71 @@
+import { consolePlugin, createClient, getActiveClient, networkPlugin, storagePlugin, } from '@capybara-devtools/core';
+import { CLIENT_PATH, DEFAULT_PORT } from '@capybara-devtools/protocol';
+import { windowErrorsPlugin } from './errors.js';
+import { cookieStorage, webStorage } from './storage.js';
+export const SDK_VERSION = '0.2.0';
+/** Traffic of a dev server's own tooling: Next.js error overlay requests and its HMR socket. */
+const DEV_SERVER_NOISE = [/\/__nextjs_[\w-]+(\?|$)/, /\/_next\/webpack-hmr(\?|$)/];
+/** React's development build prints this on every page when the React DevTools extension is missing. */
+const CONSOLE_NOISE = [/Download the React DevTools for a better development experience/];
+export function init(options = {}) {
+    // The window check makes this a no-op during server rendering, so the same entry works in Next.js.
+    if (options.enabled === false || typeof window === 'undefined')
+        return undefined;
+    // Hot reload re-runs the entry file; patching again would record everything twice.
+    const existing = getActiveClient();
+    if (existing)
+        return existing;
+    const plugins = [];
+    if (options.logs !== false)
+        plugins.push(consolePlugin({ ignore: CONSOLE_NOISE }), windowErrorsPlugin());
+    if (options.network !== false) {
+        const network = typeof options.network === 'object' ? options.network : {};
+        plugins.push(networkPlugin({ ...network, ignoreUrls: [...DEV_SERVER_NOISE, ...metroSockets(), ...(network.ignoreUrls ?? [])] }));
+    }
+    if (options.storage !== false) {
+        const extra = Array.isArray(options.storage) ? options.storage : [];
+        plugins.push(storagePlugin([...defaultStorages(), ...extra]));
+    }
+    plugins.push(...(options.plugins ?? []));
+    const host = options.host ?? (window.location.hostname || 'localhost');
+    return createClient({
+        url: `ws://${formatHost(host)}:${options.port ?? DEFAULT_PORT}${CLIENT_PATH}`,
+        session: {
+            appName: options.appName ?? (document.title || window.location.host || 'Web app'),
+            platform: 'web',
+            sdk: { name: '@capybara-devtools/web', version: SDK_VERSION },
+            url: window.location.href,
+            userAgent: navigator.userAgent,
+        },
+        plugins,
+    });
+}
+function defaultStorages() {
+    const adapters = [];
+    // Reading these throws in sandboxed iframes and when site data is blocked.
+    try {
+        adapters.push(webStorage(window.localStorage, 'localStorage', 'Local Storage'));
+    }
+    catch {
+        // unavailable
+    }
+    try {
+        adapters.push(webStorage(window.sessionStorage, 'sessionStorage', 'Session Storage'));
+    }
+    catch {
+        // unavailable
+    }
+    adapters.push(cookieStorage());
+    return adapters;
+}
+/** With Expo web, Metro serves the page and also opens /hot and /message sockets on the same origin. */
+function metroSockets() {
+    const host = window.location.host.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    return host ? [new RegExp(`^wss?://${host}/(?:hot|message)(?:[/?]|$)`)] : [];
+}
+function formatHost(host) {
+    return host.includes(':') && !host.startsWith('[') ? `[${host}]` : host;
+}
+export { getActiveClient } from '@capybara-devtools/core';
+export { cookieStorage, webStorage } from './storage.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/storage.d.ts

@@ -0,0 +1,4 @@
+import type { StorageAdapter } from '@capybara-devtools/core';
+export declare function webStorage(storage: Storage, id: string, label: string): StorageAdapter;
+export declare function cookieStorage(): StorageAdapter;
+//# sourceMappingURL=storage.d.ts.map

package/dist/storage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"storage.d.ts","sourceRoot":"","sources":["../src/storage.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,yBAAyB,CAAC;AAyC9D,wBAAgB,UAAU,CAAC,OAAO,EAAE,OAAO,EAAE,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,cAAc,CAkCtF;AAED,wBAAgB,aAAa,IAAI,cAAc,CA0B9C"}

package/dist/storage.js

@@ -0,0 +1,130 @@
+const listeners = new Map();
+let prototypePatched = false;
+// Patched once and never undone: with no listeners it costs nothing, and undoing it
+// could remove a wrapper another library installed on top of ours.
+function patchStoragePrototype() {
+    if (prototypePatched || typeof Storage === 'undefined')
+        return;
+    prototypePatched = true;
+    const proto = Storage.prototype;
+    const { setItem, removeItem, clear } = proto;
+    proto.setItem = function (key, value) {
+        setItem.call(this, key, value);
+        notify(this, 'set', String(key));
+    };
+    proto.removeItem = function (key) {
+        removeItem.call(this, key);
+        notify(this, 'remove', String(key));
+    };
+    proto.clear = function () {
+        clear.call(this);
+        notify(this, 'clear');
+    };
+}
+function notify(storage, op, key) {
+    const bucket = listeners.get(storage);
+    if (!bucket)
+        return;
+    for (const listener of bucket) {
+        try {
+            listener(op, key);
+        }
+        catch {
+            // a broken listener must not break the app's write
+        }
+    }
+}
+export function webStorage(storage, id, label) {
+    return {
+        id,
+        label,
+        keys: () => {
+            const keys = [];
+            for (let i = 0; i < storage.length; i++) {
+                const key = storage.key(i);
+                if (key !== null)
+                    keys.push(key);
+            }
+            return keys;
+        },
+        get: (key) => storage.getItem(key),
+        set: (key, value) => storage.setItem(key, value),
+        remove: (key) => storage.removeItem(key),
+        clear: () => storage.clear(),
+        watch(onChange) {
+            patchStoragePrototype();
+            const bucket = listeners.get(storage) ?? new Set();
+            listeners.set(storage, bucket);
+            bucket.add(onChange);
+            // Writes from other tabs only show up as `storage` events.
+            const onStorageEvent = (event) => {
+                if (event.storageArea !== storage)
+                    return;
+                if (event.key === null)
+                    onChange('clear');
+                else
+                    onChange(event.newValue === null ? 'remove' : 'set', event.key);
+            };
+            window.addEventListener('storage', onStorageEvent);
+            return () => {
+                bucket.delete(onChange);
+                window.removeEventListener('storage', onStorageEvent);
+            };
+        },
+    };
+}
+export function cookieStorage() {
+    const read = () => {
+        if (!document.cookie)
+            return [];
+        return document.cookie.split('; ').map((part) => {
+            const index = part.indexOf('=');
+            return index < 0 ? [decode(part), ''] : [decode(part.slice(0, index)), decode(part.slice(index + 1))];
+        });
+    };
+    const remove = (key) => {
+        document.cookie = `${encodeURIComponent(key)}=; path=/; expires=Thu, 01 Jan 1970 00:00:00 GMT`;
+    };
+    return {
+        id: 'cookies',
+        label: 'Cookies',
+        note: 'HttpOnly cookies are invisible to JavaScript. Edits are written with path=/.',
+        keys: () => read().map(([key]) => key),
+        get: (key) => read().find(([k]) => k === key)?.[1] ?? null,
+        set: (key, value) => {
+            document.cookie = `${encodeURIComponent(key)}=${encodeURIComponent(value)}; path=/`;
+        },
+        remove,
+        clear: () => {
+            for (const [key] of read())
+                remove(key);
+        },
+        watch: cookieChanges(),
+    };
+}
+/** The Cookie Store API also reports document.cookie writes; without it, cookies refresh only on demand. */
+function cookieChanges() {
+    const store = globalThis.cookieStore;
+    if (!store)
+        return undefined;
+    return (onChange) => {
+        const listener = (event) => {
+            const { changed = [], deleted = [] } = event;
+            for (const cookie of changed)
+                onChange('set', cookie.name);
+            for (const cookie of deleted)
+                onChange('remove', cookie.name);
+        };
+        store.addEventListener('change', listener);
+        return () => store.removeEventListener('change', listener);
+    };
+}
+function decode(text) {
+    try {
+        return decodeURIComponent(text);
+    }
+    catch {
+        return text;
+    }
+}
+//# sourceMappingURL=storage.js.map

package/dist/storage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"storage.js","sourceRoot":"","sources":["../src/storage.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,52 @@
 {
   "name": "@capybara-devtools/web",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "description": "Browser SDK for Capybara: logs, network and storage for React, Vite and Next.js apps",
+  "keywords": [
+    "capybara",
+    "devtools",
+    "debugger",
+    "logs",
+    "network",
+    "localstorage",
+    "react",
+    "vite",
+    "nextjs"
+  ],
+  "homepage": "https://github.com/lhphuc99/capybara#readme",
+  "bugs": "https://github.com/lhphuc99/capybara/issues",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/lhphuc99/capybara.git",
+    "directory": "packages/web"
+  },
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "sideEffects": false,
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "dev": "tsc -p tsconfig.json --watch",
+    "test": "vitest run",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  },
+  "dependencies": {
+    "@capybara-devtools/core": "0.2.0",
+    "@capybara-devtools/protocol": "0.2.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/errors.ts

@@ -0,0 +1,26 @@
+import type { Plugin } from '@capybara-devtools/core';
+
+export function windowErrorsPlugin(): Plugin {
+  return {
+    name: 'errors',
+    setup(ctx) {
+      // Bubbling listener only: resource load failures (broken <img>) don't bubble and stay out.
+      const onError = (event: ErrorEvent) => {
+        const args =
+          event.error !== undefined && event.error !== null
+            ? [event.error]
+            : [event.message, `at ${event.filename}:${event.lineno}:${event.colno}`];
+        ctx.emit('log', { level: 'error', source: 'uncaught', args: args.map((arg) => ctx.serialize(arg)) });
+      };
+      const onRejection = (event: PromiseRejectionEvent) => {
+        ctx.emit('log', { level: 'error', source: 'unhandledrejection', args: [ctx.serialize(event.reason)] });
+      };
+      window.addEventListener('error', onError);
+      window.addEventListener('unhandledrejection', onRejection);
+      return () => {
+        window.removeEventListener('error', onError);
+        window.removeEventListener('unhandledrejection', onRejection);
+      };
+    },
+  };
+}

package/src/index.ts

@@ -0,0 +1,103 @@
+import {
+  consolePlugin,
+  createClient,
+  getActiveClient,
+  networkPlugin,
+  storagePlugin,
+  type CapybaraClient,
+  type NetworkPluginOptions,
+  type Plugin,
+  type StorageAdapter,
+} from '@capybara-devtools/core';
+import { CLIENT_PATH, DEFAULT_PORT } from '@capybara-devtools/protocol';
+import { windowErrorsPlugin } from './errors.js';
+import { cookieStorage, webStorage } from './storage.js';
+
+export const SDK_VERSION = '0.2.0';
+
+/** Traffic of a dev server's own tooling: Next.js error overlay requests and its HMR socket. */
+const DEV_SERVER_NOISE = [/\/__nextjs_[\w-]+(\?|$)/, /\/_next\/webpack-hmr(\?|$)/];
+/** React's development build prints this on every page when the React DevTools extension is missing. */
+const CONSOLE_NOISE = [/Download the React DevTools for a better development experience/];
+
+export interface InitOptions {
+  /** Shown in the session picker. Defaults to the page title. */
+  appName?: string;
+  /** Machine running `capybara`. Defaults to the hostname the page was loaded from. */
+  host?: string;
+  port?: number;
+  /** Pass false to skip setup, e.g. `enabled: import.meta.env.DEV`. */
+  enabled?: boolean;
+  /** Capture console output and uncaught errors. Default true. */
+  logs?: boolean;
+  network?: boolean | NetworkPluginOptions;
+  /** `false` turns storage off; an array adds adapters next to localStorage, sessionStorage and cookies. */
+  storage?: boolean | StorageAdapter[];
+  plugins?: Plugin[];
+}
+
+export function init(options: InitOptions = {}): CapybaraClient | undefined {
+  // The window check makes this a no-op during server rendering, so the same entry works in Next.js.
+  if (options.enabled === false || typeof window === 'undefined') return undefined;
+  // Hot reload re-runs the entry file; patching again would record everything twice.
+  const existing = getActiveClient();
+  if (existing) return existing;
+
+  const plugins: Plugin[] = [];
+  if (options.logs !== false) plugins.push(consolePlugin({ ignore: CONSOLE_NOISE }), windowErrorsPlugin());
+  if (options.network !== false) {
+    const network = typeof options.network === 'object' ? options.network : {};
+    plugins.push(
+      networkPlugin({ ...network, ignoreUrls: [...DEV_SERVER_NOISE, ...metroSockets(), ...(network.ignoreUrls ?? [])] }),
+    );
+  }
+  if (options.storage !== false) {
+    const extra = Array.isArray(options.storage) ? options.storage : [];
+    plugins.push(storagePlugin([...defaultStorages(), ...extra]));
+  }
+  plugins.push(...(options.plugins ?? []));
+
+  const host = options.host ?? (window.location.hostname || 'localhost');
+  return createClient({
+    url: `ws://${formatHost(host)}:${options.port ?? DEFAULT_PORT}${CLIENT_PATH}`,
+    session: {
+      appName: options.appName ?? (document.title || window.location.host || 'Web app'),
+      platform: 'web',
+      sdk: { name: '@capybara-devtools/web', version: SDK_VERSION },
+      url: window.location.href,
+      userAgent: navigator.userAgent,
+    },
+    plugins,
+  });
+}
+
+function defaultStorages(): StorageAdapter[] {
+  const adapters: StorageAdapter[] = [];
+  // Reading these throws in sandboxed iframes and when site data is blocked.
+  try {
+    adapters.push(webStorage(window.localStorage, 'localStorage', 'Local Storage'));
+  } catch {
+    // unavailable
+  }
+  try {
+    adapters.push(webStorage(window.sessionStorage, 'sessionStorage', 'Session Storage'));
+  } catch {
+    // unavailable
+  }
+  adapters.push(cookieStorage());
+  return adapters;
+}
+
+/** With Expo web, Metro serves the page and also opens /hot and /message sockets on the same origin. */
+function metroSockets(): RegExp[] {
+  const host = window.location.host.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  return host ? [new RegExp(`^wss?://${host}/(?:hot|message)(?:[/?]|$)`)] : [];
+}
+
+function formatHost(host: string): string {
+  return host.includes(':') && !host.startsWith('[') ? `[${host}]` : host;
+}
+
+export { getActiveClient } from '@capybara-devtools/core';
+export type { CapybaraClient, NetworkPluginOptions, Plugin, StorageAdapter } from '@capybara-devtools/core';
+export { cookieStorage, webStorage } from './storage.js';

package/src/storage.ts

@@ -0,0 +1,130 @@
+import type { StorageAdapter } from '@capybara-devtools/core';
+import type { StorageOp } from '@capybara-devtools/protocol';
+
+type Listener = (op: StorageOp, key?: string) => void;
+
+const listeners = new Map<Storage, Set<Listener>>();
+let prototypePatched = false;
+
+// Patched once and never undone: with no listeners it costs nothing, and undoing it
+// could remove a wrapper another library installed on top of ours.
+function patchStoragePrototype(): void {
+  if (prototypePatched || typeof Storage === 'undefined') return;
+  prototypePatched = true;
+  const proto = Storage.prototype;
+  const { setItem, removeItem, clear } = proto;
+  proto.setItem = function (this: Storage, key: string, value: string) {
+    setItem.call(this, key, value);
+    notify(this, 'set', String(key));
+  };
+  proto.removeItem = function (this: Storage, key: string) {
+    removeItem.call(this, key);
+    notify(this, 'remove', String(key));
+  };
+  proto.clear = function (this: Storage) {
+    clear.call(this);
+    notify(this, 'clear');
+  };
+}
+
+function notify(storage: Storage, op: StorageOp, key?: string): void {
+  const bucket = listeners.get(storage);
+  if (!bucket) return;
+  for (const listener of bucket) {
+    try {
+      listener(op, key);
+    } catch {
+      // a broken listener must not break the app's write
+    }
+  }
+}
+
+export function webStorage(storage: Storage, id: string, label: string): StorageAdapter {
+  return {
+    id,
+    label,
+    keys: () => {
+      const keys: string[] = [];
+      for (let i = 0; i < storage.length; i++) {
+        const key = storage.key(i);
+        if (key !== null) keys.push(key);
+      }
+      return keys;
+    },
+    get: (key) => storage.getItem(key),
+    set: (key, value) => storage.setItem(key, value),
+    remove: (key) => storage.removeItem(key),
+    clear: () => storage.clear(),
+    watch(onChange) {
+      patchStoragePrototype();
+      const bucket = listeners.get(storage) ?? new Set<Listener>();
+      listeners.set(storage, bucket);
+      bucket.add(onChange);
+      // Writes from other tabs only show up as `storage` events.
+      const onStorageEvent = (event: StorageEvent) => {
+        if (event.storageArea !== storage) return;
+        if (event.key === null) onChange('clear');
+        else onChange(event.newValue === null ? 'remove' : 'set', event.key);
+      };
+      window.addEventListener('storage', onStorageEvent);
+      return () => {
+        bucket.delete(onChange);
+        window.removeEventListener('storage', onStorageEvent);
+      };
+    },
+  };
+}
+
+export function cookieStorage(): StorageAdapter {
+  const read = (): Array<[string, string]> => {
+    if (!document.cookie) return [];
+    return document.cookie.split('; ').map((part): [string, string] => {
+      const index = part.indexOf('=');
+      return index < 0 ? [decode(part), ''] : [decode(part.slice(0, index)), decode(part.slice(index + 1))];
+    });
+  };
+  const remove = (key: string) => {
+    document.cookie = `${encodeURIComponent(key)}=; path=/; expires=Thu, 01 Jan 1970 00:00:00 GMT`;
+  };
+  return {
+    id: 'cookies',
+    label: 'Cookies',
+    note: 'HttpOnly cookies are invisible to JavaScript. Edits are written with path=/.',
+    keys: () => read().map(([key]) => key),
+    get: (key) => read().find(([k]) => k === key)?.[1] ?? null,
+    set: (key, value) => {
+      document.cookie = `${encodeURIComponent(key)}=${encodeURIComponent(value)}; path=/`;
+    },
+    remove,
+    clear: () => {
+      for (const [key] of read()) remove(key);
+    },
+    watch: cookieChanges(),
+  };
+}
+
+/** The Cookie Store API also reports document.cookie writes; without it, cookies refresh only on demand. */
+function cookieChanges(): StorageAdapter['watch'] {
+  const store = (globalThis as { cookieStore?: EventTarget }).cookieStore;
+  if (!store) return undefined;
+  return (onChange) => {
+    const listener = (event: Event) => {
+      const { changed = [], deleted = [] } = event as Event & {
+        changed?: Array<{ name?: string }>;
+        deleted?: Array<{ name?: string }>;
+      };
+      for (const cookie of changed) onChange('set', cookie.name);
+      for (const cookie of deleted) onChange('remove', cookie.name);
+    };
+    store.addEventListener('change', listener);
+    return () => store.removeEventListener('change', listener);
+  };
+}
+
+function decode(text: string): string {
+  try {
+    return decodeURIComponent(text);
+  } catch {
+    return text;
+  }
+}