diff --git a/.changeset/backend-server-entry.md b/.changeset/backend-server-entry.md
new file mode 100644
index 00000000..66c4a738
--- /dev/null
+++ b/.changeset/backend-server-entry.md
@@ -0,0 +1,9 @@
+---
+"@wdio/devtools-backend": minor
+---
+
+The backend ships a runnable entry, so a non-Node adapter can start the dashboard itself.
+
+- `dist/server.js` is a new CLI entry, exposed as the `devtools-backend` bin. `node packages/backend/dist/server.js` and `npx @wdio/devtools-backend` both start the live dashboard, and `--port` / `--hostname` / `--help` are accepted.
+- `dist/index.js` stays the library entry the JS adapters import in-process. Its "start if run directly" guard is gone rather than repaired: `show-trace.ts` imports `start` from index, which makes index a shared module whose body tsup hoists into `dist/chunk-*.js`, and there `import.meta.url` is the chunk's path and can never equal `process.argv[1]`. The guard was therefore dead in every build, which is why `node dist/index.js` imported a module and exited 0 without serving. A leaf entry keeps its body in its own output file, so the new file needs no guard at all.
+- `dev:app` now runs `dist/server.js`, since it was watching an entry that could not start.
diff --git a/.github/workflows/python-release.yml b/.github/workflows/python-release.yml
new file mode 100644
index 00000000..9ad973d8
--- /dev/null
+++ b/.github/workflows/python-release.yml
@@ -0,0 +1,52 @@
+name: Manual PyPI Publish
+
+# Mirrors release.yml's manual, button-triggered shape for the Python adapter.
+# Unlike npm (NPM_TOKEN), PyPI uses trusted publishing (OIDC) — no secret.
+# Bump the version in packages/selenium-devtools-py/pyproject.toml before running.
+
+on:
+  workflow_dispatch:
+    inputs:
+      target:
+        description: 'Publish target'
+        required: true
+        type: choice
+        default: pypi
+        options:
+          - pypi
+          - testpypi
+
+defaults:
+  run:
+    working-directory: packages/selenium-devtools-py
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    environment: ${{ inputs.target }}
+    permissions:
+      id-token: write # PyPI trusted publishing (OIDC) — no token/secret needed
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          ref: 'main'
+      - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5
+        with:
+          python-version: '3.12'
+      - name: 🧪 Unit tests (release guard)
+        run: PYTHONPATH=src python -m unittest discover -s tests
+      - name: 📦 Build sdist + wheel
+        run: |
+          python -m pip install --upgrade build
+          python -m build
+      - name: 🚀 Publish to PyPI
+        if: ${{ inputs.target == 'pypi' }}
+        uses: pypa/gh-action-pypi-publish@cef221092ed1bacb1cc03d23a2d87d1d172e277b # release/v1
+        with:
+          packages-dir: packages/selenium-devtools-py/dist
+      - name: 🚀 Publish to TestPyPI
+        if: ${{ inputs.target == 'testpypi' }}
+        uses: pypa/gh-action-pypi-publish@cef221092ed1bacb1cc03d23a2d87d1d172e277b # release/v1
+        with:
+          packages-dir: packages/selenium-devtools-py/dist
+          repository-url: https://test.pypi.org/legacy/
diff --git a/.github/workflows/python.yml b/.github/workflows/python.yml
new file mode 100644
index 00000000..9d3102e9
--- /dev/null
+++ b/.github/workflows/python.yml
@@ -0,0 +1,46 @@
+name: Python Adapter
+
+# Deliberately NOT triggered by packages/shared/**, even though the adapter's
+# wire contract is generated from it. Doing so put a Python check on every PR
+# that touched shared, which is most of them, and a red Python job would block
+# work unrelated to this adapter. The trade-off: a shared change that breaks the
+# contract is not caught here at the moment it lands. It is still caught by the
+# drift check below on the next PR that touches this package, which regenerates
+# _contract.py and fails on any diff. Revisit once the adapter is published and
+# the coupling is worth the noise.
+on:
+  push:
+    branches:
+      - main
+    paths:
+      - packages/selenium-devtools-py/**
+      - .github/workflows/python.yml
+  pull_request:
+    paths:
+      - packages/selenium-devtools-py/**
+      - .github/workflows/python.yml
+
+permissions:
+  contents: read
+
+defaults:
+  run:
+    working-directory: packages/selenium-devtools-py
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ['3.9', '3.12']
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+      - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Contract is in sync with shared
+        run: |
+          python scripts/gen_contract.py
+          git diff --exit-code src/selenium_devtools/_contract.py
+      - name: 🧪 Unit tests
+        run: PYTHONPATH=src python -m unittest discover -s tests
diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md
index aab07153..ef0c5766 100644
--- a/ARCHITECTURE.md
+++ b/ARCHITECTURE.md
@@ -106,6 +106,7 @@ The server adapters connect to and the app talks to.
 
 Contains:
 
+- Two build entries: `index.ts` is the **library** entry (`dist/index.js`) the adapters import in-process for `start`/`stop`, and `server.ts` is the **CLI** entry (`dist/server.js`, executable, shipped as the `devtools-backend` bin) that starts the same server standalone. `server.ts` is a leaf entry on purpose: a self-start guard inside `index.ts` is dead, because `show-trace.ts` imports it and tsup hoists a shared entry's body into `dist/chunk-*.js`, where `import.meta.url` never matches `process.argv[1]`.
 - Fastify HTTP server.
 - WebSocket gateway: one connection per adapter worker, one per app client.
 - Baseline store (in-memory) for preserve-and-rerun; reuses `shared` types directly via thin `*Like` aliases (`baseline/types.ts`).
diff --git a/CLAUDE.md b/CLAUDE.md
index 31abe165..8f475542 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -287,6 +287,7 @@ Documented divergences from the conventions above. They exist today as debt to b
   - **Assert outcomes are correlated off the assertion's own promise, because the results bag does not exist.** Cucumber's Nightwatch client is built by `createClient` with **no reporter**, so `SimplifiedReporter.logAssertResult` no-ops and `results.assertions`/`results.testcases` are *never* populated — no scenario-level reconcile can recover them, which is why `currentTest: undefined` was a dead end. `nativeAssertions.ts` `observedAssertOutcome` reads the outcome from the returned promise instead (`lib/core/asynctree.js` `shouldRejectNodePromise`: a failing `assert.*` rejects its deferred, a failing `verify.*` resolves *with* the AssertionError, a pass resolves with the command value). A fulfilment of `undefined` stays **neutral** — that is an assertion enqueued but never executed after an earlier `assert.*` emptied the queue, and reading it as a pass would paint a never-run assertion green. The results bag still wins where it exists and the row's window comes from whichever source supplied the outcome, so the describe/it timeline is byte-stable. Measured: **4 of 4 assert rows with a real pass/fail** (was 2 of 4 rows, 0 correlated), spanning real 44–372 ms windows instead of a synthetic 1 ms.
   - Relatedly, cucumber's **per-step** `resetCommandTracking()` was wiping the native-assert buffer, so each scenario kept only its *last* step's assertions (measured 1 of 2). The buffer is per **test unit** — `resetTestTracking()` at `wrapBrowserOnce` now clears it.
   - **DOM `mutations` ARE captured**, and the old `ECONNRESET` / "collector not found" attribution is **wrong** — neither appears any more. The gap closed itself with document-start injection (`core/bidi-preload.ts`), confirmed on a *baseline* build so the credit is A10's. Measured per scenario with `traceGranularity:'test'` + `webSocketUrl: true`: 39 and 19 mutation entries, 2 DOM anchors each, **0 of 19 rows on the wrong document**. What remains is noise, not a gap: the screencast poller issues `/screenshot` every 200 ms into the session Nightwatch quits per scenario, logging 9–26 `WARN webdriverHttp: … socket hang up` per run. Fix is to stop the recorder before the per-scenario quit, or suppress the warn for a session in teardown.
+- **A tsup entry that another entry imports is not a leaf, so an `import.meta.url === process.argv[1]` self-start check inside it is dead code; a CLI has to be its own leaf entry.** tsup hoists a module body shared by two entries into `dist/chunk-*.js`, and there `import.meta.url` is the chunk's path, which can never equal `process.argv[1]`. `packages/backend/src/show-trace.ts` imports `start` from `index.ts`, which is what made index shared, so index's old "start if run directly" guard was dead in **every** build: `node dist/index.js` exited 0 without ever serving, while `dist/show-trace.js` self-started correctly for exactly the same reason inverted, being a leaf whose body stays in its own output file (it also compares realpaths, because the invoked path is the `node_modules/.bin` symlink). The live dashboard server is therefore its own leaf entry, `packages/backend/src/server.ts` (shebang, built to an executable `dist/server.js`, shipped as the `devtools-backend` bin, accepting `--port`, `--hostname`, `-h`/`--help`), and `index.ts` stays library-only for the three adapters' in-process `start`/`stop`. Same family as the `cucumberHooks.cts` entry above: the tsup entry list is part of the contract, and in both cases the symptom was silence rather than an error.
 - **A captured text locator is generated in the recording runner's dialect; every other branch is portable CSS.** `shared/locator-dialect.ts` `locatorDialect(runner)` is the one fact table — WDIO runners (`mocha`/`jasmine`/`cucumber`) get `a*=Logout`, `nightwatch*`/`selenium-webdriver` and an **unidentified recorder** get `//a[contains(., "Logout")]`. The id reaches the page script as `CaptureActionSnapshotInput.runner` and the zip as an extension field on `context-options`, read back through `isTestRunnerId` onto `Metadata.runner`; absent in older and foreign zips, where the player shows no hint. Under WDIO a text carrying a `"` still emits XPath — WDIO compiles `tag*=` to XPath with `"` quoting and would build a broken expression — and WDIO resolves `//` itself. `locatorsMatch` decomposes **both** sides from either dialect, so `after.point` survives whichever way round the two grammars fall; the `concat()`-stitched literal is still left to exact comparison. `@wdio/elements`' standalone `getSnapshot` deliberately keeps the portable XPath default (its output is pasted into arbitrary tools), so a WDIO run's `browser.getSnapshot()` and its trace A11y tab disagree on that one branch.
 - `Metadata.runner` (typed `TestRunnerId`) and `metadata.options.framework` (untyped `string`, read by the sidebar's `getFramework`) are two carriers of the same fact. All three adapters now set both; the next change to either should collapse `getFramework` onto `Metadata.runner`.
 - Selenium's `ctx.runner` (the *detected JS runner* — mocha/jest/cucumber, from `detectRunner()`) shadows the new `Metadata.runner` concept. Renamed to `detectedRunner` at the `driverMetadata` boundary only, where the two met inside one function and a swap would have been a silent dialect bug; the repo-wide rename in `plugin-internals.ts`/`session-lifecycle.ts` is still open.
diff --git a/examples/selenium/python-test/.gitignore b/examples/selenium/python-test/.gitignore
new file mode 100644
index 00000000..58341d59
--- /dev/null
+++ b/examples/selenium/python-test/.gitignore
@@ -0,0 +1,3 @@
+# Run output goes to test-results/, which the root .gitignore already covers.
+# *.webm stays for videos written by older versions of the adapter.
+*.webm
diff --git a/examples/selenium/python-test/web_form.py b/examples/selenium/python-test/web_form.py
new file mode 100644
index 00000000..bf13aa37
--- /dev/null
+++ b/examples/selenium/python-test/web_form.py
@@ -0,0 +1,35 @@
+"""The smallest useful DevTools example: three devtools lines, one Selenium test.
+
+This is the script reproduced in the integration one-pager, so keep the two in
+sync when either changes.
+
+Run it:
+
+    pip install -e packages/selenium-devtools-py
+    python examples/selenium/python-test/web_form.py
+
+``enable()`` starts the dashboard backend itself when none is running. Set
+DEVTOOLS_PORT instead to attach to one you already have open. Run output (the
+screencast .webm) lands in ``test-results/`` beside this file, matching the JS
+adapters.
+"""
+
+import selenium_devtools as devtools
+from selenium import webdriver
+from selenium.webdriver.common.by import By
+from selenium.webdriver.chrome.options import Options
+
+devtools.enable()  # opens the dashboard, starts capturing
+
+options = Options()
+options.add_argument("--headless=new")  # drop this line to watch the browser
+options.add_argument("--window-size=1280,1024")  # bigger viewport, fuller screencast
+driver = webdriver.Chrome(options=options)
+try:
+    driver.get("https://www.selenium.dev/selenium/web/web-form.html")
+    driver.find_element(By.NAME, "my-text").send_keys("Selenium")
+    driver.find_element(By.CSS_SELECTOR, "button").click()
+    print(driver.find_element(By.ID, "message").text)
+finally:
+    driver.quit()
+    devtools.wait_for_dashboard_close()  # hold the UI open to inspect
diff --git a/package.json b/package.json
index b6bc9ee3..b52459b4 100644
--- a/package.json
+++ b/package.json
@@ -6,12 +6,14 @@
   "scripts": {
     "build": "pnpm -r build",
     "show-trace": "node packages/backend/dist/show-trace.js",
+    "backend": "node packages/backend/dist/server.js",
     "demo:wdio": "wdio run ./examples/wdio/cucumber/wdio.conf.ts",
     "demo:wdio:mocha": "wdio run ./examples/wdio/mocha/wdio.conf.ts",
     "demo:wdio:retry": "wdio run ./examples/wdio/mocha/wdio.retry.conf.ts",
     "demo:nightwatch": "pnpm --filter @wdio/nightwatch-devtools example",
     "demo:nightwatch:retry": "pnpm --filter @wdio/nightwatch-devtools example:retry",
     "demo:selenium": "pnpm --filter @wdio/selenium-devtools example",
+    "demo:python": "python3 examples/selenium/python-test/web_form.py",
     "dev": "pnpm --parallel dev",
     "preview": "pnpm --parallel preview",
     "test": "vitest run",
diff --git a/packages/backend/README.md b/packages/backend/README.md
index ef3110a4..58d5b3c0 100644
--- a/packages/backend/README.md
+++ b/packages/backend/README.md
@@ -1,6 +1,6 @@
 # @wdio/devtools-backend
 
-The server that the three adapter packages connect to and the dashboard UI talks to. Internal to the monorepo — not published.
+The server that the three adapter packages connect to and the dashboard UI talks to. Published to npm as `@wdio/devtools-backend` (it's on [CONTRIBUTING.md](../../CONTRIBUTING.md)'s list of published packages, has a `prepublishOnly` build, and ships the `devtools-backend` and `show-trace` bins); the adapters depend on it rather than vendoring it.
 
 ## Responsibilities
 
@@ -25,7 +25,7 @@ Trace mode (see the [root README](../../README.md#-trace-mode-tracezip)) writes
   pnpm show-trace path/to/trace.zip
   ```
 
-  The same entry is shipped as a `show-trace` **bin** by the backend (`./dist/show-trace.js`) and by each adapter (`@wdio/devtools-service`, `@wdio/selenium-devtools`, `@wdio/nightwatch-devtools` each ship a thin `bin/show-trace.mjs`), so `npx show-trace <trace.zip>` works in any project that installs an adapter — backend need only be a transitive dependency. In trace-serve mode `start({ trace })` exposes the reconstructed payload at `TRACE_API.get` and skips the worker/rerun machinery.
+  The same entry is shipped as a `show-trace` **bin** by the backend (`./dist/show-trace.js`) and by each adapter (`@wdio/devtools-service`, `@wdio/selenium-devtools`, `@wdio/nightwatch-devtools` each ship a thin `bin/show-trace.mjs`), so `npx show-trace <trace.zip>` works in any project that installs an adapter — backend need only be a transitive dependency. In trace-serve mode `start({ trace })` exposes the reconstructed payload at `TRACE_API.get` and skips the worker/rerun machinery. It is one of the backend's two bins; the other, `devtools-backend` (`./dist/server.js`), starts the live dashboard server described under [Public API](#public-api).
 
 - **Reader** (`src/trace-reader.ts`, with sibling `trace-reader-{constants,types,utils,groups}.ts`) — `parseTraceZip` / `readTraceZip` reconstruct a `TracePlayerData` payload from the archive. It accepts this repo's own exporter output **and foreign zips** written by other tools (every `.trace` entry is an action-event stream, every `.network` a HAR stream, `.stacks` sidecars carry call stacks). It rebuilds:
   - **commands** — from `before`/`after` action events, with call source, result, error, nearest screenshot frame, and pointer hit point;
@@ -40,6 +40,20 @@ Because the archive uses that portable, standard trace-viewer format, the same `
 
 ## Public API
 
-The backend is consumed only by other workspace packages. Adapter launchers call `start({ port, hostname })` and receive the bound port. The dashboard accesses it via the documented HTTP routes (`packages/shared/src/baseline.ts`, `packages/shared/src/runner.ts`) and WS scopes (`packages/shared/src/ws.ts`, `packages/shared/src/routes.ts`).
+Two build entries, and they are deliberately separate files.
+
+- **Library entry** (`src/index.ts` → `dist/index.js`), consumed in-process by the other workspace packages: adapter launchers call `start({ port, hostname })` and receive the bound port, then `stop()` on teardown. The dashboard accesses the running server via the documented HTTP routes (`packages/shared/src/baseline.ts`, `packages/shared/src/runner.ts`) and WS scopes (`packages/shared/src/ws.ts`, `packages/shared/src/routes.ts`).
+
+- **CLI entry** (`src/server.ts` → the executable `dist/server.js`), shipped as the `devtools-backend` bin, which starts the same server on its own instead of from an adapter's launcher:
+
+  ```sh
+  npx @wdio/devtools-backend --port 8080 --hostname 0.0.0.0
+  ```
+
+  - `--port <number>` (or `--port=<number>`): preferred port; a free one is chosen if it's taken.
+  - `--hostname <host>` (or `--hostname=<host>`): host to bind, `localhost` by default.
+  - `-h`, `--help`: print usage and exit without starting.
+
+Don't collapse the CLI back into `index.ts` behind a "start if run directly" guard: `show-trace.ts` imports `start` from index, which makes index a shared module whose body tsup hoists into `dist/chunk-*.js`, and there `import.meta.url` is the chunk's own path and can never equal `process.argv[1]`, so the guard is dead in every build (`node dist/index.js` exited 0 without ever serving); a leaf entry keeps its body in its own output file, which is why `show-trace.js` self-starts correctly.
 
 For the full picture of how events flow adapter → backend → dashboard, see [ARCHITECTURE.md](../../ARCHITECTURE.md).
diff --git a/packages/backend/package.json b/packages/backend/package.json
index 46a1395c..b1d66f0f 100644
--- a/packages/backend/package.json
+++ b/packages/backend/package.json
@@ -18,15 +18,16 @@
     }
   },
   "bin": {
+    "devtools-backend": "./dist/server.js",
     "show-trace": "./dist/show-trace.js"
   },
   "types": "./dist/index.d.ts",
   "typeScriptVersion": "^5.0.0",
   "scripts": {
     "dev": "run-p dev:*",
-    "dev:ts": "tsup src/index.ts src/show-trace.ts --format esm --dts --watch",
-    "dev:app": "nodemon --watch ./dist ./dist/index.js",
-    "build": "tsup src/index.ts src/show-trace.ts --format esm --dts --clean",
+    "dev:ts": "tsup src/index.ts src/show-trace.ts src/server.ts --format esm --dts --watch",
+    "dev:app": "nodemon --watch ./dist ./dist/server.js",
+    "build": "tsup src/index.ts src/show-trace.ts src/server.ts --format esm --dts --clean",
     "lint": "eslint .",
     "prepublishOnly": "pnpm build"
   },
diff --git a/packages/backend/src/index.ts b/packages/backend/src/index.ts
index 173e0a0f..e5061121 100644
--- a/packages/backend/src/index.ts
+++ b/packages/backend/src/index.ts
@@ -1,5 +1,4 @@
 import fs from 'node:fs'
-import url from 'node:url'
 
 import Fastify, {
   type FastifyInstance,
@@ -443,13 +442,3 @@ export async function stop() {
 
   await server.close()
 }
-
-/**
- * start server if this file is called directly
- */
-if (import.meta.url.startsWith('file:')) {
-  const modulePath = url.fileURLToPath(import.meta.url)
-  if (process.argv[1] === modulePath) {
-    start()
-  }
-}
diff --git a/packages/backend/src/server-args.ts b/packages/backend/src/server-args.ts
new file mode 100644
index 00000000..5bad9e2d
--- /dev/null
+++ b/packages/backend/src/server-args.ts
@@ -0,0 +1,44 @@
+/**
+ * Argv parsing for the `devtools-backend` bin. Split from `server.ts` because
+ * that file starts a server as its module body, so a unit test cannot import it.
+ */
+
+export const SERVER_USAGE = `
+  Usage: devtools-backend [options]
+
+  Options:
+    --port <number>     Preferred port; a free one is chosen if it is taken
+    --hostname <host>   Host to bind (default: localhost)
+    -h, --help          Show this message
+`
+
+export interface ServerArgs {
+  help: boolean
+  port?: number
+  hostname?: string
+}
+
+/** Read `--name value` or `--name=value`, whichever the caller used. */
+function option(args: string[], name: string): string | undefined {
+  const flag = `--${name}`
+  const at = args.indexOf(flag)
+  if (at !== -1) {
+    return args[at + 1]
+  }
+  return args.find((arg) => arg.startsWith(`${flag}=`))?.slice(flag.length + 1)
+}
+
+/**
+ * A port is kept only when it parses as a positive integer, so `--port` with no
+ * value, `--port abc` and `--port 0` all fall through to the server's own
+ * default rather than binding something the caller did not ask for.
+ */
+export function parseServerArgs(args: string[]): ServerArgs {
+  const port = Number(option(args, 'port'))
+  const hostname = option(args, 'hostname')
+  return {
+    help: args.includes('-h') || args.includes('--help'),
+    ...(Number.isInteger(port) && port > 0 ? { port } : {}),
+    ...(hostname ? { hostname } : {})
+  }
+}
diff --git a/packages/backend/src/server.ts b/packages/backend/src/server.ts
new file mode 100644
index 00000000..5ec3b551
--- /dev/null
+++ b/packages/backend/src/server.ts
@@ -0,0 +1,35 @@
+#!/usr/bin/env node
+// CLI entry for the live dashboard server. `index.ts` is the LIBRARY entry the
+// JS adapters import in-process; a "start if run directly" guard cannot live
+// there, because `show-trace.ts` imports `start` from it, which makes index a
+// shared module whose body tsup hoists into `dist/chunk-*.js` — there
+// `import.meta.url` is the chunk's path and never equals `process.argv[1]`, so
+// the guard silently never fires. A leaf entry keeps its body in its own output
+// file, which is why this file needs no guard at all.
+
+import { start } from './index.js'
+import { parseServerArgs, SERVER_USAGE } from './server-args.js'
+
+async function run(args: string[]): Promise<void> {
+  const { help, ...opts } = parseServerArgs(args)
+  if (help) {
+    console.log(SERVER_USAGE)
+    return
+  }
+  try {
+    const { port } = await start(opts)
+    // Our own line, so a consumer scraping stdout for the bound port (the Python
+    // adapter does) depends on this file rather than on Fastify's logger staying
+    // enabled. The port is the one actually bound, which differs from any
+    // `--port` when that was taken.
+    const host = opts.hostname ?? 'localhost'
+    console.log(`devtools-backend listening at http://${host}:${port}`)
+  } catch (error) {
+    console.error(
+      `Failed to start WebdriverIO Devtools: ${(error as Error).message}`
+    )
+    process.exit(1)
+  }
+}
+
+void run(process.argv.slice(2))
diff --git a/packages/backend/tests/server-args.test.ts b/packages/backend/tests/server-args.test.ts
new file mode 100644
index 00000000..f309a3fb
--- /dev/null
+++ b/packages/backend/tests/server-args.test.ts
@@ -0,0 +1,64 @@
+import { describe, it, expect } from 'vitest'
+import { parseServerArgs, SERVER_USAGE } from '../src/server-args.js'
+
+describe('parseServerArgs', () => {
+  it('reads a port given as two arguments', () => {
+    expect(parseServerArgs(['--port', '4123'])).toEqual({
+      help: false,
+      port: 4123
+    })
+  })
+
+  it('reads a port given with an equals sign', () => {
+    expect(parseServerArgs(['--port=4123'])).toEqual({
+      help: false,
+      port: 4123
+    })
+  })
+
+  it('reads a hostname in either form', () => {
+    expect(parseServerArgs(['--hostname', '0.0.0.0'])).toEqual({
+      help: false,
+      hostname: '0.0.0.0'
+    })
+    expect(parseServerArgs(['--hostname=0.0.0.0'])).toEqual({
+      help: false,
+      hostname: '0.0.0.0'
+    })
+  })
+
+  it('takes both together, in any order', () => {
+    expect(
+      parseServerArgs(['--hostname', '127.0.0.1', '--port', '5000'])
+    ).toEqual({ help: false, hostname: '127.0.0.1', port: 5000 })
+  })
+
+  it('omits the port when it is absent, so the server keeps its default', () => {
+    expect(parseServerArgs([])).toEqual({ help: false })
+  })
+
+  // `--port` as the final argument reads `undefined`, and a flag as its value
+  // must not be swallowed as a port either.
+  it.each([
+    ['no value', ['--port']],
+    ['the next flag as its value', ['--port', '--hostname', 'localhost']],
+    ['a non-numeric value', ['--port', 'abc']],
+    ['a fractional value', ['--port', '80.5']],
+    ['zero', ['--port', '0']],
+    ['a negative value', ['--port', '-1']]
+  ])('drops a port given as %s', (_label, args) => {
+    expect(parseServerArgs(args as string[]).port).toBeUndefined()
+  })
+
+  it('reports help for -h and --help', () => {
+    expect(parseServerArgs(['-h']).help).toBe(true)
+    expect(parseServerArgs(['--help']).help).toBe(true)
+    expect(parseServerArgs(['--port', '3000']).help).toBe(false)
+  })
+
+  it('documents every flag it parses', () => {
+    for (const flag of ['--port', '--hostname', '-h', '--help']) {
+      expect(SERVER_USAGE).toContain(flag)
+    }
+  })
+})
diff --git a/packages/selenium-devtools-py/.gitignore b/packages/selenium-devtools-py/.gitignore
new file mode 100644
index 00000000..69b17f32
--- /dev/null
+++ b/packages/selenium-devtools-py/.gitignore
@@ -0,0 +1,8 @@
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.venv/
+venv/
+build/
+dist/
+*.egg-info/
diff --git a/packages/selenium-devtools-py/README.md b/packages/selenium-devtools-py/README.md
new file mode 100644
index 00000000..8ad4f1cc
--- /dev/null
+++ b/packages/selenium-devtools-py/README.md
@@ -0,0 +1,202 @@
+# selenium-devtools-py (Python)
+
+Python Selenium adapter for the WebdriverIO DevTools dashboard — the fourth
+adapter alongside the JS WebdriverIO / Nightwatch / Selenium-JS ones. It feeds
+the **same backend and UI**, unchanged, over the language-neutral
+`{scope, data}` WebSocket contract.
+
+**Status: Phase 1 + 2.** Live command capture + test tree; browser console &
+network via BiDi; screencast video; and a dashboard window that auto-opens and
+tears down with the run. Verified against real headless Chrome. See
+[Roadmap](#roadmap) for what's deferred.
+
+## Install (dev)
+
+```bash
+pip install -e packages/selenium-devtools-py   # or: pip install selenium-devtools-py (when published)
+```
+
+The transport is **dependency-free** (stdlib WebSocket client). The only thing
+on top of your own `selenium` install is this package; `pytest` is optional.
+
+## Use
+
+**With pytest (recommended) — no code changes to your tests:**
+
+```bash
+DEVTOOLS_ENABLE=1 pytest tests/       # DEVTOOLS_PORT=<n> also opts in (and attaches)
+```
+
+The bundled plugin auto-captures the run, opens the dashboard in a dedicated
+window, and — after the run — **keeps it open so you can inspect it**; close the
+window (or Ctrl-C) to finish. Nothing devtools-specific goes in your test files.
+
+**Without pytest** (any script / unittest) — add two lines to a normal Selenium
+script (`devtools.enable()` + `devtools.wait_for_dashboard_close()`):
+
+```python
+import selenium_devtools as devtools
+
+devtools.enable()                     # open dashboard + capture every command
+# ... your normal selenium code, ending with driver.quit() ...
+devtools.wait_for_dashboard_close()   # keep the UI open to inspect (no-op if headless)
+devtools.disable()
+```
+
+Runnable example: [`web_form.py`](../../examples/selenium/python-test/web_form.py),
+the three-line version above. From the repo root, after `pip install -e` above and
+a `pnpm build` so the backend exists:
+
+```bash
+pnpm demo:python
+```
+
+Unlike `demo:wdio` and friends, this needs the Python package installed and uses
+whatever `python3` resolves to on your PATH.
+If the backend can't be launched or reached, `enable()` warns and returns
+`None` — capture is skipped, your tests still run.
+
+**ChromeDriver:** you need one matching your Chrome (a mismatch breaks all
+Selenium, not just this). Selenium 4.6+ auto-manages it when no `chromedriver`
+is on `PATH`; otherwise keep it current (`brew upgrade chromedriver`).
+
+## What it captures
+
+| Data | How | Scope | Phase |
+|---|---|---|---|
+| Commands (driver + element) | wrap `WebDriver.execute()` — the single chokepoint all commands flow through | `commands` | 1 |
+| Session metadata | read `session_id` + `caps` on the first ready command | `metadata` | 1 |
+| Test / suite tree | pytest plugin (`pytest_runtest_logreport` / `sessionfinish`) | `suites` | 1 |
+| Browser console + JS errors | Selenium **BiDi** (`driver.script` handlers) | `consoleLogs` | 2 |
+| Network requests | Selenium **BiDi** (low-level subscribe, no interception) | `networkRequests` | 2 |
+| DOM snapshot (preview iframe) | inject `packages/script`, re-inject per navigation, drain mutations | `mutations` | 2 |
+| Screencast video | screenshot polling → ffmpeg-encoded `.webm` | `screencast` | 2 |
+
+Element actions (`click`, `send_keys`, `text`, …) are captured for free: they
+delegate to `self._parent.execute`, so the one wrapper sees them as
+`clickElement`, `getElementText`, etc.
+
+**BiDi is auto-enabled** — the adapter injects the `webSocketUrl` capability
+into the `newSession` request so console/network work out-of-box (opt out with
+`DEVTOOLS_BIDI=0`). **Screencast** needs `ffmpeg` on PATH to encode the
+`.webm`; without it, recording is skipped (one warning, no error).
+
+## Dashboard window lifecycle
+
+Like the JS adapters, `enable()` opens the dashboard in a dedicated, closable
+Chrome window; closing that window (backend `clientDisconnected`) shuts the run
+down, and ending the process (exit / Ctrl-C) closes the window. Auto-open is on
+when stdout is a TTY; force it with `DEVTOOLS_OPEN=1` or disable with `=0`.
+
+## Layout
+
+```
+src/selenium_devtools/
+  __init__.py         public API — enable() / disable() / get_capturer()
+  constants.py        defaults, env-var names, skip sets, pinned backend version
+  types.py            TypedDicts for the wire payloads (mirror packages/shared)
+  _contract.py        GENERATED from packages/shared — scope names + CONTRACT_VERSION
+  utils.py            framework-agnostic helpers (now_ms, iso, to_jsonable, call_source)
+  frames.py           pure builders for each {scope,data} payload
+  transport.py        stdlib WebSocket client (handshake, masked frames, ping/pong, control reader)
+  capturer.py         SessionCapturer: command IDs, normalize→send, metadata-once
+  instrumentation.py  execute() wrap + BiDi auto-enable + session-setup hook
+  bidi.py             BiDi console/JS-error + network capture (pure mapping + wiring)
+  screencast.py       screenshot-polling recorder + ffmpeg webm encode
+  backend.py          launch-or-attach the Node backend + port discovery
+  lifecycle.py        dashboard window open/close + shutdown-on-disconnect
+  pytest_plugin.py    suite/test tree feeder (opt-in)
+scripts/gen_contract.py   regenerate _contract.py from shared (dev-time; also a drift-guard)
+tests/                stdlib-unittest unit tests (no selenium/pytest needed)
+e2e_check.py          real-Chrome smoke (plain script)
+e2e/test_smoke.py     real-Chrome smoke (pytest + plugin)
+(example lives at repo root: examples/selenium/python-test/web_form.py)
+```
+
+## Backend & publishing
+
+Two artifacts, two registries — pip can't resolve the Node backend, so each
+coupling is handled explicitly rather than via a `workspace:^`-style resolver:
+
+| | Local (monorepo) | Published |
+|---|---|---|
+| **Adapter** (this package) | `pip install -e` | PyPI: `pip install selenium-devtools-py` |
+| **Backend + UI** (Node) | `node packages/backend/dist/server.js` | npm: `npx @wdio/devtools-backend@<pinned>` |
+| **Wire contract** (`shared`) | regenerated into `_contract.py` | the generated `_contract.py` ships in the wheel |
+
+`enable()` obtains the backend in this order (local vs published falls out of it):
+
+1. `DEVTOOLS_PORT` set → attach to an already-running backend (CI, manual).
+2. `DEVTOOLS_BACKEND_CMD` set → spawn that explicit command.
+3. monorepo `packages/backend/dist/server.js` present → spawn it (**local dev**).
+4. else → `npx @wdio/devtools-backend@<BACKEND_NPM_VERSION>` (**published**).
+
+The pinned `BACKEND_NPM_VERSION` in `backend.py` is the version link — there is
+no auto-resolution, so it's bumped deliberately alongside a contract change.
+
+Regenerate the contract after any change to `packages/shared`:
+
+```bash
+python3 packages/selenium-devtools-py/scripts/gen_contract.py
+```
+
+It fails loudly if a scope the adapter needs disappeared from `shared` — a
+build-time drift alarm.
+
+## Test
+
+```bash
+# unit (no deps):
+PYTHONPATH=src python3 -m unittest discover -s tests -v
+
+# e2e (needs selenium + a running backend; Selenium Manager fetches the driver):
+DEVTOOLS_PORT=3000 PYTHONPATH=src python3 e2e_check.py
+DEVTOOLS_PORT=3000 PYTHONPATH=src pytest e2e/test_smoke.py -p selenium_devtools.pytest_plugin -q
+```
+
+## Release (approach A)
+
+Two workflows, mirroring the JS split (`ci.yml` tests / `release.yml` publish):
+
+- **`python.yml`** — runs on PRs + pushes touching this package or `shared`:
+  unit tests on Python 3.9 + 3.12, and a contract-drift check (regenerate
+  `_contract.py`, fail on any diff). Zero repo config needed.
+- **`python-release.yml`** — **manual** (`workflow_dispatch`, like the JS
+  "Manual NPM Publish"), target `pypi` or `testpypi`. Builds the sdist + wheel
+  and publishes via **trusted publishing (OIDC)** — no token/secret.
+
+The wheel does **not** bundle the backend — approach A fetches a pinned
+`@wdio/devtools-backend` via `npx` at runtime (Node 18+ required). Bundling it
+(approach B/C) is a GA-time change.
+
+**One-time setup before the first publish** (this is what claims the PyPI name):
+
+1. On PyPI, add a **pending trusted publisher** for project
+   `selenium-devtools-py` → owner `webdriverio`, repo `devtools`, workflow
+   `python-release.yml`, environment `pypi` (repeat on TestPyPI with env
+   `testpypi` if you want a dry run first).
+2. Create matching GitHub **Environments** `pypi` (and `testpypi`).
+3. Run the workflow — the first successful publish creates and claims the name.
+
+Each release: bump `version` in `pyproject.toml`, then run the workflow (PyPI
+rejects re-uploading an existing version).
+
+## Roadmap
+
+- **Phase 2 (done)** — BiDi console/network + screenshot-polling screencast.
+  Not yet: a CDP `Page.startScreencast` push-mode fast-path, per-command
+  screenshots, and performance capture.
+- **Phase 3** — trace export, preserve-and-rerun, action snapshots. Per the
+  architecture, the heavy post-processing is a candidate to live server-side in
+  the backend (written once) rather than re-implemented here.
+
+## Design notes
+
+- **Backend/UI unchanged.** This adapter only produces the wire frames; the
+  server routes and renders them exactly as for the JS adapters.
+- **Capture never breaks tests.** Commands are recorded around the real call;
+  errors are captured *and re-raised* unchanged; a missing dashboard is a no-op.
+- **Contract drift** is the main long-term risk (see the integration artifact).
+  Mitigated two ways: `_contract.py` is generated from `packages/shared` (scope
+  names + `CONTRACT_VERSION`), and the generator fails if a required scope
+  vanishes. Full field-level type generation is a future step.
diff --git a/packages/selenium-devtools-py/e2e/test_smoke.py b/packages/selenium-devtools-py/e2e/test_smoke.py
new file mode 100644
index 00000000..4b4d647d
--- /dev/null
+++ b/packages/selenium-devtools-py/e2e/test_smoke.py
@@ -0,0 +1,35 @@
+"""pytest smoke that exercises the plugin (suites) + instrumentation (commands).
+
+Run against a running backend:
+    DEVTOOLS_PORT=63763 PYTHONPATH=src \
+      pytest e2e/test_smoke.py -p selenium_devtools.pytest_plugin -q
+
+Uses a data: URL so it needs no network.
+"""
+
+import pytest
+from selenium import webdriver
+from selenium.webdriver.chrome.options import Options
+from selenium.webdriver.common.by import By
+
+PAGE = "data:text/html,<h1>Hello DevTools</h1><a href='%23x'>link</a>"
+
+
+@pytest.fixture
+def driver():
+    opts = Options()
+    opts.add_argument("--headless=new")
+    opts.add_argument("--no-sandbox")
+    drv = webdriver.Chrome(options=opts)
+    yield drv
+    drv.quit()
+
+
+def test_homepage_loads(driver):
+    driver.get(PAGE)
+    assert "Hello DevTools" in driver.find_element(By.CSS_SELECTOR, "h1").text
+
+
+def test_link_is_clickable(driver):
+    driver.get(PAGE)
+    driver.find_element(By.CSS_SELECTOR, "a").click()
diff --git a/packages/selenium-devtools-py/e2e_check.py b/packages/selenium-devtools-py/e2e_check.py
new file mode 100644
index 00000000..7e64c2db
--- /dev/null
+++ b/packages/selenium-devtools-py/e2e_check.py
@@ -0,0 +1,47 @@
+#!/usr/bin/env python3
+"""End-to-end smoke: real headless Chrome → adapter → backend.
+
+Run against a running backend (set DEVTOOLS_PORT if not 3000):
+    DEVTOOLS_PORT=63763 PYTHONPATH=src python3 e2e_check.py
+
+Uses a data: URL so it needs no network.
+"""
+
+import sys
+import time
+
+import selenium_devtools as devtools
+
+PAGE = "data:text/html,<h1>Hello DevTools</h1><a href='%23x'>link</a>"
+
+
+def main() -> int:
+    capturer = devtools.enable()
+    if capturer is None:
+        print("backend not reachable — start it first")
+        return 1
+
+    from selenium import webdriver
+    from selenium.webdriver.chrome.options import Options
+    from selenium.webdriver.common.by import By
+
+    opts = Options()
+    opts.add_argument("--headless=new")
+    opts.add_argument("--no-sandbox")
+    driver = webdriver.Chrome(options=opts)
+    try:
+        driver.get(PAGE)
+        heading = driver.find_element(By.CSS_SELECTOR, "h1")
+        print("h1 text:", heading.text)
+        driver.find_element(By.CSS_SELECTOR, "a").click()
+        print("title:", driver.execute_script("return document.title"))
+    finally:
+        driver.quit()
+        time.sleep(1)  # let frames flush
+        devtools.disable()
+    print("done")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())
diff --git a/packages/selenium-devtools-py/pyproject.toml b/packages/selenium-devtools-py/pyproject.toml
new file mode 100644
index 00000000..8b78481b
--- /dev/null
+++ b/packages/selenium-devtools-py/pyproject.toml
@@ -0,0 +1,28 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "selenium-devtools-py"
+version = "0.1.0"
+description = "Python Selenium adapter for the WebdriverIO DevTools dashboard"
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+authors = [{ name = "WebdriverIO" }]
+keywords = ["selenium", "webdriver", "devtools", "pytest", "debugging"]
+
+# Transport is dependency-free (stdlib). selenium is the user's own dep; we
+# only patch it when present, so it's not a hard requirement to import.
+dependencies = []
+
+[project.optional-dependencies]
+selenium = ["selenium>=4.6"]
+test = ["pytest>=7", "selenium>=4.6"]
+
+# Auto-discovered by pytest; inert unless DEVTOOLS_ENABLE / DEVTOOLS_PORT is set.
+[project.entry-points.pytest11]
+selenium_devtools = "selenium_devtools.pytest_plugin"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/selenium_devtools"]
diff --git a/packages/selenium-devtools-py/scripts/gen_contract.py b/packages/selenium-devtools-py/scripts/gen_contract.py
new file mode 100644
index 00000000..925eb089
--- /dev/null
+++ b/packages/selenium-devtools-py/scripts/gen_contract.py
@@ -0,0 +1,98 @@
+#!/usr/bin/env python3
+"""Generate ``_contract.py`` from ``packages/shared`` — the Python side of the
+wire contract, derived from the single TS source of truth.
+
+Runs only in the monorepo (dev time); the generated file is committed and ships
+inside the wheel, so published installs need neither this script nor `shared`.
+
+It doubles as a drift-guard: if a scope the adapter relies on disappears from
+shared's ``TraceLog`` / ``WS_SCOPE``, generation fails loudly rather than
+letting the Python side silently send a name the UI no longer understands.
+
+Run:  python3 scripts/gen_contract.py
+"""
+
+from __future__ import annotations
+
+import json
+import re
+import sys
+from pathlib import Path
+
+# Data scopes the Python adapter emits — each must exist as a TraceLog key.
+REQUIRED_DATA_SCOPES = {
+    "SCOPE_METADATA": "metadata",
+    "SCOPE_COMMANDS": "commands",
+    "SCOPE_CONSOLE_LOGS": "consoleLogs",
+    "SCOPE_NETWORK_REQUESTS": "networkRequests",
+    "SCOPE_SUITES": "suites",
+    "SCOPE_SCREENCAST": "screencast",
+    "SCOPE_SOURCES": "sources",
+    "SCOPE_MUTATIONS": "mutations",
+}
+
+
+def _repo_root() -> Path:
+    for parent in Path(__file__).resolve().parents:
+        if (parent / "packages" / "shared" / "package.json").exists():
+            return parent
+    raise SystemExit("could not locate the monorepo root (packages/shared)")
+
+
+def _shared_version(shared: Path) -> str:
+    pkg = json.loads((shared / "package.json").read_text())
+    return pkg["version"]
+
+
+def _trace_log_keys(types_ts: str) -> list[str]:
+    m = re.search(r"export interface TraceLog \{(.*?)\n\}", types_ts, re.DOTALL)
+    if not m:
+        raise SystemExit("could not find `interface TraceLog` in shared/types.ts")
+    return re.findall(r"^\s*(\w+)\??:", m.group(1), re.MULTILINE)
+
+
+def _ws_scopes(routes_ts: str) -> dict[str, str]:
+    m = re.search(r"export const WS_SCOPE = \{(.*?)\n\} as const", routes_ts, re.DOTALL)
+    if not m:
+        raise SystemExit("could not find `WS_SCOPE` in shared/routes.ts")
+    return dict(re.findall(r"(\w+):\s*'([^']+)'", m.group(1)))
+
+
+def main() -> int:
+    root = _repo_root()
+    shared = root / "packages" / "shared"
+    version = _shared_version(shared)
+    data_keys = _trace_log_keys((shared / "src" / "types.ts").read_text())
+    control = _ws_scopes((shared / "src" / "routes.ts").read_text())
+
+    # Drift-guard.
+    missing = [v for v in REQUIRED_DATA_SCOPES.values() if v not in data_keys]
+    if missing:
+        raise SystemExit(
+            f"contract drift: scope(s) {missing} no longer in shared TraceLog "
+            f"(present: {data_keys}). Update the adapter or shared."
+        )
+
+    lines = [
+        "# GENERATED by scripts/gen_contract.py from packages/shared.",
+        "# Do not edit by hand — run the script to regenerate.",
+        f'CONTRACT_VERSION = "{version}"',
+        "",
+    ]
+    for const, value in REQUIRED_DATA_SCOPES.items():
+        lines.append(f'{const} = "{value}"')
+    lines += [
+        "",
+        f"DATA_SCOPES = frozenset({sorted(data_keys)!r})",
+        f"CONTROL_SCOPES = frozenset({sorted(control.values())!r})",
+        "",
+    ]
+    out = shared.parent / "selenium-devtools-py" / "src" / "selenium_devtools" / "_contract.py"
+    out.write_text("\n".join(lines))
+    print(f"wrote {out.relative_to(root)}  (contract v{version}, "
+          f"{len(data_keys)} data scopes, {len(control)} control scopes)")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())
diff --git a/packages/selenium-devtools-py/src/selenium_devtools/__init__.py b/packages/selenium-devtools-py/src/selenium_devtools/__init__.py
new file mode 100644
index 00000000..4a7632d4
--- /dev/null
+++ b/packages/selenium-devtools-py/src/selenium_devtools/__init__.py
@@ -0,0 +1,148 @@
+"""selenium-devtools-py — Python Selenium adapter for the DevTools dashboard.
+
+Public API:
+
+    import selenium_devtools as devtools
+    devtools.enable()          # connect + instrument; reads DEVTOOLS_HOST/PORT
+    ...  run selenium ...
+    devtools.disable()
+
+Under pytest, the bundled plugin calls these for you (gated on the
+``DEVTOOLS_ENABLE`` / ``DEVTOOLS_PORT`` env vars). The transport has no
+third-party dependency; the only requirement on top is selenium itself.
+"""
+
+from __future__ import annotations
+
+import os
+import subprocess
+import sys
+from typing import Optional
+
+from . import backend, instrumentation, lifecycle
+from ._contract import CONTRACT_VERSION
+from .capturer import SessionCapturer
+from .constants import DEFAULT_HOST, DEFAULT_PORT, ENV_HOST, ENV_PORT
+from .logcapture import LogCapturer
+from .terminal import TerminalCapturer
+from .transport import WSClient
+
+__version__ = "0.1.0"
+__all__ = [
+    "enable", "disable", "get_capturer", "dashboard_url",
+    "wait_for_dashboard_close", "CONTRACT_VERSION",
+]
+
+_active: dict = {
+    "capturer": None, "transport": None, "process": None, "url": None,
+    "handle": None, "terminal": None, "logs": None,
+}
+
+
+def enable(
+    host: Optional[str] = None,
+    port: Optional[int] = None,
+    *,
+    webdriver_cls: Optional[type] = None,
+) -> Optional[SessionCapturer]:
+    """Connect to the backend and instrument Selenium. Idempotent.
+
+    With no host/port and no ``DEVTOOLS_PORT``, the backend is launched
+    automatically (see :mod:`.backend`). Returns the SessionCapturer, or None if
+    the dashboard can't be reached/launched — a missing dashboard must never
+    break the user's test run.
+    """
+    if _active["capturer"] is not None:
+        return _active["capturer"]
+
+    process = None
+    try:
+        if host is not None or port is not None:
+            host = host or os.environ.get(ENV_HOST, DEFAULT_HOST)
+            port = int(port or os.environ.get(ENV_PORT, DEFAULT_PORT))
+        else:
+            host, port, process = backend.launch_or_attach()
+    except (OSError, RuntimeError, TimeoutError) as exc:
+        print(f"[devtools] could not start dashboard ({exc}); "
+              f"continuing without capture", file=sys.stderr)
+        return None
+
+    transport = WSClient(host, port, on_control=lifecycle.on_control)
+    try:
+        transport.connect()
+    except OSError as exc:
+        print(
+            f"[devtools] dashboard not reachable at {host}:{port} "
+            f"({exc}); continuing without capture",
+            file=sys.stderr,
+        )
+        if process is not None:
+            process.terminate()
+        return None
+
+    capturer = SessionCapturer(transport)
+    instrumentation.install(capturer, webdriver_cls)
+    # Surface the runner's output in the dashboard Console: Python logging
+    # (selenium + the adapter's own events) and the test's stdout.
+    logs = LogCapturer(capturer)
+    logs.start()
+    term = TerminalCapturer(capturer)
+    term.start()
+    url = f"http://{host}:{port}"
+    _active.update(
+        capturer=capturer, transport=transport, process=process, url=url,
+        terminal=term, logs=logs,
+    )
+
+    # Open the dashboard window and wire exit/signal + control-frame teardown so
+    # closing the window (clientDisconnected) or ending the process both tidy up.
+    handle = lifecycle.open_dashboard(url) if lifecycle.auto_open_enabled() else None
+    _active["handle"] = handle
+    lifecycle.register_exit_handlers(disable, handle)
+    return capturer
+
+
+def disable() -> None:
+    # Close the dashboard window + unregister exit/signal handlers first, so a
+    # re-enable() starts clean. Idempotent and defensive — never raises.
+    lifecycle.unregister_exit_handlers()
+    instrumentation.uninstall()
+    term = _active["terminal"]
+    if term is not None:  # restore stdout/stderr before tearing the transport down
+        term.stop()
+    logs = _active["logs"]
+    if logs is not None:  # detach the logging handler + restore logger levels
+        logs.stop()
+    transport = _active["transport"]
+    if transport is not None:
+        transport.close()
+    process = _active["process"]
+    if process is not None:  # only set when we launched it ourselves
+        process.terminate()
+        try:
+            process.wait(timeout=5)
+        except subprocess.TimeoutExpired:
+            process.kill()  # backend ignored SIGTERM — force it
+    _active.update(
+        capturer=None, transport=None, process=None, url=None, handle=None,
+        terminal=None, logs=None,
+    )
+
+
+def get_capturer() -> Optional[SessionCapturer]:
+    return _active["capturer"]
+
+
+def dashboard_url() -> Optional[str]:
+    """URL of the connected dashboard, or None if capture isn't active."""
+    return _active["url"]
+
+
+def wait_for_dashboard_close() -> None:
+    """Block until the user closes the dashboard window, so you can inspect the
+    run after your test finishes. Returns immediately if no dashboard window is
+    open (headless/CI) — safe to always call before ``disable()``."""
+    if lifecycle.dashboard_window_open():
+        print(f"[devtools] dashboard live at {dashboard_url()} — "
+              "close the window to finish.", file=sys.stderr)
+        lifecycle.wait_for_shutdown()
diff --git a/packages/selenium-devtools-py/src/selenium_devtools/_contract.py b/packages/selenium-devtools-py/src/selenium_devtools/_contract.py
new file mode 100644
index 00000000..973c8fb9
--- /dev/null
+++ b/packages/selenium-devtools-py/src/selenium_devtools/_contract.py
@@ -0,0 +1,15 @@
+# GENERATED by scripts/gen_contract.py from packages/shared.
+# Do not edit by hand — run the script to regenerate.
+CONTRACT_VERSION = "1.0.0"
+
+SCOPE_METADATA = "metadata"
+SCOPE_COMMANDS = "commands"
+SCOPE_CONSOLE_LOGS = "consoleLogs"
+SCOPE_NETWORK_REQUESTS = "networkRequests"
+SCOPE_SUITES = "suites"
+SCOPE_SCREENCAST = "screencast"
+SCOPE_SOURCES = "sources"
+SCOPE_MUTATIONS = "mutations"
+
+DATA_SCOPES = frozenset(['actionSnapshots', 'commands', 'config', 'consoleLogs', 'logs', 'metadata', 'mutations', 'networkRequests', 'screencast', 'screencastFrames', 'sources', 'suites'])
+CONTROL_SCOPES = frozenset(['clearCommands', 'clearExecutionData', 'clientConnected', 'clientDisconnected', 'config', 'replaceCommand', 'testStopped'])
diff --git a/packages/selenium-devtools-py/src/selenium_devtools/backend.py b/packages/selenium-devtools-py/src/selenium_devtools/backend.py
new file mode 100644
index 00000000..9f1bfe17
--- /dev/null
+++ b/packages/selenium-devtools-py/src/selenium_devtools/backend.py
@@ -0,0 +1,122 @@
+"""Locate or launch the dashboard backend.
+
+Python can't declare a dependency on the Node ``@wdio/devtools-backend`` the way
+the JS adapters do (no cross-ecosystem resolution). So the backend is obtained
+at runtime, and the resolution order encodes the local-vs-published split:
+
+    1. DEVTOOLS_PORT set        → attach to an already-running backend (CI, manual)
+    2. DEVTOOLS_BACKEND_CMD set → spawn that explicit command
+    3. monorepo dist present    → node packages/backend/dist/server.js     (LOCAL dev)
+    4. else                     → npx @wdio/devtools-backend@<pinned>       (PUBLISHED)
+
+The pinned version below is bumped deliberately alongside a contract change —
+there is no auto-resolution, so this constant *is* the version link.
+"""
+
+from __future__ import annotations
+
+import os
+import re
+import shlex
+import shutil
+import subprocess
+import threading
+import time
+from pathlib import Path
+from typing import List, Optional, Tuple
+
+from .constants import (
+    BACKEND_NPM_PACKAGE,
+    BACKEND_NPM_VERSION,
+    BACKEND_SPAWN_TIMEOUT_S,
+    DEFAULT_HOST,
+    ENV_BACKEND_CMD,
+    ENV_HOST,
+    ENV_PORT,
+)
+
+# Match the ACTUAL bound port from Fastify's "Server listening at http://…:PORT"
+# line — NOT the earlier "Starting … on port 3000" line, which is only the
+# *preferred* port. When 3000 is busy the backend negotiates a different port,
+# so keying off the preferred port connects to the wrong (or a dead) socket.
+# Greedy `.*` so the IPv6 form (http://[::1]:PORT) resolves to the final :PORT.
+_PORT_RE = re.compile(r"listening at .*:(\d+)")
+
+
+def _find_monorepo_backend(start: Optional[Path] = None) -> Optional[Path]:
+    """Walk up from ``start`` (default: this module) for a built backend. Present
+    only in a monorepo checkout; None from an installed wheel.
+
+    Targets ``server.js``, the backend's CLI entry, NOT ``index.js``: that one is
+    the library entry the JS adapters import, and running it starts nothing."""
+    base = start or Path(__file__).resolve()
+    for parent in base.parents:
+        candidate = parent / "packages" / "backend" / "dist" / "server.js"
+        if candidate.exists():
+            return candidate
+    return None
+
+
+def _drain(proc: subprocess.Popen) -> None:
+    """Keep reading the backend's stdout so its pipe never fills and blocks it."""
+
+    def pump() -> None:
+        assert proc.stdout is not None
+        for _ in proc.stdout:
+            pass
+
+    threading.Thread(target=pump, daemon=True).start()
+
+
+def _spawn_and_wait_for_port(
+    cmd: List[str], timeout: float = BACKEND_SPAWN_TIMEOUT_S
+) -> Tuple[subprocess.Popen, int]:
+    proc = subprocess.Popen(
+        cmd, stdout=subprocess.PIPE, stderr=subprocess.STDOUT, text=True, bufsize=1
+    )
+    assert proc.stdout is not None
+    deadline = time.time() + timeout
+    while time.time() < deadline:
+        line = proc.stdout.readline()
+        if not line:
+            if proc.poll() is not None:
+                raise RuntimeError(
+                    f"backend exited (code {proc.returncode}) before reporting a port"
+                )
+            continue
+        match = _PORT_RE.search(line)
+        if match:
+            _drain(proc)
+            return proc, int(match.group(1))
+    proc.terminate()
+    raise TimeoutError("backend did not report a port within the timeout")
+
+
+def launch_or_attach() -> Tuple[str, int, Optional[subprocess.Popen]]:
+    """Return ``(host, port, process)``. ``process`` is None when we attached to
+    a backend we don't own (caller must not terminate it)."""
+    host = os.environ.get(ENV_HOST, DEFAULT_HOST)
+
+    if os.environ.get(ENV_PORT):
+        return host, int(os.environ[ENV_PORT]), None
+
+    explicit = os.environ.get(ENV_BACKEND_CMD)
+    if explicit:
+        proc, port = _spawn_and_wait_for_port(shlex.split(explicit))
+        return host, port, proc
+
+    local = _find_monorepo_backend()
+    if local is not None:
+        proc, port = _spawn_and_wait_for_port(["node", str(local)])
+        return host, port, proc
+
+    npx = shutil.which("npx")
+    if npx is None:
+        raise RuntimeError(
+            "Node.js not found — install Node 18+ (the dashboard backend is a Node "
+            "app), or set DEVTOOLS_PORT to an already-running dashboard."
+        )
+    proc, port = _spawn_and_wait_for_port(
+        [npx, "-y", f"{BACKEND_NPM_PACKAGE}@{BACKEND_NPM_VERSION}"]
+    )
+    return host, port, proc
diff --git a/packages/selenium-devtools-py/src/selenium_devtools/bidi.py b/packages/selenium-devtools-py/src/selenium_devtools/bidi.py
new file mode 100644
index 00000000..9c311529
--- /dev/null
+++ b/packages/selenium-devtools-py/src/selenium_devtools/bidi.py
@@ -0,0 +1,412 @@
+"""Selenium BiDi capture — browser console, JS exceptions, and network.
+
+Mirrors the JS ``core/bidi.ts`` + ``selenium-devtools/bidi.ts`` split: the pure
+event→frame mapping helpers (``console_kwargs`` / ``request_sent_kwargs`` /
+``response_completed_kwargs``) take plain dicts/objects and are unit-testable
+without selenium; ``attach`` does the selenium wiring and is defensive — a BiDi
+failure is a logged no-op, never a raised error into the user's test.
+
+Two selenium-version realities shape this module (selenium 4.36):
+
+* BiDi only opens when the session was created with ``webSocketUrl`` truthy
+  (``options.web_socket_url = True`` at build). We can't set that from inside
+  the ``execute`` wrapper — the session already exists — so attach() checks the
+  capability and degrades if it's missing.
+* selenium's high-level ``network.add_request_handler`` *intercepts* (pauses)
+  requests. We deliberately avoid it: we subscribe to the network events via
+  the low-level connection so requests are observed but never stalled.
+"""
+
+from __future__ import annotations
+
+import sys
+from typing import Any, Dict, List, Optional, Tuple
+
+from .capturer import SessionCapturer
+from .constants import (
+    BIDI_CAPABILITY,
+    BIDI_LEVEL_MAP,
+    BIDI_NET_BEFORE_REQUEST,
+    BIDI_NET_RESPONSE_COMPLETED,
+)
+from .utils import now_ms
+
+
+def _warn(message: str) -> None:
+    print(f"[devtools] BiDi: {message}", file=sys.stderr)
+
+
+# ── pure mapping helpers (no selenium) ───────────────────────────────────────
+
+
+def normalize_level(level: Any) -> str:
+    """Map a BiDi log level onto the shared LogLevel union (fallback: log)."""
+    return BIDI_LEVEL_MAP.get(str(level or "").lower(), "log")
+
+
+def remote_value_to_py(value: Any) -> Any:
+    """Deserialize one BiDi RemoteValue into a JSON-friendly Python value.
+
+    The reverse of selenium's ``Script.__convert_to_local_value``: console args
+    arrive as ``{"type": ..., "value": ...}`` RemoteValues, not raw values, so
+    ``console.log('a', {b:1}, 42)`` yields dicts we unwrap into ``'a'``,
+    ``{'b': 1}``, ``42``. Anything unrecognized degrades to its string form.
+    """
+    if not isinstance(value, dict) or "type" not in value:
+        return value
+    kind = value.get("type")
+    inner = value.get("value")
+    if kind in ("null", "undefined"):
+        return None
+    if kind in ("string", "boolean", "number"):
+        # BiDi encodes NaN/Infinity/-0 as the strings "NaN"/"Infinity"/"-0" —
+        # passed through as-is since JSON can't represent the float specials.
+        return inner
+    if kind == "bigint":
+        try:
+            return int(inner)
+        except (TypeError, ValueError):
+            return str(inner)
+    if kind in ("array", "set") and isinstance(inner, list):
+        return [remote_value_to_py(item) for item in inner]
+    if kind in ("object", "map") and isinstance(inner, list):
+        out: Dict[str, Any] = {}
+        for pair in inner:
+            if isinstance(pair, (list, tuple)) and len(pair) == 2:
+                key = remote_value_to_py(pair[0])
+                out[str(key)] = remote_value_to_py(pair[1])
+        return out
+    if kind in ("date", "regexp"):
+        return inner
+    # error/function/node/window/symbol/promise/… — no serializable value.
+    return value.get("value", kind)
+
+
+def _args_from_entry(entry: Any) -> Optional[List[Any]]:
+    """Deserialized console args if the entry carries any, else None.
+
+    Returns None (not []) when ``args`` is absent so the caller can fall back to
+    ``.text`` — an empty list is a real console call with no arguments.
+    """
+    raw = _attr(entry, "args", None)
+    if not isinstance(raw, list):
+        return None
+    return [remote_value_to_py(v) for v in raw]
+
+
+def console_kwargs(entry: Any) -> Tuple[str, List[Any]]:
+    """(level, args) for capturer.capture_console from a BiDi console entry.
+
+    Accepts selenium's ConsoleLogEntry dataclass (``.level`` / ``.method`` /
+    ``.args`` / ``.text``) or a plain dict — so tests pass dicts, no selenium
+    needed. Prefers ``method`` (the actual console.X call — log/info/warn/error/
+    debug) over ``level`` (coarser), and maps every RemoteValue arg, falling
+    back to ``.text`` only when no ``args`` are present.
+    """
+    level = _attr(entry, "method", None) or _attr(entry, "level", "info")
+    args = _args_from_entry(entry)
+    if args is None:
+        text = _attr(entry, "text", None)
+        if text is None:
+            text = _attr(entry, "message", "")
+        args = [text]
+    return normalize_level(level), args
+
+
+def js_error_kwargs(entry: Any) -> Tuple[str, List[Any]]:
+    """(level, args) for a BiDi JavaScript exception — always ``error`` level.
+
+    JavaScriptLogEntry carries ``text`` (the message) and a ``stacktrace`` dict
+    rather than ``args``. We render message + formatted stack as a single arg so
+    the Console panel shows the full error, never an empty/duplicate entry.
+    """
+    text = _attr(entry, "text", None)
+    if text is None:
+        text = _attr(entry, "message", "")
+    message = str(text or "")
+    stack = _format_stacktrace(_attr(entry, "stacktrace", None))
+    combined = f"{message}\n{stack}" if stack else message
+    return "error", [combined]
+
+
+def _format_stacktrace(stacktrace: Any) -> str:
+    """Render a BiDi ``StackTrace`` ({callFrames:[{functionName,url,lineNumber,
+    columnNumber}]}) into ``at fn (url:line:col)`` lines — empty string if none."""
+    if not isinstance(stacktrace, dict):
+        return ""
+    frames = stacktrace.get("callFrames")
+    if not isinstance(frames, list):
+        return ""
+    lines: List[str] = []
+    for frame in frames:
+        if not isinstance(frame, dict):
+            continue
+        fn = frame.get("functionName") or "<anonymous>"
+        url = frame.get("url") or ""
+        line = frame.get("lineNumber")
+        col = frame.get("columnNumber")
+        location = url
+        if line is not None:
+            location = f"{url}:{line}"
+            if col is not None:
+                location = f"{url}:{line}:{col}"
+        lines.append(f"    at {fn} ({location})" if location else f"    at {fn}")
+    return "\n".join(lines)
+
+
+def request_sent_kwargs(params: Dict[str, Any]) -> Optional[Dict[str, Any]]:
+    """kwargs for the initial (pending) network frame, or None if unidentifiable.
+
+    ``params`` is the BiDi ``network.beforeRequestSent`` event params — the
+    ``.params`` dict on selenium's NetworkEvent.
+    """
+    request = params.get("request") or {}
+    request_id = str(request.get("request") or params.get("id") or "")
+    if not request_id:
+        return None
+    start_time = int(params.get("timestamp") or now_ms())
+    return {
+        "request_id": request_id,
+        "url": request.get("url") or "",
+        "method": request.get("method") or "GET",
+        "status": None,
+        "timestamp": now_ms(),
+        "start_time": start_time,
+        "request_type": request_type_for(request.get("url") or ""),
+        "request_headers": headers_to_object(request.get("headers")),
+    }
+
+
+def response_completed_kwargs(
+    params: Dict[str, Any], pending: Dict[str, Dict[str, Any]]
+) -> Optional[Dict[str, Any]]:
+    """kwargs for the finalized network frame, merged over the pending request.
+
+    Returns None when the matching request wasn't seen (out-of-order events) —
+    the caller skips rather than inventing a half-populated entry.
+    """
+    request = params.get("request") or {}
+    request_id = str(request.get("request") or params.get("id") or "")
+    prev = pending.get(request_id)
+    if prev is None:
+        return None
+    response = params.get("response") or {}
+    start_time = int(prev.get("start_time") or now_ms())
+    end_time, time = _response_timing(
+        request.get("timings"), start_time, params.get("timestamp")
+    )
+    merged = dict(prev)
+    merged.update(
+        status=_int_or(response.get("status"), prev.get("status")),
+        status_text=response.get("statusText"),
+        timestamp=now_ms(),
+        end_time=end_time,
+        time=time,
+        size=_int_or(response.get("bytesReceived"), None),
+        request_type=request_type_for(
+            prev.get("url") or "", response.get("mimeType")
+        ),
+        response_headers=headers_to_object(response.get("headers")),
+    )
+    return merged
+
+
+def request_type_for(url: str, mime_type: Optional[str] = None) -> str:
+    """Classify a request into the dashboard's Network-tab categories.
+
+    Prefers the response mime type; falls back to URL-extension heuristics.
+    Ported from core/net.ts getRequestType so the wire shape matches the JS
+    adapters exactly.
+    """
+    ct = (mime_type or "").lower()
+    u = url.lower()
+    if "text/html" in ct:
+        return "document"
+    if "text/css" in ct:
+        return "stylesheet"
+    if "javascript" in ct or "ecmascript" in ct:
+        return "script"
+    if "image/" in ct:
+        return "image"
+    if "font/" in ct or "woff" in ct:
+        return "font"
+    if "application/json" in ct:
+        return "fetch"
+    if u.endswith(".html") or u.endswith(".htm"):
+        return "document"
+    if u.endswith(".css"):
+        return "stylesheet"
+    if u.endswith(".js") or u.endswith(".mjs"):
+        return "script"
+    if any(u.endswith(ext) for ext in (".png", ".jpg", ".jpeg", ".gif", ".svg",
+                                       ".webp", ".ico")):
+        return "image"
+    if any(u.endswith(ext) for ext in (".woff", ".woff2", ".ttf", ".eot",
+                                       ".otf")):
+        return "font"
+    return "xhr"
+
+
+def headers_to_object(headers: Any) -> Optional[Dict[str, str]]:
+    """Flatten BiDi's ``[{name, value:{value}}]`` header list to a lowercased
+    ``{name: value}`` dict. Returns None for a non-list (absent) input."""
+    if not isinstance(headers, list):
+        return None
+    out: Dict[str, str] = {}
+    for h in headers:
+        if not isinstance(h, dict):
+            continue
+        name = str(h.get("name") or "").lower()
+        if not name:
+            continue
+        value = h.get("value")
+        if isinstance(value, str):
+            out[name] = value
+        elif isinstance(value, dict) and isinstance(value.get("value"), str):
+            out[name] = value["value"]
+        else:
+            out[name] = str(value)
+    return out
+
+
+def _attr(obj: Any, name: str, default: Any) -> Any:
+    if isinstance(obj, dict):
+        return obj.get(name, default)
+    return getattr(obj, name, default)
+
+
+def _int_or(value: Any, fallback: Any) -> Any:
+    try:
+        return int(value)
+    except (TypeError, ValueError):
+        return fallback
+
+
+def _response_timing(
+    timings: Any, start_time: int, timestamp: Any
+) -> Tuple[int, int]:
+    """(end_time, duration_ms) preferring the browser's FetchTimingInfo — it's
+    immune to BiDi events arriving batched in one tick (which collapses the
+    event timestamps and yields 0-duration requests). Falls back to the event
+    timestamp delta when timings are unavailable."""
+    if isinstance(timings, dict):
+        req = timings.get("requestTime")
+        end = timings.get("responseEnd")
+        if isinstance(req, (int, float)) and isinstance(end, (int, float)) and end > req:
+            time = round(end - req)
+            return start_time + time, time
+    end_time = _int_or(timestamp, None)
+    if end_time is None:
+        end_time = now_ms()
+    return end_time, max(0, end_time - start_time)
+
+
+# ── selenium wiring (defensive) ───────────────────────────────────────────────
+
+
+def _bidi_enabled(driver: Any) -> bool:
+    caps = getattr(driver, "caps", None)
+    return bool(isinstance(caps, dict) and caps.get(BIDI_CAPABILITY))
+
+
+def _attach_console(driver: Any, capturer: SessionCapturer) -> bool:
+    try:
+        script = driver.script
+    except Exception as exc:  # noqa: BLE001 — any selenium/BiDi failure is a no-op
+        _warn(f"script channel unavailable: {exc}")
+        return False
+
+    def on_console_entry(entry: Any) -> None:
+        try:
+            level, args = console_kwargs(entry)
+            capturer.capture_console(level, args, source="browser")
+        except Exception as exc:  # noqa: BLE001
+            _warn(f"console handler threw: {exc}")
+
+    def on_js_error(entry: Any) -> None:
+        try:
+            level, args = js_error_kwargs(entry)
+            capturer.capture_console(level, args, source="browser")
+        except Exception as exc:  # noqa: BLE001
+            _warn(f"JS error handler threw: {exc}")
+
+    try:
+        script.add_console_message_handler(on_console_entry)
+        script.add_javascript_error_handler(on_js_error)
+        return True
+    except Exception as exc:  # noqa: BLE001
+        _warn(f"console/JS handlers failed to attach: {exc}")
+        return False
+
+
+def _attach_network(driver: Any, capturer: SessionCapturer) -> bool:
+    """Subscribe to network events WITHOUT interception (see module docstring).
+
+    Uses the low-level connection so requests are only observed. Returns False
+    (and logs) on any failure — network BiDi is best-effort.
+    """
+    try:
+        conn = driver.network.conn
+        from selenium.webdriver.common.bidi.network import NetworkEvent  # lazy
+        from selenium.webdriver.common.bidi.session import Session  # lazy
+    except Exception as exc:  # noqa: BLE001
+        _warn(f"network channel unavailable: {exc}")
+        return False
+
+    pending: Dict[str, Dict[str, Any]] = {}
+
+    def on_request_sent(event: Any) -> None:
+        try:
+            kwargs = request_sent_kwargs(getattr(event, "params", {}) or {})
+            if kwargs is not None:
+                pending[kwargs["request_id"]] = kwargs
+                capturer.capture_network(**kwargs)
+        except Exception as exc:  # noqa: BLE001
+            _warn(f"beforeRequestSent handler threw: {exc}")
+
+    def on_response_completed(event: Any) -> None:
+        try:
+            kwargs = response_completed_kwargs(
+                getattr(event, "params", {}) or {}, pending
+            )
+            if kwargs is not None:
+                pending.pop(kwargs["request_id"], None)
+                capturer.capture_network(**kwargs)
+        except Exception as exc:  # noqa: BLE001
+            _warn(f"responseCompleted handler threw: {exc}")
+
+    try:
+        conn.execute(
+            Session(conn).subscribe(
+                BIDI_NET_BEFORE_REQUEST, BIDI_NET_RESPONSE_COMPLETED
+            )
+        )
+        conn.add_callback(NetworkEvent(BIDI_NET_BEFORE_REQUEST), on_request_sent)
+        conn.add_callback(
+            NetworkEvent(BIDI_NET_RESPONSE_COMPLETED), on_response_completed
+        )
+        return True
+    except Exception as exc:  # noqa: BLE001
+        _warn(f"network subscribe failed: {exc}")
+        return False
+
+
+def attach(driver: Any, capturer: SessionCapturer) -> bool:
+    """Wire BiDi console + network capture onto ``driver``.
+
+    Returns True if at least one channel attached. A driver without the
+    ``webSocketUrl`` capability (BiDi not enabled at build time) is skipped with
+    a one-line warning — capture continues via the command stream only.
+    """
+    if not _bidi_enabled(driver):
+        _warn(
+            f"{BIDI_CAPABILITY} not set on the session — enable BiDi with "
+            "options.web_socket_url = True to capture console/network"
+        )
+        return False
+    attached = 0
+    if _attach_console(driver, capturer):
+        attached += 1
+    if _attach_network(driver, capturer):
+        attached += 1
+    return attached > 0
diff --git a/packages/selenium-devtools-py/src/selenium_devtools/capturer.py b/packages/selenium-devtools-py/src/selenium_devtools/capturer.py
new file mode 100644
index 00000000..9cc65798
--- /dev/null
+++ b/packages/selenium-devtools-py/src/selenium_devtools/capturer.py
@@ -0,0 +1,159 @@
+"""Session capturer — the Python analogue of core's ``SessionCapturerBase``.
+
+Owns the transport, a per-session command counter, and the normalize→send
+path. Deliberately thin: it turns already-captured data into wire frames and
+pushes them. No driver knowledge lives here (that's instrumentation.py); no
+post-processing lives here (that's the backend's job, per the architecture).
+"""
+
+from __future__ import annotations
+
+import threading
+from typing import Any, List, Optional, Protocol
+
+from . import frames
+from ._contract import (
+    SCOPE_COMMANDS,
+    SCOPE_CONSOLE_LOGS,
+    SCOPE_METADATA,
+    SCOPE_MUTATIONS,
+    SCOPE_NETWORK_REQUESTS,
+    SCOPE_SCREENCAST,
+    SCOPE_SOURCES,
+    SCOPE_SUITES,
+)
+from .types import SuiteStats
+from .utils import now_ms, to_jsonable
+
+
+class Transport(Protocol):
+    connected: bool
+
+    def send_json(self, scope: str, data: Any) -> bool: ...
+    def close(self) -> None: ...
+
+
+class SessionCapturer:
+    def __init__(self, transport: Transport) -> None:
+        self._tx = transport
+        self._command_counter = 0
+        self._lock = threading.Lock()
+        self._metadata_sent: set = set()  # session ids already announced
+        self.session_id: Optional[str] = None
+
+    # ── metadata ───────────────────────────────────────────────────────────────
+
+    def ensure_metadata(
+        self, session_id: str, capabilities: Optional[dict], url: Optional[str]
+    ) -> None:
+        """Announce a session once. Keyed by id, not a boolean: one process can
+        drive several sessions (a function-scoped pytest fixture makes a driver
+        per test), and the UI keys metadata by sessionId so each one is kept
+        rather than overwriting the first."""
+        if not session_id or session_id in self._metadata_sent:
+            return
+        self._metadata_sent.add(session_id)
+        self.session_id = session_id
+        self._tx.send_json(
+            SCOPE_METADATA,
+            frames.metadata(session_id, to_jsonable(capabilities or {}), url),
+        )
+
+    # ── commands ───────────────────────────────────────────────────────────────
+
+    def capture_command(
+        self,
+        *,
+        command: str,
+        args: Any,
+        result: Any = None,
+        error: Optional[BaseException] = None,
+        start_time: int,
+        call_source: Optional[str],
+        screenshot: Optional[str] = None,
+    ) -> None:
+        with self._lock:
+            self._command_counter += 1
+            command_id = self._command_counter
+        norm_args = args if isinstance(args, list) else ([] if args is None else [args])
+        entry = frames.command_log(
+            command=command,
+            args=to_jsonable(norm_args),
+            result=to_jsonable(result),
+            error=error,
+            timestamp=now_ms(),
+            start_time=start_time,
+            call_source=call_source,
+            command_id=command_id,
+            screenshot=screenshot,
+        )
+        self._tx.send_json(SCOPE_COMMANDS, [entry])
+
+    # ── console / network ────────────────────────────────────────────────────────
+
+    def capture_console(self, level: str, args: List[Any], source: str = "browser") -> None:
+        self._tx.send_json(
+            SCOPE_CONSOLE_LOGS,
+            [frames.console_log(level=level, args=to_jsonable(args),
+                                timestamp=now_ms(), source=source)],
+        )
+
+    def capture_network(self, **kwargs: Any) -> None:
+        self._tx.send_json(SCOPE_NETWORK_REQUESTS, [frames.network_request(**kwargs)])
+
+    # ── screencast ─────────────────────────────────────────────────────────────
+
+    def send_screencast(
+        self,
+        *,
+        video_path: str,
+        video_file: str,
+        frame_count: int,
+        duration: int,
+        start_time: Optional[int],
+        session_id: Optional[str] = None,
+    ) -> None:
+        # Keyed to the session the frames came from. `session_id` is passed
+        # explicitly when finalizing a session that has already been replaced,
+        # so the video is not filed under whichever session is current.
+        target = session_id or self.session_id
+        if not target:
+            return
+        self._tx.send_json(
+            SCOPE_SCREENCAST,
+            frames.screencast(
+                session_id=target,
+                video_path=video_path,
+                video_file=video_file,
+                frame_count=frame_count,
+                duration=duration,
+                start_time=start_time,
+            ),
+        )
+
+    # ── sources / mutations ──────────────────────────────────────────────────────
+
+    def send_sources(self, sources: dict) -> None:
+        """Send a ``{absolute_path: source_text}`` map — the Source tab shows the
+        file a command's ``callSource`` points at. Empty map is a no-op."""
+        if sources:
+            self._tx.send_json(SCOPE_SOURCES, sources)
+
+    def send_mutations(self, mutations: List[Any]) -> None:
+        """Forward DOM mutations captured by the injected browser script
+        (packages/script) — the UI renders them into the snapshot iframe."""
+        if mutations:
+            self._tx.send_json(SCOPE_MUTATIONS, mutations)
+
+    # ── suites ───────────────────────────────────────────────────────────────────
+
+    def send_suites(self, suites: List[SuiteStats]) -> None:
+        # The UI expects Record<uid, SuiteStats>[] — one single-key record per
+        # suite — mirroring core's TestReporterBase.sendUpstream. A plain array
+        # of suites won't render. Empty-payload guard matches the JS behavior.
+        payload = [{s["uid"]: s} for s in suites if s.get("uid")]
+        if payload:
+            self._tx.send_json(SCOPE_SUITES, payload)
+
+    def close(self) -> None:
+        self._tx.close()
diff --git a/packages/selenium-devtools-py/src/selenium_devtools/constants.py b/packages/selenium-devtools-py/src/selenium_devtools/constants.py
new file mode 100644
index 00000000..10046d1f
--- /dev/null
+++ b/packages/selenium-devtools-py/src/selenium_devtools/constants.py
@@ -0,0 +1,81 @@
+"""Module-level constants — the single home for connection defaults, env-var
+names, the skip sets, and the pinned backend version. No internal imports."""
+
+from __future__ import annotations
+
+import os
+
+# ── Connection defaults ──────────────────────────────────────────────────────
+DEFAULT_HOST = "localhost"
+DEFAULT_PORT = 3000
+WORKER_PATH = "/worker"
+CONNECT_TIMEOUT_S = 5.0
+
+# ── Environment variables that configure the adapter ─────────────────────────
+ENV_HOST = "DEVTOOLS_HOST"
+ENV_PORT = "DEVTOOLS_PORT"
+ENV_BACKEND_CMD = "DEVTOOLS_BACKEND_CMD"
+ENV_OPT_IN = "DEVTOOLS_ENABLE"
+ENV_BIDI = "DEVTOOLS_BIDI"  # "0"/"false"/"no"/"off" disables BiDi auto-enable
+ENV_OPEN = "DEVTOOLS_OPEN"  # "0"/"false"/"no"/"off" disables dashboard auto-open
+
+# ── Backend launch ───────────────────────────────────────────────────────────
+# Pinned backend version fetched via npx from a published install. There is no
+# cross-ecosystem resolver, so this constant *is* the version link — bump it in
+# the same change that regenerates _contract.py. 1.10.0 is the first version
+# carrying the `devtools-backend` bin; `npx` cannot start anything older.
+BACKEND_NPM_VERSION = "1.10.0"
+BACKEND_NPM_PACKAGE = "@wdio/devtools-backend"
+BACKEND_SPAWN_TIMEOUT_S = 40.0
+
+# ── Instrumentation ──────────────────────────────────────────────────────────
+# Selenium commands that are bookkeeping/noise rather than user-meaningful.
+# `screenshot`/`elementScreenshot` are skipped so the screencast recorder's
+# per-command frame capture (get_screenshot_as_base64) doesn't flood the
+# Actions timeline.
+SKIP_COMMANDS = frozenset(
+    {"newSession", "quit", "status", "getLog", "getAllSessions", "getSessions",
+     "screenshot", "elementScreenshot"}
+)
+
+# Stack-frame path fragment to skip when resolving a command's call source —
+# the adapter's own package. The selenium library dir is added at runtime by
+# instrumentation (resolved from selenium.__file__), NOT matched by the
+# substring "/selenium/" — that would wrongly skip a user's own test file living
+# under a path like examples/selenium/... .
+_PACKAGE_DIR = os.path.dirname(__file__)
+SKIP_STACK_FRAMES = (_PACKAGE_DIR,)
+
+# ── BiDi ──────────────────────────────────────────────────────────────────────
+# The capability the driver must advertise for selenium's BiDi channel to open
+# (set via ``options.web_socket_url = True`` at build time). Without it,
+# accessing ``driver.script`` / ``driver.network`` raises — attach() degrades.
+BIDI_CAPABILITY = "webSocketUrl"
+# BiDi network event names we subscribe to WITHOUT interception — a plain
+# session.subscribe, so requests are observed but never paused (interception
+# would stall the user's page loads if a callback failed to continue them).
+BIDI_NET_BEFORE_REQUEST = "network.beforeRequestSent"
+BIDI_NET_RESPONSE_COMPLETED = "network.responseCompleted"
+# selenium's BiDi log entries already carry lowercase levels; this normalizes
+# the stragglers to the shared LogLevel union. Unmapped levels fall back to log.
+BIDI_LEVEL_MAP = {
+    "debug": "debug",
+    "info": "info",
+    "warn": "warn",
+    "warning": "warn",
+    "error": "error",
+    "severe": "error",
+    "log": "log",
+    "trace": "trace",
+}
+
+# ── Screencast ────────────────────────────────────────────────────────────────
+# Frames are captured synchronously (one per command) on the main thread — see
+# screencast.py for why a background poll thread is avoided. Screenshots via
+# WebDriver are always PNG.
+SCREENCAST_IMAGE_FORMAT = "png"
+# Skip encoding below this many frames — a single still isn't a video.
+SCREENCAST_MIN_FRAMES = 2
+# Output filename stem; the session id + .webm suffix are appended.
+SCREENCAST_FILENAME_PREFIX = "selenium-py-video"
+# The `screencast` wire scope is generated into _contract.py (SCOPE_SCREENCAST).
diff --git a/packages/selenium-devtools-py/src/selenium_devtools/frames.py b/packages/selenium-devtools-py/src/selenium_devtools/frames.py
new file mode 100644
index 00000000..b5deeb48
--- /dev/null
+++ b/packages/selenium-devtools-py/src/selenium_devtools/frames.py
@@ -0,0 +1,193 @@
+"""Builders for the wire frames the dashboard renders.
+
+Each function returns the ``data`` payload for a ``{scope, data}`` frame.
+Shapes mirror ``packages/shared/src/types.ts``. Keeping them here — pure and
+side-effect free — makes them unit-testable and the single place the contract
+lives on the Python side.
+"""
+
+from __future__ import annotations
+
+from typing import Any, List, Optional
+
+from .types import (
+    CommandLog,
+    ConsoleLog,
+    Metadata,
+    NetworkRequest,
+    ScreencastInfo,
+    SuiteStats,
+    TestStats,
+)
+from .utils import iso
+
+
+def metadata(
+    session_id: str,
+    capabilities: Optional[dict] = None,
+    url: Optional[str] = None,
+) -> Metadata:
+    caps = capabilities or {}
+    return {
+        "type": "testrunner",  # TraceType.Testrunner
+        "sessionId": session_id,
+        "url": url,
+        "capabilities": caps,
+        "desiredCapabilities": caps,
+        "testEnv": "python-selenium",
+    }
+
+
+def command_log(
+    *,
+    command: str,
+    args: List[Any],
+    result: Any = None,
+    error: Optional[BaseException] = None,
+    timestamp: int,
+    start_time: int,
+    call_source: Optional[str],
+    command_id: int,
+    screenshot: Optional[str] = None,
+) -> CommandLog:
+    entry: CommandLog = {
+        "command": command,
+        "args": args,
+        "result": result,
+        "timestamp": timestamp,
+        "startTime": start_time,
+        "callSource": call_source,
+        "id": command_id,
+    }
+    if error is not None:
+        entry["error"] = {
+            "name": type(error).__name__,
+            "message": str(error),
+        }
+    if screenshot:
+        entry["screenshot"] = screenshot
+    return entry
+
+
+def console_log(
+    *, level: str, args: List[Any], timestamp: int, source: str = "browser"
+) -> ConsoleLog:
+    return {"type": level, "args": args, "timestamp": timestamp, "source": source}
+
+
+def network_request(
+    *,
+    request_id: str,
+    url: str,
+    method: str,
+    timestamp: int,
+    start_time: int,
+    status: Optional[int] = None,
+    request_type: str = "fetch",
+    end_time: Optional[int] = None,
+    status_text: Optional[str] = None,
+    time: Optional[int] = None,
+    size: Optional[int] = None,
+    request_headers: Optional[dict] = None,
+    response_headers: Optional[dict] = None,
+) -> NetworkRequest:
+    entry: NetworkRequest = {
+        "id": request_id,
+        "url": url,
+        "method": method,
+        "status": status,
+        "timestamp": timestamp,
+        "startTime": start_time,
+        "endTime": end_time,
+        "type": request_type,
+    }
+    # Response-phase fields are absent on the initial request frame; omit rather
+    # than send nulls so the dashboard's "pending" state renders correctly.
+    if status_text is not None:
+        entry["statusText"] = status_text
+    if time is not None:
+        entry["time"] = time
+    if size is not None:
+        entry["size"] = size
+    if request_headers is not None:
+        entry["requestHeaders"] = request_headers
+    if response_headers is not None:
+        entry["responseHeaders"] = response_headers
+    return entry
+
+
+def screencast(
+    *,
+    session_id: str,
+    video_path: str,
+    video_file: str,
+    frame_count: int,
+    duration: int,
+    start_time: Optional[int],
+) -> ScreencastInfo:
+    info: ScreencastInfo = {
+        "sessionId": session_id,
+        "videoPath": video_path,
+        "videoFile": video_file,
+        "frameCount": frame_count,
+        "duration": duration,
+    }
+    if start_time is not None:
+        info["startTime"] = start_time
+    return info
+
+
+def test_stats(
+    *,
+    uid: str,
+    title: str,
+    full_title: str,
+    parent: str,
+    state: str,
+    file: str,
+    start_ms: int,
+    end_ms: int,
+    call_source: Optional[str] = None,
+) -> TestStats:
+    return {
+        "uid": uid,
+        "cid": "0-0",
+        "title": title,
+        "fullTitle": full_title,
+        "parent": parent,
+        "state": state,
+        "start": iso(start_ms),
+        "end": iso(end_ms),
+        "type": "test",
+        "file": file,
+        "retries": 0,
+        "_duration": max(0, end_ms - start_ms),
+        "callSource": call_source,
+    }
+
+
+def suite_stats(
+    *,
+    uid: str,
+    title: str,
+    file: str,
+    start_ms: int,
+    tests: List[TestStats],
+    end_ms: Optional[int] = None,
+    state: Optional[str] = None,
+) -> SuiteStats:
+    return {
+        "uid": uid,
+        "cid": "0-0",
+        "title": title,
+        "fullTitle": title,
+        "type": "suite",
+        "file": file,
+        "start": iso(start_ms),
+        "end": iso(end_ms) if end_ms is not None else None,
+        "state": state,
+        "tests": tests,
+        "suites": [],
+        "hooks": [],
+        "_duration": max(0, (end_ms - start_ms)) if end_ms is not None else 0,
+    }
diff --git a/packages/selenium-devtools-py/src/selenium_devtools/instrumentation.py b/packages/selenium-devtools-py/src/selenium_devtools/instrumentation.py
new file mode 100644
index 00000000..4a8dc104
--- /dev/null
+++ b/packages/selenium-devtools-py/src/selenium_devtools/instrumentation.py
@@ -0,0 +1,411 @@
+"""Driver instrumentation — the one genuinely per-language piece.
+
+Every Selenium command (driver- *and* element-level, since element methods
+delegate to ``self._parent.execute``) funnels through
+``WebDriver.execute(driver_command, params)``. Wrapping that single chokepoint
+captures the whole command stream from one place — cleaner than the JS
+adapter's prototype patching.
+
+The patch target is injected so the module imports and unit-tests without
+selenium present; ``install`` defaults to the real selenium class.
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+import sys
+import threading
+from typing import Any, Optional
+
+from . import bidi, frames
+from .capturer import SessionCapturer
+from .constants import BIDI_CAPABILITY, ENV_BIDI, SKIP_COMMANDS, SKIP_STACK_FRAMES
+from .output_dir import resolve_adapter_output_dir
+from .screencast import ScreencastRecorder
+from .snapshot import SnapshotCapturer, start_snapshot_capture
+from .sources import read_source
+from .utils import call_source, now_ms
+
+# Operational logging — surfaced in the dashboard Console (the 'runner' stream).
+_log = logging.getLogger("selenium_devtools")
+
+# Marks the adapter's OWN execute_script calls (snapshot inject/readback) so
+# patched_execute skips capturing them as user commands.
+_internal = threading.local()
+
+# User-file paths whose source we've already sent (once per file per run).
+_sources_sent: set = set()
+
+
+_skip_frames_cache: Optional[tuple] = None
+
+
+def _skip_frames() -> tuple:
+    """Call-source skip fragments: the adapter package + the REAL selenium
+    library dir (resolved from selenium.__file__), cached. Resolving the actual
+    package dir avoids skipping a user test file whose path merely contains
+    'selenium' (e.g. examples/selenium/...)."""
+    global _skip_frames_cache
+    if _skip_frames_cache is None:
+        try:
+            import selenium
+
+            extra = (os.path.dirname(os.path.abspath(selenium.__file__)) + os.sep,)
+        except Exception:  # noqa: BLE001 — narrow fallback if selenium isn't importable
+            extra = (f"{os.sep}selenium{os.sep}webdriver{os.sep}",)
+        _skip_frames_cache = tuple(SKIP_STACK_FRAMES) + extra
+    return _skip_frames_cache
+
+
+def _internal_active() -> bool:
+    return getattr(_internal, "active", False)
+
+
+# When a test framework (the pytest plugin) reports the suite tree, the adapter
+# must NOT also synthesize a default one. The plugin flips this in its configure.
+_external_suites = False
+
+
+def set_external_suites(value: bool = True) -> None:
+    """Tell the adapter a test framework owns the suite tree (suppresses the
+    default single-session suite used for plain scripts)."""
+    global _external_suites
+    _external_suites = value
+
+
+def _send_default_suite(capturer: SessionCapturer, state: str) -> None:
+    """Report the run as a single suite/test named after the entry script, so a
+    plain-script run (no test framework) still shows in the TESTS tree. No-op if
+    a framework is reporting suites."""
+    if _external_suites:
+        return
+    entry = os.path.abspath(sys.argv[0]) if sys.argv and sys.argv[0] else ""
+    title = os.path.basename(entry) or "Selenium session"
+    ds = _state.get("default_suite")
+    start = ds["start"] if ds else now_ms()
+    _state["default_suite"] = {"start": start}
+    end = start if state == "running" else now_ms()
+    test = frames.test_stats(
+        uid=f"{entry or title}::session", title=title, full_title=title,
+        parent=title, state=state, file=entry, start_ms=start, end_ms=end,
+    )
+    suite = frames.suite_stats(
+        uid=entry or title, title=title, file=entry, start_ms=start,
+        tests=[test], state=state, end_ms=(None if state == "running" else end),
+    )
+    capturer.send_suites([suite])
+
+
+def _guarded_execute_script(driver: Any) -> Any:
+    """An ``execute_script`` that runs WITHOUT command capture — for the
+    adapter's own snapshot injection/readback, which must never show up in the
+    Actions timeline (the getTraceData/inject scripts are not user commands)."""
+
+    def run(script: str, *args: Any) -> Any:
+        _internal.active = True
+        try:
+            return driver.execute_script(script, *args)
+        finally:
+            _internal.active = False
+
+    return run
+
+
+def _capture_source(capturer: SessionCapturer, call_src: Optional[str]) -> None:
+    """Send the source of the file a command's ``callSource`` points at (once).
+
+    Keyed by the exact ``callSource`` path so the Source tab always matches —
+    and works for any runner (plain script or pytest), not just the plugin.
+    Guarded: source capture must never break the user's test."""
+    if not call_src:
+        return
+    path = call_src.rsplit(":", 1)[0]  # strip the trailing ":line"
+    if not path:
+        return
+    # Screencast output lands next to the (first) test file, not the cwd.
+    if _state.get("output_dir") is None:
+        _state["output_dir"] = resolve_adapter_output_dir(test_file_path=path)
+    if path in _sources_sent:
+        return
+    try:
+        text = read_source(path)
+    except Exception:  # noqa: BLE001
+        return
+    if text is None:
+        return
+    _sources_sent.add(path)
+    capturer.send_sources({path: text})
+
+# Selenium command names that change the document — after these we drain the
+# page-side mutation buffer so the snapshot iframe stays current.
+_state: dict = {
+    "installed": False, "cls": None, "orig": None,
+    "screencast": None, "snapshot": None,
+    # Session id the per-session bringup last ran for. A boolean here silently
+    # skipped bringup for every session after the first.
+    "armed_session": None,
+    "output_dir": None,  # test-results dir beside the test file (see output_dir.py)
+    "default_suite": None,  # synthesized suite for non-framework (script) runs
+}
+
+
+def _take_screenshot(driver: Any) -> Optional[str]:
+    """One base64 PNG of the current page on the MAIN thread — no background
+    thread, so we never touch the Selenium session concurrently. Reused for both
+    the command entry (per-command snapshot view) and the screencast frame.
+    Best-effort: a transient failure (mid-navigation, dead session) returns
+    None and never breaks the test. ``screenshot`` is in SKIP_COMMANDS, so this
+    doesn't appear in the Actions timeline."""
+    fn = getattr(driver, "get_screenshot_as_base64", None)
+    if not callable(fn):
+        return None
+    try:
+        shot = fn()
+    except Exception:  # noqa: BLE001 — transient; skip this frame
+        return None
+    return shot if isinstance(shot, str) and shot else None
+
+
+def _add_screencast_frame(shot: Optional[str]) -> None:
+    """Buffer an already-captured screenshot as a screencast frame."""
+    recorder = _state.get("screencast")
+    if recorder is None or not shot:
+        return
+    try:
+        recorder.add_frame(shot)
+    except Exception as exc:  # noqa: BLE001 — never break the test
+        _log.warning("screencast add_frame threw: %s", exc)
+
+
+def _refresh_snapshot(capturer: SessionCapturer) -> None:
+    """After a command, keep the snapshot current: re-inject the collector if the
+    page navigated (self-healing — a click can submit a form and wipe it), then
+    drain the mutation buffer. Called after every command, not just explicit
+    navigations, so the initial full-document snapshot is captured even if it
+    wasn't ready the instant the navigation returned."""
+    snapshot = _state.get("snapshot")
+    if snapshot is None:
+        return
+    try:
+        snapshot.inject()  # no-op if already present; re-installs after navigation
+    except Exception as exc:  # noqa: BLE001 — never break the test
+        _log.warning("snapshot re-inject threw: %s", exc)
+    _flush_mutations(capturer)
+
+
+def _flush_mutations(capturer: SessionCapturer) -> None:
+    """Drain the page-side mutation buffer and forward it — no-op if the
+    collector was never injected. Defensive: never breaks the user's test."""
+    snapshot: SnapshotCapturer | None = _state.get("snapshot")
+    if snapshot is None:
+        return
+    try:
+        mutations = snapshot.pull_mutations()
+    except Exception as exc:  # noqa: BLE001 — capture must never break the test
+        _log.warning("mutation flush threw: %s", exc)
+        return
+    if mutations:
+        capturer.send_mutations(mutations)
+
+
+def _enable_bidi_capability(params: Any) -> None:
+    """Request BiDi at session creation by injecting ``webSocketUrl`` into the
+    newSession capabilities — the one point (before the session exists) where we
+    can. This makes console/network capture work out-of-box, matching the JS
+    adapters. Opt out with ``DEVTOOLS_BIDI=0``. Never blocks a session."""
+    if os.environ.get(ENV_BIDI, "").strip().lower() in ("0", "false", "no", "off"):
+        return
+    try:
+        caps = params.get("capabilities") if isinstance(params, dict) else None
+        if not isinstance(caps, dict):
+            return
+        always = caps.get("alwaysMatch")
+        if not isinstance(always, dict):
+            always = {}
+            caps["alwaysMatch"] = always
+        always.setdefault(BIDI_CAPABILITY, True)
+    except Exception:  # noqa: BLE001 — capability injection is best-effort
+        pass
+
+
+def _finalize_screencast(capturer: SessionCapturer, session_id: Optional[str]) -> None:
+    """Encode and forward the recording for ``session_id``. Attributed explicitly,
+    because a rotation finalizes the session that just ended while a newer one is
+    already current."""
+    recorder = _state.get("screencast")
+    if recorder is None:
+        return
+    _state["screencast"] = None
+    try:
+        info = recorder.finalize(
+            session_id or "session", output_dir=_state.get("output_dir")
+        )
+    except Exception as exc:  # noqa: BLE001
+        _log.warning("screencast finalize threw: %s", exc)
+        return
+    if info is not None:
+        capturer.send_screencast(**info, session_id=session_id)
+        _log.info("screencast saved: %s", info.get("video_path"))
+
+
+def _ensure_session_setup(driver: Any, capturer: SessionCapturer) -> None:
+    """Once per session — on the first real command — send metadata, attach
+    BiDi, and start the screencast.
+
+    This CANNOT run in the newSession branch: selenium assigns ``session_id`` /
+    ``caps`` only *after* the newSession execute() returns, so at that point the
+    driver has no session yet (BiDi caps missing, screenshots fail). By the first
+    real command the driver is fully initialized. Each step is independently
+    defensive — a BiDi or screencast failure is a logged no-op.
+    """
+    session_id = getattr(driver, "session_id", None)
+    if not session_id or session_id == _state.get("armed_session"):
+        return  # not ready yet, or already armed for this session
+    previous = _state.get("armed_session")
+    if previous:
+        # A second driver in the same process. Close out the previous session
+        # before arming this one, or its video and DOM would be attributed here.
+        _flush_mutations(capturer)
+        _state["snapshot"] = None
+        _finalize_screencast(capturer, previous)
+        _log.info("session %s replaced by %s; re-arming capture", previous, session_id)
+    _state["armed_session"] = session_id
+    capturer.ensure_metadata(session_id, getattr(driver, "caps", None), None)
+    _log.info("session %s started", session_id)
+    _send_default_suite(capturer, "running")  # tree entry for plain-script runs
+    try:
+        if bidi.attach(driver, capturer):
+            _log.info("BiDi attached — capturing console + network")
+    except Exception as exc:  # noqa: BLE001 — capture must never break the test
+        _log.warning("BiDi attach threw: %s", exc)
+    try:
+        recorder = ScreencastRecorder()
+        recorder.start(driver)
+        _state["screencast"] = recorder
+        _log.info("screencast recording started")
+    except Exception as exc:  # noqa: BLE001
+        _log.warning("screencast start threw: %s", exc)
+    try:
+        # Inject the packages/script DOM observer so the snapshot iframe fills.
+        # Use a capture-bypassing execute_script so injection/readback scripts
+        # don't pollute the Actions timeline.
+        snapshot = start_snapshot_capture(
+            driver, execute_fn=_guarded_execute_script(driver)
+        )
+        _state["snapshot"] = snapshot
+        if snapshot is not None:
+            _log.info("DOM snapshot collector injected")
+    except Exception as exc:  # noqa: BLE001
+        _log.warning("snapshot start threw: %s", exc)
+
+
+def _on_quit(capturer: SessionCapturer, driver: Any = None) -> None:
+    """On driver.quit(): finalize the screencast and forward its metadata.
+
+    ``quit`` is in the skip set, so this is the last hook before the session is
+    gone — encode here while a session id is still known."""
+    quitting = getattr(driver, "session_id", None) if driver is not None else None
+    armed = _state.get("armed_session")
+    if quitting and armed and quitting != armed:
+        # Another driver is the live one; leave its capture alone.
+        return
+    # Drain any final mutations while the session (and page) still exist.
+    _flush_mutations(capturer)
+    _state["snapshot"] = None
+    if _state.get("default_suite") is not None:
+        _send_default_suite(capturer, "passed")  # mark the script run complete
+    _finalize_screencast(capturer, quitting or armed or capturer.session_id)
+    # Cleared so a driver created later re-arms instead of being treated as this
+    # session and losing its metadata, BiDi, DOM and video.
+    _state["armed_session"] = None
+
+
+def install(capturer: SessionCapturer, webdriver_cls: Optional[type] = None) -> None:
+    if _state["installed"]:
+        return
+    if webdriver_cls is None:
+        from selenium.webdriver.remote.webdriver import WebDriver  # lazy
+
+        webdriver_cls = WebDriver
+
+    orig_execute = webdriver_cls.execute
+
+    def patched_execute(self, driver_command: str, params: Any = None):  # noqa: ANN001
+        # The adapter's own execute_script (snapshot inject/readback) runs
+        # transparently — never captured as a user command.
+        if _internal_active():
+            return orig_execute(self, driver_command, params)
+        # Skip capture for noise, but never alter behavior.
+        if driver_command in SKIP_COMMANDS:
+            # Finalize the screencast BEFORE quit tears the session down — after
+            # orig_execute the driver's WebSocket/session is gone.
+            if driver_command == "quit":
+                _on_quit(capturer, self)
+            elif driver_command == "newSession":
+                _enable_bidi_capability(params)  # request BiDi before the session opens
+            return orig_execute(self, driver_command, params)
+
+        # First real command: the driver is now fully initialized — set up
+        # metadata/BiDi/screencast once, before executing so BiDi sees this cmd.
+        _ensure_session_setup(self, capturer)
+        start = now_ms()
+        src = call_source(_skip_frames())
+        _capture_source(capturer, src)  # Source tab: send the test file once
+        try:
+            result = orig_execute(self, driver_command, params)
+        except BaseException as exc:  # capture then re-raise unchanged
+            capturer.capture_command(
+                command=driver_command,
+                args=params,
+                error=exc,
+                start_time=start,
+                call_source=src,
+            )
+            raise
+
+        # WebDriver.execute returns the full response dict; the useful payload
+        # is response["value"].
+        value = result.get("value") if isinstance(result, dict) else result
+        # One screenshot per command on this (main) thread — attached to the
+        # command (so selecting it shows the page) AND reused as a screencast
+        # frame, so we pay for only a single screenshot round-trip either way.
+        shot = _take_screenshot(self)
+        capturer.capture_command(
+            command=driver_command,
+            args=params,
+            result=value,
+            start_time=start,
+            call_source=src,
+            screenshot=shot,
+        )
+        _log.debug("command: %s", driver_command)
+        # Keep the snapshot iframe current after every command (a click can
+        # navigate too, not just get/back/…), re-injecting if the page changed.
+        _refresh_snapshot(capturer)
+        _add_screencast_frame(shot)
+        return result
+
+    webdriver_cls.execute = patched_execute  # type: ignore[assignment]
+    _sources_sent.clear()
+    _state.update(
+        installed=True, cls=webdriver_cls, orig=orig_execute,
+        armed_session=None, output_dir=None, default_suite=None,
+    )
+
+
+def uninstall() -> None:
+    recorder = _state.get("screencast")
+    if recorder is not None:
+        recorder.stop()  # never leave a poll thread running past teardown
+    if not _state["installed"]:
+        _state.update(
+            screencast=None, snapshot=None, armed_session=None,
+            output_dir=None, default_suite=None,
+        )
+        return
+    _state["cls"].execute = _state["orig"]  # type: ignore[union-attr]
+    _state.update(
+        installed=False, cls=None, orig=None, screencast=None, snapshot=None,
+        armed_session=None, output_dir=None, default_suite=None,
+    )
diff --git a/packages/selenium-devtools-py/src/selenium_devtools/lifecycle.py b/packages/selenium-devtools-py/src/selenium_devtools/lifecycle.py
new file mode 100644
index 00000000..b7ffb08d
--- /dev/null
+++ b/packages/selenium-devtools-py/src/selenium_devtools/lifecycle.py
@@ -0,0 +1,363 @@
+"""Dashboard browser-window lifecycle — mirror the JS adapters' behavior.
+
+Three flows, matching `packages/selenium-devtools`:
+
+1. On capture start, open an external browser window at the dashboard URL and
+   keep a closable handle to it.
+2. When the backend sends a ``clientDisconnected`` control frame (the user
+   closed the dashboard window/tab), shut capture down and exit the process.
+3. When the Python process ends (normal exit / SIGINT / SIGTERM), close the
+   browser window we opened.
+
+Everything here is best-effort: a failure to open or close the browser must
+never crash the user's test run. All side effects (signal handlers, atexit,
+real subprocess spawning) happen only through :func:`register_exit_handlers`
+and :func:`open_dashboard`, never at import time, so importing this module is
+inert (important for unittest).
+"""
+
+from __future__ import annotations
+
+import atexit
+import os
+import shutil
+import signal
+import subprocess
+import sys
+import tempfile
+import threading
+from typing import Callable, Optional
+
+from .constants import ENV_OPEN
+
+# ── Local timing constants (lifecycle-specific) ──────────────────────────────
+# These live here because constants.py is owned elsewhere; they could move there
+# alongside ENV_OPEN if a second module ever needs them.
+SHUTDOWN_EXIT_CODE = 0
+SHUTDOWN_GRACE_S = 1.5  # let the WS reader thread unwind before the hard exit
+BROWSER_TERM_TIMEOUT_S = 3.0
+DASHBOARD_WINDOW_SIZE = "1600,1200"
+
+# macOS Chrome/Chromium binaries, most-preferred first.
+_MACOS_CHROME_CANDIDATES = (
+    "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome",
+    "/Applications/Google Chrome Beta.app/Contents/MacOS/Google Chrome Beta",
+    "/Applications/Chromium.app/Contents/MacOS/Chromium",
+    os.path.expanduser(
+        "~/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"
+    ),
+)
+
+
+def _log(msg: str) -> None:
+    print(f"[devtools] {msg}", file=sys.stderr)
+
+
+# ── Browser handle ───────────────────────────────────────────────────────────
+
+
+class BrowserHandle:
+    """A closable reference to the browser window we opened for the dashboard.
+
+    Holds the launched subprocess plus its throwaway ``--user-data-dir`` so
+    :meth:`close` can terminate exactly this window and clean the profile up —
+    the JS adapter uses ``pkill -f`` on a unique dir; we hold the handle
+    directly, which is both more precise and unit-testable.
+    """
+
+    def __init__(
+        self,
+        proc: Optional[subprocess.Popen] = None,
+        user_data_dir: Optional[str] = None,
+    ) -> None:
+        self.proc = proc
+        self.user_data_dir = user_data_dir
+        self._closed = False
+
+    def close(self) -> None:
+        """Terminate the dashboard window and remove its temp profile. Idempotent."""
+        if self._closed:
+            return
+        self._closed = True
+        proc = self.proc
+        if proc is not None and proc.poll() is None:
+            try:
+                proc.terminate()
+                try:
+                    proc.wait(timeout=BROWSER_TERM_TIMEOUT_S)
+                except subprocess.TimeoutExpired:
+                    proc.kill()
+            except OSError:
+                pass  # best-effort: never crash on browser teardown
+        if self.user_data_dir:
+            shutil.rmtree(self.user_data_dir, ignore_errors=True)
+
+
+# ── Opening the dashboard window ─────────────────────────────────────────────
+
+
+def _find_chrome() -> Optional[str]:
+    """Path to a Chrome/Chromium binary on this machine, or None."""
+    for candidate in _MACOS_CHROME_CANDIDATES:
+        if os.path.exists(candidate):
+            return candidate
+    return None
+
+
+def _default_opener(url: str) -> BrowserHandle:
+    """Open ``url`` in a dedicated, isolated Chrome window we can later close.
+
+    We spawn the Chrome binary directly rather than stdlib ``webbrowser`` or
+    macOS ``open``: both hand the URL to the user's already-running Chrome,
+    which then shows the dashboard as a tab among all their other tabs and
+    gives us no handle to close it — exactly the bug this avoids.
+
+    The isolation guarantee is the throwaway ``--user-data-dir``: launching the
+    Chrome binary with a distinct profile dir forces a brand-new Chrome
+    *instance* (a separate process that cannot merge into the user's running
+    Chrome), so the dashboard always gets its own window. ``--app`` makes that
+    window chrome-less (no tab strip/omnibox) and ``--new-window`` is a belt-
+    and-suspenders hint. Holding the subprocess handle lets :meth:`close`
+    terminate exactly this window — more precise than the JS adapter's
+    ``pkill -f`` on the profile dir, and unit-testable.
+    """
+    chrome = _find_chrome()
+    if chrome is None:
+        _log(f"Chrome not found; open the dashboard manually: {url}")
+        return BrowserHandle()
+
+    user_data_dir = tempfile.mkdtemp(prefix="selenium-devtools-py-ui-")
+    args = [
+        chrome,
+        f"--user-data-dir={user_data_dir}",  # forces a separate Chrome instance
+        "--no-first-run",
+        "--no-default-browser-check",
+        f"--window-size={DASHBOARD_WINDOW_SIZE}",
+        "--new-window",
+        f"--app={url}",  # dedicated dashboard window, chrome-less
+    ]
+    proc = subprocess.Popen(args, stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL)
+    _log(f"Opened DevTools UI in a dedicated window: {url}")
+    return BrowserHandle(proc=proc, user_data_dir=user_data_dir)
+
+
+_FALSY = ("0", "false", "no", "off", "")
+
+
+def auto_open_enabled() -> bool:
+    """Whether the dashboard window should auto-open. Default ON, opt-out only.
+
+    Rule: open unless ``DEVTOOLS_OPEN`` is set to a falsy value
+    (``0``/``false``/``no``/``off``/empty). This matches the JS adapters, whose
+    ``openUi`` option defaults true regardless of TTY.
+
+    The previous "default off when stdout isn't a TTY" gate silently disabled
+    auto-open for the common case — running from an IDE or ``python demo.py``
+    with no attached TTY — so the user opened the URL in their main Chrome
+    instead. CI/headless runs disable it explicitly with ``DEVTOOLS_OPEN=0``.
+    """
+    val = os.environ.get(ENV_OPEN)
+    if val is None:
+        return True
+    return val.strip().lower() not in _FALSY
+
+
+def open_dashboard(
+    url: Optional[str],
+    *,
+    opener: Callable[[str], BrowserHandle] = _default_opener,
+) -> Optional[BrowserHandle]:
+    """Open ``url`` in a closable browser window; return its handle or None.
+
+    ``opener`` is injectable so tests can assert behavior without a real
+    browser. Never raises — a failed open logs one line and returns None.
+    """
+    if not url:
+        return None
+    try:
+        return opener(url)
+    except (OSError, ValueError) as exc:
+        _log(f"could not open dashboard window ({exc}); open manually: {url}")
+        return None
+
+
+# ── Shutdown wiring ──────────────────────────────────────────────────────────
+
+# Set by register_exit_handlers so the control-frame handler and signal handlers
+# can reach the package's disable() and the open window without an import cycle.
+_disable: Optional[Callable[[], None]] = None
+_handle: Optional[BrowserHandle] = None
+_handlers_registered = False
+_prev_sigint = None
+_prev_sigterm = None
+_shutting_down = False
+_shutdown_lock = threading.Lock()
+# Set when the dashboard is closed / a shutdown is triggered — lets a caller
+# (e.g. the pytest plugin) block after a run to keep the dashboard open for
+# inspection, then exit when the user closes it.
+_shutdown_event = threading.Event()
+_has_waiter = False
+
+
+def dashboard_window_open() -> bool:
+    """True if we opened a dashboard window and its process is still alive."""
+    h = _handle
+    return h is not None and h.proc is not None and h.proc.poll() is None
+
+
+def wait_for_shutdown(timeout: Optional[float] = None) -> bool:
+    """Block until the dashboard is closed (clientDisconnected) or a signal.
+
+    Used to keep the dashboard open for inspection after a run. Returns True on
+    shutdown, False on timeout. Registers a waiter so the WS handler hands
+    teardown back to the caller instead of hard-exiting out from under it."""
+    global _has_waiter
+    _has_waiter = True
+    return _shutdown_event.wait(timeout)
+
+
+def _run_disable() -> None:
+    """Call the registered disable() once, swallowing errors."""
+    fn = _disable
+    if fn is None:
+        return
+    try:
+        fn()
+    except Exception as exc:  # disable must never re-raise into a handler
+        _log(f"error during disable(): {exc}")
+
+
+def _close_handle() -> None:
+    """Close the opened browser window if any."""
+    handle = _handle
+    if handle is not None:
+        handle.close()
+
+
+def on_control(scope: str, data: dict) -> None:
+    """WS control-frame handler: shut down when the dashboard client leaves.
+
+    ``clientDisconnected`` means the user closed the dashboard window, so we
+    tear capture down and exit the process (on a short timer, off the WS reader
+    thread, so that thread can unwind cleanly). ``clientConnected`` is a no-op.
+    """
+    if scope == "clientDisconnected":
+        _log("dashboard closed; shutting down")
+        _trigger_shutdown(exit_after=True)
+
+
+def _trigger_shutdown(*, exit_after: bool, exit_code: int = SHUTDOWN_EXIT_CODE) -> None:
+    """Run disable() + close the window once; optionally hard-exit afterwards."""
+    global _shutting_down
+    with _shutdown_lock:
+        if _shutting_down:
+            return
+        _shutting_down = True
+
+    _shutdown_event.set()  # unblock any wait_for_shutdown()
+    if _has_waiter:
+        # A caller is blocked in wait_for_shutdown() and owns teardown — don't
+        # hard-exit out from under it.
+        return
+
+    _run_disable()
+    _close_handle()
+
+    if exit_after:
+        # Defer the hard exit to a daemon timer so the WS reader thread (which
+        # may be the caller) unwinds first; os._exit avoids re-entering atexit.
+        def _exit() -> None:
+            os._exit(exit_code)
+
+        timer = threading.Timer(SHUTDOWN_GRACE_S, _exit)
+        timer.daemon = True
+        timer.start()
+
+
+def _on_signal(signum, _frame) -> None:
+    """SIGINT/SIGTERM: close the window + disable, then re-raise the default."""
+    _trigger_shutdown(exit_after=False)
+    prev = _prev_sigint if signum == signal.SIGINT else _prev_sigterm
+    if callable(prev):
+        prev(signum, _frame)
+    else:
+        # Restore default disposition and re-raise so the process dies normally.
+        try:
+            signal.signal(signum, signal.SIG_DFL)
+            os.kill(os.getpid(), signum)
+        except OSError:
+            os._exit(128 + signum)
+
+
+def register_exit_handlers(
+    disable: Callable[[], None],
+    handle: Optional[BrowserHandle],
+) -> None:
+    """Register atexit + SIGINT/SIGTERM handlers to close the window on exit.
+
+    Idempotent: called from enable(). Signal handlers are only installed on the
+    main thread (Python forbids otherwise) and the previous handlers are chained
+    so we don't swallow the runner's own Ctrl-C behavior.
+    """
+    global _disable, _handle, _handlers_registered, _prev_sigint, _prev_sigterm
+    global _shutting_down, _has_waiter
+    _disable = disable
+    _handle = handle
+    # Fresh shutdown state each run (supports enable→disable→enable).
+    _shutdown_event.clear()
+    _shutting_down = False
+    _has_waiter = False
+    if _handlers_registered:
+        return
+    _handlers_registered = True
+
+    atexit.register(_close_handle)
+
+    if threading.current_thread() is threading.main_thread():
+        try:
+            _prev_sigint = signal.getsignal(signal.SIGINT)
+            _prev_sigterm = signal.getsignal(signal.SIGTERM)
+            signal.signal(signal.SIGINT, _on_signal)
+            signal.signal(signal.SIGTERM, _on_signal)
+        except (ValueError, OSError) as exc:
+            _log(f"could not install signal handlers ({exc})")
+
+
+def unregister_exit_handlers() -> None:
+    """Undo register_exit_handlers; close the window. Idempotent — for disable()."""
+    global _disable, _handle, _handlers_registered, _prev_sigint, _prev_sigterm
+    _close_handle()
+    if _handlers_registered:
+        try:
+            atexit.unregister(_close_handle)
+        except Exception:
+            pass
+        if threading.current_thread() is threading.main_thread():
+            for sig, prev in (
+                (signal.SIGINT, _prev_sigint),
+                (signal.SIGTERM, _prev_sigterm),
+            ):
+                if prev is not None:
+                    try:
+                        signal.signal(sig, prev)
+                    except (ValueError, OSError):
+                        pass
+    _disable = None
+    _handle = None
+    _handlers_registered = False
+    _prev_sigint = None
+    _prev_sigterm = None
+
+
+def _reset_for_tests() -> None:
+    """Reset module state between unit tests (never used in production)."""
+    global _disable, _handle, _handlers_registered
+    global _prev_sigint, _prev_sigterm, _shutting_down, _has_waiter
+    _disable = None
+    _handle = None
+    _handlers_registered = False
+    _prev_sigint = None
+    _prev_sigterm = None
+    _shutting_down = False
+    _has_waiter = False
+    _shutdown_event.clear()
diff --git a/packages/selenium-devtools-py/src/selenium_devtools/logcapture.py b/packages/selenium-devtools-py/src/selenium_devtools/logcapture.py
new file mode 100644
index 00000000..1984ad0b
--- /dev/null
+++ b/packages/selenium-devtools-py/src/selenium_devtools/logcapture.py
@@ -0,0 +1,70 @@
+"""Forward Python ``logging`` output to the dashboard Console — the 'runner' log
+stream, the analogue of the JS adapter surfacing ``@wdio/logger`` output
+(webdriver/BiDi lines, the adapter's own '✓ Script injected' events, etc.).
+
+Attaches a handler to the root logger and raises the adapter's + selenium's
+loggers to a useful level so their records reach the dashboard. Restores
+everything on stop.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any, Dict
+
+#: The adapter's logger name — operational events are logged under it.
+LOGGER_NAME = "selenium_devtools"
+
+_LEVEL_MAP = {
+    logging.DEBUG: "debug",
+    logging.INFO: "info",
+    logging.WARNING: "warn",
+    logging.ERROR: "error",
+    logging.CRITICAL: "error",
+}
+
+# Loggers raised to a useful level so their records reach the dashboard: the
+# adapter's own (verbose) and selenium's (info: session/BiDi lines).
+_WATCH = {LOGGER_NAME: logging.DEBUG, "selenium": logging.INFO}
+
+
+class _DashboardHandler(logging.Handler):
+    def __init__(self, capturer: Any) -> None:
+        super().__init__(level=logging.DEBUG)
+        self._capturer = capturer
+        self._reentrant = False
+
+    def emit(self, record: logging.LogRecord) -> None:
+        if self._reentrant:  # forwarding must not re-enter via its own logging
+            return
+        self._reentrant = True
+        try:
+            level = _LEVEL_MAP.get(record.levelno, "log")
+            message = f"{record.name}: {record.getMessage()}"
+            self._capturer.capture_console(level, [message], source="terminal")
+        except Exception:  # noqa: BLE001 — logging must never break the test
+            pass
+        finally:
+            self._reentrant = False
+
+
+class LogCapturer:
+    """Streams Python logging into the dashboard Console for the run's duration."""
+
+    def __init__(self, capturer: Any) -> None:
+        self._handler = _DashboardHandler(capturer)
+        self._prev_levels: Dict[str, int] = {}
+
+    def start(self) -> None:
+        logging.getLogger().addHandler(self._handler)
+        for name, level in _WATCH.items():
+            logger = logging.getLogger(name)
+            self._prev_levels[name] = logger.level
+            if logger.level == logging.NOTSET or logger.level > level:
+                logger.setLevel(level)
+
+    def stop(self) -> None:
+        logging.getLogger().removeHandler(self._handler)
+        for name, prev in self._prev_levels.items():
+            logging.getLogger(name).setLevel(prev)
+        self._prev_levels.clear()
diff --git a/packages/selenium-devtools-py/src/selenium_devtools/output_dir.py b/packages/selenium-devtools-py/src/selenium_devtools/output_dir.py
new file mode 100644
index 00000000..f22346a3
--- /dev/null
+++ b/packages/selenium-devtools-py/src/selenium_devtools/output_dir.py
@@ -0,0 +1,80 @@
+"""Where the adapter writes run output. Mirrors ``core/output-dir.ts`` so all four
+adapters group artifacts under the same ``test-results/`` subfolder, wherever the
+base directory resolves to.
+
+Base directory, by priority:
+
+    1. ``user_configured_dir`` — explicit opt-in, honored as-is.
+    2. ``dirname(test_file_path)`` — the folder holding the test that just ran.
+    3. ``fallback_dir`` (default: cwd).
+
+A candidate inside an installed-package directory is skipped: a test file
+resolved through site-packages must not receive artifacts. That is the Python
+counterpart of core skipping ``node_modules``. Each candidate must also be
+writable, or resolution falls through to the next.
+"""
+
+from __future__ import annotations
+
+import os
+from typing import List, Optional
+
+#: All run output is grouped under this subfolder, matching the JS adapters.
+OUTPUT_SUBDIR = "test-results"
+
+#: Installed-package segments: the analogue of core's ``node_modules`` filter.
+_INSTALLED_SEGMENTS = (
+    f"{os.sep}site-packages{os.sep}",
+    f"{os.sep}dist-packages{os.sep}",
+)
+
+
+def _is_writable(directory: str) -> bool:
+    return os.path.isdir(directory) and os.access(directory, os.W_OK)
+
+
+def _resolve_base_dir(
+    user_configured_dir: Optional[str],
+    test_file_path: Optional[str],
+    fallback_dir: Optional[str],
+) -> str:
+    fallback = fallback_dir or os.getcwd()
+    # An explicit directory bypasses the installed-package and writability
+    # filters: the user opted into it, and a surprising override is worse than
+    # failing where they pointed us.
+    if user_configured_dir:
+        return user_configured_dir
+    candidates: List[str] = []
+    if test_file_path:
+        candidates.append(os.path.dirname(os.path.abspath(test_file_path)))
+    candidates.append(fallback)
+    for directory in candidates:
+        if not directory:
+            continue
+        if any(seg in f"{directory}{os.sep}" for seg in _INSTALLED_SEGMENTS):
+            continue
+        if _is_writable(directory):
+            return directory
+    return fallback
+
+
+def resolve_adapter_output_dir(
+    *,
+    user_configured_dir: Optional[str] = None,
+    test_file_path: Optional[str] = None,
+    fallback_dir: Optional[str] = None,
+) -> str:
+    """Absolute path of the ``test-results`` directory to write into. Does not
+    create it; ``ensure_output_dir`` does that at write time."""
+    base = _resolve_base_dir(user_configured_dir, test_file_path, fallback_dir)
+    return os.path.join(os.path.abspath(base), OUTPUT_SUBDIR)
+
+
+def ensure_output_dir(directory: str) -> Optional[str]:
+    """Create ``directory`` if needed. Returns it, or None when it cannot be
+    created, so a caller can fall back rather than crash a user's test run."""
+    try:
+        os.makedirs(directory, exist_ok=True)
+    except OSError:
+        return None
+    return directory if _is_writable(directory) else None
diff --git a/packages/selenium-devtools-py/src/selenium_devtools/pytest_plugin.py b/packages/selenium-devtools-py/src/selenium_devtools/pytest_plugin.py
new file mode 100644
index 00000000..783770c4
--- /dev/null
+++ b/packages/selenium-devtools-py/src/selenium_devtools/pytest_plugin.py
@@ -0,0 +1,124 @@
+"""pytest plugin — feeds the suite/test tree to the dashboard.
+
+The analogue of the JS adapter's mocha/jest hooks. Inert unless the run opts in
+via ``DEVTOOLS_ENABLE=1`` or ``DEVTOOLS_PORT=...`` so installing the package never
+hijacks an unrelated pytest run. On opt-in it enables capture at session start,
+stamps per-test timing, and re-sends the ``suites`` frame as each test reports.
+"""
+
+from __future__ import annotations
+
+import os
+from typing import Dict
+
+import selenium_devtools as devtools
+from . import frames
+from .constants import ENV_OPT_IN, ENV_PORT
+from .utils import now_ms
+
+
+def _opted_in() -> bool:
+    return bool(os.environ.get(ENV_OPT_IN) or os.environ.get(ENV_PORT))
+
+
+class _SuiteRegistry:
+    """Groups tests by file into the SuiteStats[] the dashboard expects."""
+
+    def __init__(self) -> None:
+        self._suites: Dict[str, dict] = {}
+        self._tests: Dict[str, dict] = {}
+        self._starts: Dict[str, int] = {}
+
+    def mark_start(self, nodeid: str) -> None:
+        self._starts.setdefault(nodeid, now_ms())
+
+    def record(self, nodeid: str, file: str, name: str, line: int, state: str) -> None:
+        start = self._starts.get(nodeid, now_ms())
+        end = now_ms()
+        suite = self._suites.setdefault(
+            file,
+            frames.suite_stats(uid=file, title=file, file=file,
+                               start_ms=start, tests=[]),
+        )
+        self._tests[nodeid] = frames.test_stats(
+            uid=nodeid,
+            title=name,
+            full_title=f"{file} › {name}",
+            parent=file,
+            state=state,
+            file=file,
+            start_ms=start,
+            end_ms=end,
+            call_source=f"{file}:{line + 1}",
+        )
+        suite["tests"] = [t for nid, t in self._tests.items()
+                          if nid.split("::", 1)[0] == file]
+        suite["end"] = self._tests[nodeid]["end"]
+        suite["state"] = "failed" if any(
+            t["state"] == "failed" for t in suite["tests"]
+        ) else state
+
+    def snapshot(self) -> list:
+        return list(self._suites.values())
+
+
+_registry = _SuiteRegistry()
+
+# Note: test-file source capture for the Source tab lives in instrumentation.py
+# (keyed by each command's callSource path), so it works for plain scripts too —
+# not just pytest. The plugin only owns the suite/test tree.
+
+
+def pytest_configure(config) -> None:  # noqa: ANN001
+    if _opted_in():
+        capturer = devtools.enable()
+        # pytest owns the suite tree — suppress the adapter's default script suite.
+        from . import instrumentation
+
+        instrumentation.set_external_suites(True)
+        url = devtools.dashboard_url()
+        if capturer is not None and url:
+            print(f"\n[devtools] dashboard live at {url}\n")
+
+
+def pytest_runtest_logstart(nodeid, location) -> None:  # noqa: ANN001
+    if _opted_in():
+        _registry.mark_start(nodeid)
+
+
+def pytest_runtest_logreport(report) -> None:  # noqa: ANN001
+    if not _opted_in():
+        return
+    capturer = devtools.get_capturer()
+    if capturer is None:
+        return
+    # 'call' carries pass/fail; a skip surfaces at 'setup'.
+    if report.when == "call" or (report.when == "setup" and report.skipped):
+        state = (
+            "skipped" if report.skipped
+            else "passed" if report.passed
+            else "failed"
+        )
+        file, line, name = report.location
+        _registry.record(report.nodeid, file, name, line or 0, state)
+        capturer.send_suites(_registry.snapshot())
+
+
+def pytest_sessionfinish(session, exitstatus) -> None:  # noqa: ANN001
+    if not _opted_in():
+        return
+    capturer = devtools.get_capturer()
+    if capturer is not None:
+        capturer.send_suites(_registry.snapshot())
+    # Keep the dashboard open for inspection after the run — exit when the user
+    # closes the window (clientDisconnected). Only when we actually opened a
+    # window; CI (DEVTOOLS_OPEN=0) tears down immediately.
+    from . import lifecycle
+
+    if lifecycle.dashboard_window_open():
+        print(
+            "\n[devtools] dashboard is live — close the window to finish "
+            "(Ctrl-C also works).\n"
+        )
+        lifecycle.wait_for_shutdown()
+    devtools.disable()
diff --git a/packages/selenium-devtools-py/src/selenium_devtools/screencast.py b/packages/selenium-devtools-py/src/selenium_devtools/screencast.py
new file mode 100644
index 00000000..5c515659
--- /dev/null
+++ b/packages/selenium-devtools-py/src/selenium_devtools/screencast.py
@@ -0,0 +1,218 @@
+"""Screencast recorder — the Python analogue of core's ``ScreencastRecorderBase``.
+
+Frames are captured **synchronously on the main thread, one per command**
+(``driver.get_screenshot_as_base64()``), driven from the instrumentation hook.
+A background poll thread is deliberately NOT used: Selenium's session is not
+thread-safe, and a screenshot fired from a daemon thread races the main thread's
+commands and DOM-trace readback on the same connection — corrupting both the
+video and the snapshot. The reference JS adapters avoid this too (CDP push-mode
+screencast / per-command screenshots on the command queue), so we mirror that.
+
+On ``stop`` the buffered frames are encoded to a ``.webm`` via ffmpeg *if it's on
+PATH* — ffmpeg is an optional dependency, so its absence is a one-line warning
+and a skipped encode, never an error.
+
+A CDP push-mode fast-path (Chrome ``Page.startScreencast`` via
+``execute_cdp_cmd``) is a future optimization — noted here, not implemented;
+per-command capture works on every browser selenium drives.
+
+Everything is defensive: a transient screenshot failure (e.g. mid-navigation) is
+skipped and recording continues; a recorder that never captured a frame encodes
+nothing. Capture never breaks the user's test.
+"""
+
+from __future__ import annotations
+
+import os
+import shutil
+import subprocess
+import sys
+import tempfile
+from typing import Any, Callable, List, Optional
+
+from .constants import SCREENCAST_IMAGE_FORMAT, SCREENCAST_MIN_FRAMES
+from .output_dir import OUTPUT_SUBDIR, ensure_output_dir
+from .types import ScreencastFrame
+from .utils import now_ms
+
+#: Screenshot fn signature — injectable so tests drive the buffer without a
+#: real driver. Returns a base64 PNG string, or None on a transient failure.
+ScreenshotFn = Callable[[], Optional[str]]
+
+
+def _warn(message: str) -> None:
+    print(f"[devtools] screencast: {message}", file=sys.stderr)
+
+
+class ScreencastRecorder:
+    def __init__(self, *, ffmpeg_path: Optional[str] = None) -> None:
+        # Resolve ffmpeg once; None means "encoding unavailable, skip it".
+        self._ffmpeg = ffmpeg_path or shutil.which("ffmpeg")
+        self._frames: List[ScreencastFrame] = []
+        self._screenshot: Optional[ScreenshotFn] = None
+        self._active = False
+
+    # ── public API ────────────────────────────────────────────────────────────
+
+    def start(self, driver: Any, screenshot_fn: Optional[ScreenshotFn] = None) -> None:
+        """Arm the recorder and capture a seed frame. ``screenshot_fn`` is
+        injectable for tests; by default it reads
+        ``driver.get_screenshot_as_base64``. Frames are captured on the main
+        thread via :meth:`capture` — no background polling. Safe to call twice."""
+        if self._active:
+            return
+        if screenshot_fn is not None:
+            self._screenshot = screenshot_fn
+        elif driver is not None and hasattr(driver, "get_screenshot_as_base64"):
+            self._screenshot = driver.get_screenshot_as_base64
+        else:
+            _warn("driver has no get_screenshot_as_base64 — recording skipped")
+            return
+        self._active = True
+        self.capture()  # best-effort seed frame
+
+    def capture(self) -> bool:
+        """Capture one frame synchronously (main thread). No-op if not armed.
+
+        A transient failure — a screenshot taken mid-navigation, a dead session
+        — is skipped and recording stays armed, so a single miss never truncates
+        the video the way a background poll loop would. Returns True iff a frame
+        was buffered."""
+        if not self._active:
+            return False
+        fn = self._screenshot
+        if fn is None:
+            return False
+        try:
+            data = fn()
+        except Exception:  # noqa: BLE001 — transient miss; keep recording
+            return False
+        if isinstance(data, str) and data:
+            self._frames.append({"data": data, "timestamp": now_ms()})
+            return True
+        return False
+
+    def add_frame(self, data: Optional[str]) -> bool:
+        """Buffer a frame from an ALREADY-captured base64 screenshot — lets the
+        caller reuse the per-command screenshot it took for the command entry
+        instead of paying for a second screenshot round-trip. No-op if not armed
+        or the data is empty. Returns True iff a frame was buffered."""
+        if not self._active or not isinstance(data, str) or not data:
+            return False
+        self._frames.append({"data": data, "timestamp": now_ms()})
+        return True
+
+    def stop(self) -> None:
+        """Disarm the recorder. Idempotent; safe even if start() never ran."""
+        self._active = False
+
+    @property
+    def frames(self) -> List[ScreencastFrame]:
+        return list(self._frames)
+
+    @property
+    def duration(self) -> int:
+        """ms between first and last frame; 0 with fewer than 2 frames."""
+        if len(self._frames) < 2:
+            return 0
+        return self._frames[-1]["timestamp"] - self._frames[0]["timestamp"]
+
+    @property
+    def is_recording(self) -> bool:
+        return self._active
+
+    # ── finalize ──────────────────────────────────────────────────────────────
+
+    def finalize(
+        self,
+        session_id: str,
+        output_dir: Optional[str] = None,
+        *,
+        min_frames: int = SCREENCAST_MIN_FRAMES,
+        filename_prefix: str = "selenium-py-video",
+    ) -> Optional[dict]:
+        """Stop, encode the buffered frames to a ``.webm``, and return the
+        ``{video_path, video_file, frame_count, duration, start_time}`` metadata
+        the capturer forwards — or None if there's nothing to encode / ffmpeg is
+        absent. All failures are caught: screencast is best-effort."""
+        self.stop()
+        frames = self.frames
+        if len(frames) < min_frames:
+            return None
+        if not self._ffmpeg:
+            _warn("ffmpeg not found on PATH — skipping video encode "
+                  f"({len(frames)} frame(s) captured)")
+            return None
+
+        file_name = f"{filename_prefix}-{session_id}.webm"
+        target_dir = _writable_dir(output_dir)
+        video_path = os.path.join(target_dir, file_name)
+        try:
+            _encode_webm(frames, video_path, self._ffmpeg)
+        except Exception as exc:  # noqa: BLE001 — encode failure must not abort
+            _warn(f"encode failed: {exc}")
+            return None
+        return {
+            "video_path": video_path,
+            "video_file": file_name,
+            "frame_count": len(frames),
+            "duration": self.duration,
+            "start_time": frames[0]["timestamp"] if frames else None,
+        }
+
+
+def _writable_dir(preferred: Optional[str]) -> str:
+    """The directory to encode into. ``preferred`` is the resolved
+    ``test-results`` path, which will not exist on a first run, so it is created
+    here; a failure falls back to the temp dir rather than losing the video."""
+    candidate = preferred or os.path.join(os.getcwd(), OUTPUT_SUBDIR)
+    created = ensure_output_dir(candidate)
+    if created:
+        return created
+    return tempfile.gettempdir()
+
+
+def _encode_webm(frames: List[ScreencastFrame], output_path: str, ffmpeg: str) -> None:
+    """Encode base64 frames to a VP8/WebM via ffmpeg's concat demuxer, giving
+    each frame its real inter-frame duration (VFR reflects command pauses).
+    Forces CFR 10fps + all-intra so the dashboard ``<video>`` can seek —
+    mirrors core/video-encoder.ts."""
+    import base64
+
+    ext = SCREENCAST_IMAGE_FORMAT
+    tmp_dir = tempfile.mkdtemp(prefix="devtools-screencast-")
+    try:
+        manifest_lines = ["ffconcat version 1.0"]
+        for i, frame in enumerate(frames):
+            frame_path = os.path.join(tmp_dir, f"frame-{i:06d}.{ext}")
+            with open(frame_path, "wb") as fh:
+                fh.write(base64.b64decode(frame["data"]))
+            next_ts = (
+                frames[i + 1]["timestamp"]
+                if i + 1 < len(frames)
+                else frame["timestamp"] + 100
+            )
+            duration_s = max((next_ts - frame["timestamp"]) / 1000.0, 0.01)
+            manifest_lines.append(f"file '{frame_path}'")
+            manifest_lines.append(f"duration {duration_s:.6f}")
+        # ffconcat drops the final duration without a trailing file line.
+        last_path = os.path.join(tmp_dir, f"frame-{len(frames) - 1:06d}.{ext}")
+        manifest_lines.append(f"file '{last_path}'")
+        manifest_path = os.path.join(tmp_dir, "manifest.txt")
+        with open(manifest_path, "w") as fh:
+            fh.write("\n".join(manifest_lines))
+
+        subprocess.run(
+            [
+                ffmpeg, "-y",
+                "-f", "concat", "-safe", "0", "-i", manifest_path,
+                "-c:v", "libvpx", "-b:v", "1M", "-pix_fmt", "yuv420p",
+                "-vsync", "cfr", "-r", "10",
+                "-g", "1", "-keyint_min", "1", "-auto-alt-ref", "0",
+                output_path,
+            ],
+            check=True,
+            capture_output=True,
+        )
+    finally:
+        shutil.rmtree(tmp_dir, ignore_errors=True)
diff --git a/packages/selenium-devtools-py/src/selenium_devtools/snapshot.py b/packages/selenium-devtools-py/src/selenium_devtools/snapshot.py
new file mode 100644
index 00000000..a6f4cf23
--- /dev/null
+++ b/packages/selenium-devtools-py/src/selenium_devtools/snapshot.py
@@ -0,0 +1,197 @@
+"""DOM snapshot capture — the Python analogue of core's page-side trace path.
+
+The dashboard's center "browser preview" panel replays the page by applying a
+stream of DOM mutations captured in the browser. Those mutations come from the
+``packages/script`` runtime (``window.wdioTraceCollector``): we inject it once,
+then periodically read the buffered ``getTraceData()`` back and forward the
+``mutations`` array via ``capturer.send_mutations``.
+
+Mirrors ``core/script-loader.ts`` (``loadInjectableScript``) and
+``selenium-devtools/session.ts`` (``injectScript`` / ``captureTrace``). The JS
+adapter injects via ``document.createElement('script')`` rather than a BiDi
+preload, and reads back with a single atomic ``executeScript`` — we do the same.
+
+The script-path resolution and ``execute_script`` calls are injectable so the
+pure logic (path resolution, IIFE wrapping, payload normalization) unit-tests
+without selenium or a real browser. Everything is defensive: an injection or
+readback failure is a logged no-op — capture never breaks the user's test.
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+from typing import Any, Callable, List, Optional
+
+#: A ``driver.execute_script(script, *args)`` shaped callable — injectable so
+#: tests drive injection/readback without a real driver.
+ExecuteFn = Callable[..., Any]
+
+#: Installs the collector: append a <script> whose body is the injected IIFE,
+#: matching selenium-devtools/session.ts. ``arguments[0]`` is the script text.
+_INJECT_SCRIPT = (
+    "var s=document.createElement('script');"
+    "s.textContent=arguments[0];"
+    "document.head.appendChild(s);"
+    "return true;"
+)
+
+#: Atomic check+read: the collector may vanish (navigation) between an
+#: existence check and the read, so both happen in one eval — mirrors the
+#: TOCTOU fix in selenium-devtools/session.ts.
+_READ_TRACE_SCRIPT = (
+    'return typeof window.wdioTraceCollector !== "undefined"'
+    " ? window.wdioTraceCollector.getTraceData() : null;"
+)
+
+#: Cheap readiness probe used after injection.
+_READY_SCRIPT = 'return typeof window.wdioTraceCollector !== "undefined";'
+
+#: Session-lost signatures — expected during teardown, so silenced rather than
+#: logged (matches the JS adapter's error filter).
+_QUIET_ERRORS = ("ECONNREFUSED", "no such session", "invalid session id")
+
+
+def _warn(message: str) -> None:
+    print(f"[devtools] snapshot: {message}", file=sys.stderr)
+
+
+def _is_quiet_error(exc: BaseException) -> bool:
+    text = str(exc)
+    return any(marker in text for marker in _QUIET_ERRORS)
+
+
+def resolve_script_path() -> Optional[str]:
+    """Locate ``packages/script/dist/script.js`` in the monorepo, or None.
+
+    There's no cross-ecosystem resolver from Python, so walk up from this file
+    to the repo root and look for the built browser runtime. Returns None when
+    it isn't built yet — injection then becomes a no-op rather than an error.
+    """
+    here = os.path.dirname(os.path.abspath(__file__))
+    directory = here
+    while True:
+        candidate = os.path.join(directory, "packages", "script", "dist", "script.js")
+        if os.path.isfile(candidate):
+            return candidate
+        parent = os.path.dirname(directory)
+        if parent == directory:
+            return None
+        directory = parent
+
+
+def wrap_injectable(script_content: str) -> str:
+    """Wrap the raw script body in an async IIFE so its top-level ``await``
+    works inside a plain ``<script>`` element — mirrors core's
+    ``loadInjectableScript``."""
+    return f"(async function() {{ {script_content} }})()"
+
+
+def load_injectable_script(path: Optional[str] = None) -> Optional[str]:
+    """Read the browser runtime and return the IIFE-wrapped source, or None if
+    it can't be found/read. Path is injectable so tests avoid disk."""
+    resolved = path or resolve_script_path()
+    if not resolved:
+        _warn("packages/script/dist/script.js not found — snapshot capture disabled")
+        return None
+    try:
+        with open(resolved, "r", encoding="utf-8") as handle:
+            content = handle.read()
+    except OSError as exc:
+        _warn(f"could not read injected script ({resolved}): {exc}")
+        return None
+    return wrap_injectable(content)
+
+
+def normalize_mutations(trace_data: Any) -> List[Any]:
+    """Extract the ``mutations`` list from a ``getTraceData()`` payload.
+
+    The page-side collector returns ``{errors, mutations, consoleLogs,
+    networkRequests, traceLogs, metadata}``; the snapshot panel only needs
+    ``mutations``. Anything else (None, missing key, non-list) normalizes to an
+    empty list so callers never have to guard.
+    """
+    if not isinstance(trace_data, dict):
+        return []
+    mutations = trace_data.get("mutations")
+    return mutations if isinstance(mutations, list) else []
+
+
+class SnapshotCapturer:
+    """Injects the page-side collector and pulls buffered DOM mutations.
+
+    ``execute_fn`` is injectable (defaults to ``driver.execute_script``) so the
+    injection/readback wrappers test without a real browser. State is minimal:
+    a one-shot "already injected" flag mirroring the JS adapter.
+    """
+
+    def __init__(self, execute_fn: ExecuteFn, *, script_path: Optional[str] = None) -> None:
+        self._execute = execute_fn
+        self._script_path = script_path
+        self._injected = False
+
+    @property
+    def injected(self) -> bool:
+        return self._injected
+
+    def inject(self) -> bool:
+        """Ensure ``window.wdioTraceCollector`` is present on the CURRENT page.
+
+        Navigation wipes the injected collector, so we probe the live page each
+        call and re-install if it's gone (matching the JS adapter, which injects
+        per navigation) rather than trusting a one-time flag. Failures are logged
+        no-ops."""
+        wrapped = load_injectable_script(self._script_path)
+        if wrapped is None:
+            return False
+        try:
+            if self._execute(_READY_SCRIPT) is True:
+                self._injected = True
+                return True
+        except BaseException as exc:  # noqa: BLE001 — probe failure → try install
+            if not _is_quiet_error(exc):
+                _warn(f"readiness probe failed: {exc}")
+        try:
+            self._execute(_INJECT_SCRIPT, wrapped)
+            ready = self._execute(_READY_SCRIPT)
+        except BaseException as exc:  # noqa: BLE001 — capture must never break the test
+            if not _is_quiet_error(exc):
+                _warn(f"injection failed: {exc}")
+            return False
+        self._injected = ready is True
+        if ready is not True:
+            _warn("collector not detected immediately after injection")
+        return self._injected
+
+    def pull_mutations(self) -> List[Any]:
+        """Read and drain the buffered mutations (``getTraceData()`` resets the
+        page-side buffer). Returns [] on any failure or when nothing's buffered."""
+        try:
+            trace_data = self._execute(_READ_TRACE_SCRIPT)
+        except BaseException as exc:  # noqa: BLE001
+            if not _is_quiet_error(exc):
+                _warn(f"trace read failed: {exc}")
+            return []
+        return normalize_mutations(trace_data)
+
+
+def start_snapshot_capture(
+    driver: Any,
+    *,
+    script_path: Optional[str] = None,
+    execute_fn: Optional[ExecuteFn] = None,
+) -> Optional[SnapshotCapturer]:
+    """Build a ``SnapshotCapturer`` and inject the collector. Returns the capturer
+    (so callers can pull later), or None if the driver can't run scripts /
+    injection fails. Never raises.
+
+    ``execute_fn`` overrides ``driver.execute_script`` — the adapter passes a
+    capture-bypassing variant so injection/readback don't appear as commands."""
+    run = execute_fn or getattr(driver, "execute_script", None)
+    if not callable(run):
+        _warn("driver has no execute_script — snapshot capture skipped")
+        return None
+    capturer = SnapshotCapturer(run, script_path=script_path)
+    if not capturer.inject():
+        return None
+    return capturer
diff --git a/packages/selenium-devtools-py/src/selenium_devtools/sources.py b/packages/selenium-devtools-py/src/selenium_devtools/sources.py
new file mode 100644
index 00000000..0d0989de
--- /dev/null
+++ b/packages/selenium-devtools-py/src/selenium_devtools/sources.py
@@ -0,0 +1,40 @@
+"""Read test-file source safely for the dashboard's Source tab.
+
+The Source tab matches a command's ``callSource`` (an absolute ``path:line``)
+against the keys of the ``sources`` map, so callers key by the same absolute
+path. Reads are size-capped, encoding-tolerant, and never raise.
+"""
+
+from __future__ import annotations
+
+import os
+from typing import Dict, Iterable, Optional
+
+# Cap matches the intent of the JS adapter: a test file, not a bundle. Anything
+# larger is almost certainly not the source the Source tab wants to show.
+MAX_SOURCE_BYTES = 2 * 1024 * 1024
+
+
+def read_source(path: str) -> Optional[str]:
+    """Return the file's text, or None if it is missing, oversized, or unreadable."""
+    try:
+        if not os.path.isfile(path):
+            return None
+        if os.path.getsize(path) > MAX_SOURCE_BYTES:
+            return None
+        with open(path, "r", encoding="utf-8", errors="replace") as handle:
+            return handle.read()
+    except OSError:
+        return None
+
+
+def collect_sources(paths: Iterable[str]) -> Dict[str, str]:
+    """Map each readable absolute path to its source text; skip the rest."""
+    result: Dict[str, str] = {}
+    for path in paths:
+        if not path or path in result:
+            continue
+        text = read_source(path)
+        if text is not None:
+            result[path] = text
+    return result
diff --git a/packages/selenium-devtools-py/src/selenium_devtools/terminal.py b/packages/selenium-devtools-py/src/selenium_devtools/terminal.py
new file mode 100644
index 00000000..12cba212
--- /dev/null
+++ b/packages/selenium-devtools-py/src/selenium_devtools/terminal.py
@@ -0,0 +1,79 @@
+"""Capture the test's ``print()`` output (stdout) and forward each line to the
+dashboard as a ``terminal`` console log, so a test's prints show up alongside
+browser logs. ``logging`` output is handled separately by ``logcapture`` (it
+usually goes to stderr), so we tee stdout only to avoid double-capturing logs.
+
+Tees stdout (still writes to the real terminal) and splits on newlines. The
+adapter's own ``[devtools]`` lines are skipped so they don't echo back.
+"""
+
+from __future__ import annotations
+
+import sys
+import threading
+from typing import Any, Callable, Optional
+
+# The adapter's own log lines carry this prefix — never re-capture them.
+_SELF_PREFIX = "[devtools]"
+
+
+class _TeeStream:
+    """Wraps a text stream: writes through to it AND emits complete lines."""
+
+    def __init__(self, original: Any, emit: Callable[[str], None]) -> None:
+        self._orig = original
+        self._emit = emit
+        self._buf = ""
+        self._lock = threading.Lock()
+
+    def write(self, text: str) -> int:
+        written = self._orig.write(text)
+        try:
+            with self._lock:
+                self._buf += text
+                while "\n" in self._buf:
+                    line, self._buf = self._buf.split("\n", 1)
+                    line = line.rstrip("\r")
+                    if line.strip() and not line.startswith(_SELF_PREFIX):
+                        self._emit(line)
+        except Exception:  # noqa: BLE001 — capture must never break the test's output
+            pass
+        return written
+
+    def flush(self) -> None:
+        self._orig.flush()
+
+    def __getattr__(self, name: str) -> Any:
+        # Delegate isatty/fileno/encoding/etc. to the wrapped stream.
+        return getattr(self._orig, name)
+
+
+class TerminalCapturer:
+    """Tees sys.stdout into the capturer as terminal console logs."""
+
+    def __init__(self, capturer: Any) -> None:
+        self._capturer = capturer
+        self._orig_out: Optional[Any] = None
+        self._emitting = False
+
+    def start(self) -> None:
+        if self._orig_out is not None:  # already started
+            return
+        self._orig_out = sys.stdout
+        sys.stdout = _TeeStream(self._orig_out, lambda ln: self._emit("log", ln))
+
+    def stop(self) -> None:
+        if self._orig_out is not None:
+            sys.stdout = self._orig_out
+            self._orig_out = None
+
+    def _emit(self, level: str, line: str) -> None:
+        if self._emitting:  # guard against re-entry if forwarding writes anything
+            return
+        self._emitting = True
+        try:
+            self._capturer.capture_console(level, [line], source="terminal")
+        except Exception:  # noqa: BLE001
+            pass
+        finally:
+            self._emitting = False
diff --git a/packages/selenium-devtools-py/src/selenium_devtools/transport.py b/packages/selenium-devtools-py/src/selenium_devtools/transport.py
new file mode 100644
index 00000000..6cc3f1b3
--- /dev/null
+++ b/packages/selenium-devtools-py/src/selenium_devtools/transport.py
@@ -0,0 +1,188 @@
+"""Dependency-free WebSocket client for the adapter→backend ``/worker`` link.
+
+A hardened version of the Phase-0 spike's client: RFC-6455 handshake, masked
+client text frames, plus a background reader thread that handles ping/pong and
+surfaces the backend's control frames (``clientConnected`` / ``clientDisconnected``)
+to a callback. No third-party dependency — the only runtime requirement the
+adapter adds on top of selenium itself.
+"""
+
+from __future__ import annotations
+
+import base64
+import json
+import os
+import socket
+import struct
+import threading
+from typing import Callable, Optional
+
+from .constants import CONNECT_TIMEOUT_S, WORKER_PATH
+
+
+class WSClient:
+    def __init__(
+        self,
+        host: str,
+        port: int,
+        path: str = WORKER_PATH,
+        on_control: Optional[Callable[[str, dict], None]] = None,
+    ) -> None:
+        self.host = host
+        self.port = port
+        self.path = path
+        self._on_control = on_control
+        self._sock: Optional[socket.socket] = None
+        self._send_lock = threading.Lock()
+        self._reader: Optional[threading.Thread] = None
+        self._stop = threading.Event()
+        self.connected = False
+
+    # ── lifecycle ────────────────────────────────────────────────────────────
+
+    def connect(self, timeout: float = CONNECT_TIMEOUT_S) -> None:
+        sock = socket.create_connection((self.host, self.port), timeout=timeout)
+        key = base64.b64encode(os.urandom(16)).decode()
+        sock.sendall(
+            (
+                f"GET {self.path} HTTP/1.1\r\n"
+                f"Host: {self.host}:{self.port}\r\n"
+                "Upgrade: websocket\r\n"
+                "Connection: Upgrade\r\n"
+                f"Sec-WebSocket-Key: {key}\r\n"
+                "Sec-WebSocket-Version: 13\r\n"
+                "\r\n"
+            ).encode()
+        )
+        buf = b""
+        while b"\r\n\r\n" not in buf:
+            chunk = sock.recv(1024)
+            if not chunk:
+                raise ConnectionError("backend closed during handshake")
+            buf += chunk
+        status = buf.split(b"\r\n", 1)[0].decode(errors="replace")
+        if "101" not in status:
+            raise ConnectionError(f"websocket upgrade failed: {status!r}")
+
+        sock.settimeout(1.0)  # so the reader can poll the stop flag
+        self._sock = sock
+        self.connected = True
+        self._reader = threading.Thread(target=self._read_loop, daemon=True)
+        self._reader.start()
+
+    def close(self) -> None:
+        self._stop.set()
+        sock = self._sock
+        if sock is not None:
+            try:
+                self._send_frame(0x8, b"")  # close
+            except OSError:
+                pass
+            try:
+                sock.close()
+            except OSError:
+                pass
+        reader = self._reader
+        # Don't join the reader from within itself — close() can be called on the
+        # reader thread (a clientDisconnected control frame triggering shutdown).
+        if reader is not None and reader is not threading.current_thread():
+            reader.join(timeout=2.0)
+        self.connected = False
+
+    # ── sending ──────────────────────────────────────────────────────────────
+
+    def send_json(self, scope: str, data) -> bool:
+        """Send one ``{scope, data}`` frame. Returns False if not connected —
+        mirrors the JS capturer's silent-drop-on-disconnect behavior."""
+        if not self.connected or self._sock is None:
+            return False
+        try:
+            self._send_frame(0x1, json.dumps({"scope": scope, "data": data}).encode())
+            return True
+        except OSError:
+            self.connected = False
+            return False
+
+    def _send_frame(self, opcode: int, payload: bytes) -> None:
+        header = bytearray([0x80 | opcode])
+        n = len(payload)
+        if n < 126:
+            header.append(0x80 | n)
+        elif n < 65536:
+            header.append(0x80 | 126)
+            header += struct.pack(">H", n)
+        else:
+            header.append(0x80 | 127)
+            header += struct.pack(">Q", n)
+        mask = os.urandom(4)
+        header += mask
+        masked = bytes(b ^ mask[i % 4] for i, b in enumerate(payload))
+        with self._send_lock:
+            assert self._sock is not None
+            self._sock.sendall(bytes(header) + masked)
+
+    # ── receiving ──────────────────────────────────────────────────────────────
+
+    def _recv_exact(self, n: int) -> Optional[bytes]:
+        buf = b""
+        while len(buf) < n:
+            if self._stop.is_set():
+                return None
+            try:
+                chunk = self._sock.recv(n - len(buf))  # type: ignore[union-attr]
+            except socket.timeout:
+                continue
+            except OSError:
+                return None
+            if not chunk:
+                return None
+            buf += chunk
+        return buf
+
+    def _read_loop(self) -> None:
+        while not self._stop.is_set():
+            head = self._recv_exact(2)
+            if head is None:
+                break
+            opcode = head[0] & 0x0F
+            masked = bool(head[1] & 0x80)
+            length = head[1] & 0x7F
+            if length == 126:
+                ext = self._recv_exact(2)
+                if ext is None:
+                    break
+                length = struct.unpack(">H", ext)[0]
+            elif length == 127:
+                ext = self._recv_exact(8)
+                if ext is None:
+                    break
+                length = struct.unpack(">Q", ext)[0]
+            mask = self._recv_exact(4) if masked else None
+            payload = self._recv_exact(length) if length else b""
+            if payload is None:
+                break
+            if mask:
+                payload = bytes(b ^ mask[i % 4] for i, b in enumerate(payload))
+
+            if opcode == 0x8:  # close
+                break
+            if opcode == 0x9:  # ping → pong
+                try:
+                    self._send_frame(0xA, payload)
+                except OSError:
+                    break
+                continue
+            if opcode in (0x1, 0x2):  # text / binary
+                self._dispatch(payload)
+        self.connected = False
+
+    def _dispatch(self, payload: bytes) -> None:
+        if self._on_control is None:
+            return
+        try:
+            msg = json.loads(payload.decode("utf-8"))
+        except (ValueError, UnicodeDecodeError):
+            return
+        scope = msg.get("scope")
+        if isinstance(scope, str):
+            self._on_control(scope, msg.get("data") or {})
diff --git a/packages/selenium-devtools-py/src/selenium_devtools/types.py b/packages/selenium-devtools-py/src/selenium_devtools/types.py
new file mode 100644
index 00000000..ce477f41
--- /dev/null
+++ b/packages/selenium-devtools-py/src/selenium_devtools/types.py
@@ -0,0 +1,115 @@
+"""Wire payload types — the Python mirror of ``packages/shared/src/types.ts``.
+
+TypedDicts document the ``data`` payload shapes behind each ``{scope, data}``
+frame the dashboard consumes. They're structural (plain dicts at runtime); the
+value is a single typed definition per concept, checkable by mypy.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict, List, Optional, TypedDict, Union
+
+#: Anything that survives ``json.dumps``. Payloads must reduce to this.
+JSONValue = Union[
+    None, bool, int, float, str, List["JSONValue"], Dict[str, "JSONValue"]
+]
+
+#: A ``{scope, data}`` frame's scope — a value from the generated ``_contract``.
+Scope = str
+
+
+class SerializedError(TypedDict):
+    name: str
+    message: str
+
+
+class CommandLog(TypedDict, total=False):
+    command: str
+    args: List[Any]
+    result: Any
+    error: SerializedError
+    timestamp: int
+    startTime: int
+    callSource: Optional[str]
+    id: int
+    screenshot: str
+
+
+class ConsoleLog(TypedDict):
+    type: str
+    args: List[Any]
+    timestamp: int
+    source: str
+
+
+class NetworkRequest(TypedDict, total=False):
+    id: str
+    url: str
+    method: str
+    status: Optional[int]
+    statusText: str
+    timestamp: int
+    startTime: int
+    endTime: Optional[int]
+    time: int
+    size: int
+    type: str
+    requestHeaders: Dict[str, str]
+    responseHeaders: Dict[str, str]
+
+
+class ScreencastFrame(TypedDict):
+    #: Base64-encoded image (PNG in polling mode). No data URI prefix.
+    data: str
+    #: Capture time, epoch milliseconds.
+    timestamp: int
+
+
+class ScreencastInfo(TypedDict, total=False):
+    sessionId: str
+    videoPath: str
+    videoFile: str
+    frameCount: int
+    duration: int
+    startTime: int
+
+
+class Metadata(TypedDict, total=False):
+    type: str
+    sessionId: str
+    url: Optional[str]
+    capabilities: Dict[str, Any]
+    desiredCapabilities: Dict[str, Any]
+    testEnv: str
+
+
+class TestStats(TypedDict, total=False):
+    uid: str
+    cid: str
+    title: str
+    fullTitle: str
+    parent: str
+    state: str
+    start: str
+    end: str
+    type: str
+    file: str
+    retries: int
+    _duration: int
+    callSource: Optional[str]
+
+
+class SuiteStats(TypedDict, total=False):
+    uid: str
+    cid: str
+    title: str
+    fullTitle: str
+    type: str
+    file: str
+    start: str
+    end: Optional[str]
+    state: Optional[str]
+    tests: List[TestStats]
+    suites: List["SuiteStats"]
+    hooks: List[Any]
+    _duration: int
diff --git a/packages/selenium-devtools-py/src/selenium_devtools/utils.py b/packages/selenium-devtools-py/src/selenium_devtools/utils.py
new file mode 100644
index 00000000..b9cfdbe2
--- /dev/null
+++ b/packages/selenium-devtools-py/src/selenium_devtools/utils.py
@@ -0,0 +1,52 @@
+"""Small framework-agnostic helpers. No third-party imports."""
+
+from __future__ import annotations
+
+import json
+import time
+import traceback
+from typing import Any, Iterable
+
+
+def now_ms() -> int:
+    """Epoch milliseconds — the timestamp unit every frame uses."""
+    return int(time.time() * 1000)
+
+
+def iso(ms: int) -> str:
+    """ISO-8601 string. SuiteStats.start/end are TS Dates on the wire."""
+    base = time.strftime("%Y-%m-%dT%H:%M:%S", time.gmtime(ms / 1000))
+    return f"{base}.{ms % 1000:03d}Z"
+
+
+def to_jsonable(value: Any, _depth: int = 0) -> Any:
+    """Coerce an arbitrary value into something json.dumps can handle.
+
+    Selenium command params/results may carry WebElement refs or other
+    non-serializable objects; the wire only speaks JSON, so anything exotic
+    degrades to its string form rather than blowing up the send.
+    """
+    if value is None or isinstance(value, (bool, int, float, str)):
+        return value
+    if _depth > 6:
+        return str(value)
+    if isinstance(value, dict):
+        return {str(k): to_jsonable(v, _depth + 1) for k, v in value.items()}
+    if isinstance(value, (list, tuple)):
+        return [to_jsonable(v, _depth + 1) for v in value]
+    try:
+        json.dumps(value)
+        return value
+    except (TypeError, ValueError):
+        return str(value)
+
+
+def call_source(skip_substrings: Iterable[str]) -> str | None:
+    """First stack frame outside the adapter + selenium internals, as
+    ``path:line`` — what the dashboard shows as the command's origin."""
+    skips = tuple(skip_substrings)
+    # Innermost-last; walk outward (reversed) to find the user's frame.
+    for frame in reversed(traceback.extract_stack()[:-1]):
+        if not any(s in frame.filename for s in skips):
+            return f"{frame.filename}:{frame.lineno}"
+    return None
diff --git a/packages/selenium-devtools-py/tests/test_backend.py b/packages/selenium-devtools-py/tests/test_backend.py
new file mode 100644
index 00000000..9ee79e1c
--- /dev/null
+++ b/packages/selenium-devtools-py/tests/test_backend.py
@@ -0,0 +1,71 @@
+import os
+import tempfile
+import unittest
+from pathlib import Path
+
+from selenium_devtools import backend
+
+
+class TestBackendResolution(unittest.TestCase):
+    def setUp(self):
+        self._saved = {k: os.environ.get(k) for k in
+                       ("DEVTOOLS_PORT", "DEVTOOLS_HOST", "DEVTOOLS_BACKEND_CMD")}
+        for k in self._saved:
+            os.environ.pop(k, None)
+
+    def tearDown(self):
+        for k, v in self._saved.items():
+            if v is None:
+                os.environ.pop(k, None)
+            else:
+                os.environ[k] = v
+
+    def test_port_regex_uses_actual_listening_port(self):
+        # The preferred "Starting … on port 3000" line must NOT match — it's not
+        # the bound port when 3000 is busy.
+        self.assertIsNone(
+            backend._PORT_RE.search("Starting application on port 3000")
+        )
+        # The Fastify "Server listening at …:PORT" line is the real port,
+        # including the IPv6 form.
+        self.assertEqual(
+            backend._PORT_RE.search(
+                '{"msg":"Server listening at http://[::1]:63763"}'
+            ).group(1),
+            "63763",
+        )
+        self.assertEqual(
+            backend._PORT_RE.search("Server listening at http://127.0.0.1:3000").group(1),
+            "3000",
+        )
+
+    def test_attaches_when_port_env_set_without_spawning(self):
+        os.environ["DEVTOOLS_PORT"] = "4321"
+        os.environ["DEVTOOLS_HOST"] = "example.test"
+        host, port, proc = backend.launch_or_attach()
+        self.assertEqual((host, port), ("example.test", 4321))
+        self.assertIsNone(proc)  # attached, not owned
+
+    def test_finds_monorepo_backend_when_present(self):
+        with tempfile.TemporaryDirectory() as tmp:
+            dist = Path(tmp) / "packages" / "backend" / "dist"
+            dist.mkdir(parents=True)
+            (dist / "server.js").write_text("//")
+            start = Path(tmp) / "a" / "b" / "mod.py"
+            start.parent.mkdir(parents=True)
+            self.assertEqual(
+                backend._find_monorepo_backend(start=start), dist / "server.js"
+            )
+
+    def test_no_monorepo_backend_when_absent(self):
+        with tempfile.TemporaryDirectory() as tmp:
+            start = Path(tmp) / "x" / "y.py"
+            start.parent.mkdir(parents=True)
+            self.assertIsNone(backend._find_monorepo_backend(start=start))
+
+    def test_pinned_backend_version_is_set(self):
+        self.assertRegex(backend.BACKEND_NPM_VERSION, r"^\d+\.\d+\.\d+$")
+
+
+if __name__ == "__main__":
+    unittest.main()
diff --git a/packages/selenium-devtools-py/tests/test_bidi.py b/packages/selenium-devtools-py/tests/test_bidi.py
new file mode 100644
index 00000000..894619d3
--- /dev/null
+++ b/packages/selenium-devtools-py/tests/test_bidi.py
@@ -0,0 +1,374 @@
+import unittest
+
+from selenium_devtools import bidi
+from selenium_devtools.capturer import SessionCapturer
+
+
+class FakeTransport:
+    connected = True
+
+    def __init__(self):
+        self.sent = []
+
+    def send_json(self, scope, data):
+        self.sent.append((scope, data))
+        return True
+
+    def close(self):
+        pass
+
+
+class FakeLogEntry:
+    """Mimics selenium's ConsoleLogEntry/JavaScriptLogEntry dataclass."""
+
+    def __init__(self, level, text, method=None, args=None, stacktrace=None):
+        self.level = level
+        self.text = text
+        if method is not None:
+            self.method = method
+        if args is not None:
+            self.args = args
+        if stacktrace is not None:
+            self.stacktrace = stacktrace
+
+
+def _string(value):
+    return {"type": "string", "value": value}
+
+
+def _number(value):
+    return {"type": "number", "value": value}
+
+
+class TestConsoleMapping(unittest.TestCase):
+    def test_normalize_level_maps_and_falls_back(self):
+        self.assertEqual(bidi.normalize_level("SEVERE"), "error")
+        self.assertEqual(bidi.normalize_level("warning"), "warn")
+        self.assertEqual(bidi.normalize_level("info"), "info")
+        self.assertEqual(bidi.normalize_level("mystery"), "log")
+        self.assertEqual(bidi.normalize_level(None), "log")
+
+    def test_console_kwargs_from_object_text_fallback(self):
+        # No args on the entry -> falls back to .text as a single-element list.
+        level, args = bidi.console_kwargs(FakeLogEntry("error", "boom"))
+        self.assertEqual(level, "error")
+        self.assertEqual(args, ["boom"])
+
+    def test_console_kwargs_from_dict_message_fallback(self):
+        level, args = bidi.console_kwargs({"level": "warning", "message": "hi"})
+        self.assertEqual(level, "warn")
+        self.assertEqual(args, ["hi"])
+
+    def test_console_kwargs_captures_all_args(self):
+        # console.log('a', {b:1}, 42) -> args come through as RemoteValues.
+        entry = {
+            "level": "info",
+            "method": "log",
+            "text": "a [object Object] 42",  # BiDi's flattened text
+            "args": [
+                _string("a"),
+                {"type": "object", "value": [[_string("b"), _number(1)]]},
+                _number(42),
+            ],
+        }
+        level, args = bidi.console_kwargs(entry)
+        self.assertEqual(level, "log")
+        self.assertEqual(args, ["a", {"b": 1}, 42])
+
+    def test_console_kwargs_prefers_method_over_level(self):
+        # BiDi 'level' is coarse (only debug/info/warn/error); 'method' is exact.
+        entry = {"level": "info", "method": "debug", "args": [_string("d")]}
+        level, args = bidi.console_kwargs(entry)
+        self.assertEqual(level, "debug")
+        self.assertEqual(args, ["d"])
+
+    def test_console_kwargs_each_level(self):
+        cases = {
+            "log": "log",
+            "info": "info",
+            "warn": "warn",
+            "warning": "warn",
+            "error": "error",
+            "debug": "debug",
+            "trace": "trace",
+        }
+        for method, expected in cases.items():
+            entry = {"method": method, "args": [_string("x")]}
+            level, args = bidi.console_kwargs(entry)
+            self.assertEqual(level, expected, f"method={method}")
+            self.assertEqual(args, ["x"])
+
+    def test_console_kwargs_empty_args_not_replaced_by_text(self):
+        # A real console.log() with no arguments -> empty list, no text fallback.
+        entry = {"method": "log", "text": "should-not-appear", "args": []}
+        level, args = bidi.console_kwargs(entry)
+        self.assertEqual(level, "log")
+        self.assertEqual(args, [])
+
+
+class TestRemoteValueDeserialization(unittest.TestCase):
+    def test_primitives(self):
+        self.assertEqual(bidi.remote_value_to_py(_string("hi")), "hi")
+        self.assertEqual(bidi.remote_value_to_py(_number(7)), 7)
+        self.assertEqual(
+            bidi.remote_value_to_py({"type": "boolean", "value": True}), True
+        )
+        self.assertIsNone(bidi.remote_value_to_py({"type": "null"}))
+        self.assertIsNone(bidi.remote_value_to_py({"type": "undefined"}))
+
+    def test_bigint_parsed(self):
+        self.assertEqual(
+            bidi.remote_value_to_py({"type": "bigint", "value": "12345678901234567890"}),
+            12345678901234567890,
+        )
+
+    def test_array_and_object_nested(self):
+        arr = {"type": "array", "value": [_string("a"), _number(1)]}
+        self.assertEqual(bidi.remote_value_to_py(arr), ["a", 1])
+        obj = {
+            "type": "object",
+            "value": [[_string("k"), {"type": "array", "value": [_number(2)]}]],
+        }
+        self.assertEqual(bidi.remote_value_to_py(obj), {"k": [2]})
+
+    def test_non_remote_value_passthrough(self):
+        self.assertEqual(bidi.remote_value_to_py("plain"), "plain")
+        self.assertEqual(bidi.remote_value_to_py(42), 42)
+        self.assertEqual(bidi.remote_value_to_py({"no": "type"}), {"no": "type"})
+
+
+class TestJsErrorMapping(unittest.TestCase):
+    def test_js_error_is_error_level_with_message(self):
+        level, args = bidi.js_error_kwargs({"level": "error", "text": "boom"})
+        self.assertEqual(level, "error")
+        self.assertEqual(args, ["boom"])
+
+    def test_js_error_includes_stacktrace(self):
+        entry = {
+            "text": "ReferenceError: x is not defined",
+            "stacktrace": {
+                "callFrames": [
+                    {
+                        "functionName": "doThing",
+                        "url": "https://x/app.js",
+                        "lineNumber": 12,
+                        "columnNumber": 5,
+                    }
+                ]
+            },
+        }
+        level, args = bidi.js_error_kwargs(entry)
+        self.assertEqual(level, "error")
+        self.assertEqual(len(args), 1)
+        self.assertIn("ReferenceError: x is not defined", args[0])
+        self.assertIn("at doThing (https://x/app.js:12:5)", args[0])
+
+    def test_js_error_object_entry(self):
+        level, args = bidi.js_error_kwargs(FakeLogEntry("error", "kaboom"))
+        self.assertEqual(level, "error")
+        self.assertEqual(args, ["kaboom"])
+
+    def test_js_error_no_stack_is_message_only(self):
+        level, args = bidi.js_error_kwargs({"text": "oops", "stacktrace": None})
+        self.assertEqual(args, ["oops"])
+
+
+class TestNetworkMapping(unittest.TestCase):
+    def test_request_sent_kwargs_shape(self):
+        params = {
+            "request": {
+                "request": "req-1",
+                "url": "https://x/app.js",
+                "method": "GET",
+                "headers": [{"name": "Accept", "value": {"value": "*/*"}}],
+            },
+            "timestamp": 1000,
+        }
+        kw = bidi.request_sent_kwargs(params)
+        self.assertEqual(kw["request_id"], "req-1")
+        self.assertEqual(kw["url"], "https://x/app.js")
+        self.assertEqual(kw["method"], "GET")
+        self.assertEqual(kw["status"], None)
+        self.assertEqual(kw["start_time"], 1000)
+        self.assertEqual(kw["request_type"], "script")  # .js extension
+        self.assertEqual(kw["request_headers"], {"accept": "*/*"})
+
+    def test_request_sent_kwargs_none_without_id(self):
+        self.assertIsNone(bidi.request_sent_kwargs({"request": {}}))
+
+    def test_response_completed_merges_over_pending(self):
+        pending = {}
+        req = bidi.request_sent_kwargs(
+            {"request": {"request": "req-2", "url": "https://x/api",
+                         "method": "POST"}, "timestamp": 1000}
+        )
+        pending[req["request_id"]] = req
+        resp = bidi.response_completed_kwargs(
+            {
+                "request": {
+                    "request": "req-2",
+                    "timings": {"requestTime": 0, "responseEnd": 250},
+                },
+                "response": {"status": 201, "statusText": "Created",
+                             "mimeType": "application/json", "bytesReceived": 42},
+                "timestamp": 1300,
+            },
+            pending,
+        )
+        self.assertEqual(resp["status"], 201)
+        self.assertEqual(resp["status_text"], "Created")
+        self.assertEqual(resp["size"], 42)
+        self.assertEqual(resp["request_type"], "fetch")  # json mime
+        self.assertEqual(resp["time"], 250)  # from timings, not timestamp delta
+        self.assertEqual(resp["end_time"], 1000 + 250)
+
+    def test_response_completed_none_when_unmatched(self):
+        self.assertIsNone(
+            bidi.response_completed_kwargs({"request": {"request": "ghost"}}, {})
+        )
+
+    def test_response_timing_falls_back_to_timestamp_delta(self):
+        pending = {}
+        req = bidi.request_sent_kwargs(
+            {"request": {"request": "req-3", "url": "https://x"},
+             "timestamp": 500}
+        )
+        pending[req["request_id"]] = req
+        resp = bidi.response_completed_kwargs(
+            {"request": {"request": "req-3"}, "response": {"status": 200},
+             "timestamp": 700},
+            pending,
+        )
+        self.assertEqual(resp["end_time"], 700)
+        self.assertEqual(resp["time"], 200)
+
+    def test_headers_to_object_handles_non_list(self):
+        self.assertIsNone(bidi.headers_to_object(None))
+        self.assertIsNone(bidi.headers_to_object("nope"))
+
+
+class TestRequestType(unittest.TestCase):
+    def test_mime_type_precedence(self):
+        self.assertEqual(bidi.request_type_for("https://x/", "text/html"), "document")
+        self.assertEqual(bidi.request_type_for("https://x/a", "text/css"), "stylesheet")
+        self.assertEqual(bidi.request_type_for("https://x/a.js"), "script")
+        self.assertEqual(bidi.request_type_for("https://x/pic.png"), "image")
+        self.assertEqual(bidi.request_type_for("https://x/unknown"), "xhr")
+
+
+class TestAttachDefensive(unittest.TestCase):
+    """attach must degrade — never raise — when BiDi isn't available."""
+
+    def _capturer(self):
+        return SessionCapturer(FakeTransport())
+
+    def test_attach_skips_without_websocket_capability(self):
+        class Driver:
+            caps = {"browserName": "chrome"}  # no webSocketUrl
+        self.assertFalse(bidi.attach(Driver(), self._capturer()))
+
+    def test_attach_survives_channel_errors(self):
+        class Driver:
+            caps = {"webSocketUrl": "ws://x"}
+
+            @property
+            def script(self):
+                raise RuntimeError("no bidi here")
+
+            @property
+            def network(self):
+                raise RuntimeError("no bidi here")
+
+        # Both channels raise; attach returns False without propagating.
+        self.assertFalse(bidi.attach(Driver(), self._capturer()))
+
+    def test_console_handler_pushes_to_capturer(self):
+        """End-to-end: a fake script channel drives capture_console."""
+        cap = self._capturer()
+
+        class Script:
+            def add_console_message_handler(self, cb):
+                cb(FakeLogEntry("info", "hello"))
+
+            def add_javascript_error_handler(self, cb):
+                pass
+
+        class Driver:
+            caps = {"webSocketUrl": "ws://x"}
+            script = Script()
+
+            @property
+            def network(self):
+                raise RuntimeError("skip network")
+
+        self.assertTrue(bidi.attach(Driver(), cap))
+        console = [d for s, d in cap._tx.sent if s == "consoleLogs"]
+        self.assertEqual(len(console), 1)
+        self.assertEqual(console[0][0]["type"], "info")
+        self.assertEqual(console[0][0]["args"], ["hello"])
+        self.assertEqual(console[0][0]["source"], "browser")
+
+    def test_console_and_js_error_routed_separately(self):
+        """console entries -> console_kwargs; JS errors -> js_error_kwargs."""
+        cap = self._capturer()
+
+        class Script:
+            def add_console_message_handler(self, cb):
+                cb({
+                    "method": "warn",
+                    "args": [{"type": "string", "value": "danger"},
+                             {"type": "number", "value": 9}],
+                })
+
+            def add_javascript_error_handler(self, cb):
+                cb({
+                    "level": "error",
+                    "text": "TypeError: boom",
+                    "stacktrace": {"callFrames": [
+                        {"functionName": "f", "url": "u", "lineNumber": 1,
+                         "columnNumber": 2}
+                    ]},
+                })
+
+        class Driver:
+            caps = {"webSocketUrl": "ws://x"}
+            script = Script()
+
+            @property
+            def network(self):
+                raise RuntimeError("skip network")
+
+        self.assertTrue(bidi.attach(Driver(), cap))
+        console = [d[0] for s, d in cap._tx.sent if s == "consoleLogs"]
+        self.assertEqual(len(console), 2)
+        self.assertEqual(console[0]["type"], "warn")
+        self.assertEqual(console[0]["args"], ["danger", 9])
+        self.assertEqual(console[1]["type"], "error")
+        self.assertIn("TypeError: boom", console[1]["args"][0])
+        self.assertIn("at f (u:1:2)", console[1]["args"][0])
+
+    def test_malformed_console_entry_is_no_op_not_raise(self):
+        """A handler that trips on a bad entry must not propagate the error."""
+        cap = self._capturer()
+
+        class Script:
+            def add_console_message_handler(self, cb):
+                cb(object())  # no level/method/args/text attrs
+
+            def add_javascript_error_handler(self, cb):
+                pass
+
+        class Driver:
+            caps = {"webSocketUrl": "ws://x"}
+            script = Script()
+
+            @property
+            def network(self):
+                raise RuntimeError("skip network")
+
+        # Must not raise; a plain object degrades to a log-level empty-text entry.
+        self.assertTrue(bidi.attach(Driver(), cap))
+
+
+if __name__ == "__main__":
+    unittest.main()
diff --git a/packages/selenium-devtools-py/tests/test_capturer.py b/packages/selenium-devtools-py/tests/test_capturer.py
new file mode 100644
index 00000000..d6fe8e9f
--- /dev/null
+++ b/packages/selenium-devtools-py/tests/test_capturer.py
@@ -0,0 +1,64 @@
+import unittest
+
+from selenium_devtools.capturer import SessionCapturer
+
+
+class FakeTransport:
+    connected = True
+
+    def __init__(self):
+        self.sent = []
+
+    def send_json(self, scope, data):
+        self.sent.append((scope, data))
+        return True
+
+    def close(self):
+        pass
+
+
+class TestSessionCapturer(unittest.TestCase):
+    def setUp(self):
+        self.tx = FakeTransport()
+        self.cap = SessionCapturer(self.tx)
+
+    def test_metadata_sent_once(self):
+        self.cap.ensure_metadata("sess-1", {"browserName": "chrome"}, None)
+        self.cap.ensure_metadata("sess-1", {"browserName": "chrome"}, None)
+        meta_frames = [d for s, d in self.tx.sent if s == "metadata"]
+        self.assertEqual(len(meta_frames), 1)
+        self.assertEqual(meta_frames[0]["sessionId"], "sess-1")
+
+    def test_capture_command_increments_id_and_wraps_in_array(self):
+        self.cap.capture_command(command="get", args={"url": "x"},
+                                 result={"v": 1}, start_time=1, call_source=None)
+        self.cap.capture_command(command="click", args=None,
+                                 result=None, start_time=2, call_source=None)
+        cmds = [d for s, d in self.tx.sent if s == "commands"]
+        self.assertEqual(len(cmds), 2)
+        self.assertEqual(cmds[0][0]["id"], 1)
+        self.assertEqual(cmds[1][0]["id"], 2)
+        # non-list args are normalized to a list
+        self.assertEqual(cmds[0][0]["args"], [{"url": "x"}])
+        self.assertEqual(cmds[1][0]["args"], [])
+
+    def test_capture_command_records_error(self):
+        self.cap.capture_command(command="boom", args=[],
+                                 error=RuntimeError("x"), start_time=1,
+                                 call_source=None)
+        cmd = [d for s, d in self.tx.sent if s == "commands"][0][0]
+        self.assertEqual(cmd["error"]["name"], "RuntimeError")
+
+    def test_suites_sent_as_uid_keyed_records(self):
+        # UI expects Record<uid, SuiteStats>[], not a plain array of suites.
+        suite = {"uid": "suite-1", "title": "S", "tests": []}
+        self.cap.send_suites([suite])
+        self.assertIn(("suites", [{"suite-1": suite}]), self.tx.sent)
+
+    def test_suites_empty_payload_not_sent(self):
+        self.cap.send_suites([{"title": "no uid"}])
+        self.assertEqual([s for s, _ in self.tx.sent if s == "suites"], [])
+
+
+if __name__ == "__main__":
+    unittest.main()
diff --git a/packages/selenium-devtools-py/tests/test_frames.py b/packages/selenium-devtools-py/tests/test_frames.py
new file mode 100644
index 00000000..0f2105d9
--- /dev/null
+++ b/packages/selenium-devtools-py/tests/test_frames.py
@@ -0,0 +1,57 @@
+import json
+import unittest
+
+from selenium_devtools import frames
+from selenium_devtools.utils import to_jsonable
+
+
+class TestFrames(unittest.TestCase):
+    def test_metadata_shape(self):
+        m = frames.metadata("sess-1", {"browserName": "chrome"}, "https://x/")
+        self.assertEqual(m["type"], "testrunner")
+        self.assertEqual(m["sessionId"], "sess-1")
+        self.assertEqual(m["capabilities"]["browserName"], "chrome")
+
+    def test_command_log_includes_error_only_when_present(self):
+        ok = frames.command_log(
+            command="get", args=["u"], result=None, timestamp=2, start_time=1,
+            call_source="f.py:1", command_id=3,
+        )
+        self.assertNotIn("error", ok)
+        self.assertEqual(ok["id"], 3)
+        bad = frames.command_log(
+            command="get", args=[], error=ValueError("nope"),
+            timestamp=2, start_time=1, call_source=None, command_id=4,
+        )
+        self.assertEqual(bad["error"], {"name": "ValueError", "message": "nope"})
+
+    def test_suite_and_test_stats_are_json_serializable(self):
+        t = frames.test_stats(
+            uid="n::t", title="t", full_title="m › t", parent="m",
+            state="passed", file="m.py", start_ms=1000, end_ms=2200,
+        )
+        s = frames.suite_stats(uid="m.py", title="m.py", file="m.py",
+                               start_ms=1000, tests=[t], end_ms=2200, state="passed")
+        self.assertEqual(t["_duration"], 1200)
+        self.assertEqual(s["type"], "suite")
+        self.assertEqual(s["tests"][0]["state"], "passed")
+        # start/end must be ISO strings, not numbers (TS Date on the wire).
+        self.assertRegex(t["start"], r"^\d{4}-\d{2}-\d{2}T")
+        json.dumps(s)  # raises if any field is non-serializable
+
+
+class TestJsonable(unittest.TestCase):
+    def test_passes_through_primitives_and_containers(self):
+        self.assertEqual(to_jsonable({"a": [1, "b", True, None]}),
+                         {"a": [1, "b", True, None]})
+
+    def test_falls_back_to_str_for_exotic(self):
+        class Weird:
+            def __repr__(self):
+                return "<weird>"
+
+        self.assertEqual(to_jsonable(Weird()), "<weird>")
+
+
+if __name__ == "__main__":
+    unittest.main()
diff --git a/packages/selenium-devtools-py/tests/test_instrumentation.py b/packages/selenium-devtools-py/tests/test_instrumentation.py
new file mode 100644
index 00000000..b7ab62e0
--- /dev/null
+++ b/packages/selenium-devtools-py/tests/test_instrumentation.py
@@ -0,0 +1,378 @@
+import os
+import tempfile
+import unittest
+from unittest import mock
+
+from selenium_devtools import instrumentation, snapshot
+from selenium_devtools.capturer import SessionCapturer
+
+
+class FakeTransport:
+    connected = True
+
+    def __init__(self):
+        self.sent = []
+
+    def send_json(self, scope, data):
+        self.sent.append((scope, data))
+        return True
+
+    def close(self):
+        pass
+
+
+class FakeDriver:
+    """Stand-in for selenium's WebDriver — same execute() chokepoint."""
+
+    def __init__(self):
+        self.session_id = None
+        self.caps = {"browserName": "chrome"}
+
+    def execute(self, command, params=None):
+        if command == "newSession":
+            self.session_id = "sess-9"
+        if command == "boom":
+            raise ValueError("kaboom")
+        return {"value": f"ok:{command}"}
+
+
+class ScreenshotDriver(FakeDriver):
+    """Driver that can produce screenshots — exercises per-command capture."""
+
+    def get_screenshot_as_base64(self):
+        return "c2hvdA=="  # base64 for "shot"
+
+
+class TestInstrumentation(unittest.TestCase):
+    def setUp(self):
+        instrumentation.uninstall()
+        self.tx = FakeTransport()
+        self.cap = SessionCapturer(self.tx)
+        instrumentation.install(self.cap, FakeDriver)
+        self.driver = FakeDriver()
+
+    def tearDown(self):
+        instrumentation.uninstall()
+
+    def _commands(self):
+        return [d[0] for s, d in self.tx.sent if s == "commands"]
+
+    def test_captures_command_and_unwraps_value(self):
+        out = self.driver.execute("get", {"url": "https://x/"})
+        self.assertEqual(out, {"value": "ok:get"})  # behavior unchanged
+        cmds = self._commands()
+        self.assertEqual(len(cmds), 1)
+        self.assertEqual(cmds[0]["command"], "get")
+        self.assertEqual(cmds[0]["result"], "ok:get")  # unwrapped from .value
+        self.assertEqual(cmds[0]["args"], [{"url": "https://x/"}])
+
+    def test_skip_commands_not_captured(self):
+        self.driver.execute("newSession")
+        self.assertEqual(self._commands(), [])
+
+    def test_metadata_sent_on_first_real_command_not_new_session(self):
+        # session_id/caps only exist AFTER newSession returns, so setup (metadata,
+        # BiDi, screencast) is deferred to the first real command — not newSession.
+        self.driver.execute("newSession")
+        self.assertEqual([d for s, d in self.tx.sent if s == "metadata"], [])
+        self.driver.execute("get", {"url": "https://x/"})
+        metas = [d for s, d in self.tx.sent if s == "metadata"]
+        self.assertEqual(len(metas), 1)
+        self.assertEqual(metas[0]["sessionId"], "sess-9")
+
+    def test_error_is_captured_then_reraised(self):
+        with self.assertRaises(ValueError):
+            self.driver.execute("boom")
+        cmds = self._commands()
+        self.assertEqual(len(cmds), 1)
+        self.assertEqual(cmds[0]["error"]["name"], "ValueError")
+
+    def test_uninstall_restores_original(self):
+        instrumentation.uninstall()
+        self.tx.sent.clear()
+        self.driver.execute("get")
+        self.assertEqual(self._commands(), [])  # no capture after uninstall
+
+    def test_snapshot_noop_when_driver_cannot_execute_script(self):
+        # FakeDriver has no execute_script, so snapshot capture is skipped and
+        # command capture must still work normally.
+        self.driver.execute("get", {"url": "https://x/"})
+        self.assertEqual(len(self._commands()), 1)
+
+    def test_no_screenshot_when_driver_cannot_screenshot(self):
+        # FakeDriver has no get_screenshot_as_base64 — the command frame simply
+        # omits the screenshot field rather than sending a null.
+        self.driver.execute("get", {"url": "https://x/"})
+        self.assertNotIn("screenshot", self._commands()[0])
+
+    def test_screenshot_attached_to_command_on_success(self):
+        # With a screenshot-capable driver, each successful command carries the
+        # base64 screenshot the UI shows when that command is selected.
+        instrumentation.uninstall()
+        instrumentation.install(self.cap, ScreenshotDriver)
+        driver = ScreenshotDriver()
+        driver.execute("get", {"url": "https://x/"})
+        self.assertEqual(self._commands()[0]["screenshot"], "c2hvdA==")
+
+    def test_no_screenshot_attached_on_error(self):
+        instrumentation.uninstall()
+        instrumentation.install(self.cap, ScreenshotDriver)
+        driver = ScreenshotDriver()
+        driver.execute("get", {"url": "https://x/"})  # sets up the session
+        with self.assertRaises(ValueError):
+            driver.execute("boom")
+        boom = [c for c in self._commands() if c["command"] == "boom"][0]
+        self.assertNotIn("screenshot", boom)
+        self.assertEqual([d for s, d in self.tx.sent if s == "mutations"], [])
+
+
+class FakeDriverWithScript(FakeDriver):
+    """Driver whose execute_script drives the injected DOM collector."""
+
+    def __init__(self):
+        super().__init__()
+        self.session_id = "sess-9"  # already-initialized session
+        self._script_calls = []
+        self._collector_installed = False
+
+    def execute_script(self, script, *args):
+        self._script_calls.append(script)
+        if "createElement" in script:  # install
+            self._collector_installed = True
+            return True
+        if "getTraceData" in script:  # read (drains buffer)
+            return ({"mutations": [{"type": "childList", "target": "1"}]}
+                    if self._collector_installed else None)
+        if "wdioTraceCollector" in script:  # readiness probe
+            return self._collector_installed
+        return True
+
+
+class TestSnapshotWiring(unittest.TestCase):
+    """Covers the drain plumbing, not the collector's contents, so it stands in a
+    stub for the bundle. `packages/script/dist/script.js` is a gitignored build
+    artifact, and these tests would otherwise pass only on a machine that had
+    built it and fail on CI, which is what happened."""
+
+    def setUp(self):
+        self._stub = tempfile.NamedTemporaryFile("w", suffix=".js", delete=False)
+        self._stub.write("window.wdioTraceCollector = { getTraceData: () => null }\n")
+        self._stub.close()
+        self._script_patch = mock.patch.object(
+            snapshot, "resolve_script_path", return_value=self._stub.name
+        )
+        self._script_patch.start()
+        instrumentation.uninstall()
+        self.tx = FakeTransport()
+        self.cap = SessionCapturer(self.tx)
+        instrumentation.install(self.cap, FakeDriverWithScript)
+        self.driver = FakeDriverWithScript()
+
+    def tearDown(self):
+        instrumentation.uninstall()
+        self._script_patch.stop()
+        os.unlink(self._stub.name)
+
+    def _mutations(self):
+        return [d for s, d in self.tx.sent if s == "mutations"]
+
+    def test_navigation_flushes_mutations(self):
+        self.driver.execute("get", {"url": "https://x/"})
+        muts = self._mutations()
+        self.assertEqual(len(muts), 1)
+        self.assertEqual(muts[0], [{"type": "childList", "target": "1"}])
+        # The collector was injected exactly once during setup.
+        installs = [s for s in self.driver._script_calls if "createElement" in s]
+        self.assertEqual(len(installs), 1)
+
+    def test_every_command_refreshes_snapshot(self):
+        # Snapshot is drained after every command (a click can navigate too),
+        # not only on get/back/…, so the iframe stays current.
+        self.driver.execute("click", {"id": "btn"})
+        self.assertEqual(len(self._mutations()), 1)
+
+
+class TestSkipFrames(unittest.TestCase):
+    def test_user_file_under_selenium_path_is_not_skipped(self):
+        # A user's test file living under .../examples/selenium/... must NOT be
+        # mistaken for the selenium library (the old "/selenium/" substring bug).
+        frames = instrumentation._skip_frames()
+        self.assertNotIn(f"{__import__('os').sep}selenium{__import__('os').sep}", frames)
+        user_file = "/repo/examples/selenium/python-test/web_form.py"
+        self.assertFalse(any(frag in user_file for frag in frames))
+
+
+class TestDefaultSuite(unittest.TestCase):
+    def setUp(self):
+        instrumentation.uninstall()
+        instrumentation.set_external_suites(False)
+        self.tx = FakeTransport()
+        self.cap = SessionCapturer(self.tx)
+        instrumentation.install(self.cap, FakeDriver)
+        self.driver = FakeDriver()
+
+    def tearDown(self):
+        instrumentation.uninstall()
+        instrumentation.set_external_suites(False)
+
+    def _suites(self):
+        return [d for s, d in self.tx.sent if s == "suites"]
+
+    def test_script_run_gets_a_default_suite(self):
+        self.driver.execute("newSession")
+        self.driver.execute("get", {"url": "https://x/"})  # first real cmd → setup
+        suites = self._suites()
+        self.assertTrue(suites)  # a default suite was reported for the tree
+        first = list(suites[0][0].values())[0]  # {uid: SuiteStats}[]
+        self.assertEqual(first["tests"][0]["state"], "running")
+
+    def test_default_suite_suppressed_when_framework_reports(self):
+        instrumentation.set_external_suites(True)  # e.g. pytest plugin active
+        self.driver.execute("newSession")
+        self.driver.execute("get", {"url": "https://x/"})
+        self.assertEqual(self._suites(), [])  # adapter didn't synthesize one
+
+
+if __name__ == "__main__":
+    unittest.main()
+
+
+class MultiSessionDriver(FakeDriver):
+    """Driver whose session id is fixed at construction, so one process can hold
+    two of them at once — what a function-scoped pytest fixture produces."""
+
+    def __init__(self, session_id):
+        super().__init__()
+        self._sid = session_id
+        self.session_id = session_id
+
+    def execute(self, command, params=None):
+        if command == "quit":
+            return {"value": None}
+        return {"value": f"ok:{command}"}
+
+    # Deliberately no get_screenshot_as_base64: with one, arming starts a real
+    # ScreencastRecorder, and finalize shells out to ffmpeg, which wrote a .webm
+    # into the repo when these tests ran. Rotation is covered below with a stub.
+
+
+class TestMultipleSessions(unittest.TestCase):
+    """A second WebDriver in one process must be captured in full. Previously
+    `setup_done` and `_metadata_sent` were booleans, so sessions after the first
+    were attributed to session one and lost metadata, BiDi, DOM and video, and
+    the first `quit()` tore down capture for whichever driver was still live."""
+
+    def setUp(self):
+        instrumentation.uninstall()
+        self.tx = FakeTransport()
+        self.cap = SessionCapturer(self.tx)
+        self.attached = []
+        self._bidi = mock.patch.object(
+            instrumentation.bidi, "attach",
+            side_effect=lambda d, c: self.attached.append(d.session_id) or True,
+        )
+        self._bidi.start()
+        instrumentation.install(self.cap, MultiSessionDriver)
+
+    def tearDown(self):
+        instrumentation.uninstall()
+        self._bidi.stop()
+
+    def _scopes(self, scope):
+        return [d for s, d in self.tx.sent if s == scope]
+
+    def _sessions_announced(self):
+        return [m["sessionId"] for m in self._scopes("metadata")]
+
+    def test_each_session_announces_its_own_metadata(self):
+        MultiSessionDriver("sess-a").execute("get", {"url": "https://a/"})
+        MultiSessionDriver("sess-b").execute("get", {"url": "https://b/"})
+        self.assertEqual(self._sessions_announced(), ["sess-a", "sess-b"])
+
+    def test_bidi_attaches_once_per_session(self):
+        MultiSessionDriver("sess-a").execute("get", {"url": "https://a/"})
+        MultiSessionDriver("sess-b").execute("get", {"url": "https://b/"})
+        self.assertEqual(self.attached, ["sess-a", "sess-b"])
+
+    def test_repeated_commands_on_one_session_arm_it_once(self):
+        driver = MultiSessionDriver("sess-a")
+        driver.execute("get", {"url": "https://a/"})
+        driver.execute("click", {"id": "x"})
+        self.assertEqual(self._sessions_announced(), ["sess-a"])
+        self.assertEqual(self.attached, ["sess-a"])
+
+    def test_quitting_one_driver_leaves_the_other_capturing(self):
+        first = MultiSessionDriver("sess-a")
+        first.execute("get", {"url": "https://a/"})
+        second = MultiSessionDriver("sess-b")
+        second.execute("get", {"url": "https://b/"})
+        first.execute("quit")  # the stale driver, not the armed one
+        self.assertEqual(instrumentation._state["armed_session"], "sess-b")
+        second.execute("click", {"id": "x"})
+        commands = [d[0]["command"] for s, d in self.tx.sent if s == "commands"]
+        self.assertIn("click", commands)
+
+    def test_quitting_the_armed_driver_clears_arming_so_the_next_rearms(self):
+        first = MultiSessionDriver("sess-a")
+        first.execute("get", {"url": "https://a/"})
+        first.execute("quit")
+        self.assertIsNone(instrumentation._state["armed_session"])
+        MultiSessionDriver("sess-b").execute("get", {"url": "https://b/"})
+        self.assertEqual(self._sessions_announced(), ["sess-a", "sess-b"])
+
+
+class StubRecorder:
+    """Reports a finished encode without running ffmpeg or touching the disk."""
+
+    def __init__(self):
+        self.frames = []
+
+    def start(self, driver):
+        pass
+
+    def add_frame(self, shot):
+        self.frames.append(shot)
+
+    def stop(self):
+        pass
+
+    def finalize(self, session_id, output_dir=None):
+        return {
+            "video_path": f"/tmp/{session_id}.webm",
+            "video_file": f"{session_id}.webm",
+            "frame_count": 1,
+            "duration": 10,
+            "start_time": 1000,
+        }
+
+
+class TestScreencastAttributionAcrossSessions(unittest.TestCase):
+    """A rotated recording belongs to the session that produced it. send_screencast
+    keyed on the capturer's latest session id, so replacing a session filed the
+    previous session's video under the new one."""
+
+    def setUp(self):
+        instrumentation.uninstall()
+        self.tx = FakeTransport()
+        self.cap = SessionCapturer(self.tx)
+        self._rec = mock.patch.object(
+            instrumentation, "ScreencastRecorder", StubRecorder
+        )
+        self._rec.start()
+        self._bidi = mock.patch.object(
+            instrumentation.bidi, "attach", return_value=False
+        )
+        self._bidi.start()
+        instrumentation.install(self.cap, MultiSessionDriver)
+
+    def tearDown(self):
+        instrumentation.uninstall()
+        self._bidi.stop()
+        self._rec.stop()
+
+    def test_the_previous_sessions_video_is_filed_under_that_session(self):
+        MultiSessionDriver("sess-a").execute("get", {"url": "https://a/"})
+        MultiSessionDriver("sess-b").execute("get", {"url": "https://b/"})
+        videos = [d for s, d in self.tx.sent if s == "screencast"]
+        self.assertEqual([v["sessionId"] for v in videos], ["sess-a"])
+        self.assertEqual(videos[0]["videoFile"], "sess-a.webm")
diff --git a/packages/selenium-devtools-py/tests/test_lifecycle.py b/packages/selenium-devtools-py/tests/test_lifecycle.py
new file mode 100644
index 00000000..5eb6a096
--- /dev/null
+++ b/packages/selenium-devtools-py/tests/test_lifecycle.py
@@ -0,0 +1,295 @@
+"""Unit tests for the dashboard browser-window lifecycle.
+
+These never spawn a real browser or exit the process: the opener is injected,
+and the shutdown path's hard-exit timer is asserted on rather than run.
+"""
+
+import os
+import threading
+import unittest
+from unittest import mock
+
+from selenium_devtools import lifecycle
+from selenium_devtools.lifecycle import BrowserHandle
+
+
+class FakeProc:
+    """Minimal subprocess.Popen stand-in for BrowserHandle.close()."""
+
+    def __init__(self, alive=True):
+        self._alive = alive
+        self.terminated = False
+        self.killed = False
+
+    def poll(self):
+        return None if self._alive else 0
+
+    def terminate(self):
+        self.terminated = True
+        self._alive = False
+
+    def wait(self, timeout=None):
+        return 0
+
+    def kill(self):
+        self.killed = True
+        self._alive = False
+
+
+class TestBrowserHandle(unittest.TestCase):
+    def test_close_terminates_proc_and_removes_profile(self):
+        proc = FakeProc()
+        with mock.patch.object(lifecycle.shutil, "rmtree") as rmtree:
+            handle = BrowserHandle(proc=proc, user_data_dir="/tmp/fake-dir")
+            handle.close()
+        self.assertTrue(proc.terminated)
+        rmtree.assert_called_once_with("/tmp/fake-dir", ignore_errors=True)
+
+    def test_close_is_idempotent(self):
+        proc = FakeProc()
+        handle = BrowserHandle(proc=proc)
+        handle.close()
+        proc.terminated = False
+        handle.close()  # second call is a no-op
+        self.assertFalse(proc.terminated)
+
+    def test_close_on_empty_handle_is_safe(self):
+        BrowserHandle().close()  # no proc, no dir — must not raise
+
+
+class TestOpenDashboard(unittest.TestCase):
+    def test_uses_injected_opener(self):
+        sentinel = BrowserHandle()
+        opener = mock.Mock(return_value=sentinel)
+        result = lifecycle.open_dashboard("http://localhost:3000", opener=opener)
+        opener.assert_called_once_with("http://localhost:3000")
+        self.assertIs(result, sentinel)
+
+    def test_none_url_returns_none_without_opening(self):
+        opener = mock.Mock()
+        self.assertIsNone(lifecycle.open_dashboard(None, opener=opener))
+        opener.assert_not_called()
+
+    def test_opener_failure_is_swallowed(self):
+        opener = mock.Mock(side_effect=OSError("boom"))
+        self.assertIsNone(
+            lifecycle.open_dashboard("http://x", opener=opener)
+        )
+
+
+class TestDefaultOpener(unittest.TestCase):
+    """Guard the launch flags that keep the dashboard in its own Chrome window.
+
+    Never spawns a real browser: Popen, mkdtemp, and Chrome discovery are mocked.
+    """
+
+    def test_launches_isolated_dedicated_window(self):
+        fake_proc = FakeProc()
+        with mock.patch.object(
+                lifecycle, "_find_chrome", return_value="/fake/Chrome"), \
+                mock.patch.object(
+                    lifecycle.tempfile, "mkdtemp",
+                    return_value="/tmp/selenium-devtools-py-ui-x"), \
+                mock.patch.object(
+                    lifecycle.subprocess, "Popen",
+                    return_value=fake_proc) as popen:
+            handle = lifecycle._default_opener("http://localhost:3000")
+
+        args = popen.call_args.args[0]
+        # A distinct --user-data-dir is what forces a separate Chrome instance
+        # (cannot merge into the user's running Chrome).
+        self.assertIn(
+            "--user-data-dir=/tmp/selenium-devtools-py-ui-x", args)
+        self.assertIn("--new-window", args)
+        self.assertIn("--app=http://localhost:3000", args)
+        self.assertEqual(args[0], "/fake/Chrome")
+        # The URL is not passed as a bare arg (that would open an extra tab).
+        self.assertNotIn("http://localhost:3000", args)
+        self.assertIs(handle.proc, fake_proc)
+        self.assertEqual(
+            handle.user_data_dir, "/tmp/selenium-devtools-py-ui-x")
+
+    def test_chrome_not_found_returns_empty_handle_without_spawning(self):
+        with mock.patch.object(lifecycle, "_find_chrome", return_value=None), \
+                mock.patch.object(lifecycle.subprocess, "Popen") as popen:
+            handle = lifecycle._default_opener("http://localhost:3000")
+        popen.assert_not_called()  # never crash, never spawn
+        self.assertIsNone(handle.proc)
+        self.assertIsNone(handle.user_data_dir)
+        handle.close()  # empty handle stays safe to close
+
+
+class TestAutoOpenEnabled(unittest.TestCase):
+    def setUp(self):
+        self._saved = os.environ.get(lifecycle.ENV_OPEN)
+        os.environ.pop(lifecycle.ENV_OPEN, None)
+
+    def tearDown(self):
+        if self._saved is None:
+            os.environ.pop(lifecycle.ENV_OPEN, None)
+        else:
+            os.environ[lifecycle.ENV_OPEN] = self._saved
+
+    def test_env_falsy_disables(self):
+        for val in ("0", "false", "no", "off", ""):
+            os.environ[lifecycle.ENV_OPEN] = val
+            self.assertFalse(lifecycle.auto_open_enabled(), val)
+
+    def test_env_truthy_enables(self):
+        for val in ("1", "true", "yes", "on", "  YES  "):
+            os.environ[lifecycle.ENV_OPEN] = val
+            self.assertTrue(lifecycle.auto_open_enabled(), val)
+
+    def test_defaults_on_when_unset(self):
+        # Regardless of TTY: unset means open (opt-out design). A non-TTY IDE /
+        # `python demo.py` run must still auto-open into a dedicated window.
+        os.environ.pop(lifecycle.ENV_OPEN, None)
+        with mock.patch.object(lifecycle.sys.stdout, "isatty", return_value=False):
+            self.assertTrue(lifecycle.auto_open_enabled())
+        with mock.patch.object(lifecycle.sys.stdout, "isatty", return_value=True):
+            self.assertTrue(lifecycle.auto_open_enabled())
+
+
+class TestShutdownFlow(unittest.TestCase):
+    def setUp(self):
+        lifecycle._reset_for_tests()
+
+    def tearDown(self):
+        lifecycle._reset_for_tests()
+
+    def test_client_disconnected_disables_and_schedules_exit(self):
+        disable = mock.Mock()
+        handle = BrowserHandle(proc=FakeProc())
+        # register without touching real signals: not on the main thread guard
+        # not needed here — we call the internals directly.
+        lifecycle._disable = disable
+        lifecycle._handle = handle
+
+        with mock.patch.object(lifecycle.threading, "Timer") as Timer:
+            lifecycle.on_control("clientDisconnected", {})
+            Timer.assert_called_once()  # a hard-exit was scheduled
+            timer = Timer.return_value
+            self.assertTrue(timer.start.called)
+
+        disable.assert_called_once()  # capture torn down
+        self.assertTrue(handle._closed)  # window closed
+
+    def test_client_connected_is_noop(self):
+        disable = mock.Mock()
+        lifecycle._disable = disable
+        with mock.patch.object(lifecycle.threading, "Timer") as Timer:
+            lifecycle.on_control("clientConnected", {})
+            Timer.assert_not_called()
+        disable.assert_not_called()
+
+    def test_shutdown_runs_once(self):
+        disable = mock.Mock()
+        lifecycle._disable = disable
+        with mock.patch.object(lifecycle.threading, "Timer"):
+            lifecycle.on_control("clientDisconnected", {})
+            lifecycle.on_control("clientDisconnected", {})
+        disable.assert_called_once()  # guard prevents re-entry
+
+    def test_disable_errors_do_not_propagate(self):
+        lifecycle._disable = mock.Mock(side_effect=RuntimeError("bad"))
+        with mock.patch.object(lifecycle.threading, "Timer"):
+            lifecycle.on_control("clientDisconnected", {})  # must not raise
+
+
+class TestWaitForShutdown(unittest.TestCase):
+    def setUp(self):
+        lifecycle._reset_for_tests()
+
+    def tearDown(self):
+        lifecycle._reset_for_tests()
+
+    def test_dashboard_window_open(self):
+        self.assertFalse(lifecycle.dashboard_window_open())  # no handle
+        lifecycle._handle = BrowserHandle(proc=FakeProc(alive=True))
+        self.assertTrue(lifecycle.dashboard_window_open())
+        lifecycle._handle = BrowserHandle(proc=FakeProc(alive=False))
+        self.assertFalse(lifecycle.dashboard_window_open())
+
+    def test_wait_returns_false_on_timeout(self):
+        self.assertFalse(lifecycle.wait_for_shutdown(timeout=0.01))
+
+    def test_wait_unblocks_on_close_without_hard_exit(self):
+        # With a waiter registered, clientDisconnected releases it instead of
+        # hard-exiting or tearing down from the WS thread.
+        import time
+
+        disable = mock.Mock()
+        lifecycle._disable = disable
+        unblocked = threading.Event()
+
+        def waiter():
+            lifecycle.wait_for_shutdown(timeout=2)
+            unblocked.set()
+
+        t = threading.Thread(target=waiter)
+        t.start()
+        time.sleep(0.05)  # let the waiter register
+        with mock.patch.object(lifecycle.threading, "Timer") as Timer:
+            lifecycle.on_control("clientDisconnected", {})
+            Timer.assert_not_called()  # no hard-exit scheduled
+        self.assertTrue(unblocked.wait(2))  # waiter released
+        disable.assert_not_called()  # handler left teardown to the waiter
+        t.join(2)
+
+
+class TestExitHandlerRegistration(unittest.TestCase):
+    def setUp(self):
+        lifecycle._reset_for_tests()
+
+    def tearDown(self):
+        lifecycle._reset_for_tests()
+
+    def test_register_off_main_thread_skips_signals_but_wires_atexit(self):
+        disable = mock.Mock()
+        handle = BrowserHandle(proc=FakeProc())
+        results = {}
+
+        def worker():
+            with mock.patch.object(lifecycle.atexit, "register") as reg, \
+                    mock.patch.object(lifecycle.signal, "signal") as sig:
+                lifecycle.register_exit_handlers(disable, handle)
+                results["atexit"] = reg.called
+                results["signal"] = sig.called
+
+        t = threading.Thread(target=worker)
+        t.start()
+        t.join()
+        self.assertTrue(results["atexit"])
+        self.assertFalse(results["signal"])  # signals only on main thread
+
+    def test_register_is_idempotent(self):
+        disable = mock.Mock()
+        with mock.patch.object(lifecycle.atexit, "register") as reg, \
+                mock.patch.object(lifecycle.signal, "signal"), \
+                mock.patch.object(lifecycle.signal, "getsignal"), \
+                mock.patch.object(
+                    lifecycle.threading, "main_thread",
+                    return_value=threading.current_thread()):
+            lifecycle.register_exit_handlers(disable, None)
+            lifecycle.register_exit_handlers(disable, None)
+        self.assertEqual(reg.call_count, 1)
+
+    def test_unregister_closes_handle_and_restores(self):
+        disable = mock.Mock()
+        handle = BrowserHandle(proc=FakeProc())
+        with mock.patch.object(lifecycle.atexit, "register"), \
+                mock.patch.object(lifecycle.atexit, "unregister") as unreg, \
+                mock.patch.object(lifecycle.signal, "signal"), \
+                mock.patch.object(lifecycle.signal, "getsignal"), \
+                mock.patch.object(
+                    lifecycle.threading, "main_thread",
+                    return_value=threading.current_thread()):
+            lifecycle.register_exit_handlers(disable, handle)
+            lifecycle.unregister_exit_handlers()
+            self.assertTrue(unreg.called)
+        self.assertTrue(handle._closed)  # window closed on unregister
+        self.assertFalse(lifecycle._handlers_registered)
+
+
+if __name__ == "__main__":
+    unittest.main()
diff --git a/packages/selenium-devtools-py/tests/test_logcapture.py b/packages/selenium-devtools-py/tests/test_logcapture.py
new file mode 100644
index 00000000..7b08a99d
--- /dev/null
+++ b/packages/selenium-devtools-py/tests/test_logcapture.py
@@ -0,0 +1,57 @@
+import logging
+import unittest
+
+from selenium_devtools.logcapture import (
+    LOGGER_NAME,
+    LogCapturer,
+    _DashboardHandler,
+)
+
+
+class FakeCapturer:
+    def __init__(self):
+        self.logs = []
+
+    def capture_console(self, level, args, source="browser"):
+        self.logs.append((level, args, source))
+
+
+def _record(name, levelno, msg, args=()):
+    return logging.LogRecord(name, levelno, __file__, 1, msg, args, None)
+
+
+class TestHandler(unittest.TestCase):
+    def test_forwards_with_logger_name_and_terminal_source(self):
+        cap = FakeCapturer()
+        _DashboardHandler(cap).emit(_record("selenium", logging.INFO, "hi %s", ("x",)))
+        self.assertEqual(cap.logs, [("info", ["selenium: hi x"], "terminal")])
+
+    def test_level_mapping(self):
+        cap = FakeCapturer()
+        h = _DashboardHandler(cap)
+        for lvl in (logging.DEBUG, logging.WARNING, logging.ERROR):
+            h.emit(_record("n", lvl, "m"))
+        self.assertEqual([lvl for lvl, _, _ in cap.logs], ["debug", "warn", "error"])
+
+
+class TestLogCapturer(unittest.TestCase):
+    def test_captures_adapter_logs_then_restores_on_stop(self):
+        cap = FakeCapturer()
+        adapter_logger = logging.getLogger(LOGGER_NAME)
+        prev_level = adapter_logger.level
+        lc = LogCapturer(cap)
+        lc.start()
+        try:
+            self.assertIn(lc._handler, logging.getLogger().handlers)
+            logging.getLogger(LOGGER_NAME).info("hello from adapter")
+            self.assertTrue(
+                any("hello from adapter" in a[0] for _, a, _ in cap.logs)
+            )
+        finally:
+            lc.stop()
+        self.assertNotIn(lc._handler, logging.getLogger().handlers)  # detached
+        self.assertEqual(adapter_logger.level, prev_level)  # level restored
+
+
+if __name__ == "__main__":
+    unittest.main()
diff --git a/packages/selenium-devtools-py/tests/test_output_dir.py b/packages/selenium-devtools-py/tests/test_output_dir.py
new file mode 100644
index 00000000..c9c3809d
--- /dev/null
+++ b/packages/selenium-devtools-py/tests/test_output_dir.py
@@ -0,0 +1,94 @@
+import os
+import tempfile
+import unittest
+
+from selenium_devtools.output_dir import (
+    OUTPUT_SUBDIR,
+    ensure_output_dir,
+    resolve_adapter_output_dir,
+)
+
+
+class TestResolveAdapterOutputDir(unittest.TestCase):
+    def test_groups_output_under_test_results_beside_the_test_file(self):
+        with tempfile.TemporaryDirectory() as tmp:
+            spec = os.path.join(tmp, "test_login.py")
+            open(spec, "w").close()
+            self.assertEqual(
+                resolve_adapter_output_dir(test_file_path=spec),
+                os.path.join(tmp, OUTPUT_SUBDIR),
+            )
+
+    def test_falls_back_to_cwd_when_no_test_file_is_known(self):
+        with tempfile.TemporaryDirectory() as tmp:
+            self.assertEqual(
+                resolve_adapter_output_dir(fallback_dir=tmp),
+                os.path.join(tmp, OUTPUT_SUBDIR),
+            )
+
+    def test_an_explicit_dir_wins_and_is_honored_as_is(self):
+        with tempfile.TemporaryDirectory() as tmp:
+            spec = os.path.join(tmp, "test_login.py")
+            open(spec, "w").close()
+            chosen = os.path.join(tmp, "somewhere-else")
+            self.assertEqual(
+                resolve_adapter_output_dir(
+                    user_configured_dir=chosen, test_file_path=spec
+                ),
+                os.path.join(chosen, OUTPUT_SUBDIR),
+            )
+
+    # A test file resolved through an installed package must not collect
+    # artifacts; core skips node_modules for the same reason.
+    def test_skips_an_installed_package_directory(self):
+        with tempfile.TemporaryDirectory() as tmp:
+            installed = os.path.join(tmp, "lib", "site-packages", "pkg")
+            os.makedirs(installed)
+            spec = os.path.join(installed, "test_login.py")
+            open(spec, "w").close()
+            self.assertEqual(
+                resolve_adapter_output_dir(test_file_path=spec, fallback_dir=tmp),
+                os.path.join(tmp, OUTPUT_SUBDIR),
+            )
+
+    def test_falls_through_a_non_writable_candidate(self):
+        with tempfile.TemporaryDirectory() as tmp:
+            locked = os.path.join(tmp, "locked")
+            os.makedirs(locked)
+            spec = os.path.join(locked, "test_login.py")
+            open(spec, "w").close()
+            os.chmod(locked, 0o500)
+            try:
+                resolved = resolve_adapter_output_dir(
+                    test_file_path=spec, fallback_dir=tmp
+                )
+            finally:
+                os.chmod(locked, 0o700)
+            self.assertEqual(resolved, os.path.join(tmp, OUTPUT_SUBDIR))
+
+    def test_the_path_is_absolute_even_for_a_relative_test_file(self):
+        self.assertTrue(
+            os.path.isabs(resolve_adapter_output_dir(test_file_path="tests/test_x.py"))
+        )
+
+
+class TestEnsureOutputDir(unittest.TestCase):
+    def test_creates_the_directory_and_returns_it(self):
+        with tempfile.TemporaryDirectory() as tmp:
+            target = os.path.join(tmp, OUTPUT_SUBDIR)
+            self.assertEqual(ensure_output_dir(target), target)
+            self.assertTrue(os.path.isdir(target))
+
+    def test_is_idempotent(self):
+        with tempfile.TemporaryDirectory() as tmp:
+            target = os.path.join(tmp, OUTPUT_SUBDIR)
+            ensure_output_dir(target)
+            self.assertEqual(ensure_output_dir(target), target)
+
+    def test_returns_none_when_it_cannot_create(self):
+        with tempfile.TemporaryDirectory() as tmp:
+            os.chmod(tmp, 0o500)
+            try:
+                self.assertIsNone(ensure_output_dir(os.path.join(tmp, "nope", "deep")))
+            finally:
+                os.chmod(tmp, 0o700)
diff --git a/packages/selenium-devtools-py/tests/test_screencast.py b/packages/selenium-devtools-py/tests/test_screencast.py
new file mode 100644
index 00000000..96d43800
--- /dev/null
+++ b/packages/selenium-devtools-py/tests/test_screencast.py
@@ -0,0 +1,208 @@
+import os
+import shutil
+import tempfile
+import unittest
+
+from selenium_devtools.capturer import SessionCapturer
+from selenium_devtools.screencast import ScreencastRecorder
+
+# 16x16 PNG — a real decodable frame with even dimensions so libvpx/yuv420p can
+# actually encode a video (odd/1px dimensions make ffmpeg reject the stream).
+_PNG_FRAME = (
+    "iVBORw0KGgoAAAANSUhEUgAAABAAAAAQCAIAAACQkWg2AAAAEElEQVR4"
+    "nGNgGAWjYBTAAAADEAABPywr7AAAAABJRU5ErkJggg=="
+)
+
+
+class FakeTransport:
+    connected = True
+
+    def __init__(self):
+        self.sent = []
+
+    def send_json(self, scope, data):
+        self.sent.append((scope, data))
+        return True
+
+    def close(self):
+        pass
+
+
+def _stub_shots(*values):
+    """A screenshot fn returning each value in turn, then the last forever."""
+    seq = list(values)
+
+    def fn():
+        return seq.pop(0) if len(seq) > 1 else seq[0]
+
+    return fn
+
+
+class TestBuffering(unittest.TestCase):
+    def test_capture_buffers_frames_per_call(self):
+        # Frames are captured synchronously, one per capture() — the seed frame
+        # from start() plus one for each explicit capture.
+        rec = ScreencastRecorder()
+        rec.start(driver=None, screenshot_fn=_stub_shots("a", "b", "c"))
+        rec.capture()
+        rec.capture()
+        self.assertGreaterEqual(len(rec.frames), 2)
+        self.assertTrue(all("data" in f and "timestamp" in f for f in rec.frames))
+
+    def test_capture_is_noop_after_stop(self):
+        rec = ScreencastRecorder()
+        rec.start(driver=None, screenshot_fn=lambda: "x")
+        rec.stop()
+        rec.stop()  # no raise
+        count_after_stop = len(rec.frames)
+        self.assertFalse(rec.capture())  # disarmed → no frame
+        self.assertEqual(len(rec.frames), count_after_stop)
+        self.assertFalse(rec.is_recording)
+
+    def test_stays_armed_when_seed_screenshot_fails(self):
+        # A failed seed (page still loading) must not disable the recorder — a
+        # later capture can still succeed. The old poll loop died on first miss.
+        rec = ScreencastRecorder()
+        rec.start(driver=None, screenshot_fn=lambda: None)
+        self.assertTrue(rec.is_recording)
+        self.assertEqual(rec.frames, [])
+
+    def test_transient_failure_does_not_stop_recording(self):
+        calls = {"n": 0}
+
+        def flaky():
+            calls["n"] += 1
+            if calls["n"] == 2:
+                raise RuntimeError("session busy")
+            return "shot"
+
+        rec = ScreencastRecorder()
+        rec.start(driver=None, screenshot_fn=flaky)  # seed ok (call 1)
+        self.assertFalse(rec.capture())  # call 2 raises → skipped, not fatal
+        self.assertTrue(rec.is_recording)  # still armed
+        self.assertTrue(rec.capture())  # call 3 succeeds
+        self.assertGreaterEqual(len(rec.frames), 2)
+
+    def test_duration_zero_below_two_frames(self):
+        rec = ScreencastRecorder()
+        rec.start(driver=None, screenshot_fn=lambda: "only")
+        rec.stop()
+        self.assertEqual(rec.duration, 0)
+
+    def test_uses_driver_screenshot_when_no_fn(self):
+        class Driver:
+            def get_screenshot_as_base64(self):
+                return "shot"
+
+        rec = ScreencastRecorder()
+        rec.start(Driver())  # seed frame via driver's screenshot
+        self.assertTrue(rec.is_recording)
+        self.assertGreaterEqual(len(rec.frames), 1)
+
+    def test_start_skips_when_driver_has_no_screenshot(self):
+        rec = ScreencastRecorder()
+        rec.start(object())  # no get_screenshot_as_base64
+        self.assertFalse(rec.is_recording)
+
+    def test_add_frame_buffers_precaptured_screenshot(self):
+        # add_frame reuses a screenshot the caller already took (for the command
+        # entry) instead of paying for a second round-trip.
+        rec = ScreencastRecorder()
+        rec.start(driver=None, screenshot_fn=lambda: "seed")
+        self.assertTrue(rec.add_frame("reused"))
+        self.assertEqual(rec.frames[-1]["data"], "reused")
+
+    def test_add_frame_noop_when_disarmed_or_empty(self):
+        rec = ScreencastRecorder()
+        self.assertFalse(rec.add_frame("x"))  # not started
+        rec.start(driver=None, screenshot_fn=lambda: "seed")
+        self.assertFalse(rec.add_frame(None))  # empty payload
+        self.assertFalse(rec.add_frame(""))
+
+
+class TestFinalize(unittest.TestCase):
+    def test_finalize_empty_frames_returns_none(self):
+        rec = ScreencastRecorder()
+        self.assertIsNone(rec.finalize("sess-1"))
+
+    def test_finalize_below_min_frames_returns_none(self):
+        rec = ScreencastRecorder()
+        rec.start(driver=None, screenshot_fn=lambda: "one")
+        rec.stop()
+        # Only the seed frame captured → below the 2-frame minimum.
+        self.assertIsNone(rec.finalize("sess-1", min_frames=2))
+
+    def test_finalize_skips_encode_without_ffmpeg(self):
+        rec = ScreencastRecorder(ffmpeg_path=None)
+        rec._ffmpeg = None  # force "ffmpeg unavailable"
+        rec._frames = [{"data": "a", "timestamp": 1}, {"data": "b", "timestamp": 2}]
+        self.assertIsNone(rec.finalize("sess-1"))
+
+
+class TestCapturerSend(unittest.TestCase):
+    def test_send_screencast_builds_scoped_frame(self):
+        cap = SessionCapturer(FakeTransport())
+        cap.session_id = "sess-9"
+        cap.send_screencast(
+            video_path="/tmp/v.webm", video_file="v.webm",
+            frame_count=5, duration=1000, start_time=42,
+        )
+        frames_sent = [d for s, d in cap._tx.sent if s == "screencast"]
+        self.assertEqual(len(frames_sent), 1)
+        info = frames_sent[0]
+        self.assertEqual(info["sessionId"], "sess-9")
+        self.assertEqual(info["videoFile"], "v.webm")
+        self.assertEqual(info["frameCount"], 5)
+        self.assertEqual(info["startTime"], 42)
+
+    def test_send_screencast_noop_without_session(self):
+        cap = SessionCapturer(FakeTransport())
+        cap.send_screencast(
+            video_path="/tmp/v.webm", video_file="v.webm",
+            frame_count=5, duration=1000, start_time=42,
+        )
+        self.assertEqual(cap._tx.sent, [])
+
+    def test_screencast_frame_carries_videopath_for_backend_registry(self):
+        # The backend intercepts scope=='screencast', registers `videoPath`, and
+        # serves that file at /api/video/:sessionId — so the frame MUST carry
+        # videoPath alongside sessionId.
+        cap = SessionCapturer(FakeTransport())
+        cap.session_id = "sess-9"
+        cap.send_screencast(
+            video_path="/abs/v.webm", video_file="v.webm",
+            frame_count=5, duration=1000, start_time=42,
+        )
+        info = [d for s, d in cap._tx.sent if s == "screencast"][0]
+        self.assertEqual(info["videoPath"], "/abs/v.webm")
+        self.assertEqual(info["sessionId"], "sess-9")
+
+
+class TestScreencastDeliveryEndToEnd(unittest.TestCase):
+    """finalize → send_screencast must yield a frame pointing at a real file."""
+
+    @unittest.skipUnless(shutil.which("ffmpeg"), "ffmpeg not on PATH")
+    def test_finalize_encodes_and_delivers_frame(self):
+        out_dir = tempfile.mkdtemp(prefix="screencast-test-")
+        self.addCleanup(lambda: shutil.rmtree(out_dir, ignore_errors=True))
+        rec = ScreencastRecorder()
+        rec._frames = [
+            {"data": _PNG_FRAME, "timestamp": 1000},
+            {"data": _PNG_FRAME, "timestamp": 1200},
+        ]
+        info = rec.finalize("sess-7", output_dir=out_dir)
+        self.assertIsNotNone(info)
+        self.assertTrue(os.path.isfile(info["video_path"]))
+        self.assertEqual(info["frame_count"], 2)
+
+        cap = SessionCapturer(FakeTransport())
+        cap.session_id = "sess-7"
+        cap.send_screencast(**info)
+        frame = [d for s, d in cap._tx.sent if s == "screencast"][0]
+        # videoPath is what the backend reads off disk to serve the video.
+        self.assertTrue(os.path.isfile(frame["videoPath"]))
+        self.assertEqual(frame["sessionId"], "sess-7")
+
+
+if __name__ == "__main__":
+    unittest.main()
diff --git a/packages/selenium-devtools-py/tests/test_snapshot.py b/packages/selenium-devtools-py/tests/test_snapshot.py
new file mode 100644
index 00000000..d8cb3c22
--- /dev/null
+++ b/packages/selenium-devtools-py/tests/test_snapshot.py
@@ -0,0 +1,194 @@
+import os
+import tempfile
+import unittest
+
+from selenium_devtools import snapshot
+from selenium_devtools.snapshot import (
+    SnapshotCapturer,
+    load_injectable_script,
+    normalize_mutations,
+    resolve_script_path,
+    start_snapshot_capture,
+    wrap_injectable,
+)
+
+
+class FakeExec:
+    """Records execute_script calls; returns queued values in order."""
+
+    def __init__(self, *returns):
+        self.calls = []
+        self._returns = list(returns)
+
+    def __call__(self, script, *args):
+        self.calls.append((script, args))
+        if self._returns:
+            return self._returns.pop(0)
+        return None
+
+
+class TestScriptResolution(unittest.TestCase):
+    # `packages/script/dist/script.js` is a gitignored build artifact, so a CI job
+    # that only sets up Python has no copy. Mirrors the JS suite's
+    # `it.skipIf(!scriptPackageAvailable)` guard on the same dependency.
+    @unittest.skipUnless(
+        resolve_script_path(), "packages/script/dist/script.js is not built"
+    )
+    def test_resolves_monorepo_script(self):
+        path = resolve_script_path()
+        self.assertIsNotNone(path)
+        self.assertTrue(path.endswith(os.path.join("script", "dist", "script.js")))
+        self.assertTrue(os.path.isfile(path))
+
+
+class TestWrapAndLoad(unittest.TestCase):
+    def test_wrap_produces_async_iife(self):
+        wrapped = wrap_injectable("doThing();")
+        self.assertEqual(wrapped, "(async function() { doThing(); })()")
+
+    def test_load_reads_and_wraps(self):
+        with tempfile.NamedTemporaryFile("w", suffix=".js", delete=False) as fh:
+            fh.write("BODY")
+            temp = fh.name
+        try:
+            out = load_injectable_script(temp)
+        finally:
+            os.unlink(temp)
+        self.assertEqual(out, "(async function() { BODY })()")
+
+    def test_load_missing_file_returns_none(self):
+        self.assertIsNone(load_injectable_script("/no/such/script.js"))
+
+
+class TestNormalizeMutations(unittest.TestCase):
+    def test_extracts_mutation_list(self):
+        payload = {
+            "mutations": [{"type": "childList", "target": "1"}],
+            "consoleLogs": [],
+            "metadata": {"url": "https://x/"},
+        }
+        self.assertEqual(normalize_mutations(payload), [{"type": "childList", "target": "1"}])
+
+    def test_missing_key_returns_empty(self):
+        self.assertEqual(normalize_mutations({"consoleLogs": []}), [])
+
+    def test_non_list_mutations_returns_empty(self):
+        self.assertEqual(normalize_mutations({"mutations": "oops"}), [])
+
+    def test_none_payload_returns_empty(self):
+        self.assertEqual(normalize_mutations(None), [])
+
+    def test_non_dict_payload_returns_empty(self):
+        self.assertEqual(normalize_mutations([1, 2, 3]), [])
+
+
+class TestSnapshotCapturerInject(unittest.TestCase):
+    def _tmp_script(self):
+        fh = tempfile.NamedTemporaryFile("w", suffix=".js", delete=False)
+        fh.write("COLLECTOR")
+        fh.close()
+        self.addCleanup(lambda: os.path.exists(fh.name) and os.unlink(fh.name))
+        return fh.name
+
+    def test_inject_appends_script_and_probes(self):
+        # probe (absent) -> install -> probe (present)
+        exec_fn = FakeExec(False, None, True)
+        cap = SnapshotCapturer(exec_fn, script_path=self._tmp_script())
+        self.assertTrue(cap.inject())
+        self.assertTrue(cap.injected)
+        install = [c for c in exec_fn.calls if "createElement('script')" in c[0]]
+        self.assertEqual(len(install), 1)
+        self.assertEqual(install[0][1], ("(async function() { COLLECTOR })()",))
+        self.assertTrue(any("wdioTraceCollector" in c[0] for c in exec_fn.calls))
+
+    def test_inject_skips_install_when_collector_present(self):
+        # Self-healing: collector already on the page → probe True → no install.
+        exec_fn = FakeExec(True)
+        cap = SnapshotCapturer(exec_fn, script_path=self._tmp_script())
+        self.assertTrue(cap.inject())
+        self.assertEqual([c for c in exec_fn.calls if "createElement" in c[0]], [])
+
+    def test_inject_reinjects_after_navigation(self):
+        # Navigation wipes the collector: probe absent both times → 2 installs.
+        exec_fn = FakeExec(False, None, True, False, None, True)
+        cap = SnapshotCapturer(exec_fn, script_path=self._tmp_script())
+        cap.inject()
+        cap.inject()
+        installs = [c for c in exec_fn.calls if "createElement" in c[0]]
+        self.assertEqual(len(installs), 2)
+
+    def test_inject_missing_script_is_noop(self):
+        exec_fn = FakeExec()
+        cap = SnapshotCapturer(exec_fn, script_path="/no/such.js")
+        self.assertFalse(cap.inject())
+        self.assertFalse(cap.injected)
+        self.assertEqual(exec_fn.calls, [])  # script missing → no execute at all
+
+    def test_inject_swallows_execute_errors(self):
+        def boom(script, *args):
+            raise RuntimeError("no such session")
+
+        cap = SnapshotCapturer(boom, script_path=self._tmp_script())
+        self.assertFalse(cap.inject())  # no raise
+        self.assertFalse(cap.injected)
+
+
+class TestSnapshotCapturerPull(unittest.TestCase):
+    def test_pull_returns_normalized_mutations(self):
+        trace = {"mutations": [{"type": "attributes", "target": "9"}]}
+        exec_fn = FakeExec(trace)
+        cap = SnapshotCapturer(exec_fn)
+        self.assertEqual(cap.pull_mutations(), [{"type": "attributes", "target": "9"}])
+        # The read uses the atomic getTraceData expression.
+        self.assertIn("getTraceData", exec_fn.calls[0][0])
+
+    def test_pull_null_trace_returns_empty(self):
+        cap = SnapshotCapturer(FakeExec(None))
+        self.assertEqual(cap.pull_mutations(), [])
+
+    def test_pull_swallows_execute_errors(self):
+        def boom(script, *args):
+            raise RuntimeError("boom")
+
+        cap = SnapshotCapturer(boom)
+        self.assertEqual(cap.pull_mutations(), [])  # no raise
+
+
+class TestStartSnapshotCapture(unittest.TestCase):
+    def _tmp_script(self):
+        fh = tempfile.NamedTemporaryFile("w", suffix=".js", delete=False)
+        fh.write("C")
+        fh.close()
+        self.addCleanup(lambda: os.path.exists(fh.name) and os.unlink(fh.name))
+        return fh.name
+
+    def test_returns_capturer_when_driver_can_execute(self):
+        class Driver:
+            def __init__(self):
+                self.calls = []
+
+            def execute_script(self, script, *args):
+                self.calls.append(script)
+                return True  # ready probe
+
+        driver = Driver()
+        cap = start_snapshot_capture(driver, script_path=self._tmp_script())
+        self.assertIsInstance(cap, SnapshotCapturer)
+        self.assertTrue(cap.injected)
+
+    def test_none_when_driver_has_no_execute_script(self):
+        self.assertIsNone(start_snapshot_capture(object()))
+
+    def test_none_when_injection_fails(self):
+        class Driver:
+            def execute_script(self, script, *args):
+                return None
+
+        # No script on disk → injection returns None.
+        self.assertIsNone(
+            start_snapshot_capture(Driver(), script_path="/no/such.js")
+        )
+
+
+if __name__ == "__main__":
+    unittest.main()
diff --git a/packages/selenium-devtools-py/tests/test_sources.py b/packages/selenium-devtools-py/tests/test_sources.py
new file mode 100644
index 00000000..39361726
--- /dev/null
+++ b/packages/selenium-devtools-py/tests/test_sources.py
@@ -0,0 +1,73 @@
+import os
+import tempfile
+import unittest
+
+from selenium_devtools import sources
+
+
+class TestReadSource(unittest.TestCase):
+    def setUp(self):
+        self._dir = tempfile.TemporaryDirectory()
+        self.addCleanup(self._dir.cleanup)
+        self.root = self._dir.name
+
+    def _write(self, name, data, mode="w"):
+        path = os.path.join(self.root, name)
+        with open(path, mode) as handle:
+            handle.write(data)
+        return path
+
+    def test_reads_utf8_text(self):
+        path = self._write("t.py", "def test_x():\n    assert True\n")
+        self.assertEqual(sources.read_source(path), "def test_x():\n    assert True\n")
+
+    def test_missing_file_returns_none(self):
+        self.assertIsNone(sources.read_source(os.path.join(self.root, "nope.py")))
+
+    def test_directory_returns_none(self):
+        self.assertIsNone(sources.read_source(self.root))
+
+    def test_oversize_file_returns_none(self):
+        path = self._write("big.py", "x" * (sources.MAX_SOURCE_BYTES + 1))
+        self.assertIsNone(sources.read_source(path))
+
+    def test_at_cap_is_read(self):
+        path = self._write("ok.py", "y" * sources.MAX_SOURCE_BYTES)
+        result = sources.read_source(path)
+        self.assertIsNotNone(result)
+        self.assertEqual(len(result), sources.MAX_SOURCE_BYTES)
+
+    def test_invalid_bytes_do_not_raise(self):
+        path = self._write("bad.py", b"\xff\xfe not utf8", mode="wb")
+        # errors="replace" keeps the read total; the point is it never raises.
+        self.assertIsNotNone(sources.read_source(path))
+
+
+class TestCollectSources(unittest.TestCase):
+    def setUp(self):
+        self._dir = tempfile.TemporaryDirectory()
+        self.addCleanup(self._dir.cleanup)
+        self.root = self._dir.name
+
+    def _write(self, name, data):
+        path = os.path.join(self.root, name)
+        with open(path, "w") as handle:
+            handle.write(data)
+        return path
+
+    def test_maps_readable_paths_by_absolute_key(self):
+        a = self._write("a.py", "AAA")
+        b = self._write("b.py", "BBB")
+        result = sources.collect_sources([a, b])
+        self.assertEqual(result, {a: "AAA", b: "BBB"})
+        self.assertTrue(all(os.path.isabs(k) for k in result))
+
+    def test_skips_unreadable_and_dedupes(self):
+        a = self._write("a.py", "AAA")
+        missing = os.path.join(self.root, "gone.py")
+        result = sources.collect_sources([a, a, missing, ""])
+        self.assertEqual(result, {a: "AAA"})
+
+
+if __name__ == "__main__":
+    unittest.main()
diff --git a/packages/selenium-devtools-py/tests/test_terminal.py b/packages/selenium-devtools-py/tests/test_terminal.py
new file mode 100644
index 00000000..e459f2ed
--- /dev/null
+++ b/packages/selenium-devtools-py/tests/test_terminal.py
@@ -0,0 +1,60 @@
+import io
+import sys
+import unittest
+
+from selenium_devtools.terminal import TerminalCapturer, _TeeStream
+
+
+class FakeCapturer:
+    def __init__(self):
+        self.logs = []
+
+    def capture_console(self, level, args, source="browser"):
+        self.logs.append((level, args, source))
+
+
+class TestTee(unittest.TestCase):
+    def test_writes_through_and_emits_complete_lines(self):
+        buf = io.StringIO()
+        emitted = []
+        tee = _TeeStream(buf, emitted.append)
+        tee.write("hello\nworld\n")
+        self.assertEqual(buf.getvalue(), "hello\nworld\n")  # passthrough intact
+        self.assertEqual(emitted, ["hello", "world"])
+
+    def test_partial_line_is_buffered_until_newline(self):
+        emitted = []
+        tee = _TeeStream(io.StringIO(), emitted.append)
+        tee.write("par")
+        tee.write("tial\n")
+        self.assertEqual(emitted, ["partial"])
+
+    def test_skips_self_prefixed_and_blank_lines(self):
+        emitted = []
+        tee = _TeeStream(io.StringIO(), emitted.append)
+        tee.write("[devtools] internal\n\n   \nreal line\n")
+        self.assertEqual(emitted, ["real line"])
+
+    def test_delegates_unknown_attrs(self):
+        tee = _TeeStream(io.StringIO(), lambda _l: None)
+        self.assertFalse(tee.isatty())  # delegated to StringIO
+
+
+class TestTerminalCapturer(unittest.TestCase):
+    def test_start_captures_then_stop_restores(self):
+        cap = FakeCapturer()
+        orig_out, orig_err = sys.stdout, sys.stderr
+        tc = TerminalCapturer(cap)
+        tc.start()
+        try:
+            self.assertIsNot(sys.stdout, orig_out)  # wrapped while active
+            sys.stdout.write("captured line\n")
+        finally:
+            tc.stop()
+        self.assertIs(sys.stdout, orig_out)  # restored
+        self.assertIs(sys.stderr, orig_err)
+        self.assertIn(("log", ["captured line"], "terminal"), cap.logs)
+
+
+if __name__ == "__main__":
+    unittest.main()
diff --git a/packages/selenium-devtools-py/tests/test_transport.py b/packages/selenium-devtools-py/tests/test_transport.py
new file mode 100644
index 00000000..de713c58
--- /dev/null
+++ b/packages/selenium-devtools-py/tests/test_transport.py
@@ -0,0 +1,24 @@
+import threading
+import unittest
+
+from selenium_devtools.transport import WSClient
+
+
+class TestClose(unittest.TestCase):
+    def test_close_from_reader_thread_does_not_join_self(self):
+        # close() can run ON the reader thread (a clientDisconnected control
+        # frame triggering shutdown) — it must not try to join itself.
+        client = WSClient("localhost", 1)
+        client._reader = threading.current_thread()
+        client.connected = True
+        client.close()  # must not raise "cannot join current thread"
+        self.assertFalse(client.connected)
+
+    def test_close_is_safe_when_never_connected(self):
+        client = WSClient("localhost", 1)
+        client.close()  # no socket, no reader — no raise
+        self.assertFalse(client.connected)
+
+
+if __name__ == "__main__":
+    unittest.main()