From df2bf12494a0a1501974b9c9f40e46609becb3fb Mon Sep 17 00:00:00 2001
From: Vishnu Vardhan <vishnu.p@browserstack.com>
Date: Mon, 12 Oct 2026 17:21:28 +0530
Subject: [PATCH 01/18] fix(selenium-devtools): capture a plain script and let
 it exit

A runnerless script that never called DevTools.startTest dropped every
command: only a start call created the TestManager, so the "Selenium
Session" row the README promises never appeared. One is now created for
a script whose runner is undetected.

Such a script also never exited. Teardown runs on beforeExit, which the
open worker socket stopped from firing; the socket is now unref'd once
connected and re-ref'd while closing, so the close still completes.
---
 .changeset/selenium-plain-script-capture.md   |  5 +
 .../selenium-devtools/src/helpers/runtime.ts  |  9 +-
 packages/selenium-devtools/src/index.ts       |  2 +
 packages/selenium-devtools/src/session.ts     | 14 +++
 .../selenium-devtools/src/test-management.ts  | 13 ++-
 packages/selenium-devtools/src/types.ts       |  4 +
 .../tests/plain-script.test.ts                | 91 +++++++++++++++++++
 7 files changed, 136 insertions(+), 2 deletions(-)
 create mode 100644 .changeset/selenium-plain-script-capture.md
 create mode 100644 packages/selenium-devtools/tests/plain-script.test.ts

diff --git a/.changeset/selenium-plain-script-capture.md b/.changeset/selenium-plain-script-capture.md
new file mode 100644
index 00000000..0a9d8c65
--- /dev/null
+++ b/.changeset/selenium-plain-script-capture.md
@@ -0,0 +1,5 @@
+---
+'@wdio/selenium-devtools': patch
+---
+
+A plain `node script.js` run with no test runner is now captured without calling `DevTools.startTest`: its commands land under the "Selenium Session" row the README describes, where before every command was dropped. Such a script also exits once its work is done, where before the open dashboard connection kept the process alive indefinitely, which also left a rerun of a plain script running after it finished.
diff --git a/packages/selenium-devtools/src/helpers/runtime.ts b/packages/selenium-devtools/src/helpers/runtime.ts
index eba09138..1fc21133 100644
--- a/packages/selenium-devtools/src/helpers/runtime.ts
+++ b/packages/selenium-devtools/src/helpers/runtime.ts
@@ -1,5 +1,7 @@
 import { createRequire } from 'node:module'
 
+import type { DetectedRunner } from '../types.js'
+
 export function detectOwnVersion(): string {
   try {
     return createRequire(import.meta.url)('../../package.json').version
@@ -8,7 +10,7 @@ export function detectOwnVersion(): string {
   }
 }
 
-export function detectRunner(): string {
+export function detectRunner(): DetectedRunner {
   const argv = (process.argv[1] || '').toLowerCase()
   if (argv.includes('mocha')) {
     return 'mocha'
@@ -31,6 +33,11 @@ export function detectRunner(): string {
   return 'unknown'
 }
 
+/** A plain script: no runner hook declares its test boundaries. */
+export function isRunnerless(runner: DetectedRunner): boolean {
+  return runner === 'node' || runner === 'unknown'
+}
+
 export function detectSeleniumVersion(): string | undefined {
   const tryRead = (req: NodeRequire): string | undefined => {
     try {
diff --git a/packages/selenium-devtools/src/index.ts b/packages/selenium-devtools/src/index.ts
index 25ce477a..3d59ae85 100644
--- a/packages/selenium-devtools/src/index.ts
+++ b/packages/selenium-devtools/src/index.ts
@@ -32,6 +32,7 @@ import {
   startScenario as tmStartScenario,
   endScenario as tmEndScenario,
   flushPendingTestActions as tmFlushPendingTestActions,
+  ensureRunnerlessTracking,
   buildStartTestMeta,
   type StartTestMeta,
   type StartScenarioMeta,
@@ -520,6 +521,7 @@ class SeleniumDevToolsPlugin {
 
   #flushPendingTestActions() {
     tmFlushPendingTestActions(this.#getInternals())
+    ensureRunnerlessTracking(this.#getInternals(), DETECTED_RUNNER)
     // The first test's startTest fires before the driver/capturer exists, so
     // its per-test boundary is recorded here once capture is live.
     if (this.#options.traceGranularity === 'test') {
diff --git a/packages/selenium-devtools/src/session.ts b/packages/selenium-devtools/src/session.ts
index 99eb4481..6450cce8 100644
--- a/packages/selenium-devtools/src/session.ts
+++ b/packages/selenium-devtools/src/session.ts
@@ -1,3 +1,5 @@
+import type { IncomingMessage } from 'node:http'
+
 import logger from '@wdio/logger'
 import {
   COLLECTOR_READY_EXPRESSION,
@@ -40,6 +42,7 @@ export class SessionCapturer extends SessionCapturerBase {
   #clientConnected = false
   #clientConnectedWaiters: Array<() => void> = []
   #onClientDisconnected?: () => void
+  #socket: IncomingMessage['socket'] | undefined
 
   constructor(
     devtoolsOptions: { hostname?: string; port?: number } = {},
@@ -47,6 +50,11 @@ export class SessionCapturer extends SessionCapturerBase {
   ) {
     super(devtoolsOptions)
     this.#driver = driver
+    // Teardown runs on `beforeExit`, which a ref'd socket stops from ever firing.
+    this.ws?.once('upgrade', (res: IncomingMessage) => {
+      this.#socket = res.socket
+      this.#socket.unref()
+    })
 
     // Skip console patching when running under Jest's CustomConsole / Vitest —
     // those reroute writes through their own console, which causes our patched
@@ -97,6 +105,12 @@ export class SessionCapturer extends SessionCapturerBase {
     this.#driver = driver
   }
 
+  /** Re-ref'd first so the close handshake keeps the process alive until it lands. */
+  override async closeWebSocket(): Promise<void> {
+    this.#socket?.ref()
+    await super.closeWebSocket()
+  }
+
   awaitClientConnected(): Promise<void> {
     if (this.#clientConnected) {
       return Promise.resolve()
diff --git a/packages/selenium-devtools/src/test-management.ts b/packages/selenium-devtools/src/test-management.ts
index e62d17de..b8b6cd96 100644
--- a/packages/selenium-devtools/src/test-management.ts
+++ b/packages/selenium-devtools/src/test-management.ts
@@ -10,12 +10,13 @@
 
 import logger from '@wdio/logger'
 import { TestManager } from './helpers/testManager.js'
+import { isRunnerless } from './helpers/runtime.js'
 import { getCallSourceFromStack } from './helpers/utils.js'
 import { DEFAULTS } from './constants.js'
 import type { SessionCapturer } from './session.js'
 import type { TestReporter } from './reporter.js'
 import type { SuiteManager } from './helpers/suiteManager.js'
-import type { TestStats } from './types.js'
+import type { DetectedRunner, TestStats } from './types.js'
 import type { RetryTracker } from '@wdio/devtools-core'
 
 const log = logger('@wdio/selenium-devtools:test-management')
@@ -256,6 +257,16 @@ export function ensureSuiteAndTestManager(
   }
 }
 
+/** Without a TestManager every command is dropped, so a plain script gets the session one. */
+export function ensureRunnerlessTracking(
+  ctx: TestManagementCtx,
+  runner: DetectedRunner
+): void {
+  if (!ctx.testManager && isRunnerless(runner)) {
+    ensureSuiteAndTestManager(ctx, DEFAULTS.SESSION_TITLE)
+  }
+}
+
 /** Apply any startTest/endTest calls buffered before testManager existed. */
 export function flushPendingTestActions(ctx: TestManagementCtx): void {
   if (ctx.pendingTestActions.length === 0) {
diff --git a/packages/selenium-devtools/src/types.ts b/packages/selenium-devtools/src/types.ts
index 784daa1c..7de5b1de 100644
--- a/packages/selenium-devtools/src/types.ts
+++ b/packages/selenium-devtools/src/types.ts
@@ -58,6 +58,10 @@ import type {
 } from '@wdio/devtools-shared'
 export type { ScreencastFrame, ScreencastOptions } from '@wdio/devtools-shared'
 
+/** What `detectRunner` reads off the process; `node` and `unknown` mean no runner. */
+export type DetectedRunner =
+  'mocha' | 'jest' | 'jasmine' | 'vitest' | 'cucumber' | 'node' | 'unknown'
+
 /**
  * Minimal shape of a selenium-webdriver `WebDriver` instance that the plugin
  * relies on. We don't import the type from selenium-webdriver to avoid a hard
diff --git a/packages/selenium-devtools/tests/plain-script.test.ts b/packages/selenium-devtools/tests/plain-script.test.ts
new file mode 100644
index 00000000..2e34114a
--- /dev/null
+++ b/packages/selenium-devtools/tests/plain-script.test.ts
@@ -0,0 +1,91 @@
+import { createServer } from 'node:http'
+import type { AddressInfo } from 'node:net'
+import { Socket } from 'node:net'
+
+import { RetryTracker } from '@wdio/devtools-core'
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { WebSocketServer } from 'ws'
+
+import { SuiteManager } from '../src/helpers/suiteManager.js'
+import { isRunnerless } from '../src/helpers/runtime.js'
+import { TestReporter } from '../src/reporter.js'
+import { SessionCapturer } from '../src/session.js'
+import {
+  ensureRunnerlessTracking,
+  type TestManagementCtx
+} from '../src/test-management.js'
+import type { DetectedRunner } from '../src/types.js'
+
+function makeCtx(): TestManagementCtx {
+  const testReporter = new TestReporter(vi.fn())
+  return {
+    retryTracker: new RetryTracker(),
+    testReporter,
+    sessionCapturer: undefined,
+    suiteManager: new SuiteManager(testReporter),
+    testManager: undefined,
+    testFilePath: undefined,
+    pendingTestActions: [],
+    pendingScenario: null
+  }
+}
+
+describe('a plain script that never calls startTest', () => {
+  // Regression: only a start call created the TestManager, so a plain script dropped every command.
+  it.each<DetectedRunner>(['unknown', 'node'])(
+    'gets a session test under runner %s',
+    (runner) => {
+      const ctx = makeCtx()
+      ensureRunnerlessTracking(ctx, runner)
+      expect(ctx.testManager?.getOrEnsureTest()?.title).toBe('Selenium Session')
+    }
+  )
+
+  it.each<DetectedRunner>(['mocha', 'jest', 'cucumber'])(
+    'leaves %s to declare its own test boundaries',
+    (runner) => {
+      const ctx = makeCtx()
+      ensureRunnerlessTracking(ctx, runner)
+      expect(ctx.testManager).toBeUndefined()
+      expect(isRunnerless(runner)).toBe(false)
+    }
+  )
+})
+
+describe('the worker socket', () => {
+  const servers: Array<() => Promise<void>> = []
+  afterEach(async () => {
+    vi.restoreAllMocks()
+    await Promise.all(servers.splice(0).map((close) => close()))
+  })
+
+  async function backend(): Promise<number> {
+    const server = createServer()
+    const wss = new WebSocketServer({ server })
+    await new Promise<void>((r) => server.listen(0, '127.0.0.1', r))
+    servers.push(async () => {
+      for (const c of wss.clients) {
+        c.terminate()
+      }
+      wss.close()
+      await new Promise((r) => server.close(r))
+    })
+    return (server.address() as AddressInfo).port
+  }
+
+  // Regression: a ref'd socket kept `beforeExit` from firing, so a finished plain script hung.
+  it('does not hold the process open, but holds it while closing', async () => {
+    const unref = vi.spyOn(Socket.prototype, 'unref')
+    const ref = vi.spyOn(Socket.prototype, 'ref')
+    const capturer = new SessionCapturer({
+      hostname: '127.0.0.1',
+      port: await backend()
+    })
+    await capturer.waitForConnection(2000)
+    expect(unref).toHaveBeenCalled()
+
+    await capturer.closeWebSocket()
+    expect(ref).toHaveBeenCalled()
+    capturer.cleanup()
+  })
+})

From 4e1378e6898afea54479c263059a46f56ee81f9b Mon Sep 17 00:00:00 2001
From: Vishnu Vardhan <vishnu.p@browserstack.com>
Date: Mon, 12 Oct 2026 17:21:28 +0530
Subject: [PATCH 02/18] refactor(shared): one replaceCommand rule for the app
 and the backend

The app and the backend's baseline store each carried their own copy of
how a replaceCommand payload finds its row: by stable id, else the last
row carrying the old timestamp. It now lives once in shared, with a test
pinning the case that matters: two rows completing in one millisecond.
---
 packages/app/src/controller/contextUpdates.ts | 29 +--------------
 packages/backend/src/baselineStore.ts         | 13 +------
 packages/shared/src/command-replace.ts        | 34 +++++++++++++++++
 packages/shared/src/index.ts                  |  1 +
 packages/shared/tests/command-replace.test.ts | 37 +++++++++++++++++++
 5 files changed, 75 insertions(+), 39 deletions(-)
 create mode 100644 packages/shared/src/command-replace.ts
 create mode 100644 packages/shared/tests/command-replace.test.ts

diff --git a/packages/app/src/controller/contextUpdates.ts b/packages/app/src/controller/contextUpdates.ts
index 41b2a8d0..c17a4dff 100644
--- a/packages/app/src/controller/contextUpdates.ts
+++ b/packages/app/src/controller/contextUpdates.ts
@@ -9,39 +9,12 @@
 
 import {
   deviceFromCapabilities,
-  type CommandLog,
   type NetworkRequest,
   type Metadata,
   type MetadataBySession
 } from '@wdio/devtools-shared'
 
-/**
- * Replace an existing command entry (matched first by stable `id`, then by
- * `timestamp` as a fallback for runners that don't surface ids). When no
- * match is found, the new entry is appended.
- */
-export function replaceCommand(
-  current: CommandLog[],
-  oldTimestamp: number,
-  newCommand: CommandLog
-): CommandLog[] {
-  let idx = -1
-  const newId = (newCommand as CommandLog & { id?: number }).id
-  if (typeof newId === 'number') {
-    idx = current.findIndex(
-      (c) => (c as CommandLog & { id?: number }).id === newId
-    )
-  }
-  if (idx === -1) {
-    idx = current.map((c) => c.timestamp).lastIndexOf(oldTimestamp)
-  }
-  if (idx !== -1) {
-    const next = [...current]
-    next[idx] = newCommand
-    return next
-  }
-  return [...current, newCommand]
-}
+export { replaceCommand } from '@wdio/devtools-shared'
 
 /**
  * Merge incoming network requests into the current list, deduping by `id`.
diff --git a/packages/backend/src/baselineStore.ts b/packages/backend/src/baselineStore.ts
index 85b1ebf1..3c73ace0 100644
--- a/packages/backend/src/baselineStore.ts
+++ b/packages/backend/src/baselineStore.ts
@@ -3,7 +3,7 @@
  * into an accumulator, then time-window-filters per test/suite on demand.
  */
 import logger from '@wdio/logger'
-import type { Metadata } from '@wdio/devtools-shared'
+import { replaceCommandIndex, type Metadata } from '@wdio/devtools-shared'
 
 import type {
   ActiveRun,
@@ -102,18 +102,9 @@ class BaselineStore {
     return this.#activeRun
   }
 
-  // Mirrors the app's command replacement: match by stable `id`, then by the
-  // old timestamp, appending only when neither locates the original.
   #replaceCommand(oldTimestamp: number | undefined, command: CommandLogLike) {
     const cmds = this.#activeRun.commands
-    const newId = (command as { id?: number }).id
-    let idx = -1
-    if (typeof newId === 'number') {
-      idx = cmds.findIndex((c) => (c as { id?: number }).id === newId)
-    }
-    if (idx === -1 && oldTimestamp !== undefined) {
-      idx = cmds.map((c) => c.timestamp).lastIndexOf(oldTimestamp)
-    }
+    const idx = replaceCommandIndex(cmds, oldTimestamp, command)
     if (idx === -1) {
       cmds.push(command)
     } else {
diff --git a/packages/shared/src/command-replace.ts b/packages/shared/src/command-replace.ts
new file mode 100644
index 00000000..5bf30f3f
--- /dev/null
+++ b/packages/shared/src/command-replace.ts
@@ -0,0 +1,34 @@
+import type { CommandLog } from './types.js'
+
+/** Same stable `id`, else the last row with the old timestamp (two rows can share a millisecond), else -1. */
+export function replaceCommandIndex(
+  current: readonly CommandLog[],
+  oldTimestamp: number | undefined,
+  command: CommandLog
+): number {
+  if (typeof command.id === 'number') {
+    const byId = current.findIndex((c) => c.id === command.id)
+    if (byId !== -1) {
+      return byId
+    }
+  }
+  return oldTimestamp === undefined
+    ? -1
+    : current.map((c) => c.timestamp).lastIndexOf(oldTimestamp)
+}
+
+/** A copy of `current` with the replacement applied, appended when it locates nothing. */
+export function replaceCommand(
+  current: readonly CommandLog[],
+  oldTimestamp: number | undefined,
+  command: CommandLog
+): CommandLog[] {
+  const next = [...current]
+  const at = replaceCommandIndex(current, oldTimestamp, command)
+  if (at === -1) {
+    next.push(command)
+  } else {
+    next[at] = command
+  }
+  return next
+}
diff --git a/packages/shared/src/index.ts b/packages/shared/src/index.ts
index 841d024a..cd9963e2 100644
--- a/packages/shared/src/index.ts
+++ b/packages/shared/src/index.ts
@@ -8,6 +8,7 @@ export * from './console.js'
 export * from './device.js'
 export * from './element-scripts.js'
 export * from './collector.js'
+export * from './command-replace.js'
 export * from './files.js'
 export * from './image.js'
 export * from './locator-dialect.js'
diff --git a/packages/shared/tests/command-replace.test.ts b/packages/shared/tests/command-replace.test.ts
new file mode 100644
index 00000000..8ad538cc
--- /dev/null
+++ b/packages/shared/tests/command-replace.test.ts
@@ -0,0 +1,37 @@
+import { describe, expect, it } from 'vitest'
+
+import { replaceCommand, replaceCommandIndex } from '../src/command-replace.js'
+import type { CommandLog } from '../src/types.js'
+
+const row = (command: string, timestamp: number, id?: number): CommandLog => ({
+  command,
+  args: [],
+  timestamp,
+  ...(id === undefined ? {} : { id })
+})
+
+describe('replaceCommand', () => {
+  // Regression: two rows completing in one millisecond, matched by timestamp
+  // alone, sent the second row's update onto the first and erased it.
+  it('targets the row by id when two rows share a timestamp', () => {
+    const current = [row('sendKeys', 42, 4), row('findElement', 42, 5)]
+    const next = replaceCommand(current, 42, row('findElement', 42, 5))
+    expect(next.map((r) => r.command)).toEqual(['sendKeys', 'findElement'])
+  })
+
+  it('falls back to the last row with the old timestamp', () => {
+    const current = [row('a', 42), row('b', 42)]
+    expect(replaceCommandIndex(current, 42, row('c', 42))).toBe(1)
+  })
+
+  it('appends when nothing matches', () => {
+    const next = replaceCommand([row('a', 1)], 999, row('b', 999))
+    expect(next.map((r) => r.command)).toEqual(['a', 'b'])
+  })
+
+  it('does not mutate the list it was given', () => {
+    const current = [row('a', 1, 1)]
+    replaceCommand(current, 1, row('b', 1, 1))
+    expect(current[0].command).toBe('a')
+  })
+})

From ec141fd30410c227ef496eb7a92532755000f3d4 Mon Sep 17 00:00:00 2001
From: Vishnu Vardhan <vishnu.p@browserstack.com>
Date: Mon, 12 Oct 2026 17:21:28 +0530
Subject: [PATCH 03/18] refactor(shared): move RunCapabilities and
 RunnerOptions into shared

They describe what an adapter puts in Metadata.options for the run
controls, which crosses the wire, so they belong beside Metadata. The
app keeps its names through a re-export.
---
 packages/app/src/components/sidebar/types.ts | 15 +--------------
 packages/shared/src/types.ts                 | 17 +++++++++++++++++
 2 files changed, 18 insertions(+), 14 deletions(-)

diff --git a/packages/app/src/components/sidebar/types.ts b/packages/app/src/components/sidebar/types.ts
index 5375ba9c..b3b03fd5 100644
--- a/packages/app/src/components/sidebar/types.ts
+++ b/packages/app/src/components/sidebar/types.ts
@@ -12,20 +12,7 @@ export interface TestEntry {
   suiteType?: string
 }
 
-export interface RunCapabilities {
-  canRunSuites: boolean
-  canRunTests: boolean
-  canRunAll: boolean
-}
-
-export interface RunnerOptions {
-  framework?: string
-  configFile?: string
-  configFilePath?: string
-  runCapabilities?: Partial<RunCapabilities>
-  rerunCommand?: string
-  launchCommand?: string
-}
+export type { RunCapabilities, RunnerOptions } from '@wdio/devtools-shared'
 
 export interface TestRunDetail {
   uid: string
diff --git a/packages/shared/src/types.ts b/packages/shared/src/types.ts
index c1e0b582..919fe4bb 100644
--- a/packages/shared/src/types.ts
+++ b/packages/shared/src/types.ts
@@ -470,6 +470,23 @@ export interface CucumberPickle {
   steps?: CucumberPickleStep[]
 }
 
+/** Which run controls the dashboard offers for a session. */
+export interface RunCapabilities {
+  canRunSuites: boolean
+  canRunTests: boolean
+  canRunAll: boolean
+}
+
+/** What an adapter puts in `Metadata.options` for the run controls; the backend spawns these commands. */
+export interface RunnerOptions {
+  framework?: string
+  configFile?: string
+  configFilePath?: string
+  runCapabilities?: Partial<RunCapabilities>
+  rerunCommand?: string
+  launchCommand?: string
+}
+
 export interface Metadata {
   type: TraceType
   url?: string

From c2c4f8312f869ffc4b0928be67554276f5d5231f Mon Sep 17 00:00:00 2001
From: Vishnu Vardhan <vishnu.p@browserstack.com>
Date: Mon, 12 Oct 2026 17:21:28 +0530
Subject: [PATCH 04/18] fix(selenium-devtools-py): carry the browser's error
 message, not str()

A WebDriverException's str() prefixes "Message: " and appends the
driver's stacktrace, so the dashboard's Errors tab showed both around the
browser's text. The row now carries `msg`, the browser's own message, as
the JavaScript adapters do; other exceptions keep their str().
---
 .../changes/browser-error-message.md                  |  5 +++++
 .../src/selenium_devtools/frames.py                   |  4 +++-
 packages/selenium-devtools-py/tests/test_frames.py    | 11 +++++++++++
 3 files changed, 19 insertions(+), 1 deletion(-)
 create mode 100644 packages/selenium-devtools-py/changes/browser-error-message.md

diff --git a/packages/selenium-devtools-py/changes/browser-error-message.md b/packages/selenium-devtools-py/changes/browser-error-message.md
new file mode 100644
index 00000000..68a287b1
--- /dev/null
+++ b/packages/selenium-devtools-py/changes/browser-error-message.md
@@ -0,0 +1,5 @@
+---
+patch
+---
+
+A failed command's row now carries the browser's own error message, as the JavaScript adapters send it. It used to carry the exception's string form, so the dashboard's Errors tab showed `Message: ` before the text and the driver's stacktrace after it.
diff --git a/packages/selenium-devtools-py/src/selenium_devtools/frames.py b/packages/selenium-devtools-py/src/selenium_devtools/frames.py
index c8ea8a07..e4ef51ba 100644
--- a/packages/selenium-devtools-py/src/selenium_devtools/frames.py
+++ b/packages/selenium-devtools-py/src/selenium_devtools/frames.py
@@ -92,7 +92,9 @@ def command_log(
     if error is not None:
         entry["error"] = {
             "name": type(error).__name__,
-            "message": str(error),
+            # A WebDriverException's str() adds "Message: " and the driver's
+            # stacktrace; `msg` is the browser's own text, which the JS adapters send.
+            "message": getattr(error, "msg", None) or str(error),
         }
     if screenshot:
         entry["screenshot"] = screenshot
diff --git a/packages/selenium-devtools-py/tests/test_frames.py b/packages/selenium-devtools-py/tests/test_frames.py
index 5a3ffc4e..99c263e2 100644
--- a/packages/selenium-devtools-py/tests/test_frames.py
+++ b/packages/selenium-devtools-py/tests/test_frames.py
@@ -49,6 +49,17 @@ def test_command_log_includes_error_only_when_present(self):
         )
         self.assertEqual(bad["error"], {"name": "ValueError", "message": "nope"})
 
+    def test_a_webdriver_error_carries_the_browsers_message_not_its_str(self):
+        # Regression: str() gave the Errors tab "Message: ...\nStacktrace: ...".
+        from selenium.common.exceptions import WebDriverException
+
+        error = WebDriverException("net::ERR_FAILED at /broken", stacktrace=["#0 0x55d0"])
+        row = frames.command_log(
+            command="get", args=[], error=error,
+            timestamp=2, start_time=1, call_source=None, command_id=5,
+        )
+        self.assertEqual(row["error"]["message"], "net::ERR_FAILED at /broken")
+
     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",

From 6e848a8b5fac3d006c091f32faf23b03dd66568d Mon Sep 17 00:00:00 2001
From: Vishnu Vardhan <vishnu.p@browserstack.com>
Date: Mon, 12 Oct 2026 17:21:28 +0530
Subject: [PATCH 05/18] test: add a cross-adapter conformance suite

Each adapter runs one scenario as its own process against a fake W3C
WebDriver that records what really happened in the browser, reporting
into a recording backend through the rerun reuse handshake, so no
adapter gains a test-only path. One checker judges every recorded frame
stream against behavioural rules, with and without BiDi. The fake
recognises the collector by its own source rather than any adapter's
idiom, and the recording backend serves the real collector bundle.

Known gaps need a reason and fail once they stop occurring. Every run
writes its stream and verdict to out/, and an HTML report places each
violation on the event it concerns, naming the adapter responsibility
the broken rule tests. Covers selenium-devtools and selenium-devtools-py.

Refs #300
---
 .gitignore                                    |   2 +
 packages/conformance/package.json             |  26 ++
 .../conformance/scenarios/python_scenario.py  |  37 +++
 packages/conformance/scenarios/selenium.ts    |  32 ++
 packages/conformance/src/allowlist.ts         |  38 +++
 packages/conformance/src/checker.ts           | 247 ++++++++++++++
 packages/conformance/src/constants.ts         | 120 +++++++
 packages/conformance/src/fake-bidi.ts         |  47 +++
 packages/conformance/src/fake-webdriver.ts    | 300 ++++++++++++++++++
 packages/conformance/src/harness.ts           |  70 ++++
 packages/conformance/src/recording-backend.ts |  75 +++++
 packages/conformance/src/report-html.ts       | 177 +++++++++++
 packages/conformance/src/report.ts            |  45 +++
 packages/conformance/src/rule-guide.ts        |  78 +++++
 packages/conformance/src/timeline.ts          |  81 +++++
 packages/conformance/src/types.ts             | 136 ++++++++
 packages/conformance/tests/checker.test.ts    | 216 +++++++++++++
 packages/conformance/tests/python.test.ts     |  74 +++++
 packages/conformance/tests/report.test.ts     | 149 +++++++++
 packages/conformance/tests/selenium.test.ts   |  52 +++
 packages/conformance/tsconfig.json            |   4 +
 pnpm-lock.yaml                                |  86 ++---
 pnpm-workspace.yaml                           |   1 +
 23 files changed, 2038 insertions(+), 55 deletions(-)
 create mode 100644 packages/conformance/package.json
 create mode 100644 packages/conformance/scenarios/python_scenario.py
 create mode 100644 packages/conformance/scenarios/selenium.ts
 create mode 100644 packages/conformance/src/allowlist.ts
 create mode 100644 packages/conformance/src/checker.ts
 create mode 100644 packages/conformance/src/constants.ts
 create mode 100644 packages/conformance/src/fake-bidi.ts
 create mode 100644 packages/conformance/src/fake-webdriver.ts
 create mode 100644 packages/conformance/src/harness.ts
 create mode 100644 packages/conformance/src/recording-backend.ts
 create mode 100644 packages/conformance/src/report-html.ts
 create mode 100644 packages/conformance/src/report.ts
 create mode 100644 packages/conformance/src/rule-guide.ts
 create mode 100644 packages/conformance/src/timeline.ts
 create mode 100644 packages/conformance/src/types.ts
 create mode 100644 packages/conformance/tests/checker.test.ts
 create mode 100644 packages/conformance/tests/python.test.ts
 create mode 100644 packages/conformance/tests/report.test.ts
 create mode 100644 packages/conformance/tests/selenium.test.ts
 create mode 100644 packages/conformance/tsconfig.json

diff --git a/.gitignore b/.gitignore
index ad7b9c30..1ca4ecec 100644
--- a/.gitignore
+++ b/.gitignore
@@ -54,6 +54,8 @@ examples/**/trace-*/
 
 # test results
 examples/**/test-results*/
+packages/conformance/**/test-results*/
+packages/conformance/out/
 
 # vitest --coverage output
 coverage/
diff --git a/packages/conformance/package.json b/packages/conformance/package.json
new file mode 100644
index 00000000..73df2f02
--- /dev/null
+++ b/packages/conformance/package.json
@@ -0,0 +1,26 @@
+{
+  "name": "@wdio/devtools-conformance",
+  "version": "1.0.0",
+  "private": true,
+  "author": "Vishnu Vardhan",
+  "description": "Cross-adapter conformance suite: drives each adapter through one scenario against a fake WebDriver server, records the frames it sends, and checks them against behavioural rules. Test-only, never published or bundled.",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/webdriverio/devtools.git",
+    "directory": "packages/conformance"
+  },
+  "type": "module",
+  "scripts": {
+    "lint": "eslint ."
+  },
+  "license": "MIT",
+  "devDependencies": {
+    "@types/node": "26.6.4",
+    "@types/selenium-webdriver": "^4.35.6",
+    "@types/ws": "^8.18.2",
+    "@wdio/devtools-shared": "workspace:^",
+    "@wdio/selenium-devtools": "workspace:^",
+    "selenium-webdriver": "^4.50.0",
+    "ws": "^8.22.0"
+  }
+}
diff --git a/packages/conformance/scenarios/python_scenario.py b/packages/conformance/scenarios/python_scenario.py
new file mode 100644
index 00000000..bb2e6d7a
--- /dev/null
+++ b/packages/conformance/scenarios/python_scenario.py
@@ -0,0 +1,37 @@
+"""The conformance scenario, driven through selenium-devtools-py.
+
+Run by the conformance harness, which points ``enable()`` at its recording
+backend through the reuse handshake and Selenium at its fake WebDriver.
+"""
+
+import os
+
+from selenium import webdriver
+from selenium.common.exceptions import WebDriverException
+from selenium.webdriver.common.by import By
+
+import selenium_devtools
+
+
+def env(name: str) -> str:
+    value = os.environ.get(name)
+    if not value:
+        raise SystemExit(f"{name} is not set; run this through the conformance harness")
+    return value
+
+
+selenium_devtools.enable()
+driver = webdriver.Remote(command_executor=env("CONFORMANCE_WEBDRIVER"), options=webdriver.ChromeOptions())
+try:
+    driver.get(env("CONFORMANCE_LOGIN_URL"))
+    driver.find_element(By.CSS_SELECTOR, "#username").send_keys("tom")
+    driver.find_element(By.CSS_SELECTOR, "#password").send_keys("secret")
+    driver.find_element(By.CSS_SELECTOR, 'button[type="submit"]').click()
+    driver.find_element(By.CSS_SELECTOR, "#logout").click()
+    try:
+        driver.get(env("CONFORMANCE_BROKEN_URL"))
+    except WebDriverException:
+        pass
+finally:
+    driver.quit()
+    selenium_devtools.disable()
diff --git a/packages/conformance/scenarios/selenium.ts b/packages/conformance/scenarios/selenium.ts
new file mode 100644
index 00000000..dc617d16
--- /dev/null
+++ b/packages/conformance/scenarios/selenium.ts
@@ -0,0 +1,32 @@
+// Imported first: the import is what patches selenium-webdriver.
+import { DevTools } from '@wdio/selenium-devtools'
+import { Builder, By } from 'selenium-webdriver'
+
+import { SCENARIO_ENV } from '../src/constants.js'
+
+DevTools.configure({ openUi: false })
+
+const env = (name: string): string => {
+  const value = process.env[name]
+  if (!value) {
+    throw new Error(
+      `${name} is not set; run this through the conformance harness`
+    )
+  }
+  return value
+}
+
+const driver = await new Builder()
+  .forBrowser('chrome')
+  .usingServer(env(SCENARIO_ENV.webdriver))
+  .build()
+try {
+  await driver.get(env(SCENARIO_ENV.login))
+  await driver.findElement(By.css('#username')).sendKeys('tom')
+  await driver.findElement(By.css('#password')).sendKeys('secret')
+  await driver.findElement(By.css('button[type="submit"]')).click()
+  await driver.findElement(By.css('#logout')).click()
+  await driver.get(env(SCENARIO_ENV.broken)).catch(() => undefined)
+} finally {
+  await driver.quit()
+}
diff --git a/packages/conformance/src/allowlist.ts b/packages/conformance/src/allowlist.ts
new file mode 100644
index 00000000..361f89bd
--- /dev/null
+++ b/packages/conformance/src/allowlist.ts
@@ -0,0 +1,38 @@
+import type { AdapterId, Judgement, KnownGap, Violation } from './types.js'
+
+export const KNOWN_GAPS: KnownGap[] = [
+  {
+    adapter: 'selenium-devtools',
+    bidi: false,
+    rules: ['every-document-anchored', 'navigation-row-shows-destination'],
+    reason:
+      'Without BiDi the collector is appended as a <script> after a readiness poll, so a document the test leaves within tens of ms is never anchored. CLAUDE.md Known debt: "Document-start injection is what removes the whole race class".',
+    timingDependent: true
+  }
+]
+
+export function judge(
+  adapter: AdapterId,
+  bidi: boolean,
+  violations: Violation[]
+): Judgement {
+  const gaps = gapsFor(adapter, bidi)
+  return {
+    unexplained: violations.filter((v) => !explainingGap(gaps, v)),
+    stale: gaps.filter(
+      (g) =>
+        !g.timingDependent && !violations.some((v) => g.rules.includes(v.rule))
+    )
+  }
+}
+
+export function gapsFor(adapter: AdapterId, bidi: boolean): KnownGap[] {
+  return KNOWN_GAPS.filter((g) => g.adapter === adapter && g.bidi === bidi)
+}
+
+export function explainingGap(
+  gaps: KnownGap[],
+  violation: Violation
+): KnownGap | undefined {
+  return gaps.find((g) => g.rules.includes(violation.rule))
+}
diff --git a/packages/conformance/src/checker.ts b/packages/conformance/src/checker.ts
new file mode 100644
index 00000000..00c76ef0
--- /dev/null
+++ b/packages/conformance/src/checker.ts
@@ -0,0 +1,247 @@
+import {
+  mapCommandToAction,
+  replaceCommand,
+  type CommandLog,
+  type Metadata,
+  type RunnerOptions,
+  type ReplaceCommandWsPayload,
+  type TraceMutation
+} from '@wdio/devtools-shared'
+
+import { ACTION_METHODS, RULES, SCOPES } from './constants.js'
+import type {
+  GroundTruth,
+  RecordedStream as Stream,
+  Violation,
+  WireFrame
+} from './types.js'
+
+export function checkConformance(
+  frames: WireFrame[],
+  truth: GroundTruth
+): Violation[] {
+  const stream = readStream(frames)
+  return [
+    ...metadataFirst(stream),
+    ...completionStamp(stream),
+    ...anchors(stream, truth),
+    ...navigationShowsDestination(stream),
+    ...failureRecorded(stream, truth),
+    ...replaceTargetsRow(stream),
+    ...rowPerAction(stream, truth),
+    ...runControlsHaveCommand(stream)
+  ]
+}
+
+// Frames are cast per scope: each scope's payload shape is shared's contract.
+export function readStream(frames: WireFrame[]): Stream {
+  let rows: CommandLog[] = []
+  const anchors: TraceMutation[] = []
+  for (const { scope, data } of frames) {
+    if (scope === SCOPES.commands) {
+      rows.push(...(data as CommandLog[]))
+    } else if (scope === SCOPES.replaceCommand) {
+      // The dashboard's own rule, so the rows judged are the rows a user sees.
+      const { oldTimestamp, command } = data as ReplaceCommandWsPayload
+      rows = replaceCommand(rows, oldTimestamp, command)
+    } else if (scope === SCOPES.mutations) {
+      anchors.push(
+        ...(data as TraceMutation[]).filter(
+          (m) => m.type === 'childList' && m.url !== undefined
+        )
+      )
+    }
+  }
+  anchors.sort((a, b) => a.timestamp - b.timestamp)
+  return { frames, rows, anchors }
+}
+
+function metadataFirst({ frames }: Stream): Violation[] {
+  const metadata = frames.findIndex((f) => f.scope === SCOPES.metadata)
+  const commands = frames.findIndex((f) => f.scope === SCOPES.commands)
+  if (commands === -1 || (metadata !== -1 && metadata < commands)) {
+    return []
+  }
+  return [
+    {
+      rule: RULES.metadataFirst,
+      message: `first commands frame (#${commands}) arrived before any metadata`,
+      ...rowSubject((frames[commands].data as CommandLog[])[0])
+    }
+  ]
+}
+
+function completionStamp({ rows }: Stream): Violation[] {
+  return rows
+    .filter((r) => r.startTime !== undefined && r.startTime > r.timestamp)
+    .map((r) => ({
+      rule: RULES.completionStamp,
+      message: `${r.command} ends (${r.timestamp}) before it starts (${r.startTime})`,
+      ...rowSubject(r)
+    }))
+}
+
+// An anchor belongs to the document born after the previous one and no earlier than the anchor.
+function anchors(stream: Stream, truth: GroundTruth): Violation[] {
+  const counts = truth.documents.map(() => 0)
+  const out: Violation[] = []
+  for (const anchor of stream.anchors) {
+    const at = truth.documents.findIndex(
+      (d, i) =>
+        anchor.timestamp <= d.bornAt &&
+        (i === 0 || anchor.timestamp > truth.documents[i - 1].bornAt)
+    )
+    if (at === -1 || truth.documents[at].url !== anchor.url) {
+      out.push({
+        rule: RULES.anchorBirthTime,
+        message: `anchor for ${anchor.url} at ${anchor.timestamp} matches no document born then`,
+        subject: { kind: 'anchor', timestamp: anchor.timestamp }
+      })
+      continue
+    }
+    counts[at]++
+  }
+  truth.documents.forEach((doc, i) => {
+    if (counts[i] === 0) {
+      out.push({
+        rule: RULES.documentAnchored,
+        message: `document ${doc.url} born at ${doc.bornAt} has no anchor`,
+        subject: { kind: 'document', timestamp: doc.bornAt }
+      })
+    } else if (counts[i] > 1) {
+      out.push({
+        rule: RULES.anchorOnce,
+        message: `document ${doc.url} born at ${doc.bornAt} has ${counts[i]} anchors`,
+        subject: { kind: 'document', timestamp: doc.bornAt }
+      })
+    }
+  })
+  return out
+}
+
+function navigationShowsDestination(stream: Stream): Violation[] {
+  const out: Violation[] = []
+  for (const row of stream.rows) {
+    const target = navigationTarget(row)
+    if (!target || row.error) {
+      continue
+    }
+    const shown = stream.anchors
+      .filter((a) => a.timestamp <= row.timestamp)
+      .at(-1)
+    if (shown?.url !== target) {
+      out.push({
+        rule: RULES.navigationShowsDestination,
+        message: `${row.command}(${target}) at ${row.timestamp} replays ${shown?.url ?? 'no document'}`,
+        ...rowSubject(row)
+      })
+    }
+  }
+  return out
+}
+
+function failureRecorded(stream: Stream, truth: GroundTruth): Violation[] {
+  return truth.failedNavigations.flatMap(({ url, message }): Violation[] => {
+    const row = stream.rows.find((r) => navigationTarget(r) === url && r.error)
+    if (!row) {
+      return [
+        {
+          rule: RULES.failureRecorded,
+          message: `navigation to ${url} failed in the browser but no row carries an error`
+        }
+      ]
+    }
+    // The Errors tab shows this text, so it must be the browser's, not a binding's formatting of it.
+    const shown = row.error?.message.trim()
+    return shown === message
+      ? []
+      : [
+          {
+            rule: RULES.errorCarriesBrowserMessage,
+            message: `${row.command}(${url}) shows ${JSON.stringify(row.error?.message)} instead of ${JSON.stringify(message)}`,
+            subject: { kind: 'row', timestamp: row.timestamp }
+          }
+        ]
+  })
+}
+
+function replaceTargetsRow({ frames }: Stream): Violation[] {
+  const sent = new Set<number>()
+  const out: Violation[] = []
+  for (const { scope, data } of frames) {
+    if (scope === SCOPES.commands) {
+      for (const row of data as CommandLog[]) {
+        sent.add(row.timestamp)
+      }
+    } else if (scope === SCOPES.replaceCommand) {
+      const { oldTimestamp } = data as ReplaceCommandWsPayload
+      if (!sent.has(oldTimestamp)) {
+        out.push({
+          rule: RULES.replaceTargetsRow,
+          message: `replaceCommand names ${oldTimestamp}, which no earlier row carries`
+        })
+      }
+    }
+  }
+  return out
+}
+
+function rowSubject(row: CommandLog | undefined): Pick<Violation, 'subject'> {
+  return row ? { subject: { kind: 'row', timestamp: row.timestamp } } : {}
+}
+
+// A lost row and a duplicated one both break every invariant silently, so rows are counted against the browser.
+// The backend falls back from either command to the other, and to the wdio binary only when both are missing.
+function runControlsHaveCommand({ frames }: Stream): Violation[] {
+  return frames
+    .filter((f) => f.scope === SCOPES.metadata)
+    .flatMap((f) => {
+      const options = (f.data as Metadata).options as RunnerOptions | undefined
+      const advertised = Object.entries(options?.runCapabilities ?? {})
+        .filter(([, on]) => on)
+        .map(([name]) => name)
+      if (
+        !advertised.length ||
+        options?.launchCommand ||
+        options?.rerunCommand
+      ) {
+        return []
+      }
+      return [
+        {
+          rule: RULES.runControlsHaveCommand,
+          message: `metadata advertises ${advertised.join(', ')} but carries neither launchCommand nor rerunCommand`
+        }
+      ]
+    })
+}
+
+function rowPerAction(stream: Stream, truth: GroundTruth): Violation[] {
+  return ACTION_METHODS.flatMap((method) => {
+    const rows = stream.rows.filter(
+      (r) => mapCommandToAction(r.command)?.method === method
+    ).length
+    const received = truth.actions[method]
+    return rows === received
+      ? []
+      : [
+          {
+            rule: RULES.rowPerAction,
+            message: `${method}: the browser received ${received}, the stream shows ${rows} row(s)`
+          }
+        ]
+  })
+}
+
+/** The url a navigation row loads, passed bare (`get(url)`) or as W3C `{url}`. */
+export function navigationTarget(row: CommandLog): string | undefined {
+  if (mapCommandToAction(row.command)?.method !== 'navigate') {
+    return undefined
+  }
+  const [arg] = row.args
+  if (typeof arg === 'string') {
+    return arg
+  }
+  const url = (arg as { url?: unknown } | undefined)?.url
+  return typeof url === 'string' ? url : undefined
+}
diff --git a/packages/conformance/src/constants.ts b/packages/conformance/src/constants.ts
new file mode 100644
index 00000000..2c644f2f
--- /dev/null
+++ b/packages/conformance/src/constants.ts
@@ -0,0 +1,120 @@
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+import { WS_SCOPE, type WsMessageScope } from '@wdio/devtools-shared'
+
+export const REPO_ROOT = path.resolve(
+  path.dirname(fileURLToPath(import.meta.url)),
+  '../../..'
+)
+
+export const COLLECTOR_BUNDLE = path.join(
+  REPO_ROOT,
+  'packages/script/dist/script.js'
+)
+
+export const RULES = {
+  metadataFirst: 'metadata-before-commands',
+  completionStamp: 'row-stamped-at-completion',
+  anchorBirthTime: 'anchor-carries-birth-time',
+  documentAnchored: 'every-document-anchored',
+  anchorOnce: 'one-anchor-per-document',
+  navigationShowsDestination: 'navigation-row-shows-destination',
+  failureRecorded: 'failed-command-has-error-row',
+  errorCarriesBrowserMessage: 'error-row-carries-browser-message',
+  replaceTargetsRow: 'replace-targets-a-sent-row',
+  rowPerAction: 'one-row-per-browser-action',
+  runControlsHaveCommand: 'run-controls-have-a-command'
+} as const
+
+const GUIDE = 'docs/ADAPTERS.md'
+
+/** The responsibilities a rule can test, each a section of the adapter guide (paths from the repo root). */
+export const RESPONSIBILITIES = {
+  'command-interception': {
+    title: 'Driver command interception',
+    section: `${GUIDE}#2a-driver-command-interception`
+  },
+  collector: {
+    title: 'Collector injection and draining',
+    section: `${GUIDE}#2b-collector-injection-and-draining`
+  },
+  'framework-hooks': {
+    title: 'Test-framework hooks',
+    section: `${GUIDE}#2c-test-framework-hooks`
+  },
+  transport: {
+    title: 'Transport, backend launch, and reruns',
+    section: `${GUIDE}#2d-transport-backend-launch-and-reruns`
+  },
+  'wire-contract': {
+    title: 'The wire contract',
+    section: `${GUIDE}#frames-you-send`
+  }
+} as const
+
+/** The collector's own source assigns its global; an adapter's probes and drains only read it. */
+export const COLLECTOR_SIGNATURE = /wdioTraceCollector\s*=(?!=)/
+
+/** User actions the fake browser counts, named as shared's ACTION_MAP names their method. */
+export const ACTION_METHODS = ['navigate', 'click', 'fill'] as const
+
+/** The scopes the rules read. */
+export const SCOPES = {
+  metadata: 'metadata',
+  commands: 'commands',
+  mutations: 'mutations',
+  replaceCommand: WS_SCOPE.replaceCommand
+} as const satisfies Record<string, WsMessageScope>
+
+/** Every scenario reads these and nothing else, so each language drives the
+ *  same pages in the same order. The Python scenario repeats the names. */
+export const SCENARIO_ENV = {
+  webdriver: 'CONFORMANCE_WEBDRIVER',
+  login: 'CONFORMANCE_LOGIN_URL',
+  broken: 'CONFORMANCE_BROKEN_URL'
+} as const
+
+export const SCENARIO_TIMEOUT_MS = 60_000
+
+export const ELEMENT_KEY = 'element-6066-11e4-a52e-4f735466cecf'
+
+// Long enough that a row stamped at invocation predates the page it loaded.
+export const NAVIGATION_HALF_MS = 15
+
+export const BLANK_PNG =
+  'iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNkYAAAAAYAAjCB0C8AAAAASUVORK5CYII='
+
+/** Selector → the page a click on it loads, or `null` for a field. */
+export const PAGES: Record<string, Record<string, string | null>> = {
+  '/login': {
+    '#username': null,
+    '#password': null,
+    'button[type="submit"]': '/secure'
+  },
+  '/secure': { '#flash': null, '#logout': '/login' }
+}
+
+export const BROKEN_PATH = '/broken'
+
+export const BIDI_PATH = '/session/conformance/bidi'
+
+/** BiDi results whose callers read a field back; every other command gets `{}`. */
+export const BIDI_RESULTS: Record<string, unknown> = {
+  'script.addPreloadScript': { script: 'preload-1' },
+  'session.subscribe': { subscription: 'subscription-1' },
+  'network.addIntercept': { intercept: 'intercept-1' },
+  'browsingContext.getTree': {
+    contexts: [
+      { context: 'context-1', url: 'about:blank', children: [], parent: null }
+    ]
+  }
+}
+
+/** Every scenario run dumps its stream here, and the HTML report is rebuilt from what is present. */
+export const OUT_DIR = path.join(REPO_ROOT, 'packages/conformance/out')
+
+export const REPORT_INDEX = 'index.html'
+
+// Long enough to identify an argument, short enough to keep a timeline row on one line.
+export const TARGET_MAX_CHARS = 120
diff --git a/packages/conformance/src/fake-bidi.ts b/packages/conformance/src/fake-bidi.ts
new file mode 100644
index 00000000..12cf0394
--- /dev/null
+++ b/packages/conformance/src/fake-bidi.ts
@@ -0,0 +1,47 @@
+import type { Server } from 'node:http'
+
+import { WebSocketServer, type WebSocket } from 'ws'
+
+import { BIDI_PATH, BIDI_RESULTS } from './constants.js'
+
+interface Command {
+  id: number
+  method: string
+}
+
+/** A BiDi endpoint that acknowledges every command and emits no events; reports a preload registration. */
+export function attachFakeBidi(
+  server: Server,
+  onPreload: () => void
+): () => void {
+  const wss = new WebSocketServer({ noServer: true })
+  server.on('upgrade', (req, socket, head) => {
+    if (req.url !== BIDI_PATH) {
+      socket.destroy()
+      return
+    }
+    wss.handleUpgrade(req, socket, head, (ws) => answer(ws, onPreload))
+  })
+  return () => {
+    for (const client of wss.clients) {
+      client.terminate()
+    }
+    wss.close()
+  }
+}
+
+function answer(ws: WebSocket, onPreload: () => void): void {
+  ws.on('message', (raw) => {
+    const { id, method } = JSON.parse(String(raw)) as Command
+    if (method === 'script.addPreloadScript') {
+      onPreload()
+    }
+    ws.send(
+      JSON.stringify({
+        type: 'success',
+        id,
+        result: BIDI_RESULTS[method] ?? {}
+      })
+    )
+  })
+}
diff --git a/packages/conformance/src/fake-webdriver.ts b/packages/conformance/src/fake-webdriver.ts
new file mode 100644
index 00000000..e1e66e3a
--- /dev/null
+++ b/packages/conformance/src/fake-webdriver.ts
@@ -0,0 +1,300 @@
+import {
+  createServer,
+  type IncomingMessage,
+  type Server,
+  type ServerResponse
+} from 'node:http'
+import type { AddressInfo } from 'node:net'
+
+import type { TraceMutation } from '@wdio/devtools-shared'
+
+import {
+  BIDI_PATH,
+  BLANK_PNG,
+  BROKEN_PATH,
+  COLLECTOR_SIGNATURE,
+  ELEMENT_KEY,
+  NAVIGATION_HALF_MS,
+  PAGES
+} from './constants.js'
+import { attachFakeBidi } from './fake-bidi.js'
+import type {
+  ActionMethod,
+  BrowserDocument,
+  FailedNavigation,
+  GroundTruth
+} from './types.js'
+
+interface Document extends BrowserDocument {
+  path: string
+  collector: boolean
+  anchored: boolean
+  buffer: TraceMutation[]
+}
+
+interface Element {
+  selector: string
+  document: Document
+}
+
+type Reply = { status?: number; value: unknown }
+
+const sleep = (ms: number) => new Promise((r) => setTimeout(r, ms))
+
+const anchorOf = (url: string, bornAt: number): TraceMutation => ({
+  type: 'childList',
+  url,
+  timestamp: bornAt,
+  addedNodes: [],
+  removedNodes: []
+})
+
+/** A W3C WebDriver over a two-page model; without a preload its collector anchors only when a drain forces it. */
+export class FakeWebDriver {
+  readonly origin: string
+  #server: Server
+  #bidi: boolean
+  #closeBidi: () => void = () => {}
+  #preloaded = false
+  #documents: Document[] = []
+  #failedNavigations: FailedNavigation[] = []
+  #actions: Record<ActionMethod, number> = { navigate: 0, click: 0, fill: 0 }
+  #elements = new Map<string, Element>()
+
+  private constructor(server: Server, bidi: boolean) {
+    this.#server = server
+    this.#bidi = bidi
+    this.origin = `http://127.0.0.1:${(server.address() as AddressInfo).port}`
+  }
+
+  /** With `bidi`, a registered preload puts the collector in every later document from birth. */
+  static async start({ bidi = false } = {}): Promise<FakeWebDriver> {
+    const server = createServer()
+    await new Promise<void>((r) => server.listen(0, '127.0.0.1', r))
+    const driver = new FakeWebDriver(server, bidi)
+    server.on('request', (req, res) => void driver.#handle(req, res))
+    if (bidi) {
+      driver.#closeBidi = attachFakeBidi(
+        server,
+        () => (driver.#preloaded = true)
+      )
+    }
+    return driver
+  }
+
+  url(path: string): string {
+    return `${this.origin}${path}`
+  }
+
+  truth(): GroundTruth {
+    return {
+      documents: this.#documents.map(({ url, bornAt }) => ({ url, bornAt })),
+      failedNavigations: [...this.#failedNavigations],
+      actions: { ...this.#actions }
+    }
+  }
+
+  close(): Promise<void> {
+    this.#endBidi()
+    return new Promise((r) => this.#server.close(() => r()))
+  }
+
+  #endBidi(): void {
+    this.#closeBidi()
+    this.#closeBidi = () => {}
+  }
+
+  get #current(): Document | undefined {
+    return this.#documents.at(-1)
+  }
+
+  async #handle(req: IncomingMessage, res: ServerResponse): Promise<void> {
+    let body = ''
+    for await (const chunk of req) {
+      body += chunk
+    }
+    const params = body ? (JSON.parse(body) as Record<string, unknown>) : {}
+    const path = (req.url ?? '').replace(/^\/session\/[^/]+/, '')
+    const reply = await this.#route(req.method ?? 'GET', path, params)
+    res.writeHead(reply.status ?? 200, { 'content-type': 'application/json' })
+    res.end(JSON.stringify({ value: reply.value }))
+  }
+
+  // An endpoint not listed answers null, which every caller reads as "nothing to report".
+  async #route(
+    method: string,
+    path: string,
+    params: Record<string, unknown>
+  ): Promise<Reply> {
+    if (method === 'POST' && path === '/session') {
+      const wantsBidi = JSON.stringify(params).includes('"webSocketUrl":true')
+      const capabilities: Record<string, unknown> = { browserName: 'chrome' }
+      if (this.#bidi && wantsBidi) {
+        capabilities.webSocketUrl = `${this.origin.replace('http', 'ws')}${BIDI_PATH}`
+      }
+      return { value: { sessionId: 'conformance', capabilities } }
+    }
+    if (method === 'DELETE' && path === '') {
+      // A browser drops its BiDi socket with the session; one left open holds the adapter's process.
+      this.#endBidi()
+      return { value: null }
+    }
+    if (method === 'POST' && path === '/url') {
+      this.#actions.navigate++
+      return this.#navigate(new URL(String(params.url)).pathname)
+    }
+    if (method === 'GET' && path === '/url') {
+      return { value: this.#current?.url ?? 'about:blank' }
+    }
+    if (method === 'GET' && path === '/title') {
+      return { value: this.#current?.path ?? '' }
+    }
+    if (method === 'POST' && (path === '/element' || path === '/elements')) {
+      return this.#find(String(params.value), path === '/elements')
+    }
+    const element = path.match(/^\/element\/([^/]+)\/(value|click|clear|text)$/)
+    if (element) {
+      return this.#onElement(element[1], element[2], params)
+    }
+    if (method === 'POST' && path.startsWith('/execute/')) {
+      return {
+        value: this.#execute(
+          String(params.script),
+          JSON.stringify(params.args ?? [])
+        )
+      }
+    }
+    if (path === '/screenshot') {
+      return { value: BLANK_PNG }
+    }
+    if (path === '/window/rect') {
+      return { value: { x: 0, y: 0, width: 1280, height: 720 } }
+    }
+    return { value: null }
+  }
+
+  async #navigate(path: string): Promise<Reply> {
+    await sleep(NAVIGATION_HALF_MS)
+    if (path === BROKEN_PATH) {
+      const message = `net::ERR_FAILED at ${path}`
+      this.#failedNavigations.push({ url: this.url(path), message })
+      return {
+        status: 500,
+        // A driver's native frames ride along beside the message, as chromedriver sends them.
+        value: {
+          error: 'unknown error',
+          message,
+          stacktrace: '#0 0x55d0 <unknown>'
+        }
+      }
+    }
+    const url = this.url(path)
+    const bornAt = Date.now()
+    // A preloaded collector anchors its document at birth, as `packages/script` does in Chrome.
+    const preloaded = this.#preloaded
+    this.#documents.push({
+      path,
+      url,
+      bornAt,
+      collector: preloaded,
+      anchored: preloaded,
+      buffer: preloaded ? [anchorOf(url, bornAt)] : []
+    })
+    await sleep(NAVIGATION_HALF_MS)
+    return { value: null }
+  }
+
+  #find(selector: string, many: boolean): Reply {
+    const doc = this.#current
+    if (!doc || !(selector in (PAGES[doc.path] ?? {}))) {
+      return many
+        ? { value: [] }
+        : {
+            status: 404,
+            value: {
+              error: 'no such element',
+              message: `no element ${selector}`,
+              stacktrace: ''
+            }
+          }
+    }
+    const id = `el-${this.#elements.size + 1}`
+    this.#elements.set(id, { selector, document: doc })
+    const ref = { [ELEMENT_KEY]: id }
+    return { value: many ? [ref] : ref }
+  }
+
+  async #onElement(
+    id: string,
+    action: string,
+    params: Record<string, unknown>
+  ): Promise<Reply> {
+    const el = this.#elements.get(id)
+    if (!el || el.document !== this.#current) {
+      return {
+        status: 404,
+        value: { error: 'stale element reference', message: id, stacktrace: '' }
+      }
+    }
+    if (action === 'value') {
+      this.#actions.fill++
+    } else if (action === 'click') {
+      this.#actions.click++
+    }
+    if (action === 'value' && el.document.collector) {
+      el.document.buffer.push({
+        type: 'attributes',
+        target: el.selector,
+        attributeName: 'value',
+        attributeValue: String(params.text ?? ''),
+        addedNodes: [],
+        removedNodes: [],
+        timestamp: Date.now()
+      })
+    }
+    const destination =
+      action === 'click' ? PAGES[el.document.path][el.selector] : null
+    if (destination) {
+      return this.#navigate(destination)
+    }
+    return { value: action === 'text' ? el.selector : null }
+  }
+
+  // Recognised by the collector's own API, not by how any one adapter phrases its scripts.
+  #execute(script: string, args: string): unknown {
+    const doc = this.#current
+    if (!doc) {
+      return null
+    }
+    if (COLLECTOR_SIGNATURE.test(script) || COLLECTOR_SIGNATURE.test(args)) {
+      doc.collector = true
+      return true
+    }
+    if (script.includes('getTraceData')) {
+      return this.#drain(doc, script.includes('captureCurrentDom'))
+    }
+    if (script.includes('wdioTraceCollector')) {
+      return doc.collector
+    }
+    return null
+  }
+
+  #drain(doc: Document, forceAnchor: boolean): unknown {
+    if (!doc.collector) {
+      return null
+    }
+    if (forceAnchor && !doc.anchored) {
+      doc.anchored = true
+      doc.buffer.unshift(anchorOf(doc.url, doc.bornAt))
+    }
+    const mutations = doc.buffer.splice(0)
+    return {
+      errors: [],
+      mutations,
+      consoleLogs: [],
+      networkRequests: [],
+      traceLogs: [],
+      metadata: {}
+    }
+  }
+}
diff --git a/packages/conformance/src/harness.ts b/packages/conformance/src/harness.ts
new file mode 100644
index 00000000..cc5c8c77
--- /dev/null
+++ b/packages/conformance/src/harness.ts
@@ -0,0 +1,70 @@
+import { spawn } from 'node:child_process'
+
+import { REUSE_ENV } from '@wdio/devtools-shared'
+
+import {
+  BROKEN_PATH,
+  REPO_ROOT,
+  SCENARIO_ENV,
+  SCENARIO_TIMEOUT_MS
+} from './constants.js'
+import { FakeWebDriver } from './fake-webdriver.js'
+import { RecordingBackend } from './recording-backend.js'
+import type { ScenarioRun } from './types.js'
+
+/** Runs a scenario process against the fakes, reached through the rerun reuse handshake so no adapter gains a test path. */
+export async function runScenario(
+  command: string,
+  args: string[],
+  { env = {}, bidi }: { env?: NodeJS.ProcessEnv; bidi: boolean }
+): Promise<ScenarioRun> {
+  const driver = await FakeWebDriver.start({ bidi })
+  const backend = await RecordingBackend.start()
+  try {
+    const { exitCode, output } = await run(command, args, {
+      ...process.env,
+      ...env,
+      [REUSE_ENV.REUSE]: '1',
+      [REUSE_ENV.HOST]: backend.host,
+      [REUSE_ENV.PORT]: String(backend.port),
+      [SCENARIO_ENV.webdriver]: driver.origin,
+      [SCENARIO_ENV.login]: driver.url('/login'),
+      [SCENARIO_ENV.broken]: driver.url(BROKEN_PATH)
+    })
+    return {
+      frames: [...backend.frames],
+      truth: driver.truth(),
+      exitCode,
+      output
+    }
+  } finally {
+    await backend.close()
+    await driver.close()
+  }
+}
+
+function run(
+  command: string,
+  args: string[],
+  env: NodeJS.ProcessEnv
+): Promise<{ exitCode: number | null; output: string }> {
+  return new Promise((resolve, reject) => {
+    const child = spawn(command, args, { cwd: REPO_ROOT, env })
+    let output = ''
+    child.stdout.on('data', (d) => (output += d))
+    child.stderr.on('data', (d) => (output += d))
+    const timer = setTimeout(() => {
+      child.kill('SIGKILL')
+      reject(
+        new Error(
+          `scenario timed out after ${SCENARIO_TIMEOUT_MS} ms:\n${output}`
+        )
+      )
+    }, SCENARIO_TIMEOUT_MS)
+    child.on('error', reject)
+    child.on('close', (exitCode) => {
+      clearTimeout(timer)
+      resolve({ exitCode, output })
+    })
+  })
+}
diff --git a/packages/conformance/src/recording-backend.ts b/packages/conformance/src/recording-backend.ts
new file mode 100644
index 00000000..cfcbda1c
--- /dev/null
+++ b/packages/conformance/src/recording-backend.ts
@@ -0,0 +1,75 @@
+import { readFile } from 'node:fs/promises'
+import { createServer, type Server } from 'node:http'
+import type { AddressInfo } from 'node:net'
+
+import { WebSocketServer } from 'ws'
+
+import {
+  COLLECTOR_API,
+  COLLECTOR_CONTENT_TYPE,
+  ELEMENT_SCRIPTS_API,
+  WS_PATHS
+} from '@wdio/devtools-shared'
+
+import { COLLECTOR_BUNDLE } from './constants.js'
+import type { WireFrame } from './types.js'
+
+/** Stands in for the dashboard: records every worker-socket frame in arrival order and stubs the routes adapters fetch. */
+export class RecordingBackend {
+  readonly host = '127.0.0.1'
+  readonly port: number
+  readonly frames: WireFrame[] = []
+  #server: Server
+  #wss: WebSocketServer
+
+  private constructor(server: Server, wss: WebSocketServer) {
+    this.#server = server
+    this.#wss = wss
+    this.port = (server.address() as AddressInfo).port
+  }
+
+  static async start(): Promise<RecordingBackend> {
+    const server = createServer((req, res) => {
+      const path = (req.url ?? '').split('?')[0]
+      if (path === COLLECTOR_API.get) {
+        // The real bundle, as the real backend serves it, so every adapter injects the same collector.
+        readFile(COLLECTOR_BUNDLE, 'utf8').then(
+          (source) => {
+            res.writeHead(200, { 'content-type': COLLECTOR_CONTENT_TYPE })
+            res.end(source)
+          },
+          () => res.writeHead(404).end()
+        )
+      } else if (path === ELEMENT_SCRIPTS_API.get) {
+        res.writeHead(200, { 'content-type': 'application/json' })
+        res.end(JSON.stringify({ accessibilityTree: 'null', elements: '[]' }))
+      } else {
+        res.writeHead(404).end()
+      }
+    })
+    const wss = new WebSocketServer({ noServer: true })
+    server.on('upgrade', (req, socket, head) => {
+      if ((req.url ?? '').split('?')[0] !== WS_PATHS.worker) {
+        socket.destroy()
+        return
+      }
+      wss.handleUpgrade(req, socket, head, (ws) => wss.emit('connection', ws))
+    })
+    await new Promise<void>((r) => server.listen(0, '127.0.0.1', r))
+    const backend = new RecordingBackend(server, wss)
+    wss.on('connection', (ws) => {
+      ws.on('message', (raw) =>
+        backend.frames.push(JSON.parse(String(raw)) as WireFrame)
+      )
+    })
+    return backend
+  }
+
+  close(): Promise<void> {
+    for (const client of this.#wss.clients) {
+      client.terminate()
+    }
+    this.#wss.close()
+    return new Promise((r) => this.#server.close(() => r()))
+  }
+}
diff --git a/packages/conformance/src/report-html.ts b/packages/conformance/src/report-html.ts
new file mode 100644
index 00000000..65e923fd
--- /dev/null
+++ b/packages/conformance/src/report-html.ts
@@ -0,0 +1,177 @@
+import { explainingGap, gapsFor } from './allowlist.js'
+import { RESPONSIBILITIES } from './constants.js'
+import { RULE_GUIDE } from './rule-guide.js'
+import { buildTimeline } from './timeline.js'
+import type { KnownGap, RunReport, TimelineEvent, Violation } from './types.js'
+
+const STYLE = `
+:root{color-scheme:light dark;--bg:#fff;--fg:#1d1f23;--muted:#5f6670;--line:#d9dde3;--panel:#f5f7f9;--pass:#17723a;--fail:#b3261e;--warn:#8a5a00;--doc:#3355aa;--anchor:#6a3fa0}
+@media (prefers-color-scheme:dark){:root{--bg:#15171a;--fg:#e6e8eb;--muted:#9aa2ad;--line:#33373d;--panel:#1e2125;--pass:#5fcf86;--fail:#ff8a80;--warn:#e6b450;--doc:#8fa8ff;--anchor:#c39bff}}
+*{box-sizing:border-box}
+body{margin:0;padding:16px;background:var(--bg);color:var(--fg);font:14px/1.45 system-ui,sans-serif}
+h1{font-size:20px;margin:0 0 16px}
+details.run{border:1px solid var(--line);border-radius:6px;margin:0 0 16px;background:var(--bg)}
+details.run>summary{cursor:pointer;padding:10px 12px;background:var(--panel);border-radius:6px;display:flex;flex-wrap:wrap;gap:12px;align-items:baseline}
+.badge{font-weight:700;padding:1px 8px;border-radius:4px;border:1px solid currentColor}
+.pass{color:var(--pass)}.fail{color:var(--fail)}
+.counts{color:var(--muted)}
+.body{padding:12px;overflow-x:auto}
+table{border-collapse:collapse;width:100%}
+td,th{text-align:left;padding:3px 8px;border-bottom:1px solid var(--line);vertical-align:top}
+th{color:var(--muted);font-weight:600}
+td.t{font-variant-numeric:tabular-nums;white-space:nowrap;color:var(--muted)}
+code{font:12px/1.4 ui-monospace,monospace;word-break:break-all}
+.k-document{color:var(--doc)}.k-anchor{color:var(--anchor)}
+.err{color:var(--fail);font-weight:700}
+ul.v{margin:4px 0;padding-left:18px}
+li.unexplained{color:var(--fail)}
+li.allowed{color:var(--warn)}
+.reason{display:block;color:var(--muted)}
+.look{border:1px solid var(--fail);border-radius:6px;padding:8px 12px;margin:0 0 12px}
+.look>ul>li{margin:6px 0}
+a{color:var(--doc)}
+pre{background:var(--panel);padding:8px;border-radius:4px;overflow-x:auto;font:12px/1.4 ui-monospace,monospace}
+`
+
+export function renderReport(runs: RunReport[]): string {
+  const sorted = [...runs].sort(
+    (a, b) =>
+      a.adapter.localeCompare(b.adapter) || Number(b.bidi) - Number(a.bidi)
+  )
+  return `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width,initial-scale=1">
+<title>Conformance report</title>
+<style>${STYLE}</style>
+</head>
+<body>
+<h1>Conformance report</h1>
+${sorted.length ? sorted.map(renderRun).join('\n') : '<p>No runs recorded.</p>'}
+</body>
+</html>
+`
+}
+
+export function runPassed(run: RunReport): boolean {
+  return (
+    run.exitCode === 0 && run.unexplained.length === 0 && run.stale.length === 0
+  )
+}
+
+export function escapeHtml(text: string): string {
+  return text
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&#39;')
+}
+
+function renderRun(run: RunReport): string {
+  const passed = runPassed(run)
+  const timeline = buildTimeline(run)
+  const unexplained = new Set(run.unexplained.map(violationKey))
+  const gaps = gapsFor(run.adapter, run.bidi)
+  const renderViolations = (violations: Violation[]) =>
+    renderViolationList(violations, unexplained, gaps)
+  const rows = timeline.events
+    .map((e) => renderEvent(e, timeline.origin, renderViolations))
+    .join('\n')
+  return `<details class="run"${passed ? '' : ' open'}>
+<summary><strong>${escapeHtml(run.adapter)}</strong>
+<span>bidi ${run.bidi ? 'on' : 'off'}</span>
+<span class="badge ${passed ? 'pass">PASS' : 'fail">FAIL'}</span>
+<span class="counts">exit ${escapeHtml(String(run.exitCode))}, ${timeline.events.length} events, ${run.violations.length} violations, ${run.unexplained.length} unexplained, ${run.stale.length} stale gaps</span></summary>
+<div class="body">
+${renderWhereToLook(run)}
+${timeline.unplaced.length ? `<p>Run-level violations:</p>${renderViolations(timeline.unplaced)}` : ''}
+${run.stale.map(renderStale).join('\n')}
+<table>
+<thead><tr><th>time</th><th>event</th><th>detail</th></tr></thead>
+<tbody>
+${rows}
+</tbody>
+</table>
+<details><summary>scenario output</summary><pre>${escapeHtml(run.output)}</pre></details>
+</div>
+</details>`
+}
+
+function renderEvent(
+  event: TimelineEvent,
+  origin: number,
+  renderViolations: (violations: Violation[]) => string
+): string {
+  const rel = (ms: number) => `+${ms - origin} ms`
+  const [label, detail] =
+    event.kind === 'row'
+      ? [
+          `${escapeHtml(event.command)}${event.failed ? ' <span class="err">error</span>' : ''}`,
+          `<code>${escapeHtml(event.target)}</code> ${escapeHtml(
+            event.startTime === undefined
+              ? `ends ${rel(event.timestamp)}`
+              : `${rel(event.startTime)} .. ${rel(event.timestamp)}`
+          )}`
+        ]
+      : [
+          event.kind === 'document' ? 'document born' : 'DOM anchor',
+          `<code>${escapeHtml(event.url)}</code>`
+        ]
+  return `<tr class="k-${event.kind}"><td class="t">${escapeHtml(rel(event.at))}</td><td>${label}</td><td>${detail}${
+    event.violations.length ? renderViolations(event.violations) : ''
+  }</td></tr>`
+}
+
+function renderViolationList(
+  violations: Violation[],
+  unexplained: Set<string>,
+  gaps: KnownGap[]
+): string {
+  const items = violations.map((v) => {
+    const isUnexplained = unexplained.has(violationKey(v))
+    const reason = isUnexplained
+      ? ''
+      : `<span class="reason">allowlisted: ${escapeHtml(
+          explainingGap(gaps, v)?.reason ?? 'no reason recorded'
+        )}</span>`
+    return `<li class="${isUnexplained ? 'unexplained' : 'allowed'}"><strong>${
+      isUnexplained ? 'UNEXPLAINED' : 'allowlisted'
+    }</strong> <code>${escapeHtml(v.rule)}</code>: ${escapeHtml(v.message)}${reason}</li>`
+  })
+  return `<ul class="v">${items.join('')}</ul>`
+}
+
+// The report sits three levels below the repo root, which the guide's paths are relative to.
+const REPO_ROOT_FROM_REPORT = '../../../'
+
+function renderWhereToLook(run: RunReport): string {
+  const rules = [...new Set(run.unexplained.map((v) => v.rule))]
+  if (!rules.length) {
+    return ''
+  }
+  const items = rules.map((rule) => {
+    const guide = RULE_GUIDE[rule]
+    const { title, section } = RESPONSIBILITIES[guide.responsibility]
+    return `<li><code>${escapeHtml(rule)}</code>: ${escapeHtml(guide.meaning)}
+<span class="reason">Usual cause: ${escapeHtml(guide.cause)}</span>
+<span class="reason">Responsibility: <a href="${escapeHtml(REPO_ROOT_FROM_REPORT + section)}">${escapeHtml(title)}</a> (${escapeHtml(section)})</span></li>`
+  })
+  return `<div class="look"><strong>Where to look</strong><ul>${items.join('')}</ul></div>`
+}
+
+function renderStale(gap: KnownGap): string {
+  return `<p class="fail"><strong>Stale gap</strong> (${escapeHtml(
+    gap.rules.join(', ')
+  )}): ${escapeHtml(gap.reason)}</p>`
+}
+
+function violationKey(v: Violation): string {
+  return JSON.stringify([
+    v.rule,
+    v.message,
+    v.subject?.kind,
+    v.subject?.timestamp
+  ])
+}
diff --git a/packages/conformance/src/report.ts b/packages/conformance/src/report.ts
new file mode 100644
index 00000000..a36268ce
--- /dev/null
+++ b/packages/conformance/src/report.ts
@@ -0,0 +1,45 @@
+import { mkdir, readdir, readFile, rename, writeFile } from 'node:fs/promises'
+import path from 'node:path'
+
+import { OUT_DIR, REPORT_INDEX } from './constants.js'
+import { renderReport } from './report-html.js'
+import type { RunReport } from './types.js'
+
+/** Dumps one run and rebuilds the HTML report; logs instead of throwing, so a report problem never fails a run. */
+export async function writeRunReport(
+  report: RunReport,
+  outDir = OUT_DIR
+): Promise<void> {
+  try {
+    await mkdir(outDir, { recursive: true })
+    const name = `${report.adapter}-${report.bidi ? 'bidi' : 'no-bidi'}.json`
+    await writeAtomically(
+      path.join(outDir, name),
+      JSON.stringify(report, null, 2)
+    )
+    await writeAtomically(
+      path.join(outDir, REPORT_INDEX),
+      renderReport(await readRunReports(outDir))
+    )
+  } catch (err) {
+    console.error(`conformance: could not write the report to ${outDir}:`, err)
+  }
+}
+
+// Test files run in parallel workers, so another worker may be reading the dir while this one writes.
+async function writeAtomically(file: string, content: string): Promise<void> {
+  const tmp = `${file}.${process.pid}.tmp`
+  await writeFile(tmp, content)
+  await rename(tmp, file)
+}
+
+// Each file was written by writeRunReport, so its shape is RunReport.
+async function readRunReports(outDir: string): Promise<RunReport[]> {
+  const files = (await readdir(outDir)).filter((f) => f.endsWith('.json'))
+  return Promise.all(
+    files.map(
+      async (f) =>
+        JSON.parse(await readFile(path.join(outDir, f), 'utf8')) as RunReport
+    )
+  )
+}
diff --git a/packages/conformance/src/rule-guide.ts b/packages/conformance/src/rule-guide.ts
new file mode 100644
index 00000000..a8baa52d
--- /dev/null
+++ b/packages/conformance/src/rule-guide.ts
@@ -0,0 +1,78 @@
+import type { RuleGuide, RuleId } from './types.js'
+
+/** Per rule: what a break means, its usual cause, and the adapter responsibility it tests. */
+export const RULE_GUIDE: Record<RuleId, RuleGuide> = {
+  'metadata-before-commands': {
+    meaning:
+      'Command rows arrived before the session metadata, so the dashboard has no session to file them under.',
+    cause: 'Metadata is sent lazily, after the first command is captured.',
+    responsibility: 'wire-contract'
+  },
+  'row-stamped-at-completion': {
+    meaning: 'A row ends before it starts: its timestamps are inconsistent.',
+    cause:
+      'timestamp and startTime are taken from different clocks, or swapped.',
+    responsibility: 'command-interception'
+  },
+  'anchor-carries-birth-time': {
+    meaning:
+      "A full-page DOM snapshot is stamped with a time that matches no page's birth, so replay applies it to the wrong page.",
+    cause:
+      'The anchor is stamped at drain time instead of keeping the document birth time the collector gave it.',
+    responsibility: 'collector'
+  },
+  'every-document-anchored': {
+    meaning:
+      'A page the browser loaded never got a full-page DOM snapshot, so the dashboard has nothing to replay for it.',
+    cause:
+      'The drain does not force captureCurrentDom(), or the collector was never present in that document (no preload, injection too late).',
+    responsibility: 'collector'
+  },
+  'one-anchor-per-document': {
+    meaning: 'A page got more than one full-page snapshot.',
+    cause:
+      'The collector was injected twice into one document, resetting its once-per-document guard.',
+    responsibility: 'collector'
+  },
+  'navigation-row-shows-destination': {
+    meaning:
+      'Replaying a navigation row shows the page it left, or no page, instead of the page it loaded.',
+    cause:
+      'The row is stamped at invocation rather than completion, or the destination was never anchored (check every-document-anchored first).',
+    responsibility: 'command-interception'
+  },
+  'failed-command-has-error-row': {
+    meaning:
+      'A command failed in the browser, but no row carries the error, so the dashboard shows it as a success or not at all.',
+    cause: 'The interception path does not report a command that throws.',
+    responsibility: 'command-interception'
+  },
+  'error-row-carries-browser-message': {
+    meaning:
+      "The Errors tab shows a failed command's message as the language binding formatted it, not as the browser sent it.",
+    cause:
+      "The row stores the exception's string form, which some bindings decorate with a prefix or a stacktrace. Store the driver's own message field.",
+    responsibility: 'command-interception'
+  },
+  'replace-targets-a-sent-row': {
+    meaning:
+      'An update names a row that was never sent, so the dashboard appends it as a new row.',
+    cause:
+      'The update is sent before its row, or keyed by a timestamp the row does not carry.',
+    responsibility: 'wire-contract'
+  },
+  'run-controls-have-a-command': {
+    meaning:
+      'The dashboard shows Run buttons, but pressing one makes the backend fall back to the WebdriverIO binary.',
+    cause:
+      'Run capabilities are declared without building launchCommand or rerunCommand. Derive capabilities from the commands that exist.',
+    responsibility: 'transport'
+  },
+  'one-row-per-browser-action': {
+    meaning:
+      'The rows do not match what the browser did: a navigation, click or keystroke is missing or appears twice.',
+    cause:
+      'A command is skipped or captured twice by the interception, or an update overwrote another row (updates match by id, then timestamp).',
+    responsibility: 'command-interception'
+  }
+}
diff --git a/packages/conformance/src/timeline.ts b/packages/conformance/src/timeline.ts
new file mode 100644
index 00000000..b36cb391
--- /dev/null
+++ b/packages/conformance/src/timeline.ts
@@ -0,0 +1,81 @@
+import type { CommandLog } from '@wdio/devtools-shared'
+
+import { navigationTarget, readStream } from './checker.js'
+import { TARGET_MAX_CHARS } from './constants.js'
+import type { RunReport, Timeline, TimelineEvent, Violation } from './types.js'
+
+const KIND_ORDER: Record<TimelineEvent['kind'], number> = {
+  document: 0,
+  anchor: 1,
+  row: 2
+}
+
+/** Orders a run's documents, anchors and rows by time and attaches each violation to the event it concerns. */
+export function buildTimeline(report: RunReport): Timeline {
+  const { rows, anchors } = readStream(report.frames)
+  const events: TimelineEvent[] = [
+    ...report.truth.documents.map((d): TimelineEvent => ({
+      kind: 'document',
+      at: d.bornAt,
+      url: d.url,
+      violations: []
+    })),
+    ...anchors.map((a): TimelineEvent => ({
+      kind: 'anchor',
+      at: a.timestamp,
+      url: a.url ?? '',
+      violations: []
+    })),
+    ...rows.map(rowEvent)
+  ].sort((a, b) => a.at - b.at || KIND_ORDER[a.kind] - KIND_ORDER[b.kind])
+
+  const unplaced: Violation[] = []
+  for (const violation of report.violations) {
+    const event = events.find((e) => concerns(e, violation))
+    if (event) {
+      event.violations.push(violation)
+    } else {
+      unplaced.push(violation)
+    }
+  }
+  return { origin: origin(events), events, unplaced }
+}
+
+function rowEvent(row: CommandLog): TimelineEvent {
+  return {
+    kind: 'row',
+    at: row.startTime ?? row.timestamp,
+    command: row.command,
+    target: rowTarget(row),
+    startTime: row.startTime,
+    timestamp: row.timestamp,
+    failed: Boolean(row.error),
+    violations: []
+  }
+}
+
+function rowTarget(row: CommandLog): string {
+  const target =
+    navigationTarget(row) ??
+    row.selector ??
+    (row.args.length ? JSON.stringify(row.args) : '')
+  return target.length > TARGET_MAX_CHARS
+    ? `${target.slice(0, TARGET_MAX_CHARS)}...`
+    : target
+}
+
+function concerns(event: TimelineEvent, { subject }: Violation): boolean {
+  if (!subject || subject.kind !== event.kind) {
+    return false
+  }
+  const stamp = event.kind === 'row' ? event.timestamp : event.at
+  return stamp === subject.timestamp
+}
+
+function origin(events: TimelineEvent[]): number {
+  // A row that breaks the completion rule ends before it starts, so its end can be the earliest time.
+  const times = events.flatMap((e) =>
+    e.kind === 'row' ? [e.at, e.timestamp] : [e.at]
+  )
+  return times.length ? Math.min(...times) : 0
+}
diff --git a/packages/conformance/src/types.ts b/packages/conformance/src/types.ts
new file mode 100644
index 00000000..919e2b81
--- /dev/null
+++ b/packages/conformance/src/types.ts
@@ -0,0 +1,136 @@
+import type { CommandLog, TraceMutation } from '@wdio/devtools-shared'
+
+import type { ACTION_METHODS, RESPONSIBILITIES, RULES } from './constants.js'
+
+/** A frame as received, before any rule narrows it: an adapter may send any scope. */
+export interface WireFrame {
+  scope: string
+  data: unknown
+}
+
+/** A document the browser created, as the fake WebDriver saw it. */
+export interface BrowserDocument {
+  url: string
+  bornAt: number
+}
+
+/** A navigation the browser refused, with the message it answered. */
+export interface FailedNavigation {
+  url: string
+  message: string
+}
+
+/** What happened in the browser, independent of any adapter. */
+export interface GroundTruth {
+  documents: BrowserDocument[]
+  failedNavigations: FailedNavigation[]
+  /** How many of each user action the browser received, keyed by shared's action method. */
+  actions: Record<ActionMethod, number>
+}
+
+export type ActionMethod = (typeof ACTION_METHODS)[number]
+
+export type RuleId = (typeof RULES)[keyof typeof RULES]
+
+/** The timeline event a violation concerns, so a report can show it in place. */
+export interface ViolationSubject {
+  kind: 'row' | 'anchor' | 'document'
+  timestamp: number
+}
+
+export interface Violation {
+  rule: RuleId
+  message: string
+  /** Absent when the violation concerns the run as a whole or an event that never happened. */
+  subject?: ViolationSubject
+}
+
+/** The frame stream as the rules read it: rows after every replaceCommand, anchors in time order. */
+export interface RecordedStream {
+  frames: WireFrame[]
+  rows: CommandLog[]
+  anchors: TraceMutation[]
+}
+
+export type AdapterId = 'selenium-devtools' | 'selenium-devtools-py'
+
+/** What a broken rule means and where to look, shown beside a failing run. */
+export interface RuleGuide {
+  meaning: string
+  cause: string
+  responsibility: Responsibility
+}
+
+/** What every adapter implements, in any language; the adapter guide documents each. */
+export type Responsibility = keyof typeof RESPONSIBILITIES
+
+/** A difference an adapter is allowed to show, and why. */
+export interface KnownGap {
+  adapter: AdapterId
+  bidi: boolean
+  rules: RuleId[]
+  reason: string
+  /** Set when the gap is a race, so a run that happens to win it is not stale. */
+  timingDependent?: boolean
+}
+
+export interface Judgement {
+  /** Violations no gap explains: these fail the run. */
+  unexplained: Violation[]
+  /** Gaps declared for this run that matched nothing, so no longer hold. */
+  stale: KnownGap[]
+}
+
+export interface ScenarioRun {
+  frames: WireFrame[]
+  truth: GroundTruth
+  exitCode: number | null
+  output: string
+}
+
+/** Everything one scenario run produced, as written to the conformance out dir. */
+export interface RunReport {
+  adapter: AdapterId
+  bidi: boolean
+  exitCode: number | null
+  truth: GroundTruth
+  violations: Violation[]
+  unexplained: Violation[]
+  stale: KnownGap[]
+  frames: WireFrame[]
+  output: string
+}
+
+interface TimelineEventBase {
+  /** Absolute ms; a report subtracts the run's first event. */
+  at: number
+  violations: Violation[]
+}
+
+export interface DocumentEvent extends TimelineEventBase {
+  kind: 'document'
+  url: string
+}
+
+export interface AnchorEvent extends TimelineEventBase {
+  kind: 'anchor'
+  url: string
+}
+
+export interface RowEvent extends TimelineEventBase {
+  kind: 'row'
+  command: string
+  target: string
+  startTime?: number
+  timestamp: number
+  failed: boolean
+}
+
+export type TimelineEvent = DocumentEvent | AnchorEvent | RowEvent
+
+export interface Timeline {
+  origin: number
+  events: TimelineEvent[]
+  /** Violations with no subject, or whose subject is not on the timeline. */
+  unplaced: Violation[]
+}
diff --git a/packages/conformance/tests/checker.test.ts b/packages/conformance/tests/checker.test.ts
new file mode 100644
index 00000000..3bdd80f4
--- /dev/null
+++ b/packages/conformance/tests/checker.test.ts
@@ -0,0 +1,216 @@
+import { describe, expect, it } from 'vitest'
+
+import { checkConformance } from '../src/checker.js'
+import { RULES } from '../src/constants.js'
+import type { GroundTruth, WireFrame } from '../src/types.js'
+
+const LOGIN = 'http://fake/login'
+const SECURE = 'http://fake/secure'
+const BROKEN = 'http://fake/broken'
+
+const truth: GroundTruth = {
+  documents: [
+    { url: LOGIN, bornAt: 100 },
+    { url: SECURE, bornAt: 300 }
+  ],
+  failedNavigations: [{ url: BROKEN, message: 'net::ERR_FAILED at /broken' }],
+  actions: { navigate: 3, click: 1, fill: 0 }
+}
+
+const anchor = (url: string, timestamp: number) => ({
+  type: 'childList',
+  url,
+  timestamp,
+  addedNodes: [],
+  removedNodes: []
+})
+
+const row = (
+  command: string,
+  args: unknown[],
+  startTime: number,
+  timestamp: number,
+  extra = {}
+) => ({
+  command,
+  args,
+  startTime,
+  timestamp,
+  ...extra
+})
+
+function conformingStream(): WireFrame[] {
+  return [
+    { scope: 'metadata', data: { type: 'testrunner' } },
+    { scope: 'commands', data: [row('get', [LOGIN], 90, 110)] },
+    { scope: 'mutations', data: [anchor(LOGIN, 100)] },
+    { scope: 'commands', data: [row('click', [], 200, 320)] },
+    { scope: 'mutations', data: [anchor(SECURE, 300)] },
+    { scope: 'commands', data: [row('get', [{ url: SECURE }], 330, 340)] },
+    {
+      scope: 'commands',
+      data: [
+        row('get', [BROKEN], 350, 360, {
+          error: { name: 'Error', message: 'net::ERR_FAILED at /broken' }
+        })
+      ]
+    },
+    {
+      scope: 'replaceCommand',
+      data: { oldTimestamp: 110, command: row('get', [LOGIN], 90, 110) }
+    }
+  ]
+}
+
+const rules = (frames: WireFrame[]) =>
+  checkConformance(frames, truth).map((v) => v.rule)
+
+describe('checkConformance', () => {
+  it('passes a stream that follows every rule', () => {
+    expect(checkConformance(conformingStream(), truth)).toEqual([])
+  })
+
+  it('flags commands sent before any metadata', () => {
+    expect(rules(conformingStream().slice(1))).toEqual([RULES.metadataFirst])
+  })
+
+  it('flags a row that ends before it starts', () => {
+    const frames = conformingStream()
+    frames[3] = { scope: 'commands', data: [row('click', [], 330, 320)] }
+    expect(rules(frames)).toEqual([RULES.completionStamp])
+  })
+
+  it('flags a navigation stamped at invocation, which replays the previous page', () => {
+    const frames = conformingStream()
+    frames[5] = { scope: 'commands', data: [row('get', [SECURE], 290, 290)] }
+    expect(rules(frames)).toEqual([RULES.navigationShowsDestination])
+  })
+
+  it('flags a document that never got an anchor', () => {
+    const frames = conformingStream().filter(
+      (f) =>
+        !(f.scope === 'mutations' && JSON.stringify(f.data).includes(SECURE))
+    )
+    expect(rules(frames)).toContain(RULES.documentAnchored)
+  })
+
+  it('flags a document anchored twice', () => {
+    const frames = [
+      ...conformingStream(),
+      { scope: 'mutations', data: [anchor(SECURE, 300)] }
+    ]
+    expect(rules(frames)).toEqual([RULES.anchorOnce])
+  })
+
+  it('flags an anchor stamped after its document was born', () => {
+    const frames = conformingStream()
+    frames[2] = { scope: 'mutations', data: [anchor(LOGIN, 150)] }
+    expect(rules(frames)).toContain(RULES.anchorBirthTime)
+  })
+
+  it('flags a failed navigation with no error row', () => {
+    const frames = conformingStream().filter(
+      (f) => !JSON.stringify(f.data).includes(BROKEN)
+    )
+    expect(rules(frames)).toContain(RULES.failureRecorded)
+  })
+
+  it('flags a replaceCommand naming a row never sent', () => {
+    const frames = [
+      ...conformingStream(),
+      {
+        scope: 'replaceCommand',
+        data: { oldTimestamp: 999, command: row('get', [], 0, 999) }
+      }
+    ]
+    expect(rules(frames)).toContain(RULES.replaceTargetsRow)
+  })
+
+  it('flags a row the browser saw but the stream lost', () => {
+    const frames = conformingStream().filter(
+      (f) => !JSON.stringify(f.data).includes('"click"')
+    )
+    expect(rules(frames)).toEqual([RULES.rowPerAction])
+  })
+
+  it('flags a duplicated row', () => {
+    const frames = [
+      ...conformingStream(),
+      { scope: 'commands', data: [row('click', [], 400, 410)] }
+    ]
+    expect(rules(frames)).toEqual([RULES.rowPerAction])
+  })
+
+  // Regression: a replacement matched by timestamp alone overwrote a row that finished in the same ms.
+  it('applies a replacement to the row with its id, not the first at that timestamp', () => {
+    const frames: WireFrame[] = [
+      ...conformingStream(),
+      {
+        scope: 'commands',
+        data: [
+          row('sendKeys', ['x'], 410, 420, { id: 7 }),
+          row('click', [], 415, 420, { id: 8 })
+        ]
+      },
+      {
+        scope: 'replaceCommand',
+        data: {
+          oldTimestamp: 420,
+          command: row('click', [], 415, 420, { id: 8 })
+        }
+      }
+    ]
+    const withTwoMore = {
+      ...truth,
+      actions: { navigate: 3, click: 2, fill: 1 }
+    }
+    expect(checkConformance(frames, withTwoMore)).toEqual([])
+  })
+
+  it('flags run controls advertised with no command behind them', () => {
+    const frames = conformingStream()
+    frames[0] = {
+      scope: 'metadata',
+      data: {
+        type: 'testrunner',
+        options: { runCapabilities: { canRunAll: true, canRunTests: false } }
+      }
+    }
+    expect(rules(frames)).toEqual([RULES.runControlsHaveCommand])
+  })
+
+  it('accepts run controls served by either command, as the backend falls back between them', () => {
+    const frames = conformingStream()
+    frames[0] = {
+      scope: 'metadata',
+      data: {
+        type: 'testrunner',
+        options: {
+          runCapabilities: { canRunAll: true, canRunTests: true },
+          launchCommand: 'node script.js'
+        }
+      }
+    }
+    expect(checkConformance(frames, truth)).toEqual([])
+  })
+
+  it("flags an error row whose message is the binding's formatting, not the browser's", () => {
+    const frames = conformingStream().map((f) =>
+      JSON.stringify(f.data).includes(BROKEN) && f.scope === 'commands'
+        ? {
+            scope: 'commands',
+            data: [
+              row('get', [BROKEN], 350, 360, {
+                error: {
+                  name: 'WebDriverException',
+                  message:
+                    'Message: net::ERR_FAILED at /broken\nStacktrace:\n#0 0x55d0 <unknown>\n'
+                }
+              })
+            ]
+          }
+        : f
+    )
+    expect(rules(frames)).toEqual([RULES.errorCarriesBrowserMessage])
+  })
+})
diff --git a/packages/conformance/tests/python.test.ts b/packages/conformance/tests/python.test.ts
new file mode 100644
index 00000000..04bc7728
--- /dev/null
+++ b/packages/conformance/tests/python.test.ts
@@ -0,0 +1,74 @@
+import { spawnSync } from 'node:child_process'
+import { copyFileSync, existsSync, mkdtempSync, rmSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import path from 'node:path'
+
+import { afterEach, describe, expect, it } from 'vitest'
+
+import { judge } from '../src/allowlist.js'
+import { checkConformance } from '../src/checker.js'
+import { COLLECTOR_BUNDLE, REPO_ROOT } from '../src/constants.js'
+import { runScenario } from '../src/harness.js'
+import { writeRunReport } from '../src/report.js'
+
+const PYTHON = process.env.CONFORMANCE_PYTHON ?? 'python3'
+const ADAPTER_SRC = path.join(REPO_ROOT, 'packages/selenium-devtools-py/src')
+const SCENARIO = path.join(
+  REPO_ROOT,
+  'packages/conformance/scenarios/python_scenario.py'
+)
+
+// Needs selenium and the built collector; CI has both, so only a local run may skip.
+const ready =
+  (spawnSync(PYTHON, ['-c', 'import selenium'], {
+    env: { ...process.env, PYTHONPATH: ADAPTER_SRC }
+  }).status === 0 &&
+    existsSync(COLLECTOR_BUNDLE)) ||
+  Boolean(process.env.CI)
+
+const scratch: string[] = []
+afterEach(() => {
+  for (const dir of scratch.splice(0)) {
+    rmSync(dir, { recursive: true, force: true })
+  }
+})
+
+describe.each([true, false])(
+  'selenium-devtools-py conformance (bidi: %s)',
+  (bidi) => {
+    it.skipIf(!ready)(
+      'emits a stream that follows every rule',
+      async () => {
+        // Run from a copy: the adapter writes its video beside the script it runs.
+        const dir = mkdtempSync(path.join(tmpdir(), 'conformance-'))
+        scratch.push(dir)
+        const script = path.join(dir, 'python_scenario.py')
+        copyFileSync(SCENARIO, script)
+
+        const run = await runScenario(PYTHON, [script], {
+          env: { PYTHONPATH: ADAPTER_SRC },
+          bidi
+        })
+        const violations = checkConformance(run.frames, run.truth)
+        const { unexplained, stale } = judge(
+          'selenium-devtools-py',
+          bidi,
+          violations
+        )
+        await writeRunReport({
+          adapter: 'selenium-devtools-py',
+          bidi,
+          ...run,
+          violations,
+          unexplained,
+          stale
+        })
+        expect(run.exitCode, run.output).toBe(0)
+        expect(run.truth.documents.length).toBe(3)
+        expect(unexplained).toEqual([])
+        expect(stale, 'a known gap no longer occurs: remove it').toEqual([])
+      },
+      90_000
+    )
+  }
+)
diff --git a/packages/conformance/tests/report.test.ts b/packages/conformance/tests/report.test.ts
new file mode 100644
index 00000000..2d102f1b
--- /dev/null
+++ b/packages/conformance/tests/report.test.ts
@@ -0,0 +1,149 @@
+import { describe, expect, it } from 'vitest'
+
+import { RULES } from '../src/constants.js'
+import { renderReport } from '../src/report-html.js'
+import type { RunReport, Violation } from '../src/types.js'
+
+const LOGIN = 'http://fake/login'
+const SECURE = 'http://fake/secure'
+
+function run(overrides: Partial<RunReport> = {}): RunReport {
+  return {
+    adapter: 'selenium-devtools',
+    bidi: true,
+    exitCode: 0,
+    truth: {
+      documents: [
+        { url: LOGIN, bornAt: 1100 },
+        { url: SECURE, bornAt: 1300 }
+      ],
+      failedNavigations: [],
+      actions: { navigate: 0, click: 0, fill: 0 }
+    },
+    violations: [],
+    unexplained: [],
+    stale: [],
+    frames: [
+      { scope: 'metadata', data: {} },
+      {
+        scope: 'mutations',
+        data: [
+          {
+            type: 'childList',
+            url: SECURE,
+            timestamp: 1300,
+            addedNodes: [],
+            removedNodes: []
+          }
+        ]
+      },
+      {
+        scope: 'commands',
+        data: [
+          { command: 'click', args: [], startTime: 1250, timestamp: 1320 },
+          { command: 'get', args: [LOGIN], startTime: 1000, timestamp: 1110 }
+        ]
+      }
+    ],
+    output: '',
+    ...overrides
+  }
+}
+
+const unanchored: Violation = {
+  rule: RULES.documentAnchored,
+  message: `document ${LOGIN} born at 1100 has no anchor`,
+  subject: { kind: 'document', timestamp: 1100 }
+}
+
+describe('renderReport', () => {
+  it('marks a clean run PASS and a run with unexplained violations FAIL', () => {
+    expect(renderReport([run()])).toContain('>PASS<')
+    const failing = renderReport([
+      run({ violations: [unanchored], unexplained: [unanchored] })
+    ])
+    expect(failing).toContain('>FAIL<')
+    expect(failing).not.toContain('>PASS<')
+  })
+
+  it('marks a nonzero exit as FAIL', () => {
+    expect(renderReport([run({ exitCode: 1 })])).toContain('>FAIL<')
+  })
+
+  it('shows an unexplained violation inline next to its document', () => {
+    const html = renderReport([
+      run({ violations: [unanchored], unexplained: [unanchored] })
+    ])
+    const row = html.slice(html.indexOf(`document born</td><td><code>${LOGIN}`))
+    expect(row.slice(0, row.indexOf('</tr>'))).toContain(
+      '<li class="unexplained"><strong>UNEXPLAINED</strong>'
+    )
+  })
+
+  it('marks an allowlisted violation with its gap reason', () => {
+    const html = renderReport([
+      run({ bidi: false, violations: [unanchored], unexplained: [] })
+    ])
+    expect(html).toContain('<li class="allowed"><strong>allowlisted</strong>')
+    expect(html).toContain('allowlisted: Without BiDi the collector')
+    expect(html).not.toContain('class="unexplained"')
+    expect(html).toContain('>PASS<')
+  })
+
+  it('escapes text taken from the stream', () => {
+    const hostile = '<script>alert("x")</script>'
+    const html = renderReport([
+      run({
+        frames: [
+          {
+            scope: 'commands',
+            data: [
+              {
+                command: 'sendKeys',
+                args: [hostile],
+                startTime: 1000,
+                timestamp: 1010
+              }
+            ]
+          }
+        ],
+        output: hostile
+      })
+    ])
+    expect(html).not.toContain('<script>')
+    expect(html).toContain('&lt;script&gt;')
+  })
+
+  it('orders events by time, relative to the first event', () => {
+    const html = renderReport([run()])
+    const order = [
+      '>+0 ms<',
+      `<code>${LOGIN}</code> +0 ms .. +110 ms`,
+      `document born</td><td><code>${LOGIN}`,
+      '>+250 ms<',
+      `document born</td><td><code>${SECURE}`,
+      `DOM anchor</td><td><code>${SECURE}`
+    ].map((s) => html.indexOf(s))
+    expect(order.every((i) => i !== -1)).toBe(true)
+    expect([...order].sort((a, b) => a - b)).toEqual(order)
+  })
+
+  it('points a failing run at the responsibility the broken rule tests', () => {
+    const html = renderReport([
+      run({
+        adapter: 'selenium-devtools-py',
+        violations: [unanchored],
+        unexplained: [unanchored]
+      })
+    ])
+    expect(html).toContain('Where to look')
+    expect(html).toContain('Collector injection and draining')
+    expect(html).toContain(
+      'href="../../../docs/ADAPTERS.md#2b-collector-injection-and-draining"'
+    )
+  })
+
+  it('shows no guidance for a passing run', () => {
+    expect(renderReport([run()])).not.toContain('Where to look')
+  })
+})
diff --git a/packages/conformance/tests/selenium.test.ts b/packages/conformance/tests/selenium.test.ts
new file mode 100644
index 00000000..3a8ff9b5
--- /dev/null
+++ b/packages/conformance/tests/selenium.test.ts
@@ -0,0 +1,52 @@
+import { existsSync } from 'node:fs'
+import path from 'node:path'
+
+import { describe, expect, it } from 'vitest'
+
+import { judge } from '../src/allowlist.js'
+import { checkConformance } from '../src/checker.js'
+import { COLLECTOR_BUNDLE, REPO_ROOT } from '../src/constants.js'
+import { runScenario } from '../src/harness.js'
+import { writeRunReport } from '../src/report.js'
+
+// The scenario runs the built adapter and injects the built collector. CI builds first, so only a local run may skip.
+const ready =
+  [
+    path.join(REPO_ROOT, 'packages/selenium-devtools/dist/index.js'),
+    COLLECTOR_BUNDLE
+  ].every((f) => existsSync(f)) || Boolean(process.env.CI)
+
+describe.each([true, false])(
+  'selenium-devtools conformance (bidi: %s)',
+  (bidi) => {
+    it.skipIf(!ready)(
+      'emits a stream that follows every rule',
+      async () => {
+        const run = await runScenario(
+          path.join(REPO_ROOT, 'node_modules/.bin/tsx'),
+          ['packages/conformance/scenarios/selenium.ts'],
+          { bidi }
+        )
+        const violations = checkConformance(run.frames, run.truth)
+        const { unexplained, stale } = judge(
+          'selenium-devtools',
+          bidi,
+          violations
+        )
+        await writeRunReport({
+          adapter: 'selenium-devtools',
+          bidi,
+          ...run,
+          violations,
+          unexplained,
+          stale
+        })
+        expect(run.exitCode, run.output).toBe(0)
+        expect(run.truth.documents.length).toBe(3)
+        expect(unexplained).toEqual([])
+        expect(stale, 'a known gap no longer occurs: remove it').toEqual([])
+      },
+      90_000
+    )
+  }
+)
diff --git a/packages/conformance/tsconfig.json b/packages/conformance/tsconfig.json
new file mode 100644
index 00000000..01ecbeb4
--- /dev/null
+++ b/packages/conformance/tsconfig.json
@@ -0,0 +1,4 @@
+{
+  "extends": "../../tsconfig.json",
+  "include": ["src/**/*.ts", "scenarios/**/*.ts"]
+}
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index f43d92ac..0bc01c2c 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -272,7 +272,7 @@ importers:
         version: 11.3.3
       '@wdio/cli':
         specifier: '>=9'
-        version: 9.30.1(@types/node@26.6.4)(expect-webdriverio@7.0.1)
+        version: 9.30.1(@types/node@26.6.4)(expect-webdriverio@7.0.1)(puppeteer-core@21.11.0)
       '@wdio/devtools-app':
         specifier: workspace:^
         version: link:../app
@@ -329,6 +329,30 @@ importers:
         specifier: 6.0.3
         version: 6.0.3
 
+  packages/conformance:
+    devDependencies:
+      '@types/node':
+        specifier: 26.6.4
+        version: 26.6.4
+      '@types/selenium-webdriver':
+        specifier: ^4.35.6
+        version: 4.35.6
+      '@types/ws':
+        specifier: ^8.18.2
+        version: 8.18.2
+      '@wdio/devtools-shared':
+        specifier: workspace:^
+        version: link:../shared
+      '@wdio/selenium-devtools':
+        specifier: workspace:^
+        version: link:../selenium-devtools
+      selenium-webdriver:
+        specifier: ^4.50.0
+        version: 4.50.0
+      ws:
+        specifier: ^8.22.0
+        version: 8.22.0
+
   packages/core:
     devDependencies:
       '@types/ws':
@@ -388,7 +412,7 @@ importers:
         version: 6.0.3
       vitest:
         specifier: ^5.0.2
-        version: 5.0.3(@types/node@26.6.4)(@vitest/coverage-v8@5.0.3)(happy-dom@20.14.5)(jsdom@24.1.3)(vite@8.3.2(@types/node@26.6.4)(esbuild@0.27.7)(jiti@2.7.0)(tsx@4.23.15)(yaml@2.9.1))
+        version: 5.0.3(@types/node@26.6.4)(@vitest/coverage-v8@5.0.3)(happy-dom@20.14.5)(jsdom@24.1.3)(vite@8.3.2(@types/node@26.6.4)(esbuild@0.28.2)(jiti@2.7.0)(tsx@4.23.15)(yaml@2.9.1))
 
   packages/nightwatch-devtools:
     dependencies:
@@ -10608,15 +10632,6 @@ snapshots:
     dependencies:
       '@vitest/istanbul-lib-coverage': 1.0.2
 
-  '@vitest/mocker@5.0.3(vite@8.3.2(@types/node@26.6.4)(esbuild@0.27.7)(jiti@2.7.0)(tsx@4.23.15)(yaml@2.9.1))':
-    dependencies:
-      '@jridgewell/trace-mapping': 0.3.31
-      '@vitest/spy': 5.0.3
-      estree-walker: 3.0.3
-      magic-string: 1.4.2
-    optionalDependencies:
-      vite: 8.3.2(@types/node@26.6.4)(esbuild@0.27.7)(jiti@2.7.0)(tsx@4.23.15)(yaml@2.9.1)
-
   '@vitest/mocker@5.0.3(vite@8.3.2(@types/node@26.6.4)(esbuild@0.28.2)(jiti@2.7.0)(tsx@4.23.15)(yaml@2.9.1))':
     dependencies:
       '@jridgewell/trace-mapping': 0.3.31
@@ -10763,11 +10778,11 @@ snapshots:
       - utf-8-validate
       - yaml
 
-  '@wdio/cli@9.30.1(@types/node@26.6.4)(expect-webdriverio@7.0.1)':
+  '@wdio/cli@9.30.1(@types/node@26.6.4)(expect-webdriverio@7.0.1)(puppeteer-core@21.11.0)':
     dependencies:
       '@vitest/snapshot': 2.1.9
       '@wdio/config': 9.30.1
-      '@wdio/globals': 9.29.1(expect-webdriverio@7.0.1)(webdriverio@9.30.1)
+      '@wdio/globals': 9.29.1(expect-webdriverio@7.0.1)(webdriverio@9.30.1(puppeteer-core@21.11.0))
       '@wdio/logger': 9.29.1
       '@wdio/protocols': 9.30.1
       '@wdio/types': 9.30.1
@@ -10888,9 +10903,9 @@ snapshots:
       expect-webdriverio: 7.0.1(@wdio/globals@9.31.3)(@wdio/logger@9.29.1)(webdriverio@9.30.1)
       webdriverio: 9.30.1(puppeteer-core@21.11.0)
 
-  '@wdio/globals@9.29.1(expect-webdriverio@7.0.1)(webdriverio@9.30.1)':
+  '@wdio/globals@9.29.1(expect-webdriverio@7.0.1)(webdriverio@9.30.1(puppeteer-core@21.11.0))':
     dependencies:
-      expect-webdriverio: 7.0.1(@wdio/globals@9.31.3)(@wdio/logger@9.29.1)(webdriverio@9.30.1)
+      expect-webdriverio: 7.0.1(@wdio/globals@9.31.3)(@wdio/logger@9.29.1)(webdriverio@9.30.1(puppeteer-core@21.11.0))
       webdriverio: 9.30.1(puppeteer-core@21.11.0)
 
   '@wdio/globals@9.31.3(expect-webdriverio@6.1.0(@wdio/globals@9.31.3(expect-webdriverio@7.0.1(@wdio/globals@9.31.3)(@wdio/logger@9.29.1)(webdriverio@9.30.1))(webdriverio@9.30.1(puppeteer-core@21.11.0)))(@wdio/logger@9.29.1)(webdriverio@9.30.1(puppeteer-core@21.11.0)))(webdriverio@9.30.1(puppeteer-core@21.11.0))':
@@ -15121,7 +15136,7 @@ snapshots:
   proxy-agent@6.3.1:
     dependencies:
       agent-base: 7.1.4
-      debug: 4.3.4
+      debug: 4.4.3(supports-color@5.5.0)
       http-proxy-agent: 7.0.2
       https-proxy-agent: 7.0.6
       lru-cache: 7.18.3
@@ -16526,21 +16541,6 @@ snapshots:
       - '@swc/helpers'
       - rollup
 
-  vite@8.3.2(@types/node@26.6.4)(esbuild@0.27.7)(jiti@2.7.0)(tsx@4.23.15)(yaml@2.9.1):
-    dependencies:
-      lightningcss: 1.33.0
-      picomatch: 4.0.7
-      postcss: 8.5.28
-      rolldown: 1.2.12
-      tinyglobby: 0.2.17
-    optionalDependencies:
-      '@types/node': 26.6.4
-      esbuild: 0.27.7
-      fsevents: 2.3.3
-      jiti: 2.7.0
-      tsx: 4.23.15
-      yaml: 2.9.1
-
   vite@8.3.2(@types/node@26.6.4)(esbuild@0.28.2)(jiti@2.7.0)(tsx@4.23.15)(yaml@2.9.1):
     dependencies:
       lightningcss: 1.33.0
@@ -16556,30 +16556,6 @@ snapshots:
       tsx: 4.23.15
       yaml: 2.9.1
 
-  vitest@5.0.3(@types/node@26.6.4)(@vitest/coverage-v8@5.0.3)(happy-dom@20.14.5)(jsdom@24.1.3)(vite@8.3.2(@types/node@26.6.4)(esbuild@0.27.7)(jiti@2.7.0)(tsx@4.23.15)(yaml@2.9.1)):
-    dependencies:
-      '@types/chai': 5.2.3
-      '@vitest/mocker': 5.0.3(vite@8.3.2(@types/node@26.6.4)(esbuild@0.27.7)(jiti@2.7.0)(tsx@4.23.15)(yaml@2.9.1))
-      chai: 6.2.2
-      es-module-lexer: 2.3.2
-      expect-type: 1.4.0
-      magic-string: 1.4.2
-      obug: 2.2.1
-      picomatch: 4.0.7
-      std-env: 4.3.0
-      tinybench: 6.2.0
-      tinyexec: 1.3.1
-      tinyglobby: 0.2.17
-      vite: 8.3.2(@types/node@26.6.4)(esbuild@0.27.7)(jiti@2.7.0)(tsx@4.23.15)(yaml@2.9.1)
-      why-is-node-running: 3.2.1
-    optionalDependencies:
-      '@types/node': 26.6.4
-      '@vitest/coverage-v8': 5.0.3(vitest@5.0.3)
-      happy-dom: 20.14.5
-      jsdom: 24.1.3
-    transitivePeerDependencies:
-      - msw
-
   vitest@5.0.3(@types/node@26.6.4)(@vitest/coverage-v8@5.0.3)(happy-dom@20.14.5)(jsdom@24.1.3)(vite@8.3.2(@types/node@26.6.4)(esbuild@0.28.2)(jiti@2.7.0)(tsx@4.23.15)(yaml@2.9.1)):
     dependencies:
       '@types/chai': 5.2.3
diff --git a/pnpm-workspace.yaml b/pnpm-workspace.yaml
index c8ada72b..8c6a5084 100644
--- a/pnpm-workspace.yaml
+++ b/pnpm-workspace.yaml
@@ -10,6 +10,7 @@ packages:
   - 'packages/app'
   - 'packages/nightwatch-devtools'
   - 'packages/selenium-devtools'
+  - 'packages/conformance'
   - 'examples/wdio'
   - 'examples/selenium-js'
   - 'examples/nightwatch'

From b42554f00c0db15b5ddeca76b079d91d11755383 Mon Sep 17 00:00:00 2001
From: Vishnu Vardhan <vishnu.p@browserstack.com>
Date: Mon, 12 Oct 2026 17:21:29 +0530
Subject: [PATCH 06/18] ci: run the conformance suite with Python and upload
 its report on failure

---
 .github/workflows/ci.yml | 14 ++++++++++++++
 1 file changed, 14 insertions(+)

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 6cd81815..c70815a4 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -43,8 +43,22 @@ jobs:
       # because it is fast and its failures are cheaper to read.
       - name: 🔎 Typecheck
         run: pnpm typecheck
+      # The conformance suite runs the Python adapter beside the JS ones, so a
+      # capture fix missing from one language fails this job.
+      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
+        with:
+          python-version: '3.13'
+      - name: Install the Python adapter
+        run: pip install -e packages/selenium-devtools-py
       - name: 🧪 Run Tests
         run: pnpm test
+      - name: Upload conformance report
+        if: failure()
+        uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
+        with:
+          name: conformance-report
+          path: packages/conformance/out/
+          if-no-files-found: ignore
 
   # Separate job because these are the only tests that need a real browser, and
   # they parallelise with `build` instead of extending it. No bundle step: the

From c490b5aefc651e95574e83b1074f133f471fea55 Mon Sep 17 00:00:00 2001
From: Vishnu Vardhan <vishnu.p@browserstack.com>
Date: Mon, 12 Oct 2026 17:21:29 +0530
Subject: [PATCH 07/18] docs: describe the conformance suite and add an
 adapter-author guide

---
 ARCHITECTURE.md  |  12 +-
 docs/ADAPTERS.md | 279 +++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 290 insertions(+), 1 deletion(-)
 create mode 100644 docs/ADAPTERS.md

diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md
index 6cee2380..7bc230b2 100644
--- a/ARCHITECTURE.md
+++ b/ARCHITECTURE.md
@@ -135,7 +135,7 @@ Contains:
 - `pytest_plugin.py` — the suite tree, keyed by pytest nodeid; auto-discovered, opt-in by env var.
 - `rerun.py`, `run_id.py`, `performance.py`, `transport.py` — run controls, run identity, navigation timings, and a stdlib-only WebSocket client.
 
-Live mode only: it does not write a trace archive. That work, and the question of whether the ~3,100 lines of trace transforms in `core` should move behind the wire rather than be reimplemented per language, is tracked in [#330](https://github.com/webdriverio/devtools/issues/330) and [#278](https://github.com/webdriverio/devtools/issues/278).
+It writes trace archives without running the transforms itself: `trace_export.py` streams the action snapshots and filmstrip frames, then sends a `traceExport` request and the backend builds the archive from the run it accumulated, answering with `traceExported`. `export_trace()` and teardown (`disable()`, the pytest plugin's session finish) trigger it. Writing an adapter in another language is covered in [docs/ADAPTERS.md](./docs/ADAPTERS.md).
 
 Imports from: `selenium` (required, 4.44+). Does not import: `core`, `shared`, any other package.
 
@@ -188,6 +188,16 @@ Imports from: `core`. The script bodies, serializers, types, and locator generat
 
 The DOM-walking scripts run in the page via `browser.execute`, so — like `script` — they avoid Node-only APIs.
 
+### `packages/conformance`: cross-adapter conformance suite
+
+Test-only and never published or bundled. Each adapter runs one scenario (open `/login`, type, submit to `/secure`, log out, then a navigation that fails) as its own process, against a fake W3C WebDriver server that models two pages and records what really happened in the browser: which documents were born and when, and which navigations failed. The adapter reports into a recording backend that stands in for the dashboard, reached through the same reuse handshake a rerun uses, so no adapter gains a code path for being tested. `src/checker.ts` then judges the recorded frame stream against behavioural rules, for example "a navigation row replays the page it navigated to" and "every document gets exactly one anchor at its birth time". Every adapter is checked by the same rules, so a capture fix that lands in one language and not another fails CI.
+
+Each scenario runs twice, with and without BiDi. The fake answers the BiDi commands the adapters send, and a registered preload puts the collector into every later document from birth, as in Chrome. A difference an adapter is allowed to show lives in `src/allowlist.ts` with a mandatory reason, and an entry that stops matching fails the run, so a closed gap forces its own removal.
+
+Every run, passing or failing, dumps its frames, ground truth, violations and scenario output to `packages/conformance/out/<adapter>-<bidi|no-bidi>.json` and rebuilds `out/index.html`, a self-contained page laying each run out as a timeline of documents, command rows and DOM anchors with every violation beside the event it concerns. CI uploads `out/` as the `conformance-report` artifact when the `build` job fails.
+
+Covers `selenium-devtools` and `selenium-devtools-py`. The WDIO service and Nightwatch have no scenario yet. The fake emits no BiDi events, so console and network capture are not checked.
+
 ### `examples/`
 
 Per-adapter demo projects used for manual verification. One directory per adapter, and inside it one directory per test runner, named for the runner itself:
diff --git a/docs/ADAPTERS.md b/docs/ADAPTERS.md
new file mode 100644
index 00000000..edee3bd4
--- /dev/null
+++ b/docs/ADAPTERS.md
@@ -0,0 +1,279 @@
+# Writing an adapter for a new language
+
+This guide is for someone adding devtools support to a language or framework that cannot import the TypeScript packages in this repo: Java + JUnit, C# + NUnit, Ruby + RSpec, and so on. It assumes you know WebDriver and your target framework, and that you have read the package map in [ARCHITECTURE.md](../ARCHITECTURE.md).
+
+The worked example throughout is the Python adapter, `packages/selenium-devtools-py`. It shares no code with the JavaScript adapters, only the wire format, so everything it does is something your adapter has to do too.
+
+---
+
+## 1. What an adapter is, and what it is not
+
+An adapter is a process-local library that watches a test run and streams `{scope, data}` JSON frames over one WebSocket to the devtools backend. That is the whole interface. It does not render anything, store anything, or build trace archives itself.
+
+What you reuse, and how you reach it from another language:
+
+| You get | Provided by | How a non-JS adapter reaches it |
+|---|---|---|
+| The dashboard UI (Actions, Console, Network, DOM replay, Source, video) | `packages/app`, served by the backend | Nothing to do: it renders whatever frames you send. |
+| WS gateway, broadcast to dashboard tabs, run accumulation, Preserve & Rerun | `packages/backend` | Connect to `/worker` and send frames. |
+| The page-side DOM collector (`window.wdioTraceCollector`) | `packages/script`, served by the backend | `GET /api/collector` (`COLLECTOR_API.get` in `shared/src/collector.ts`). Raw JS source. |
+| Element / accessibility-tree scripts for the trace's A11y tab | `shared/src/element-scripts.ts`, served by the backend | `GET /api/element-scripts?runner=<TestRunnerId>` (`ELEMENT_SCRIPTS_API`). JSON `{accessibilityTree, elements}`. |
+| Trace archive (`trace.zip`) building, retention policy, per-test slicing | `packages/trace`, run by the backend | Send a `traceExport` frame on the worker socket; the answer comes back as `traceExported` (`shared/src/trace-export.ts`). |
+| Rerun / Run-all from the dashboard | backend `runner.ts` | Publish `launchCommand` / `rerunCommand` in your `metadata` frame and honour the reuse handshake (section 2d). |
+| The backend itself | `@wdio/devtools-backend` on npm (`dist/server.js`, bin `devtools-backend`) | Spawn it with Node, or attach to one already running. |
+
+Serving the collector and element scripts over HTTP means their version always matches the backend you are talking to. Do not vendor a copy.
+
+What an adapter must not do: re-implement the trace transforms, invent scope names, or branch on anything the backend did not tell you. If you need a new concept on the wire, it starts as a change to `packages/shared`.
+
+## 2. The four responsibilities
+
+### 2a. Driver command interception
+
+**Contract.** Every user-visible WebDriver command produces one row in a `commands` frame (a `CommandLog`, see `wire-schema.json`):
+
+- `startTime` is the wall clock (epoch ms) at **invocation**.
+- `timestamp` is the wall clock at **completion**, after the driver has answered. `timestamp >= startTime`.
+- `command` uses a name the trace vocabulary knows. `ACTION_MAP` in `shared/src/trace-actions.ts` already maps raw W3C protocol names (`get`, `clickElement`, `sendKeysToElement`, `clearElement`, `getElementText`, `goBack`, ...) because a protocol-level adapter reports those. An unmapped command still shows live but is dropped from a trace.
+- A failed command still produces a row, with `error: {name, message}`, and the original exception is rethrown unchanged.
+- Optional fields are omitted, never sent as `null` (the schema rejects `null` for an optional field).
+- Your own scripts (collector injection, drains, screenshots) must not appear as rows.
+
+To enrich a row after the fact (navigation timings, for example), send `replaceCommand` with `{oldTimestamp, command}`. The backend and app match on `timestamp`, not on `id`, so keep row timestamps distinct.
+
+**Pitfall already hit.** Two JS adapters stamped `timestamp` with the invocation clock while the page's mutation stream runs on real time, so a fill row replayed an empty field and a navigation row replayed the page it had just left (CLAUDE.md Known debt: "A command row is stamped at COMPLETION").
+
+**Python.** `instrumentation.py` `install()` patches `WebDriver.execute`, the single chokepoint every driver and element command flows through (`patched_execute`). It records `start = now_ms()` before calling through, and `SessionCapturer.capture_command` in `capturer.py` stamps `timestamp=now_ms()` after the call returns. `frames.command_log` in `frames.py` builds the row and omits unset fields. Internal scripts run through `_guarded_execute_script`, which sets a flag that `patched_execute` checks so they bypass capture. `SKIP_COMMANDS` and `NAVIGATION_COMMANDS` live in `constants.py`; `_attach_performance` sends the enriched navigation row via `send_replace_command`.
+
+Find the equivalent chokepoint in your binding (Java's `CommandExecutor`, .NET's `ICommandExecutor`, Ruby's bridge `execute`) rather than wrapping each public method.
+
+### 2b. Collector injection and draining
+
+**Contract.** The collector lives in the page and buffers DOM mutations. A **DOM anchor** is a `childList` mutation carrying `url`; the collector stamps it with the document's own `performance.timeOrigin`, i.e. the document's birth time. Your adapter must:
+
+1. **Get the source** from `GET /api/collector`.
+2. **Install it at document start when BiDi is available.** Request `webSocketUrl: true` in the new-session capabilities, then call BiDi `script.addPreloadScript` with **no browsing-context id** (global, so later contexts are covered) and the source wrapped as a function declaration: `async () => { <source> }`. Register it before the session's first navigation.
+3. **Fall back to `<script>` injection** when BiDi is absent: append a `<script>` whose body is the source wrapped as `(async function() { <source> })()`, into the current document, and repeat whenever a drain finds no collector.
+4. **Drain with a forced anchor.** Read the buffer with one atomic script that also anchors the current document:
+
+```js
+if (!(typeof window.wdioTraceCollector !== "undefined")) { return null; } window.wdioTraceCollector.captureCurrentDom(); return window.wdioTraceCollector.getTraceData();
+```
+
+This is `collectorDrainExpression(true)` in `core/src/script-loader.ts`. Forcing is free after a document's first anchor (the collector guards it). A `null` result means "no collector in this document": inject once and drain again (`drainCollectorWithRecovery` in the same file). Forward the payload's `mutations` array as a `mutations` frame.
+
+5. **Drain after any command that could have moved the page**, and once more before the session ends. Python drains after every captured command; the JS Selenium adapter uses a deny-list (`warrantsLiveDrain` in `selenium-devtools/src/helpers/commandPostActions.ts`). Either is acceptable; draining too rarely is not.
+
+**Pitfalls already hit.**
+- `<script>` injection only instruments the document that exists when it runs, so every navigation becomes a race; the preload removes the race class (Known debt: "Document-start injection is what removes the whole race class").
+- A drain issued right after a navigation beats the collector's own asynchronous first anchor, and the destination's buffer dies with the page unless the drain forces the anchor (Known debt: "A drain must anchor the document it reads").
+- A preload dies with its session; if your framework replaces sessions mid-run, re-register it for the new one (Known debt: "A preload dies with its session").
+
+**Python.** `collector_source.py` `fetch_collector_source` (cached per backend), `bidi_preload.py` `register_collector_preload` and `as_function_declaration`, `snapshot.py` (`_INJECT_SCRIPT`, `_DRAIN_SCRIPT`, `wrap_injectable`, `SnapshotCapturer.inject`, `SnapshotCapturer.pull_mutations` with one recovery), wired in `instrumentation.py` `_ensure_session_setup` (preload first, then `start_snapshot_capture`) and `_refresh_snapshot` / `_flush_mutations` after each command. `_enable_bidi_capability` adds `webSocketUrl` to the new-session request.
+
+### 2c. Test-framework hooks
+
+**Contract.** The suite tree is sent as a `suites` frame whose data is an **array of single-key records**, `[{"<uid>": SuiteStats}]`; a plain array of suites does not render. `SuiteStats.start`/`end` and `TestStats.start`/`end` are ISO-8601 strings. Required fields are listed in `wire-schema.json` (`uid`, `cid`, `title`, `fullTitle`, `type`, `file`, `start`, `tests`, `suites`, `hooks`, `_duration` for a suite; a test adds `parent`, `state`, `end`, `retries`). The frame is resent whole as states change; the app merges by uid.
+
+- Publish the tree early (all tests `pending`), flip a test to `running` when it starts, then to its terminal state.
+- Set `testUid` on every command row captured while a test runs. Without it the trace has no test boundaries.
+- A setup or teardown failure is a test failure. A test whose setup failed never reports a "call" phase in most runners, so it must not be left `running`.
+- Make uids stable and, if you can, directly addressable by your runner, so one rerun slot covers every row (see 2d).
+- Without a framework (a plain script), synthesize one suite holding one test so the tree is not empty.
+
+**Pitfall already hit.** A rerun process collects a subset of the tests, so anything derived from "this collection" (sibling order, the Run-all command) is wrong for the tree it merges into; Python orders siblings by source line for that reason (Known debt: "A rerun's process collects a SUBSET").
+
+**Python.** `pytest_plugin.py`: `pytest_collection_finish` publishes every item as `pending`, `pytest_runtest_logstart` sets `capturer.test_uid` and marks `running`, `pytest_runtest_logreport` with `reported_state` maps setup/call/teardown outcomes, `pytest_sessionfinish` publishes the final tree and requests the trace export. `_SuiteRegistry` builds the tree; `frames.test_stats` / `frames.suite_stats` build the payloads; `capturer.send_suites` wraps each suite in its single-key record. The plain-script tree is `instrumentation.py` `_send_default_suite`.
+
+### 2d. Transport, backend launch, and reruns
+
+**Worker socket.** Open one WebSocket to `ws://<host>:<port>/worker?runId=<id>` (`WS_PATHS.worker`, `WORKER_WS_QUERY.runId` in `shared/src/routes.ts`). The query must be on the upgrade request line, because the backend decides then whether this connect continues the current run (keep accumulated state) or starts a new one (wipe it). Every worker of one run must send the same id: read `DEVTOOLS_RUN_ID` (`RUNNER_ENV.RUN_ID`) and adopt it if present, otherwise generate one and export it before forking workers. Send `reconnect=1` if you reopen the socket mid-run.
+
+Frames you will receive from the backend on that socket:
+
+| Scope | Meaning |
+|---|---|
+| `clientConnected` | A dashboard tab is open. |
+| `clientDisconnected` | The last dashboard tab closed. Python treats this as "shut down". |
+| `traceExported` | Answer to your `traceExport` request, matched on `requestId`. |
+
+The backend handles `clearCommands`, `config` and `screencast` from you itself (a `screencast` frame registers `videoPath` so the UI can fetch the video from `/api/video/:sessionId`), handles `traceExport`, and forwards every other frame to the dashboard tabs while recording it for Preserve & Rerun.
+
+**Backend launch or attach, in this order** (Python's `backend.py` `launch_or_attach`):
+
+1. Reuse handshake set (`DEVTOOLS_APP_REUSE=1` plus `DEVTOOLS_APP_HOST` / `DEVTOOLS_APP_PORT`): attach to that backend. This wins over everything else.
+2. An explicit port configured by the user: attach.
+3. Otherwise spawn `node <backend>/dist/server.js` (or `npx @wdio/devtools-backend@<pinned>`) and read the bound port from its `listening at ...:<port>` log line. The preferred port may be busy, so do not assume it.
+
+**Reuse handshake.** When the dashboard reruns something, the backend spawns your published command in a fresh process with these set (`REUSE_ENV` in `shared/src/runner.ts`):
+
+```
+DEVTOOLS_APP_REUSE=1
+DEVTOOLS_APP_HOST=<backend host>
+DEVTOOLS_APP_PORT=<backend port>
+DEVTOOLS_RERUN_LAUNCH_COMMAND=<the parent's Run-all command, when it had one>
+```
+
+Attach to that backend, do not open a second dashboard window, and when `DEVTOOLS_APP_REUSE=1` republish `DEVTOOLS_RERUN_LAUNCH_COMMAND` as your `launchCommand` rather than deriving it from your own (narrowed) arguments.
+
+**Run controls.** Put these in `metadata.options`:
+
+```json
+{
+  "runCapabilities": {"canRunSuites": true, "canRunTests": true, "canRunAll": true},
+  "launchCommand": "<runs everything>",
+  "rerunCommand": "<runs one entry> {{testId}}"
+}
+```
+
+`{{testId}}` (`RERUN_SLOT.testId`) is replaced with the entry's uid verbatim and shell-quoted; `{{testName}}` is replaced with its label, regex-escaped, for runners that filter by name pattern. Use one or the other. Only advertise a capability you built a command for. Set `DEVTOOLS_RUNNER_CWD` (`RUNNER_ENV.RUNNER_CWD`) to the directory reruns must start in **before** spawning the backend, since the backend reads it from its own environment.
+
+**Pitfall already hit.** An adapter that ignored the reuse handshake launched a second backend and window for every rerun, so the window the user clicked Rerun in never changed (Known debt: "A spawned rerun must be pointed back at the backend that asked for it").
+
+**Python.** `transport.py` `WSClient` (a dependency-free RFC 6455 client; `request_target` adds the run id), `run_id.py` `resolve_run_id` / `reset_run_id`, `backend.py` `reuse_target` and `launch_or_attach`, `rerun.py` (`configure_script`, `configure_pytest`, `_inherited_launch`, `_publish`, `_stamp_runner_cwd`), `lifecycle.py` `on_control`. `__init__.py` `enable()` shows the order: configure rerun commands, launch or attach, connect, install instrumentation.
+
+**Trace mode.** If your adapter offers trace archives, send any `screencastFrames` and `actionSnapshots` first (in batches), then `traceExport` with `{requestId, outputDir, sessionId, tracePolicy?, traceGranularity?}`, and wait for `traceExported` on the reader side. Never let a failed export fail the run. Python: `trace_export.py` (`send_frames`, `send_action_snapshots`, `export`, `on_result`) driven by `__init__.py` `export_trace`.
+
+## 3. The wire contract
+
+### Frames you send
+
+| Scope | `data` | When |
+|---|---|---|
+| `metadata` | `Metadata` (`type`, `sessionId`, `capabilities`, `runner`, `options`, `viewport?`, `url?`) | Once per WebDriver session, **before** its first `commands` frame. |
+| `commands` | `CommandLog[]` | One per command, at completion. |
+| `replaceCommand` | `{oldTimestamp, command}` | To update a row already sent. |
+| `mutations` | `TraceMutation[]` | Each collector drain. |
+| `suites` | `[{uid: SuiteStats}]` | Whenever the tree changes. |
+| `consoleLogs` / `networkRequests` | `ConsoleLog[]` / `NetworkRequest[]` | From BiDi `log.entryAdded` / `network.*` events, if you capture them. |
+| `sources` | `{absolutePath: fileText}` | Once per file a `callSource` (`path:line`) points at. |
+| `screencast` | `ScreencastInfo` (`sessionId`, `videoPath`, ...) | After you encode a session video. |
+| `screencastFrames`, `actionSnapshots`, `traceExport` | see `trace-export.ts` | Trace mode only. |
+
+`metadata.runner` must be a `TestRunnerId` (`TEST_RUNNER_IDS` in `shared/src/types.ts`). It selects the locator dialect for element scripts and how the backend treats the run. A protocol-level adapter currently reports `selenium-webdriver`; a new runner id is a `shared` change.
+
+All times are epoch milliseconds except the suite/test `start`/`end` ISO strings. The shape of a row as Python's `frames.command_log` builds it (values illustrative):
+
+```json
+{"scope": "commands", "data": [{
+  "command": "clickElement", "args": [{"id": "f.93A1"}], "result": null,
+  "timestamp": 1760000000412, "startTime": 1760000000398, "id": 5,
+  "callSource": "/abs/path/test_login.py:22",
+  "selector": "button[type=\"submit\"]", "testUid": "test_login.py::test_valid"
+}]}
+```
+
+### Generating your types
+
+`packages/shared/wire-schema.json` is a JSON Schema (draft 2020-12) generated from shared's TypeScript types by `packages/shared/scripts/wire-schema.ts`: one entry per scope under `scopes`, shared shapes under `$defs`. A vitest test (`packages/shared/tests/wire-schema.test.ts`) fails when the committed copy is stale; regenerate with:
+
+```sh
+pnpm --filter @wdio/devtools-shared gen:wire-schema
+```
+
+Generate your language's types from that file and commit the output. `packages/selenium-devtools-py/scripts/gen_contract.py` is the model and does two things:
+
+- `_TypedDictWriter` renders every `$defs` entry as a Python `TypedDict` into `_wire_types.py`.
+- It reads the constants that are not types straight out of `shared/src` (scope names, `WORKER_WS_QUERY.runId`, `RUNNER_ENV.RUN_ID` and `RUNNER_CWD`, `REUSE_ENV`, `RERUN_SLOT.testId`, `COLLECTOR_API`, `ELEMENT_SCRIPTS_API`, `TRACE_EXPORT_SCOPE`, `TEST_RUNNER_IDS`) into `_contract.py`, and **fails generation** if one the adapter depends on has disappeared. A renamed scope is otherwise silent: the frame is delivered and dropped.
+
+CI runs the generator and then `git diff --exit-code` on both outputs (`.github/actions/python-package/action.yml`), so a `shared` change that alters the contract turns the adapter's job red. Do the same for your language. Note that Python's `/worker` path is still a hand-written constant (`constants.py` `WORKER_PATH`), not generated; generate yours.
+
+### Validating what you send
+
+Generated types document the contract but rarely enforce it at runtime. Python's `tests/wire_contract.py` validates every frame against `wire-schema.json` in unit tests: `RecordingTransport.send_json` checks each frame with `violations(scope, data)` (unknown fields, missing required fields, `null` where shared expects absence) and fails the owning test at cleanup. It collects rather than raises because the adapter's senders swallow exceptions, which would hide the violation exactly where it matters. Give your adapter a fake transport that does the same, and use it in every unit test that sends.
+
+## 4. Proving it: the conformance suite
+
+`packages/conformance` runs each adapter, as its own process, through one fixed scenario against a fake W3C WebDriver server, records every frame it sends, and judges the stream with behavioural rules. The same rules apply to every adapter.
+
+### What the harness does
+
+`src/harness.ts` `runScenario(command, args, {env, bidi})`:
+
+1. Starts `FakeWebDriver` (`src/fake-webdriver.ts`) and `RecordingBackend` (`src/recording-backend.ts`).
+2. Spawns your scenario with the **reuse handshake** pointing at the recording backend (`DEVTOOLS_APP_REUSE=1`, `DEVTOOLS_APP_HOST`, `DEVTOOLS_APP_PORT`), so your adapter needs no test-only code path, plus the scenario variables (`SCENARIO_ENV` in `src/constants.ts`):
+
+```
+CONFORMANCE_WEBDRIVER=<fake WebDriver origin>
+CONFORMANCE_LOGIN_URL=<origin>/login
+CONFORMANCE_BROKEN_URL=<origin>/broken
+```
+
+3. Returns the recorded frames, the fake's ground truth (which documents were born and when, which navigations failed), the exit code and the output. The scenario times out after 60 s.
+
+The recording backend accepts only `/worker` upgrades, serves the real collector bundle at `/api/collector` as the real backend does, and stubs `/api/element-scripts`. The fake WebDriver models two pages (`PAGES`), answers `/url`, `/title`, `/element(s)`, element `value`/`click`/`clear`/`text`, `/execute/*`, `/screenshot`, `/window/rect`, and returns `null` for anything else. It returns a BiDi `webSocketUrl` only when the scenario runs with `bidi: true` **and** the new-session request asked for `webSocketUrl: true`; registering a preload (`script.addPreloadScript`) then gives every later document a collector anchored at birth (`src/fake-bidi.ts`).
+
+The fake recognises the collector, not your adapter's way of using it, so inject and drain however your language makes natural:
+
+| A script or its arguments | Fake treats it as |
+|---|---|
+| contain the collector's own source (it assigns `window.wdioTraceCollector`) | an injection, by any mechanism: the current document now has a collector |
+| call `getTraceData()` | a drain; with `captureCurrentDom()` also called, a forced anchor |
+| otherwise read `wdioTraceCollector` | the readiness probe |
+
+### The scenario
+
+Every scenario performs these steps, in this order, with nothing else in between (see `scenarios/python_scenario.py` and `scenarios/selenium.ts`):
+
+1. Enable the adapter (it attaches through the reuse handshake; do not open a UI).
+2. Create a remote session at `CONFORMANCE_WEBDRIVER`.
+3. Navigate to `CONFORMANCE_LOGIN_URL`.
+4. Type `tom` into `#username` and `secret` into `#password` (CSS selectors).
+5. Click `button[type="submit"]` (navigates to `/secure`).
+6. Click `#logout` (navigates back to `/login`).
+7. Navigate to `CONFORMANCE_BROKEN_URL`, which fails with HTTP 500; catch and ignore the error.
+8. Quit the session and disable the adapter. Exit 0.
+
+The browser therefore creates exactly three documents.
+
+### Adding your language
+
+1. Add your id to `AdapterId` in `src/types.ts`.
+2. Add `scenarios/<lang>_scenario.<ext>` performing the steps above. Read the three variables by name (the Python scenario repeats them, since it cannot import `SCENARIO_ENV`).
+3. Add `tests/<lang>.test.ts` mirroring `tests/python.test.ts`: `describe.each([true, false])` over `bidi`, call `runScenario`, then `checkConformance(run.frames, run.truth)`, `judge('<your id>', bidi, violations)`, `writeRunReport({...})`, and assert exit code 0, three documents, no `unexplained` violations and no `stale` gaps. Gate it with `it.skipIf(!ready)` where `ready` is true in CI (`|| Boolean(process.env.CI)`), so only a local machine without your toolchain may skip.
+4. Make sure CI installs your toolchain before `pnpm test` in `.github/workflows/ci.yml` (Python's install step is there).
+
+Run it locally with `pnpm test packages/conformance/tests/<lang>.test.ts`. Vitest only collects `packages/**/tests/**/*.test.ts`.
+
+### The rules
+
+Defined in `src/checker.ts`, names in `RULES` (`src/constants.ts`):
+
+| Rule | What it checks |
+|---|---|
+| `metadata-before-commands` | A `metadata` frame arrives before the first `commands` frame. |
+| `row-stamped-at-completion` | No row has `startTime > timestamp`. |
+| `anchor-carries-birth-time` | Every anchor's `url` and `timestamp` match a document the fake created, at its birth time. |
+| `every-document-anchored` | Every document the fake created has an anchor. |
+| `one-anchor-per-document` | No document has more than one anchor. |
+| `navigation-row-shows-destination` | For each successful navigation row, the latest anchor at or before its `timestamp` is the destination url. |
+| `failed-command-has-error-row` | Every navigation that failed in the browser has a row carrying `error`. |
+| `replace-targets-a-sent-row` | Every `replaceCommand.oldTimestamp` names a row already sent. |
+| `one-row-per-browser-action` | The number of `navigate`, `click` and `fill` rows equals what the fake browser received, after applying `replaceCommand` the way the dashboard does (shared `replaceCommand`: by `id`, then the last row with the old timestamp). |
+| `run-controls-have-a-command` | If `metadata.options.runCapabilities` advertises any control, the metadata carries `launchCommand` or `rerunCommand`. The backend falls back from either to the other and only to the WebdriverIO binary when both are missing, so a control with neither runs the wrong tool. |
+
+Navigation rows are recognised through `mapCommandToAction` (`method: 'navigate'`), with the url taken from a bare string arg or a W3C `{url}` arg, so name your navigation command accordingly.
+
+### Reading a failure
+
+A failing test prints the `unexplained` violations, each `{rule, message, subject?}`, for example `get(http://127.0.0.1:53211/login) at 1760000000412 replays no document` under `navigation-row-shows-destination`. Each run also writes `packages/conformance/out/<adapter>-<bidi|no-bidi>.json` (frames, ground truth, violations, output) and rebuilds `packages/conformance/out/index.html`, a report with each run's documents, anchors and rows on one timeline and the violations placed on the event they concern (`src/report.ts`, `src/report-html.ts`, `src/timeline.ts`). A failing run opens with a "Where to look" block: for each unexplained rule, what it means, its usual cause, and which of the responsibilities in section 2 it tests, linked to that section (`src/rule-guide.ts`). It names no adapter's files: the section says what the responsibility requires, and your adapter's own structure says where it lives. The directory is gitignored; CI uploads it as the `conformance-report` artifact when the job fails. A failing `exitCode` assertion includes the scenario's full output.
+
+### Allowlist entries
+
+`src/allowlist.ts` `KNOWN_GAPS` lists differences an adapter is allowed to show: `{adapter, bidi, rules, reason, timingDependent?}`. An entry is legitimate only for a documented limitation that cannot be fixed in the adapter (for example, the `<script>` fallback without BiDi racing a short-lived document), and `reason` is required: say what happens and point at the Known debt entry. An entry that stops matching is reported as `stale` and fails the run, so a fixed gap forces its own removal; `timingDependent: true` exempts a race that a run can happen to win. Do not allowlist a rule your adapter breaks because it is unfinished.
+
+## 5. Checklist
+
+- [ ] Commands intercepted at the binding's single chokepoint; `startTime` at invocation, `timestamp` at completion; failures produce an `error` row and rethrow.
+- [ ] Command names map through `ACTION_MAP`; optional fields omitted, never `null`.
+- [ ] Internal scripts and screenshots bypass capture.
+- [ ] `metadata` sent once per session before its first command, with `runner` and `options`.
+- [ ] Collector fetched from `/api/collector`; BiDi `webSocketUrl: true` requested; global preload registered before the first navigation and re-registered per new session.
+- [ ] `<script>` fallback when BiDi is absent; drains force the anchor and recover once on `null`; drain after page-moving commands and at session end.
+- [ ] Suite tree sent as single-key records, published early, states updated from setup, call and teardown; `testUid` on every row.
+- [ ] Worker socket at `/worker?runId=...`; run id adopted from or exported to `DEVTOOLS_RUN_ID`.
+- [ ] Reuse handshake attaches first and suppresses a second window; inherited `DEVTOOLS_RERUN_LAUNCH_COMMAND` republished; `DEVTOOLS_RUNNER_CWD` set before spawning the backend.
+- [ ] `launchCommand` / `rerunCommand` published only when serviceable, with `{{testId}}` or `{{testName}}`.
+- [ ] Types and constants generated from `wire-schema.json` and `shared/src`, with a CI drift check.
+- [ ] Unit tests validate every sent frame against the schema.
+- [ ] Conformance scenario and test added, passing with and without BiDi, any allowlist entry carrying a reason.

From bca22d8be1b750bced996a575d2d3abad166dbee Mon Sep 17 00:00:00 2001
From: Vishnu Vardhan <vishnu.p@browserstack.com>
Date: Tue, 13 Oct 2026 12:47:33 +0530
Subject: [PATCH 08/18] test(conformance): compare adapters with each other,
 not only with the rules

The rules only catch what someone thought to write a rule for. Each run
is now reduced to what a dashboard user sees (each step's shared action
name, target, outcome and the page it replays, the pages snapshotted, the
run controls) and compared across adapters within a mode. Any difference
fails as an adapters-agree-on-* rule unless a declared gap explains it,
and a gap explains it only while its holder's own run shows the gap, so
one adapter's known limitation cannot mask another adapter regressing.

To compare runs they have to exist side by side, so adapters are now
registered once in src/adapters.ts and one test runs every registered
adapter in both modes, sequentially, writing the report once at the end.
The two per-adapter test files are gone; they also rebuilt index.html
independently, so one could drop the other's newer run. A scenario that
cannot run becomes a failed report rather than a thrown error.
---
 packages/conformance/src/adapters.ts          |  48 +++++
 packages/conformance/src/agreement.ts         | 114 ++++++++++
 packages/conformance/src/allowlist.ts         |   7 +-
 packages/conformance/src/constants.ts         |   7 +-
 packages/conformance/src/harness.ts           |  44 +++-
 packages/conformance/src/normalize.ts         |  57 +++++
 packages/conformance/src/report.ts            |  22 +-
 packages/conformance/src/rule-guide.ts        |  34 +++
 packages/conformance/src/types.ts             |  37 ++++
 packages/conformance/tests/agreement.test.ts  | 194 ++++++++++++++++++
 .../conformance/tests/conformance.test.ts     |  50 +++++
 packages/conformance/tests/python.test.ts     |  74 -------
 packages/conformance/tests/selenium.test.ts   |  52 -----
 13 files changed, 601 insertions(+), 139 deletions(-)
 create mode 100644 packages/conformance/src/adapters.ts
 create mode 100644 packages/conformance/src/agreement.ts
 create mode 100644 packages/conformance/src/normalize.ts
 create mode 100644 packages/conformance/tests/agreement.test.ts
 create mode 100644 packages/conformance/tests/conformance.test.ts
 delete mode 100644 packages/conformance/tests/python.test.ts
 delete mode 100644 packages/conformance/tests/selenium.test.ts

diff --git a/packages/conformance/src/adapters.ts b/packages/conformance/src/adapters.ts
new file mode 100644
index 00000000..baf6cc2b
--- /dev/null
+++ b/packages/conformance/src/adapters.ts
@@ -0,0 +1,48 @@
+import { spawnSync } from 'node:child_process'
+import { copyFileSync, existsSync, mkdtempSync, rmSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import path from 'node:path'
+
+import { COLLECTOR_BUNDLE, REPO_ROOT } from './constants.js'
+import type { AdapterScenario } from './types.js'
+
+const PYTHON = process.env.CONFORMANCE_PYTHON ?? 'python3'
+const PYTHON_SRC = path.join(REPO_ROOT, 'packages/selenium-devtools-py/src')
+const scenario = (file: string) =>
+  path.join(REPO_ROOT, 'packages/conformance/scenarios', file)
+
+/** Every adapter the suite runs. Adding one is an entry here plus its scenario script. */
+export const ADAPTERS: AdapterScenario[] = [
+  {
+    id: 'selenium-devtools',
+    ready: () =>
+      [
+        path.join(REPO_ROOT, 'packages/selenium-devtools/dist/index.js'),
+        COLLECTOR_BUNDLE
+      ].every((f) => existsSync(f)),
+    prepare: () => ({
+      command: path.join(REPO_ROOT, 'node_modules/.bin/tsx'),
+      args: [scenario('selenium.ts')]
+    })
+  },
+  {
+    id: 'selenium-devtools-py',
+    ready: () =>
+      existsSync(COLLECTOR_BUNDLE) &&
+      spawnSync(PYTHON, ['-c', 'import selenium'], {
+        env: { ...process.env, PYTHONPATH: PYTHON_SRC }
+      }).status === 0,
+    prepare: () => {
+      // Run from a copy: the adapter writes its video beside the script it runs.
+      const dir = mkdtempSync(path.join(tmpdir(), 'conformance-'))
+      const script = path.join(dir, 'python_scenario.py')
+      copyFileSync(scenario('python_scenario.py'), script)
+      return {
+        command: PYTHON,
+        args: [script],
+        env: { PYTHONPATH: PYTHON_SRC },
+        cleanup: () => rmSync(dir, { recursive: true, force: true })
+      }
+    }
+  }
+]
diff --git a/packages/conformance/src/agreement.ts b/packages/conformance/src/agreement.ts
new file mode 100644
index 00000000..1547a234
--- /dev/null
+++ b/packages/conformance/src/agreement.ts
@@ -0,0 +1,114 @@
+import { gapsFor } from './allowlist.js'
+import { RULES } from './constants.js'
+import { normalizeRun } from './normalize.js'
+import type {
+  AdapterId,
+  Divergence,
+  NormalizedRun,
+  NormalizedStep,
+  RuleId,
+  RunReport
+} from './types.js'
+
+/** Every adapter compared against the first, within one mode: no per-behaviour rule is needed to spot a difference. */
+export function compareRuns(runs: RunReport[]): Divergence[] {
+  const [reference, ...others] = [...runs].sort((a, b) =>
+    a.adapter.localeCompare(b.adapter)
+  )
+  if (!reference) {
+    return []
+  }
+  const ref = normalizeRun(reference.frames)
+  return others.flatMap((other) =>
+    compareTwo(
+      [reference.adapter, other.adapter],
+      ref,
+      normalizeRun(other.frames)
+    )
+  )
+}
+
+function compareTwo(
+  adapters: [AdapterId, AdapterId],
+  a: NormalizedRun,
+  b: NormalizedRun
+): Divergence[] {
+  const out: Divergence[] = []
+  const add = (rule: RuleId, message: string) =>
+    out.push({
+      rule,
+      adapters,
+      message: `${adapters.join(' vs ')}: ${message}`
+    })
+  const actionsOf = (r: NormalizedRun) =>
+    r.steps.map((s) => `${s.action} ${s.target}`)
+  const firstDiff = firstDifference(actionsOf(a), actionsOf(b))
+  if (firstDiff !== undefined) {
+    add(RULES.agreeOnActions, describeAt(firstDiff, actionsOf(a), actionsOf(b)))
+  }
+  const aligned = Math.min(firstDiff ?? a.steps.length, b.steps.length)
+  for (let i = 0; i < aligned; i++) {
+    compareStep(i, a.steps[i], b.steps[i], add)
+  }
+  if (firstDifference(a.snapshots, b.snapshots) !== undefined) {
+    add(
+      RULES.agreeOnSnapshots,
+      `snapshots [${a.snapshots.join(', ')}] vs [${b.snapshots.join(', ')}]`
+    )
+  }
+  if (a.runControls !== b.runControls) {
+    add(RULES.agreeOnRunControls, `${a.runControls} vs ${b.runControls}`)
+  }
+  return out
+}
+
+function compareStep(
+  i: number,
+  a: NormalizedStep,
+  b: NormalizedStep,
+  add: (rule: RuleId, message: string) => void
+): void {
+  const where = `step ${i + 1} (${a.action} ${a.target})`
+  if (a.outcome !== b.outcome) {
+    add(RULES.agreeOnErrors, `${where}: ${a.outcome} vs ${b.outcome}`)
+  }
+  if (a.page !== b.page) {
+    add(RULES.agreeOnPages, `${where} shows ${a.page} vs ${b.page}`)
+  }
+}
+
+function firstDifference(a: string[], b: string[]): number | undefined {
+  const length = Math.max(a.length, b.length)
+  for (let i = 0; i < length; i++) {
+    if (a[i] !== b[i]) {
+      return i
+    }
+  }
+  return undefined
+}
+
+function describeAt(i: number, a: string[], b: string[]): string {
+  return `step ${i + 1} is ${a[i] ?? '(nothing)'} vs ${b[i] ?? '(nothing)'} (${a.length} vs ${b.length} steps)`
+}
+
+/** A divergence is explained when either adapter declares a gap for it in this mode. */
+export function judgeDivergences(
+  divergences: Divergence[],
+  runs: RunReport[]
+): { unexplained: Divergence[]; explained: Divergence[] } {
+  // A gap excuses a difference only while it is occurring, i.e. its holder's own run shows it.
+  const occurring = (id: AdapterId) => {
+    const run = runs.find((r) => r.adapter === id)
+    return run
+      ? gapsFor(id, run.bidi).filter((g) =>
+          run.violations.some((v) => g.rules.includes(v.rule))
+        )
+      : []
+  }
+  const explainedBy = (d: Divergence) =>
+    d.adapters.some((id) => occurring(id).some((g) => g.rules.includes(d.rule)))
+  return {
+    unexplained: divergences.filter((d) => !explainedBy(d)),
+    explained: divergences.filter(explainedBy)
+  }
+}
diff --git a/packages/conformance/src/allowlist.ts b/packages/conformance/src/allowlist.ts
index 361f89bd..2e02b4e0 100644
--- a/packages/conformance/src/allowlist.ts
+++ b/packages/conformance/src/allowlist.ts
@@ -4,7 +4,12 @@ export const KNOWN_GAPS: KnownGap[] = [
   {
     adapter: 'selenium-devtools',
     bidi: false,
-    rules: ['every-document-anchored', 'navigation-row-shows-destination'],
+    rules: [
+      'every-document-anchored',
+      'navigation-row-shows-destination',
+      'adapters-agree-on-pages',
+      'adapters-agree-on-snapshots'
+    ],
     reason:
       'Without BiDi the collector is appended as a <script> after a readiness poll, so a document the test leaves within tens of ms is never anchored. CLAUDE.md Known debt: "Document-start injection is what removes the whole race class".',
     timingDependent: true
diff --git a/packages/conformance/src/constants.ts b/packages/conformance/src/constants.ts
index 2c644f2f..532ec556 100644
--- a/packages/conformance/src/constants.ts
+++ b/packages/conformance/src/constants.ts
@@ -24,7 +24,12 @@ export const RULES = {
   errorCarriesBrowserMessage: 'error-row-carries-browser-message',
   replaceTargetsRow: 'replace-targets-a-sent-row',
   rowPerAction: 'one-row-per-browser-action',
-  runControlsHaveCommand: 'run-controls-have-a-command'
+  runControlsHaveCommand: 'run-controls-have-a-command',
+  agreeOnActions: 'adapters-agree-on-actions',
+  agreeOnErrors: 'adapters-agree-on-errors',
+  agreeOnPages: 'adapters-agree-on-pages',
+  agreeOnSnapshots: 'adapters-agree-on-snapshots',
+  agreeOnRunControls: 'adapters-agree-on-run-controls'
 } as const
 
 const GUIDE = 'docs/ADAPTERS.md'
diff --git a/packages/conformance/src/harness.ts b/packages/conformance/src/harness.ts
index cc5c8c77..05541365 100644
--- a/packages/conformance/src/harness.ts
+++ b/packages/conformance/src/harness.ts
@@ -8,9 +8,11 @@ import {
   SCENARIO_ENV,
   SCENARIO_TIMEOUT_MS
 } from './constants.js'
+import { judge } from './allowlist.js'
+import { checkConformance } from './checker.js'
 import { FakeWebDriver } from './fake-webdriver.js'
 import { RecordingBackend } from './recording-backend.js'
-import type { ScenarioRun } from './types.js'
+import type { AdapterScenario, RunReport, ScenarioRun } from './types.js'
 
 /** Runs a scenario process against the fakes, reached through the rerun reuse handshake so no adapter gains a test path. */
 export async function runScenario(
@@ -43,6 +45,46 @@ export async function runScenario(
   }
 }
 
+/** Runs one adapter in one mode and judges its stream; a scenario that cannot run becomes a failed report, not a thrown error. */
+export async function runAdapter(
+  adapter: AdapterScenario,
+  bidi: boolean
+): Promise<RunReport> {
+  const launch = adapter.prepare()
+  try {
+    const run = await runScenario(launch.command, launch.args, {
+      env: launch.env,
+      bidi
+    })
+    const violations = checkConformance(run.frames, run.truth)
+    return {
+      adapter: adapter.id,
+      bidi,
+      ...run,
+      violations,
+      ...judge(adapter.id, bidi, violations)
+    }
+  } catch (err) {
+    return {
+      adapter: adapter.id,
+      bidi,
+      exitCode: null,
+      output: String(err),
+      frames: [],
+      truth: {
+        documents: [],
+        failedNavigations: [],
+        actions: { navigate: 0, click: 0, fill: 0 }
+      },
+      violations: [],
+      unexplained: [],
+      stale: []
+    }
+  } finally {
+    launch.cleanup?.()
+  }
+}
+
 function run(
   command: string,
   args: string[],
diff --git a/packages/conformance/src/normalize.ts b/packages/conformance/src/normalize.ts
new file mode 100644
index 00000000..1cfeb859
--- /dev/null
+++ b/packages/conformance/src/normalize.ts
@@ -0,0 +1,57 @@
+import type { CommandLog, RunnerOptions, Metadata } from '@wdio/devtools-shared'
+import { mapCommandToAction } from '@wdio/devtools-shared'
+
+import { navigationTarget, readStream } from './checker.js'
+import { SCOPES } from './constants.js'
+import type { NormalizedRun, NormalizedStep, WireFrame } from './types.js'
+
+/** A run reduced to what a dashboard user sees: everything an adapter may legitimately vary is dropped. */
+export function normalizeRun(frames: WireFrame[]): NormalizedRun {
+  const { rows, anchors } = readStream(frames)
+  const steps = rows
+    .map((row): NormalizedStep | undefined => {
+      const action = mapCommandToAction(row.command)
+      if (!action) {
+        return undefined
+      }
+      const shown = anchors.filter((a) => a.timestamp <= row.timestamp).at(-1)
+      return {
+        action: `${action.class}.${action.method}`,
+        target: targetOf(row),
+        outcome: row.error ? `error: ${row.error.message.trim()}` : 'ok',
+        page: shown?.url ? pathOf(shown.url) : '(none)'
+      }
+    })
+    .filter((s): s is NormalizedStep => s !== undefined)
+  return {
+    steps,
+    snapshots: anchors.map((a) => pathOf(a.url ?? '')),
+    runControls: runControlsOf(frames)
+  }
+}
+
+// Ports differ per run, so a url compares by its path.
+function pathOf(url: string): string {
+  try {
+    return new URL(url).pathname
+  } catch {
+    return url
+  }
+}
+
+function targetOf(row: CommandLog): string {
+  const url = navigationTarget(row)
+  return url ? pathOf(url) : (row.selector ?? '')
+}
+
+function runControlsOf(frames: WireFrame[]): string {
+  const metadata = frames.find((f) => f.scope === SCOPES.metadata)
+  const options = (metadata?.data as Metadata | undefined)?.options as
+    RunnerOptions | undefined
+  const advertised = Object.entries(options?.runCapabilities ?? {})
+    .filter(([, on]) => on)
+    .map(([name]) => name)
+    .sort()
+  const command = Boolean(options?.launchCommand || options?.rerunCommand)
+  return `${advertised.join(', ') || 'none'}; ${command ? 'with' : 'without'} a command`
+}
diff --git a/packages/conformance/src/report.ts b/packages/conformance/src/report.ts
index a36268ce..04e19e97 100644
--- a/packages/conformance/src/report.ts
+++ b/packages/conformance/src/report.ts
@@ -5,18 +5,20 @@ import { OUT_DIR, REPORT_INDEX } from './constants.js'
 import { renderReport } from './report-html.js'
 import type { RunReport } from './types.js'
 
-/** Dumps one run and rebuilds the HTML report; logs instead of throwing, so a report problem never fails a run. */
-export async function writeRunReport(
-  report: RunReport,
+/** Dumps each run and rebuilds the HTML report; logs instead of throwing, so a report problem never fails a run. */
+export async function writeRunReports(
+  reports: RunReport[],
   outDir = OUT_DIR
 ): Promise<void> {
   try {
     await mkdir(outDir, { recursive: true })
-    const name = `${report.adapter}-${report.bidi ? 'bidi' : 'no-bidi'}.json`
-    await writeAtomically(
-      path.join(outDir, name),
-      JSON.stringify(report, null, 2)
-    )
+    for (const report of reports) {
+      const name = `${report.adapter}-${report.bidi ? 'bidi' : 'no-bidi'}.json`
+      await writeAtomically(
+        path.join(outDir, name),
+        JSON.stringify(report, null, 2)
+      )
+    }
     await writeAtomically(
       path.join(outDir, REPORT_INDEX),
       renderReport(await readRunReports(outDir))
@@ -26,14 +28,14 @@ export async function writeRunReport(
   }
 }
 
-// Test files run in parallel workers, so another worker may be reading the dir while this one writes.
+// A reader of the dir (a browser reloading the report) never sees a half-written file.
 async function writeAtomically(file: string, content: string): Promise<void> {
   const tmp = `${file}.${process.pid}.tmp`
   await writeFile(tmp, content)
   await rename(tmp, file)
 }
 
-// Each file was written by writeRunReport, so its shape is RunReport.
+// Each file was written by writeRunReports, so its shape is RunReport.
 async function readRunReports(outDir: string): Promise<RunReport[]> {
   const files = (await readdir(outDir)).filter((f) => f.endsWith('.json'))
   return Promise.all(
diff --git a/packages/conformance/src/rule-guide.ts b/packages/conformance/src/rule-guide.ts
index a8baa52d..0396a4d2 100644
--- a/packages/conformance/src/rule-guide.ts
+++ b/packages/conformance/src/rule-guide.ts
@@ -68,6 +68,40 @@ export const RULE_GUIDE: Record<RuleId, RuleGuide> = {
       'Run capabilities are declared without building launchCommand or rerunCommand. Derive capabilities from the commands that exist.',
     responsibility: 'transport'
   },
+  'adapters-agree-on-actions': {
+    meaning:
+      'For the same scenario, the adapters report a different sequence of user actions.',
+    cause:
+      'One adapter skips, adds or misnames a command; compare the two columns in the agreement table.',
+    responsibility: 'command-interception'
+  },
+  'adapters-agree-on-errors': {
+    meaning:
+      'The same step succeeded in one adapter and failed in another, or failed with different text.',
+    cause:
+      'One adapter reports the error differently: a decorated message, or a failure it never reports.',
+    responsibility: 'command-interception'
+  },
+  'adapters-agree-on-pages': {
+    meaning:
+      'Replaying the same step shows a different page in different adapters.',
+    cause:
+      'One adapter stamps the row at a different moment, or anchors the page at a different time or not at all.',
+    responsibility: 'collector'
+  },
+  'adapters-agree-on-snapshots': {
+    meaning: 'The adapters captured full-page snapshots of different pages.',
+    cause:
+      'One adapter drains or injects the collector at different moments, or does not force the anchor.',
+    responsibility: 'collector'
+  },
+  'adapters-agree-on-run-controls': {
+    meaning:
+      'The adapters offer different Run buttons, or one has no command behind them.',
+    cause:
+      'Run capabilities are declared differently; derive them from the commands each adapter builds.',
+    responsibility: 'transport'
+  },
   'one-row-per-browser-action': {
     meaning:
       'The rows do not match what the browser did: a navigation, click or keystroke is missing or appears twice.',
diff --git a/packages/conformance/src/types.ts b/packages/conformance/src/types.ts
index 919e2b81..c425dea6 100644
--- a/packages/conformance/src/types.ts
+++ b/packages/conformance/src/types.ts
@@ -54,6 +54,43 @@ export interface RecordedStream {
 
 export type AdapterId = 'selenium-devtools' | 'selenium-devtools-py'
 
+/** One user-visible action, as the dashboard would present it. */
+export interface NormalizedStep {
+  /** Shared's action name (`Page.navigate`, `Element.fill`), so adapters' command names compare equal. */
+  action: string
+  target: string
+  outcome: string
+  /** The page a replay of this step shows. */
+  page: string
+}
+
+export interface NormalizedRun {
+  steps: NormalizedStep[]
+  /** The page each DOM anchor belongs to, in order. */
+  snapshots: string[]
+  runControls: string
+}
+
+/** Two adapters told different stories about the same scenario. */
+export interface Divergence extends Violation {
+  adapters: [AdapterId, AdapterId]
+}
+
+/** How the conformance suite launches one adapter's scenario. */
+export interface AdapterScenario {
+  id: AdapterId
+  /** False only locally, when a prerequisite (a build, an interpreter) is missing; CI must not skip. */
+  ready(): boolean
+  prepare(): ScenarioLaunch
+}
+
+export interface ScenarioLaunch {
+  command: string
+  args: string[]
+  env?: NodeJS.ProcessEnv
+  cleanup?: () => void
+}
+
 /** What a broken rule means and where to look, shown beside a failing run. */
 export interface RuleGuide {
   meaning: string
diff --git a/packages/conformance/tests/agreement.test.ts b/packages/conformance/tests/agreement.test.ts
new file mode 100644
index 00000000..490278c6
--- /dev/null
+++ b/packages/conformance/tests/agreement.test.ts
@@ -0,0 +1,194 @@
+import { describe, expect, it } from 'vitest'
+
+import { compareRuns, judgeDivergences } from '../src/agreement.js'
+import { RULES } from '../src/constants.js'
+import { normalizeRun } from '../src/normalize.js'
+import { renderReport } from '../src/report-html.js'
+import type { AdapterId, RunReport, WireFrame } from '../src/types.js'
+
+const anchor = (url: string, timestamp: number) => ({
+  type: 'childList',
+  url,
+  timestamp,
+  addedNodes: [],
+  removedNodes: []
+})
+
+/** One adapter's stream for: navigate to /login, type into #username. */
+function stream(
+  port: number,
+  names: { navigate: string; fill: string },
+  error?: string
+): WireFrame[] {
+  return [
+    {
+      scope: 'metadata',
+      data: {
+        type: 'testrunner',
+        options: { runCapabilities: { canRunAll: true }, launchCommand: 'run' }
+      }
+    },
+    {
+      scope: 'commands',
+      data: [
+        {
+          command: names.navigate,
+          args: [`http://127.0.0.1:${port}/login`],
+          startTime: 0,
+          timestamp: 20
+        },
+        {
+          command: names.fill,
+          args: ['tom'],
+          selector: '#username',
+          startTime: 30,
+          timestamp: 40,
+          ...(error ? { error: { name: 'Error', message: error } } : {})
+        }
+      ]
+    },
+    { scope: 'mutations', data: [anchor(`http://127.0.0.1:${port}/login`, 10)] }
+  ]
+}
+
+const report = (
+  adapter: AdapterId,
+  frames: WireFrame[],
+  bidi = true
+): RunReport => ({
+  adapter,
+  bidi,
+  exitCode: 0,
+  truth: {
+    documents: [],
+    failedNavigations: [],
+    actions: { navigate: 0, click: 0, fill: 0 }
+  },
+  violations: [],
+  unexplained: [],
+  stale: [],
+  frames,
+  output: ''
+})
+
+const JS = { navigate: 'get', fill: 'sendKeys' }
+const PY = { navigate: 'get', fill: 'sendKeysToElement' }
+
+describe('normalizeRun', () => {
+  it("reduces each adapter's command names and ports to what a user sees", () => {
+    expect(normalizeRun(stream(1111, JS))).toEqual(
+      normalizeRun(stream(2222, PY))
+    )
+    expect(normalizeRun(stream(1111, JS)).steps[1]).toEqual({
+      action: 'Element.fill',
+      target: '#username',
+      outcome: 'ok',
+      page: '/login'
+    })
+  })
+})
+
+describe('compareRuns', () => {
+  it('finds nothing when the adapters tell the same story', () => {
+    expect(
+      compareRuns([
+        report('selenium-devtools', stream(1, JS)),
+        report('selenium-devtools-py', stream(2, PY))
+      ])
+    ).toEqual([])
+  })
+
+  it('flags a step that fails with different text, with no rule written for that field', () => {
+    const divergences = compareRuns([
+      report('selenium-devtools', stream(1, JS, 'net::ERR_FAILED')),
+      report('selenium-devtools-py', stream(2, PY, 'Message: net::ERR_FAILED'))
+    ])
+    expect(divergences.map((d) => d.rule)).toEqual([RULES.agreeOnErrors])
+  })
+
+  it('flags a step one adapter never reported', () => {
+    const missing = stream(2, PY)
+    missing[1] = {
+      scope: 'commands',
+      data: (missing[1].data as unknown[]).slice(0, 1)
+    }
+    const divergences = compareRuns([
+      report('selenium-devtools', stream(1, JS)),
+      report('selenium-devtools-py', missing)
+    ])
+    expect(divergences.map((d) => d.rule)).toEqual([RULES.agreeOnActions])
+  })
+
+  it('flags different pages and snapshots', () => {
+    const unanchored = stream(2, PY).filter((f) => f.scope !== 'mutations')
+    const rules = compareRuns([
+      report('selenium-devtools', stream(1, JS)),
+      report('selenium-devtools-py', unanchored)
+    ]).map((d) => d.rule)
+    expect(rules).toEqual([
+      RULES.agreeOnPages,
+      RULES.agreeOnPages,
+      RULES.agreeOnSnapshots
+    ])
+  })
+})
+
+describe('judgeDivergences', () => {
+  const missingAnchor = {
+    rule: RULES.documentAnchored,
+    message: 'document /login has no anchor'
+  }
+
+  it("excuses a difference while the holder's own run shows its gap", () => {
+    const js = {
+      ...report(
+        'selenium-devtools',
+        stream(1, JS).filter((f) => f.scope !== 'mutations'),
+        false
+      ),
+      violations: [missingAnchor]
+    }
+    const py = report('selenium-devtools-py', stream(2, PY), false)
+    const { unexplained } = judgeDivergences(compareRuns([js, py]), [js, py])
+    expect(unexplained).toEqual([])
+  })
+
+  // Regression: a gap excused any matching difference, so it masked the OTHER adapter regressing.
+  it('does not excuse a difference when the gap is not occurring', () => {
+    const js = report('selenium-devtools', stream(1, JS), false)
+    const py = report(
+      'selenium-devtools-py',
+      stream(2, PY).filter((f) => f.scope !== 'mutations'),
+      false
+    )
+    const { unexplained } = judgeDivergences(compareRuns([js, py]), [js, py])
+    expect(unexplained.map((d) => d.rule)).toContain(RULES.agreeOnSnapshots)
+  })
+
+  it('does not excuse a difference in a mode the gap does not cover', () => {
+    const js = {
+      ...report(
+        'selenium-devtools',
+        stream(1, JS).filter((f) => f.scope !== 'mutations'),
+        true
+      ),
+      violations: [missingAnchor]
+    }
+    const py = report('selenium-devtools-py', stream(2, PY), true)
+    const { unexplained } = judgeDivergences(compareRuns([js, py]), [js, py])
+    expect(unexplained).toHaveLength(3)
+  })
+})
+
+describe('the agreement section of the report', () => {
+  it('marks a mode where adapters diverge, and highlights the differing row', () => {
+    const html = renderReport([
+      report('selenium-devtools', stream(1, JS, 'net::ERR_FAILED')),
+      report('selenium-devtools-py', stream(2, PY, 'Message: net::ERR_FAILED'))
+    ])
+    expect(html).toContain('Do the adapters agree?')
+    expect(html).toContain('DIVERGE')
+    expect(html).not.toContain('KNOWN DIFFERENCES')
+    expect(html).toContain('class="differs"')
+  })
+})
diff --git a/packages/conformance/tests/conformance.test.ts b/packages/conformance/tests/conformance.test.ts
new file mode 100644
index 00000000..067c53bd
--- /dev/null
+++ b/packages/conformance/tests/conformance.test.ts
@@ -0,0 +1,50 @@
+import { beforeAll, describe, expect, it } from 'vitest'
+
+import { ADAPTERS } from '../src/adapters.js'
+import { compareRuns, judgeDivergences } from '../src/agreement.js'
+import { runAdapter } from '../src/harness.js'
+import { writeRunReports } from '../src/report.js'
+import type { AdapterId, RunReport } from '../src/types.js'
+
+const MODES = [true, false]
+// Only a local run may skip an adapter whose prerequisites are missing; CI has them all.
+const active = new Set<AdapterId>(
+  ADAPTERS.filter((a) => process.env.CI || a.ready()).map((a) => a.id)
+)
+const reports: RunReport[] = []
+const reportFor = (id: AdapterId, bidi: boolean) =>
+  reports.find((r) => r.adapter === id && r.bidi === bidi)
+
+// Sequential, so one scenario's timing never depends on another sharing the machine.
+beforeAll(async () => {
+  for (const adapter of ADAPTERS.filter((a) => active.has(a.id))) {
+    for (const bidi of MODES) {
+      reports.push(await runAdapter(adapter, bidi))
+    }
+  }
+  await writeRunReports(reports)
+}, 300_000)
+
+describe.each(ADAPTERS.map((a) => a.id))('%s', (id) => {
+  it.skipIf(!active.has(id)).each(MODES)(
+    'follows every rule (bidi: %s)',
+    (bidi) => {
+      const run = reportFor(id, bidi)
+      expect(run?.exitCode, run?.output).toBe(0)
+      expect(run?.truth.documents.length).toBe(3)
+      expect(run?.unexplained).toEqual([])
+      expect(run?.stale, 'a known gap no longer occurs: remove it').toEqual([])
+    }
+  )
+})
+
+describe('adapters agree', () => {
+  it.skipIf(active.size < 2).each(MODES)(
+    'tell the same story for the same scenario (bidi: %s)',
+    (bidi) => {
+      const runs = reports.filter((r) => r.bidi === bidi)
+      const { unexplained } = judgeDivergences(compareRuns(runs), runs)
+      expect(unexplained).toEqual([])
+    }
+  )
+})
diff --git a/packages/conformance/tests/python.test.ts b/packages/conformance/tests/python.test.ts
deleted file mode 100644
index 04bc7728..00000000
--- a/packages/conformance/tests/python.test.ts
+++ /dev/null
@@ -1,74 +0,0 @@
-import { spawnSync } from 'node:child_process'
-import { copyFileSync, existsSync, mkdtempSync, rmSync } from 'node:fs'
-import { tmpdir } from 'node:os'
-import path from 'node:path'
-
-import { afterEach, describe, expect, it } from 'vitest'
-
-import { judge } from '../src/allowlist.js'
-import { checkConformance } from '../src/checker.js'
-import { COLLECTOR_BUNDLE, REPO_ROOT } from '../src/constants.js'
-import { runScenario } from '../src/harness.js'
-import { writeRunReport } from '../src/report.js'
-
-const PYTHON = process.env.CONFORMANCE_PYTHON ?? 'python3'
-const ADAPTER_SRC = path.join(REPO_ROOT, 'packages/selenium-devtools-py/src')
-const SCENARIO = path.join(
-  REPO_ROOT,
-  'packages/conformance/scenarios/python_scenario.py'
-)
-
-// Needs selenium and the built collector; CI has both, so only a local run may skip.
-const ready =
-  (spawnSync(PYTHON, ['-c', 'import selenium'], {
-    env: { ...process.env, PYTHONPATH: ADAPTER_SRC }
-  }).status === 0 &&
-    existsSync(COLLECTOR_BUNDLE)) ||
-  Boolean(process.env.CI)
-
-const scratch: string[] = []
-afterEach(() => {
-  for (const dir of scratch.splice(0)) {
-    rmSync(dir, { recursive: true, force: true })
-  }
-})
-
-describe.each([true, false])(
-  'selenium-devtools-py conformance (bidi: %s)',
-  (bidi) => {
-    it.skipIf(!ready)(
-      'emits a stream that follows every rule',
-      async () => {
-        // Run from a copy: the adapter writes its video beside the script it runs.
-        const dir = mkdtempSync(path.join(tmpdir(), 'conformance-'))
-        scratch.push(dir)
-        const script = path.join(dir, 'python_scenario.py')
-        copyFileSync(SCENARIO, script)
-
-        const run = await runScenario(PYTHON, [script], {
-          env: { PYTHONPATH: ADAPTER_SRC },
-          bidi
-        })
-        const violations = checkConformance(run.frames, run.truth)
-        const { unexplained, stale } = judge(
-          'selenium-devtools-py',
-          bidi,
-          violations
-        )
-        await writeRunReport({
-          adapter: 'selenium-devtools-py',
-          bidi,
-          ...run,
-          violations,
-          unexplained,
-          stale
-        })
-        expect(run.exitCode, run.output).toBe(0)
-        expect(run.truth.documents.length).toBe(3)
-        expect(unexplained).toEqual([])
-        expect(stale, 'a known gap no longer occurs: remove it').toEqual([])
-      },
-      90_000
-    )
-  }
-)
diff --git a/packages/conformance/tests/selenium.test.ts b/packages/conformance/tests/selenium.test.ts
deleted file mode 100644
index 3a8ff9b5..00000000
--- a/packages/conformance/tests/selenium.test.ts
+++ /dev/null
@@ -1,52 +0,0 @@
-import { existsSync } from 'node:fs'
-import path from 'node:path'
-
-import { describe, expect, it } from 'vitest'
-
-import { judge } from '../src/allowlist.js'
-import { checkConformance } from '../src/checker.js'
-import { COLLECTOR_BUNDLE, REPO_ROOT } from '../src/constants.js'
-import { runScenario } from '../src/harness.js'
-import { writeRunReport } from '../src/report.js'
-
-// The scenario runs the built adapter and injects the built collector. CI builds first, so only a local run may skip.
-const ready =
-  [
-    path.join(REPO_ROOT, 'packages/selenium-devtools/dist/index.js'),
-    COLLECTOR_BUNDLE
-  ].every((f) => existsSync(f)) || Boolean(process.env.CI)
-
-describe.each([true, false])(
-  'selenium-devtools conformance (bidi: %s)',
-  (bidi) => {
-    it.skipIf(!ready)(
-      'emits a stream that follows every rule',
-      async () => {
-        const run = await runScenario(
-          path.join(REPO_ROOT, 'node_modules/.bin/tsx'),
-          ['packages/conformance/scenarios/selenium.ts'],
-          { bidi }
-        )
-        const violations = checkConformance(run.frames, run.truth)
-        const { unexplained, stale } = judge(
-          'selenium-devtools',
-          bidi,
-          violations
-        )
-        await writeRunReport({
-          adapter: 'selenium-devtools',
-          bidi,
-          ...run,
-          violations,
-          unexplained,
-          stale
-        })
-        expect(run.exitCode, run.output).toBe(0)
-        expect(run.truth.documents.length).toBe(3)
-        expect(unexplained).toEqual([])
-        expect(stale, 'a known gap no longer occurs: remove it').toEqual([])
-      },
-      90_000
-    )
-  }
-)

From da055732e0de8ebce4b580709556ce8022c66731 Mon Sep 17 00:00:00 2001
From: Vishnu Vardhan <vishnu.p@browserstack.com>
Date: Tue, 13 Oct 2026 12:47:33 +0530
Subject: [PATCH 09/18] test(conformance): show where adapters agree in the
 report

A table per mode, a column per adapter and a row per step, differing rows highlighted, headed AGREE, KNOWN DIFFERENCES (n) or DIVERGE.
---
 packages/conformance/src/report-agreement.ts | 107 +++++++++++++++++++
 packages/conformance/src/report-html.ts      |   8 +-
 2 files changed, 113 insertions(+), 2 deletions(-)
 create mode 100644 packages/conformance/src/report-agreement.ts

diff --git a/packages/conformance/src/report-agreement.ts b/packages/conformance/src/report-agreement.ts
new file mode 100644
index 00000000..d6aa8087
--- /dev/null
+++ b/packages/conformance/src/report-agreement.ts
@@ -0,0 +1,107 @@
+import { gapsFor } from './allowlist.js'
+import { compareRuns, judgeDivergences } from './agreement.js'
+import { normalizeRun } from './normalize.js'
+import type { Divergence, NormalizedStep, RunReport } from './types.js'
+
+type Escape = (text: string) => string
+
+/** One table per mode: a column per adapter, a row per step, differing rows highlighted. */
+export function renderAgreement(runs: RunReport[], escape: Escape): string {
+  const sections = [true, false]
+    .map((bidi) => runs.filter((r) => r.bidi === bidi))
+    .filter((group) => group.length > 1)
+    .map((group) => renderMode(group, escape))
+  return sections.length
+    ? `<h2>Do the adapters agree?</h2>\n${sections.join('\n')}`
+    : ''
+}
+
+function renderMode(runs: RunReport[], escape: Escape): string {
+  const sorted = [...runs].sort((a, b) => a.adapter.localeCompare(b.adapter))
+  const bidi = sorted[0].bidi
+  const normalized = sorted.map((r) => normalizeRun(r.frames))
+  const { unexplained, explained } = judgeDivergences(
+    compareRuns(sorted),
+    sorted
+  )
+  const agree = unexplained.length === 0 && explained.length === 0
+  const length = Math.max(...normalized.map((n) => n.steps.length))
+  const stepRows = Array.from({ length }, (_, i) =>
+    renderRow(
+      `${i + 1}`,
+      normalized.map((n) => describeStep(n.steps[i])),
+      escape
+    )
+  )
+  const footRows = [
+    renderRow(
+      'snapshots',
+      normalized.map((n) => n.snapshots.join(', ') || '(none)'),
+      escape
+    ),
+    renderRow(
+      'run controls',
+      normalized.map((n) => n.runControls),
+      escape
+    )
+  ]
+  return `<details class="run"${agree ? '' : ' open'}>
+<summary><strong>bidi ${bidi ? 'on' : 'off'}</strong>
+${verdictBadge(unexplained.length, explained.length)}
+<span class="counts">${unexplained.length} unexplained, ${explained.length} allowlisted differences</span></summary>
+<div class="body">
+${renderDivergences(unexplained, explained, bidi, escape)}
+<table>
+<thead><tr><th>step</th>${sorted.map((r) => `<th>${escape(r.adapter)}</th>`).join('')}</tr></thead>
+<tbody>
+${[...stepRows, ...footRows].join('\n')}
+</tbody>
+</table>
+</div>
+</details>`
+}
+
+function describeStep(step: NormalizedStep | undefined): string {
+  return step
+    ? `${step.action} ${step.target} → ${step.outcome}, shows ${step.page}`
+    : '(no step)'
+}
+
+function renderRow(label: string, cells: string[], escape: Escape): string {
+  const differs = new Set(cells).size > 1
+  return `<tr${differs ? ' class="differs"' : ''}><td class="t">${escape(label)}</td>${cells
+    .map((c) => `<td><code>${escape(c)}</code></td>`)
+    .join('')}</tr>`
+}
+
+function renderDivergences(
+  unexplained: Divergence[],
+  explained: Divergence[],
+  bidi: boolean,
+  escape: Escape
+): string {
+  const reasonFor = (d: Divergence) =>
+    d.adapters
+      .flatMap((id) => gapsFor(id, bidi))
+      .find((g) => g.rules.includes(d.rule))?.reason ?? ''
+  const items = [
+    ...unexplained.map(
+      (d) =>
+        `<li class="unexplained"><strong>UNEXPLAINED</strong> <code>${escape(d.rule)}</code>: ${escape(d.message)}</li>`
+    ),
+    ...explained.map(
+      (d) =>
+        `<li class="allowed"><strong>allowlisted</strong> <code>${escape(d.rule)}</code>: ${escape(d.message)}<span class="reason">${escape(reasonFor(d))}</span></li>`
+    )
+  ]
+  return items.length ? `<ul class="v">${items.join('')}</ul>` : ''
+}
+
+function verdictBadge(unexplained: number, explained: number): string {
+  if (unexplained) {
+    return '<span class="badge fail">DIVERGE</span>'
+  }
+  return explained
+    ? `<span class="badge known">KNOWN DIFFERENCES (${explained})</span>`
+    : '<span class="badge pass">AGREE</span>'
+}
diff --git a/packages/conformance/src/report-html.ts b/packages/conformance/src/report-html.ts
index 65e923fd..a3a651fd 100644
--- a/packages/conformance/src/report-html.ts
+++ b/packages/conformance/src/report-html.ts
@@ -1,5 +1,6 @@
 import { explainingGap, gapsFor } from './allowlist.js'
 import { RESPONSIBILITIES } from './constants.js'
+import { renderAgreement } from './report-agreement.js'
 import { RULE_GUIDE } from './rule-guide.js'
 import { buildTimeline } from './timeline.js'
 import type { KnownGap, RunReport, TimelineEvent, Violation } from './types.js'
@@ -10,10 +11,12 @@ const STYLE = `
 *{box-sizing:border-box}
 body{margin:0;padding:16px;background:var(--bg);color:var(--fg);font:14px/1.45 system-ui,sans-serif}
 h1{font-size:20px;margin:0 0 16px}
+h2{font-size:16px;margin:20px 0 10px}
+tr.differs td{background:color-mix(in srgb,var(--fail) 14%,transparent)}
 details.run{border:1px solid var(--line);border-radius:6px;margin:0 0 16px;background:var(--bg)}
 details.run>summary{cursor:pointer;padding:10px 12px;background:var(--panel);border-radius:6px;display:flex;flex-wrap:wrap;gap:12px;align-items:baseline}
 .badge{font-weight:700;padding:1px 8px;border-radius:4px;border:1px solid currentColor}
-.pass{color:var(--pass)}.fail{color:var(--fail)}
+.pass{color:var(--pass)}.fail{color:var(--fail)}.known{color:var(--warn)}
 .counts{color:var(--muted)}
 .body{padding:12px;overflow-x:auto}
 table{border-collapse:collapse;width:100%}
@@ -48,7 +51,8 @@ export function renderReport(runs: RunReport[]): string {
 </head>
 <body>
 <h1>Conformance report</h1>
-${sorted.length ? sorted.map(renderRun).join('\n') : '<p>No runs recorded.</p>'}
+${renderAgreement(sorted, escapeHtml)}
+${sorted.length ? `<h2>Each adapter against the rules</h2>\n${sorted.map(renderRun).join('\n')}` : '<p>No runs recorded.</p>'}
 </body>
 </html>
 `

From 7803f266941ba30b6e430136d6d4cbe7e560aed3 Mon Sep 17 00:00:00 2001
From: Vishnu Vardhan <vishnu.p@browserstack.com>
Date: Tue, 13 Oct 2026 12:47:33 +0530
Subject: [PATCH 10/18] docs: describe cross-adapter agreement and the adapter
 registry

---
 ARCHITECTURE.md  |  2 ++
 docs/ADAPTERS.md | 10 +++++++---
 2 files changed, 9 insertions(+), 3 deletions(-)

diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md
index 7bc230b2..cd5ce812 100644
--- a/ARCHITECTURE.md
+++ b/ARCHITECTURE.md
@@ -196,6 +196,8 @@ Each scenario runs twice, with and without BiDi. The fake answers the BiDi comma
 
 Every run, passing or failing, dumps its frames, ground truth, violations and scenario output to `packages/conformance/out/<adapter>-<bidi|no-bidi>.json` and rebuilds `out/index.html`, a self-contained page laying each run out as a timeline of documents, command rows and DOM anchors with every violation beside the event it concerns. CI uploads `out/` as the `conformance-report` artifact when the `build` job fails.
 
+Beside the rules, the adapters are compared with each other: each run is reduced to what a dashboard user sees (steps, outcomes, the page each step replays, snapshots, run controls) and any difference between adapters in the same mode fails unless a declared gap explains it. The rules catch every adapter being wrong in the same way; the comparison catches a difference no rule anticipated. Adapters are registered once in `src/adapters.ts`.
+
 Covers `selenium-devtools` and `selenium-devtools-py`. The WDIO service and Nightwatch have no scenario yet. The fake emits no BiDi events, so console and network capture are not checked.
 
 ### `examples/`
diff --git a/docs/ADAPTERS.md b/docs/ADAPTERS.md
index edee3bd4..b91945fd 100644
--- a/docs/ADAPTERS.md
+++ b/docs/ADAPTERS.md
@@ -230,10 +230,10 @@ The browser therefore creates exactly three documents.
 
 1. Add your id to `AdapterId` in `src/types.ts`.
 2. Add `scenarios/<lang>_scenario.<ext>` performing the steps above. Read the three variables by name (the Python scenario repeats them, since it cannot import `SCENARIO_ENV`).
-3. Add `tests/<lang>.test.ts` mirroring `tests/python.test.ts`: `describe.each([true, false])` over `bidi`, call `runScenario`, then `checkConformance(run.frames, run.truth)`, `judge('<your id>', bidi, violations)`, `writeRunReport({...})`, and assert exit code 0, three documents, no `unexplained` violations and no `stale` gaps. Gate it with `it.skipIf(!ready)` where `ready` is true in CI (`|| Boolean(process.env.CI)`), so only a local machine without your toolchain may skip.
+3. Add one entry to `ADAPTERS` in `src/adapters.ts`: `ready()` (your toolchain and build are present) and `prepare()` (the command, args and env that launch your scenario, plus an optional `cleanup`). `tests/conformance.test.ts` then runs your adapter in both modes, holds it to every rule, and compares it with every other adapter. `ready()` may only skip a local run; in CI a missing prerequisite fails.
 4. Make sure CI installs your toolchain before `pnpm test` in `.github/workflows/ci.yml` (Python's install step is there).
 
-Run it locally with `pnpm test packages/conformance/tests/<lang>.test.ts`. Vitest only collects `packages/**/tests/**/*.test.ts`.
+Run it locally with `pnpm test packages/conformance`. Vitest only collects `packages/**/tests/**/*.test.ts`.
 
 ### The rules
 
@@ -252,11 +252,15 @@ Defined in `src/checker.ts`, names in `RULES` (`src/constants.ts`):
 | `one-row-per-browser-action` | The number of `navigate`, `click` and `fill` rows equals what the fake browser received, after applying `replaceCommand` the way the dashboard does (shared `replaceCommand`: by `id`, then the last row with the old timestamp). |
 | `run-controls-have-a-command` | If `metadata.options.runCapabilities` advertises any control, the metadata carries `launchCommand` or `rerunCommand`. The backend falls back from either to the other and only to the WebdriverIO binary when both are missing, so a control with neither runs the wrong tool. |
 
+### Cross-adapter agreement
+
+The rules check each adapter against what the fake browser did. A second check needs no rules: within each mode, every adapter's stream is reduced to what a dashboard user sees (`src/normalize.ts`: each step's shared action name, target, outcome and the page it replays, the pages snapshotted, the run controls offered; timestamps, ids, ports and raw command names dropped) and compared with the others (`src/agreement.ts`). Any difference fails as one of `adapters-agree-on-actions`, `-on-errors`, `-on-pages`, `-on-snapshots` or `-on-run-controls`, unless a gap of either adapter declares it. This is what catches a difference no rule anticipated; the rules catch every adapter being wrong in the same way.
+
 Navigation rows are recognised through `mapCommandToAction` (`method: 'navigate'`), with the url taken from a bare string arg or a W3C `{url}` arg, so name your navigation command accordingly.
 
 ### Reading a failure
 
-A failing test prints the `unexplained` violations, each `{rule, message, subject?}`, for example `get(http://127.0.0.1:53211/login) at 1760000000412 replays no document` under `navigation-row-shows-destination`. Each run also writes `packages/conformance/out/<adapter>-<bidi|no-bidi>.json` (frames, ground truth, violations, output) and rebuilds `packages/conformance/out/index.html`, a report with each run's documents, anchors and rows on one timeline and the violations placed on the event they concern (`src/report.ts`, `src/report-html.ts`, `src/timeline.ts`). A failing run opens with a "Where to look" block: for each unexplained rule, what it means, its usual cause, and which of the responsibilities in section 2 it tests, linked to that section (`src/rule-guide.ts`). It names no adapter's files: the section says what the responsibility requires, and your adapter's own structure says where it lives. The directory is gitignored; CI uploads it as the `conformance-report` artifact when the job fails. A failing `exitCode` assertion includes the scenario's full output.
+A failing test prints the `unexplained` violations, each `{rule, message, subject?}`, for example `get(http://127.0.0.1:53211/login) at 1760000000412 replays no document` under `navigation-row-shows-destination`. Each run also writes `packages/conformance/out/<adapter>-<bidi|no-bidi>.json` (frames, ground truth, violations, output) and rebuilds `packages/conformance/out/index.html`, a report with each run's documents, anchors and rows on one timeline and the violations placed on the event they concern (`src/report.ts`, `src/report-html.ts`, `src/timeline.ts`). The report opens with "Do the adapters agree?": per mode, a column per adapter and a row per step, differing rows highlighted. A failing run opens with a "Where to look" block: for each unexplained rule, what it means, its usual cause, and which of the responsibilities in section 2 it tests, linked to that section (`src/rule-guide.ts`). It names no adapter's files: the section says what the responsibility requires, and your adapter's own structure says where it lives. The directory is gitignored; CI uploads it as the `conformance-report` artifact when the job fails. A failing `exitCode` assertion includes the scenario's full output.
 
 ### Allowlist entries
 

From 5ee1461e3cd96acf02fa5d091c1e8cd1d27d78c4 Mon Sep 17 00:00:00 2001
From: Vishnu Vardhan <vishnu.p@browserstack.com>
Date: Tue, 13 Oct 2026 13:11:02 +0530
Subject: [PATCH 11/18] test(conformance): judge rows and anchors against the
 browser's own clock

A row stamped at invocation passed as long as startTime did not exceed
timestamp, and only navigation rows were held to the page they showed,
so a click or a fill stamped early slipped through. The fake now records
when it completed each action, and the nth row of a kind must end no
earlier than the nth completion of that kind; an equal millisecond is
fine, since a fast command legitimately finishes in the one it started.

An anchor was accepted anywhere between two births; it must now carry its
document's exact birth time, which is what the collector stamps.

A second injection into a document now starts a fresh, unanchored
collector, as the real bundle does, so a duplicate anchor can be modelled
and one-anchor-per-document can actually fire.
---
 packages/conformance/src/checker.ts          | 34 ++++++++----
 packages/conformance/src/fake-webdriver.ts   | 55 ++++++++++++++------
 packages/conformance/src/types.ts            |  4 +-
 packages/conformance/tests/agreement.test.ts |  2 +-
 packages/conformance/tests/checker.test.ts   | 43 +++++++++++++--
 packages/conformance/tests/report.test.ts    |  2 +-
 6 files changed, 109 insertions(+), 31 deletions(-)

diff --git a/packages/conformance/src/checker.ts b/packages/conformance/src/checker.ts
index 00c76ef0..e0b535a9 100644
--- a/packages/conformance/src/checker.ts
+++ b/packages/conformance/src/checker.ts
@@ -23,7 +23,7 @@ export function checkConformance(
   const stream = readStream(frames)
   return [
     ...metadataFirst(stream),
-    ...completionStamp(stream),
+    ...completionStamp(stream, truth),
     ...anchors(stream, truth),
     ...navigationShowsDestination(stream),
     ...failureRecorded(stream, truth),
@@ -71,27 +71,43 @@ function metadataFirst({ frames }: Stream): Violation[] {
   ]
 }
 
-function completionStamp({ rows }: Stream): Violation[] {
-  return rows
+function completionStamp({ rows }: Stream, truth: GroundTruth): Violation[] {
+  const inverted = rows
     .filter((r) => r.startTime !== undefined && r.startTime > r.timestamp)
     .map((r) => ({
       rule: RULES.completionStamp,
       message: `${r.command} ends (${r.timestamp}) before it starts (${r.startTime})`,
       ...rowSubject(r)
     }))
+  // The nth row of an action kind is the nth such action the browser completed; equal ms is fine.
+  const early = ACTION_METHODS.flatMap((method) => {
+    const completions = truth.actions[method]
+    return rows
+      .filter((r) => mapCommandToAction(r.command)?.method === method)
+      .flatMap((r, i) =>
+        i < completions.length && r.timestamp < completions[i]
+          ? [
+              {
+                rule: RULES.completionStamp,
+                message: `${r.command} is stamped ${r.timestamp}, before the browser completed it at ${completions[i]}`,
+                ...rowSubject(r)
+              }
+            ]
+          : []
+      )
+  })
+  return [...inverted, ...early]
 }
 
-// An anchor belongs to the document born after the previous one and no earlier than the anchor.
+// The collector stamps an anchor with its document's own birth time, so a match is exact.
 function anchors(stream: Stream, truth: GroundTruth): Violation[] {
   const counts = truth.documents.map(() => 0)
   const out: Violation[] = []
   for (const anchor of stream.anchors) {
     const at = truth.documents.findIndex(
-      (d, i) =>
-        anchor.timestamp <= d.bornAt &&
-        (i === 0 || anchor.timestamp > truth.documents[i - 1].bornAt)
+      (d) => d.url === anchor.url && d.bornAt === anchor.timestamp
     )
-    if (at === -1 || truth.documents[at].url !== anchor.url) {
+    if (at === -1) {
       out.push({
         rule: RULES.anchorBirthTime,
         message: `anchor for ${anchor.url} at ${anchor.timestamp} matches no document born then`,
@@ -221,7 +237,7 @@ function rowPerAction(stream: Stream, truth: GroundTruth): Violation[] {
     const rows = stream.rows.filter(
       (r) => mapCommandToAction(r.command)?.method === method
     ).length
-    const received = truth.actions[method]
+    const received = truth.actions[method].length
     return rows === received
       ? []
       : [
diff --git a/packages/conformance/src/fake-webdriver.ts b/packages/conformance/src/fake-webdriver.ts
index e1e66e3a..0af185dc 100644
--- a/packages/conformance/src/fake-webdriver.ts
+++ b/packages/conformance/src/fake-webdriver.ts
@@ -37,7 +37,8 @@ interface Element {
   document: Document
 }
 
-type Reply = { status?: number; value: unknown }
+/** `action` marks a user action, stamped as completed when its response is sent. */
+type Reply = { status?: number; value: unknown; action?: ActionMethod }
 
 const sleep = (ms: number) => new Promise((r) => setTimeout(r, ms))
 
@@ -58,7 +59,11 @@ export class FakeWebDriver {
   #preloaded = false
   #documents: Document[] = []
   #failedNavigations: FailedNavigation[] = []
-  #actions: Record<ActionMethod, number> = { navigate: 0, click: 0, fill: 0 }
+  #actions: Record<ActionMethod, number[]> = {
+    navigate: [],
+    click: [],
+    fill: []
+  }
   #elements = new Map<string, Element>()
 
   private constructor(server: Server, bidi: boolean) {
@@ -90,7 +95,11 @@ export class FakeWebDriver {
     return {
       documents: this.#documents.map(({ url, bornAt }) => ({ url, bornAt })),
       failedNavigations: [...this.#failedNavigations],
-      actions: { ...this.#actions }
+      actions: {
+        navigate: [...this.#actions.navigate],
+        click: [...this.#actions.click],
+        fill: [...this.#actions.fill]
+      }
     }
   }
 
@@ -116,16 +125,18 @@ export class FakeWebDriver {
     const params = body ? (JSON.parse(body) as Record<string, unknown>) : {}
     const path = (req.url ?? '').replace(/^\/session\/[^/]+/, '')
     const reply = await this.#route(req.method ?? 'GET', path, params)
+    if (reply.action) {
+      this.#actions[reply.action].push(Date.now())
+    }
     res.writeHead(reply.status ?? 200, { 'content-type': 'application/json' })
     res.end(JSON.stringify({ value: reply.value }))
   }
 
-  // An endpoint not listed answers null, which every caller reads as "nothing to report".
-  async #route(
+  #session(
     method: string,
     path: string,
     params: Record<string, unknown>
-  ): Promise<Reply> {
+  ): Reply | undefined {
     if (method === 'POST' && path === '/session') {
       const wantsBidi = JSON.stringify(params).includes('"webSocketUrl":true')
       const capabilities: Record<string, unknown> = { browserName: 'chrome' }
@@ -139,9 +150,24 @@ export class FakeWebDriver {
       this.#endBidi()
       return { value: null }
     }
+    return undefined
+  }
+
+  // An endpoint not listed answers null, which every caller reads as "nothing to report".
+  async #route(
+    method: string,
+    path: string,
+    params: Record<string, unknown>
+  ): Promise<Reply> {
+    const session = this.#session(method, path, params)
+    if (session) {
+      return session
+    }
     if (method === 'POST' && path === '/url') {
-      this.#actions.navigate++
-      return this.#navigate(new URL(String(params.url)).pathname)
+      return {
+        ...(await this.#navigate(new URL(String(params.url)).pathname)),
+        action: 'navigate'
+      }
     }
     if (method === 'GET' && path === '/url') {
       return { value: this.#current?.url ?? 'about:blank' }
@@ -236,11 +262,6 @@ export class FakeWebDriver {
         value: { error: 'stale element reference', message: id, stacktrace: '' }
       }
     }
-    if (action === 'value') {
-      this.#actions.fill++
-    } else if (action === 'click') {
-      this.#actions.click++
-    }
     if (action === 'value' && el.document.collector) {
       el.document.buffer.push({
         type: 'attributes',
@@ -252,12 +273,14 @@ export class FakeWebDriver {
         timestamp: Date.now()
       })
     }
+    const kind: ActionMethod | undefined =
+      action === 'value' ? 'fill' : action === 'click' ? 'click' : undefined
     const destination =
       action === 'click' ? PAGES[el.document.path][el.selector] : null
     if (destination) {
-      return this.#navigate(destination)
+      return { ...(await this.#navigate(destination)), action: kind }
     }
-    return { value: action === 'text' ? el.selector : null }
+    return { value: action === 'text' ? el.selector : null, action: kind }
   }
 
   // Recognised by the collector's own API, not by how any one adapter phrases its scripts.
@@ -267,7 +290,9 @@ export class FakeWebDriver {
       return null
     }
     if (COLLECTOR_SIGNATURE.test(script) || COLLECTOR_SIGNATURE.test(args)) {
+      // A fresh collector starts unanchored, as the real one does, so injecting twice can anchor twice.
       doc.collector = true
+      doc.anchored = false
       return true
     }
     if (script.includes('getTraceData')) {
diff --git a/packages/conformance/src/types.ts b/packages/conformance/src/types.ts
index c425dea6..e2602890 100644
--- a/packages/conformance/src/types.ts
+++ b/packages/conformance/src/types.ts
@@ -24,8 +24,8 @@ export interface FailedNavigation {
 export interface GroundTruth {
   documents: BrowserDocument[]
   failedNavigations: FailedNavigation[]
-  /** How many of each user action the browser received, keyed by shared's action method. */
-  actions: Record<ActionMethod, number>
+  /** When the browser completed each user action, in order, keyed by shared's action method. */
+  actions: Record<ActionMethod, number[]>
 }
 
 export type ActionMethod = (typeof ACTION_METHODS)[number]
diff --git a/packages/conformance/tests/agreement.test.ts b/packages/conformance/tests/agreement.test.ts
index 490278c6..55c133e2 100644
--- a/packages/conformance/tests/agreement.test.ts
+++ b/packages/conformance/tests/agreement.test.ts
@@ -62,7 +62,7 @@ const report = (
   truth: {
     documents: [],
     failedNavigations: [],
-    actions: { navigate: 0, click: 0, fill: 0 }
+    actions: { navigate: [], click: [], fill: [] }
   },
   violations: [],
   unexplained: [],
diff --git a/packages/conformance/tests/checker.test.ts b/packages/conformance/tests/checker.test.ts
index 3bdd80f4..e33b4d32 100644
--- a/packages/conformance/tests/checker.test.ts
+++ b/packages/conformance/tests/checker.test.ts
@@ -14,7 +14,7 @@ const truth: GroundTruth = {
     { url: SECURE, bornAt: 300 }
   ],
   failedNavigations: [{ url: BROKEN, message: 'net::ERR_FAILED at /broken' }],
-  actions: { navigate: 3, click: 1, fill: 0 }
+  actions: { navigate: [110, 340, 360], click: [320], fill: [] }
 }
 
 const anchor = (url: string, timestamp: number) => ({
@@ -83,7 +83,12 @@ describe('checkConformance', () => {
   it('flags a navigation stamped at invocation, which replays the previous page', () => {
     const frames = conformingStream()
     frames[5] = { scope: 'commands', data: [row('get', [SECURE], 290, 290)] }
-    expect(rules(frames)).toEqual([RULES.navigationShowsDestination])
+    expect(rules(frames)).toEqual(
+      expect.arrayContaining([
+        RULES.navigationShowsDestination,
+        RULES.completionStamp
+      ])
+    )
   })
 
   it('flags a document that never got an anchor', () => {
@@ -162,7 +167,7 @@ describe('checkConformance', () => {
     ]
     const withTwoMore = {
       ...truth,
-      actions: { navigate: 3, click: 2, fill: 1 }
+      actions: { navigate: [110, 340, 360], click: [320, 420], fill: [420] }
     }
     expect(checkConformance(frames, withTwoMore)).toEqual([])
   })
@@ -213,4 +218,36 @@ describe('checkConformance', () => {
     )
     expect(rules(frames)).toEqual([RULES.errorCarriesBrowserMessage])
   })
+
+  it('flags a click stamped before the browser completed it', () => {
+    const frames = conformingStream()
+    frames[3] = { scope: 'commands', data: [row('click', [], 200, 200)] }
+    expect(rules(frames)).toContain(RULES.completionStamp)
+  })
+
+  it('flags typing stamped before the browser completed it', () => {
+    const frames = [
+      ...conformingStream(),
+      { scope: 'commands', data: [row('sendKeys', ['x'], 400, 400)] }
+    ]
+    const typed = { ...truth, actions: { ...truth.actions, fill: [410] } }
+    expect(checkConformance(frames, typed).map((v) => v.rule)).toEqual([
+      RULES.completionStamp
+    ])
+  })
+
+  it('accepts a row stamped in the same millisecond its action completed', () => {
+    const frames = [
+      ...conformingStream(),
+      { scope: 'commands', data: [row('sendKeys', ['x'], 410, 410)] }
+    ]
+    const typed = { ...truth, actions: { ...truth.actions, fill: [410] } }
+    expect(checkConformance(frames, typed)).toEqual([])
+  })
+
+  it('flags an anchor stamped before its document was born', () => {
+    const frames = conformingStream()
+    frames[2] = { scope: 'mutations', data: [anchor(LOGIN, 99)] }
+    expect(rules(frames)).toContain(RULES.anchorBirthTime)
+  })
 })
diff --git a/packages/conformance/tests/report.test.ts b/packages/conformance/tests/report.test.ts
index 2d102f1b..6989e2c7 100644
--- a/packages/conformance/tests/report.test.ts
+++ b/packages/conformance/tests/report.test.ts
@@ -18,7 +18,7 @@ function run(overrides: Partial<RunReport> = {}): RunReport {
         { url: SECURE, bornAt: 1300 }
       ],
       failedNavigations: [],
-      actions: { navigate: 0, click: 0, fill: 0 }
+      actions: { navigate: [], click: [], fill: [] }
     },
     violations: [],
     unexplained: [],

From 09b93566336b332e7e6d6662101fed77593af3b4 Mon Sep 17 00:00:00 2001
From: Vishnu Vardhan <vishnu.p@browserstack.com>
Date: Tue, 13 Oct 2026 13:11:02 +0530
Subject: [PATCH 12/18] test(conformance): keep a hung scenario's frames, and
 only count a real collector preload

A scenario timeout rejected, so a hung adapter, the bug class this suite
has already caught, lost the frames that showed where it hung. The run is
now killed and reported as failed with everything recorded up to then.

The fake BiDi endpoint counted any script.addPreloadScript as the
collector; it now reads the body and registers only the collector's own
source, so an empty preload no longer produces a passing stream.
---
 packages/conformance/src/fake-bidi.ts    |  13 ++-
 packages/conformance/src/harness.ts      |  45 ++++----
 packages/conformance/tests/fakes.test.ts | 124 +++++++++++++++++++++++
 3 files changed, 159 insertions(+), 23 deletions(-)
 create mode 100644 packages/conformance/tests/fakes.test.ts

diff --git a/packages/conformance/src/fake-bidi.ts b/packages/conformance/src/fake-bidi.ts
index 12cf0394..4529068f 100644
--- a/packages/conformance/src/fake-bidi.ts
+++ b/packages/conformance/src/fake-bidi.ts
@@ -2,14 +2,15 @@ import type { Server } from 'node:http'
 
 import { WebSocketServer, type WebSocket } from 'ws'
 
-import { BIDI_PATH, BIDI_RESULTS } from './constants.js'
+import { BIDI_PATH, BIDI_RESULTS, COLLECTOR_SIGNATURE } from './constants.js'
 
 interface Command {
   id: number
   method: string
+  params?: { functionDeclaration?: string }
 }
 
-/** A BiDi endpoint that acknowledges every command and emits no events; reports a preload registration. */
+/** A BiDi endpoint that acknowledges every command and emits no events; reports when the collector is registered as a preload. */
 export function attachFakeBidi(
   server: Server,
   onPreload: () => void
@@ -32,8 +33,12 @@ export function attachFakeBidi(
 
 function answer(ws: WebSocket, onPreload: () => void): void {
   ws.on('message', (raw) => {
-    const { id, method } = JSON.parse(String(raw)) as Command
-    if (method === 'script.addPreloadScript') {
+    const { id, method, params } = JSON.parse(String(raw)) as Command
+    // Only the collector's own source counts; an unrelated preload instruments nothing.
+    if (
+      method === 'script.addPreloadScript' &&
+      COLLECTOR_SIGNATURE.test(params?.functionDeclaration ?? '')
+    ) {
       onPreload()
     }
     ws.send(
diff --git a/packages/conformance/src/harness.ts b/packages/conformance/src/harness.ts
index 05541365..2a847a0c 100644
--- a/packages/conformance/src/harness.ts
+++ b/packages/conformance/src/harness.ts
@@ -18,21 +18,30 @@ import type { AdapterScenario, RunReport, ScenarioRun } from './types.js'
 export async function runScenario(
   command: string,
   args: string[],
-  { env = {}, bidi }: { env?: NodeJS.ProcessEnv; bidi: boolean }
+  {
+    env = {},
+    bidi,
+    timeoutMs = SCENARIO_TIMEOUT_MS
+  }: { env?: NodeJS.ProcessEnv; bidi: boolean; timeoutMs?: number }
 ): Promise<ScenarioRun> {
   const driver = await FakeWebDriver.start({ bidi })
   const backend = await RecordingBackend.start()
   try {
-    const { exitCode, output } = await run(command, args, {
-      ...process.env,
-      ...env,
-      [REUSE_ENV.REUSE]: '1',
-      [REUSE_ENV.HOST]: backend.host,
-      [REUSE_ENV.PORT]: String(backend.port),
-      [SCENARIO_ENV.webdriver]: driver.origin,
-      [SCENARIO_ENV.login]: driver.url('/login'),
-      [SCENARIO_ENV.broken]: driver.url(BROKEN_PATH)
-    })
+    const { exitCode, output } = await run(
+      command,
+      args,
+      {
+        ...process.env,
+        ...env,
+        [REUSE_ENV.REUSE]: '1',
+        [REUSE_ENV.HOST]: backend.host,
+        [REUSE_ENV.PORT]: String(backend.port),
+        [SCENARIO_ENV.webdriver]: driver.origin,
+        [SCENARIO_ENV.login]: driver.url('/login'),
+        [SCENARIO_ENV.broken]: driver.url(BROKEN_PATH)
+      },
+      timeoutMs
+    )
     return {
       frames: [...backend.frames],
       truth: driver.truth(),
@@ -74,7 +83,7 @@ export async function runAdapter(
       truth: {
         documents: [],
         failedNavigations: [],
-        actions: { navigate: 0, click: 0, fill: 0 }
+        actions: { navigate: [], click: [], fill: [] }
       },
       violations: [],
       unexplained: [],
@@ -88,21 +97,19 @@ export async function runAdapter(
 function run(
   command: string,
   args: string[],
-  env: NodeJS.ProcessEnv
+  env: NodeJS.ProcessEnv,
+  timeoutMs: number
 ): Promise<{ exitCode: number | null; output: string }> {
   return new Promise((resolve, reject) => {
     const child = spawn(command, args, { cwd: REPO_ROOT, env })
     let output = ''
     child.stdout.on('data', (d) => (output += d))
     child.stderr.on('data', (d) => (output += d))
+    // Killed, not rejected: the frames recorded before a hang are the evidence of it.
     const timer = setTimeout(() => {
+      output += `\nscenario timed out after ${timeoutMs} ms`
       child.kill('SIGKILL')
-      reject(
-        new Error(
-          `scenario timed out after ${SCENARIO_TIMEOUT_MS} ms:\n${output}`
-        )
-      )
-    }, SCENARIO_TIMEOUT_MS)
+    }, timeoutMs)
     child.on('error', reject)
     child.on('close', (exitCode) => {
       clearTimeout(timer)
diff --git a/packages/conformance/tests/fakes.test.ts b/packages/conformance/tests/fakes.test.ts
new file mode 100644
index 00000000..3920cb84
--- /dev/null
+++ b/packages/conformance/tests/fakes.test.ts
@@ -0,0 +1,124 @@
+import { afterEach, describe, expect, it } from 'vitest'
+import WebSocket from 'ws'
+
+import { checkConformance } from '../src/checker.js'
+import { RULES } from '../src/constants.js'
+import { FakeWebDriver } from '../src/fake-webdriver.js'
+import { runScenario } from '../src/harness.js'
+import type { WireFrame } from '../src/types.js'
+
+/** The one line every real collector bundle carries: it assigns its global. */
+const COLLECTOR_SOURCE = 'window.wdioTraceCollector = new (class {})()'
+const PROBE = 'return typeof window.wdioTraceCollector !== "undefined";'
+const FORCED_DRAIN =
+  'window.wdioTraceCollector.captureCurrentDom(); return window.wdioTraceCollector.getTraceData();'
+
+const drivers: FakeWebDriver[] = []
+afterEach(async () => {
+  for (const driver of drivers.splice(0)) {
+    await driver.close()
+  }
+})
+
+async function start(bidi: boolean): Promise<FakeWebDriver> {
+  const driver = await FakeWebDriver.start({ bidi })
+  drivers.push(driver)
+  return driver
+}
+
+async function call(
+  driver: FakeWebDriver,
+  method: string,
+  path: string,
+  body?: unknown
+): Promise<unknown> {
+  const res = await fetch(`${driver.origin}${path}`, {
+    method,
+    headers: { 'content-type': 'application/json' },
+    body: body === undefined ? undefined : JSON.stringify(body)
+  })
+  return ((await res.json()) as { value: unknown }).value
+}
+
+const session = (driver: FakeWebDriver) =>
+  call(driver, 'POST', '/session', {
+    capabilities: { alwaysMatch: { webSocketUrl: true } }
+  }) as Promise<{ capabilities: { webSocketUrl?: string } }>
+
+const execute = (driver: FakeWebDriver, script: string) =>
+  call(driver, 'POST', '/session/conformance/execute/sync', {
+    script,
+    args: []
+  })
+
+async function registerPreload(
+  url: string,
+  functionDeclaration: string
+): Promise<void> {
+  const ws = new WebSocket(url)
+  await new Promise((resolve) => ws.once('open', resolve))
+  const answered = new Promise((resolve) => ws.once('message', resolve))
+  ws.send(
+    JSON.stringify({
+      id: 1,
+      method: 'script.addPreloadScript',
+      params: { functionDeclaration }
+    })
+  )
+  await answered
+  ws.close()
+}
+
+describe('the fake BiDi endpoint', () => {
+  // Regression: any preload counted as the collector, so an empty one produced a passing stream.
+  it('registers a collector preload only when the body is the collector', async () => {
+    for (const [body, expected] of [
+      ['() => {}', false],
+      [`async () => { ${COLLECTOR_SOURCE} }`, true]
+    ] as const) {
+      const driver = await start(true)
+      const { capabilities } = await session(driver)
+      await registerPreload(capabilities.webSocketUrl!, body)
+      await call(driver, 'POST', '/session/conformance/url', {
+        url: driver.url('/login')
+      })
+      expect(await execute(driver, PROBE), body).toBe(expected)
+    }
+  })
+})
+
+describe('the fake collector', () => {
+  // Regression: re-injection kept the document anchored, so a duplicate anchor could never be modelled.
+  it('anchors again after a second injection, which one-anchor-per-document flags', async () => {
+    const driver = await start(false)
+    await session(driver)
+    await call(driver, 'POST', '/session/conformance/url', {
+      url: driver.url('/login')
+    })
+    const mutations: unknown[] = []
+    for (let i = 0; i < 2; i++) {
+      await execute(driver, COLLECTOR_SOURCE)
+      const drained = (await execute(driver, FORCED_DRAIN)) as {
+        mutations: unknown[]
+      }
+      mutations.push(...drained.mutations)
+    }
+    const frames: WireFrame[] = [{ scope: 'mutations', data: mutations }]
+    const rules = checkConformance(frames, driver.truth()).map((v) => v.rule)
+    expect(rules).toContain(RULES.anchorOnce)
+  })
+})
+
+describe('the harness', () => {
+  // Regression: a timeout rejected, so a hung adapter lost the frames that showed where it hung.
+  it('reports a hung scenario as a failed run instead of throwing', async () => {
+    const run = await runScenario(
+      process.execPath,
+      ['-e', 'setTimeout(() => {}, 10000)'],
+      { bidi: false, timeoutMs: 200 }
+    )
+    expect(run.exitCode).not.toBe(0)
+    expect(run.output).toContain('timed out')
+    expect(Array.isArray(run.frames)).toBe(true)
+  })
+})

From bb49e1cd7f12fcac9a0a3652a9faeab7e5080a2f Mon Sep 17 00:00:00 2001
From: Vishnu Vardhan <vishnu.p@browserstack.com>
Date: Tue, 13 Oct 2026 13:11:02 +0530
Subject: [PATCH 13/18] docs(adapters): replaceCommand matches by id first,
 then by the old timestamp

---
 docs/ADAPTERS.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/ADAPTERS.md b/docs/ADAPTERS.md
index b91945fd..34f14f40 100644
--- a/docs/ADAPTERS.md
+++ b/docs/ADAPTERS.md
@@ -39,7 +39,7 @@ What an adapter must not do: re-implement the trace transforms, invent scope nam
 - Optional fields are omitted, never sent as `null` (the schema rejects `null` for an optional field).
 - Your own scripts (collector injection, drains, screenshots) must not appear as rows.
 
-To enrich a row after the fact (navigation timings, for example), send `replaceCommand` with `{oldTimestamp, command}`. The backend and app match on `timestamp`, not on `id`, so keep row timestamps distinct.
+To enrich a row after the fact (navigation timings, for example), send `replaceCommand` with `{oldTimestamp, command}`. Preserve the original row's `id`: the backend and app match a numeric `id` first, then fall back to the last row with `oldTimestamp`. If neither matches, they append the replacement as a new row.
 
 **Pitfall already hit.** Two JS adapters stamped `timestamp` with the invocation clock while the page's mutation stream runs on real time, so a fill row replayed an empty field and a navigation row replayed the page it had just left (CLAUDE.md Known debt: "A command row is stamped at COMPLETION").
 

From c1901768cce5a0ed952ad3600f9b78bd4b1a7322 Mon Sep 17 00:00:00 2001
From: Vishnu Vardhan <vishnu.p@browserstack.com>
Date: Tue, 13 Oct 2026 13:32:08 +0530
Subject: [PATCH 14/18] test(conformance): compare what a fill typed, not only
 that it typed

A fill's text is read whatever shape the binding packaged it in (bare, or the W3C text and value payload), so two adapters typing different text no longer compare equal.
---
 packages/conformance/src/normalize.ts        |  19 ++-
 packages/conformance/src/report-agreement.ts |   4 +-
 packages/conformance/tests/agreement.test.ts | 164 ++++++++++++++-----
 3 files changed, 140 insertions(+), 47 deletions(-)

diff --git a/packages/conformance/src/normalize.ts b/packages/conformance/src/normalize.ts
index 1cfeb859..487465d4 100644
--- a/packages/conformance/src/normalize.ts
+++ b/packages/conformance/src/normalize.ts
@@ -18,8 +18,10 @@ export function normalizeRun(frames: WireFrame[]): NormalizedRun {
       return {
         action: `${action.class}.${action.method}`,
         target: targetOf(row),
+        ...(action.method === 'fill' ? { input: inputOf(row) } : {}),
         outcome: row.error ? `error: ${row.error.message.trim()}` : 'ok',
-        page: shown?.url ? pathOf(shown.url) : '(none)'
+        page: shown?.url ? pathOf(shown.url) : '(none)',
+        at: row.timestamp
       }
     })
     .filter((s): s is NormalizedStep => s !== undefined)
@@ -31,7 +33,7 @@ export function normalizeRun(frames: WireFrame[]): NormalizedRun {
 }
 
 // Ports differ per run, so a url compares by its path.
-function pathOf(url: string): string {
+export function pathOf(url: string): string {
   try {
     return new URL(url).pathname
   } catch {
@@ -44,6 +46,19 @@ function targetOf(row: CommandLog): string {
   return url ? pathOf(url) : (row.selector ?? '')
 }
 
+// A fill's text as the binding packaged it: bare, or the W3C `{text}` / `{value: [...]}` payload.
+function inputOf(row: CommandLog): string | undefined {
+  const [arg] = row.args
+  if (typeof arg === 'string') {
+    return arg
+  }
+  const payload = arg as { text?: unknown; value?: unknown } | undefined
+  if (typeof payload?.text === 'string') {
+    return payload.text
+  }
+  return Array.isArray(payload?.value) ? payload.value.join('') : undefined
+}
+
 function runControlsOf(frames: WireFrame[]): string {
   const metadata = frames.find((f) => f.scope === SCOPES.metadata)
   const options = (metadata?.data as Metadata | undefined)?.options as
diff --git a/packages/conformance/src/report-agreement.ts b/packages/conformance/src/report-agreement.ts
index d6aa8087..e03b88e5 100644
--- a/packages/conformance/src/report-agreement.ts
+++ b/packages/conformance/src/report-agreement.ts
@@ -8,7 +8,7 @@ type Escape = (text: string) => string
 /** One table per mode: a column per adapter, a row per step, differing rows highlighted. */
 export function renderAgreement(runs: RunReport[], escape: Escape): string {
   const sections = [true, false]
-    .map((bidi) => runs.filter((r) => r.bidi === bidi))
+    .map((bidi) => runs.filter((r) => r.bidi === bidi && !r.checkerError))
     .filter((group) => group.length > 1)
     .map((group) => renderMode(group, escape))
   return sections.length
@@ -63,7 +63,7 @@ ${[...stepRows, ...footRows].join('\n')}
 
 function describeStep(step: NormalizedStep | undefined): string {
   return step
-    ? `${step.action} ${step.target} → ${step.outcome}, shows ${step.page}`
+    ? `${step.action} ${step.target}${step.input === undefined ? '' : ` ${JSON.stringify(step.input)}`} → ${step.outcome}, shows ${step.page}`
     : '(no step)'
 }
 
diff --git a/packages/conformance/tests/agreement.test.ts b/packages/conformance/tests/agreement.test.ts
index 55c133e2..01ab7095 100644
--- a/packages/conformance/tests/agreement.test.ts
+++ b/packages/conformance/tests/agreement.test.ts
@@ -4,7 +4,12 @@ import { compareRuns, judgeDivergences } from '../src/agreement.js'
 import { RULES } from '../src/constants.js'
 import { normalizeRun } from '../src/normalize.js'
 import { renderReport } from '../src/report-html.js'
-import type { AdapterId, RunReport, WireFrame } from '../src/types.js'
+import type {
+  AdapterId,
+  RunReport,
+  Violation,
+  WireFrame
+} from '../src/types.js'
 
 const anchor = (url: string, timestamp: number) => ({
   type: 'childList',
@@ -14,12 +19,34 @@ const anchor = (url: string, timestamp: number) => ({
   removedNodes: []
 })
 
+interface Dialect {
+  navigate: string
+  fill: string
+  fillArgs: (text: string) => unknown[]
+}
+
+/** JS passes the text bare; Python passes the W3C payload its binding built. */
+const JS: Dialect = { navigate: 'get', fill: 'sendKeys', fillArgs: (t) => [t] }
+const PY: Dialect = {
+  navigate: 'get',
+  fill: 'sendKeysToElement',
+  fillArgs: (t) => [{ text: t, value: [...t], id: 'el-1' }]
+}
+
+interface Variant {
+  error?: string
+  text?: string
+  /** Pages anchored, as [path, timestamp]. */
+  anchors?: [string, number][]
+}
+
 /** One adapter's stream for: navigate to /login, type into #username. */
 function stream(
   port: number,
-  names: { navigate: string; fill: string },
-  error?: string
+  dialect: Dialect,
+  { error, text = 'tom', anchors = [['/login', 10]] }: Variant = {}
 ): WireFrame[] {
+  const url = (path: string) => `http://127.0.0.1:${port}${path}`
   return [
     {
       scope: 'metadata',
@@ -32,14 +59,14 @@ function stream(
       scope: 'commands',
       data: [
         {
-          command: names.navigate,
-          args: [`http://127.0.0.1:${port}/login`],
+          command: dialect.navigate,
+          args: [url('/login')],
           startTime: 0,
           timestamp: 20
         },
         {
-          command: names.fill,
-          args: ['tom'],
+          command: dialect.fill,
+          args: dialect.fillArgs(text),
           selector: '#username',
           startTime: 30,
           timestamp: 40,
@@ -47,14 +74,15 @@ function stream(
         }
       ]
     },
-    { scope: 'mutations', data: [anchor(`http://127.0.0.1:${port}/login`, 10)] }
+    { scope: 'mutations', data: anchors.map(([p, ts]) => anchor(url(p), ts)) }
   ]
 }
 
 const report = (
   adapter: AdapterId,
   frames: WireFrame[],
-  bidi = true
+  bidi = true,
+  violations: Violation[] = []
 ): RunReport => ({
   adapter,
   bidi,
@@ -64,26 +92,41 @@ const report = (
     failedNavigations: [],
     actions: { navigate: [], click: [], fill: [] }
   },
-  violations: [],
+  violations,
   unexplained: [],
   stale: [],
   frames,
   output: ''
 })
 
-const JS = { navigate: 'get', fill: 'sendKeys' }
-const PY = { navigate: 'get', fill: 'sendKeysToElement' }
+/** What the JS no-BiDi gap produces for this stream when nothing is anchored. */
+const wrongPage = (timestamp: number): Violation => ({
+  rule: RULES.rowReplaysPage,
+  message: 'replays no document',
+  subject: { kind: 'row', timestamp }
+})
+const unanchored = (port: number, path: string): Violation => ({
+  rule: RULES.documentAnchored,
+  message: `document ${path} has no anchor`,
+  subject: {
+    kind: 'document',
+    timestamp: 10,
+    url: `http://127.0.0.1:${port}${path}`
+  }
+})
 
 describe('normalizeRun', () => {
-  it("reduces each adapter's command names and ports to what a user sees", () => {
+  it("reduces each adapter's command names, payloads and ports to what a user sees", () => {
     expect(normalizeRun(stream(1111, JS))).toEqual(
       normalizeRun(stream(2222, PY))
     )
     expect(normalizeRun(stream(1111, JS)).steps[1]).toEqual({
       action: 'Element.fill',
       target: '#username',
+      input: 'tom',
       outcome: 'ok',
-      page: '/login'
+      page: '/login',
+      at: 40
     })
   })
 })
@@ -98,10 +141,22 @@ describe('compareRuns', () => {
     ).toEqual([])
   })
 
-  it('flags a step that fails with different text, with no rule written for that field', () => {
+  it('flags a fill whose typed text differs, with no rule written for that field', () => {
+    const divergences = compareRuns([
+      report('selenium-devtools', stream(1, JS)),
+      report('selenium-devtools-py', stream(2, PY, { text: 'wrong' }))
+    ])
+    expect(divergences.map((d) => d.rule)).toEqual([RULES.agreeOnActions])
+    expect(divergences[0].message).toContain('types "tom" vs "wrong"')
+  })
+
+  it('flags a step that fails with different text', () => {
     const divergences = compareRuns([
-      report('selenium-devtools', stream(1, JS, 'net::ERR_FAILED')),
-      report('selenium-devtools-py', stream(2, PY, 'Message: net::ERR_FAILED'))
+      report('selenium-devtools', stream(1, JS, { error: 'net::ERR_FAILED' })),
+      report(
+        'selenium-devtools-py',
+        stream(2, PY, { error: 'Message: net::ERR_FAILED' })
+      )
     ])
     expect(divergences.map((d) => d.rule)).toEqual([RULES.agreeOnErrors])
   })
@@ -120,10 +175,9 @@ describe('compareRuns', () => {
   })
 
   it('flags different pages and snapshots', () => {
-    const unanchored = stream(2, PY).filter((f) => f.scope !== 'mutations')
     const rules = compareRuns([
       report('selenium-devtools', stream(1, JS)),
-      report('selenium-devtools-py', unanchored)
+      report('selenium-devtools-py', stream(2, PY, { anchors: [] }))
     ]).map((d) => d.rule)
     expect(rules).toEqual([
       RULES.agreeOnPages,
@@ -134,31 +188,54 @@ describe('compareRuns', () => {
 })
 
 describe('judgeDivergences', () => {
-  const missingAnchor = {
-    rule: RULES.documentAnchored,
-    message: 'document /login has no anchor'
-  }
+  const jsGap = (port: number) => [
+    wrongPage(20),
+    wrongPage(40),
+    unanchored(port, '/login')
+  ]
 
-  it("excuses a difference while the holder's own run shows its gap", () => {
-    const js = {
-      ...report(
-        'selenium-devtools',
-        stream(1, JS).filter((f) => f.scope !== 'mutations'),
-        false
-      ),
-      violations: [missingAnchor]
-    }
+  it("excuses a difference where the holder's own run shows its gap", () => {
+    const js = report(
+      'selenium-devtools',
+      stream(1, JS, { anchors: [] }),
+      false,
+      jsGap(1)
+    )
     const py = report('selenium-devtools-py', stream(2, PY), false)
     const { unexplained } = judgeDivergences(compareRuns([js, py]), [js, py])
     expect(unexplained).toEqual([])
   })
 
+  // The reviewer's case: JS misses its anchors while Python stamps the fill after a later navigation.
+  it('does not excuse the other adapter being wrong at the same step', () => {
+    const js = report(
+      'selenium-devtools',
+      stream(1, JS, { anchors: [] }),
+      false,
+      [...jsGap(1), unanchored(1, '/secure')]
+    )
+    const py = report(
+      'selenium-devtools-py',
+      stream(2, PY, {
+        anchors: [
+          ['/login', 10],
+          ['/secure', 35]
+        ]
+      }),
+      false,
+      [wrongPage(40)]
+    )
+    const { unexplained } = judgeDivergences(compareRuns([js, py]), [js, py])
+    expect(unexplained.map((d) => d.rule)).toEqual([RULES.agreeOnPages])
+    expect(unexplained[0].message).toContain('step 2')
+  })
+
   // Regression: a gap excused any matching difference, so it masked the OTHER adapter regressing.
   it('does not excuse a difference when the gap is not occurring', () => {
     const js = report('selenium-devtools', stream(1, JS), false)
     const py = report(
       'selenium-devtools-py',
-      stream(2, PY).filter((f) => f.scope !== 'mutations'),
+      stream(2, PY, { anchors: [] }),
       false
     )
     const { unexplained } = judgeDivergences(compareRuns([js, py]), [js, py])
@@ -166,14 +243,12 @@ describe('judgeDivergences', () => {
   })
 
   it('does not excuse a difference in a mode the gap does not cover', () => {
-    const js = {
-      ...report(
-        'selenium-devtools',
-        stream(1, JS).filter((f) => f.scope !== 'mutations'),
-        true
-      ),
-      violations: [missingAnchor]
-    }
+    const js = report(
+      'selenium-devtools',
+      stream(1, JS, { anchors: [] }),
+      true,
+      jsGap(1)
+    )
     const py = report('selenium-devtools-py', stream(2, PY), true)
     const { unexplained } = judgeDivergences(compareRuns([js, py]), [js, py])
     expect(unexplained).toHaveLength(3)
@@ -183,8 +258,11 @@ describe('judgeDivergences', () => {
 describe('the agreement section of the report', () => {
   it('marks a mode where adapters diverge, and highlights the differing row', () => {
     const html = renderReport([
-      report('selenium-devtools', stream(1, JS, 'net::ERR_FAILED')),
-      report('selenium-devtools-py', stream(2, PY, 'Message: net::ERR_FAILED'))
+      report('selenium-devtools', stream(1, JS, { error: 'net::ERR_FAILED' })),
+      report(
+        'selenium-devtools-py',
+        stream(2, PY, { error: 'Message: net::ERR_FAILED' })
+      )
     ])
     expect(html).toContain('Do the adapters agree?')
     expect(html).toContain('DIVERGE')

From 46e186c27cac139c66a3bee6e48a9e5553c7150f Mon Sep 17 00:00:00 2001
From: Vishnu Vardhan <vishnu.p@browserstack.com>
Date: Tue, 13 Oct 2026 13:32:08 +0530
Subject: [PATCH 15/18] test(conformance): scope a gap to the step it occurs
 on, and hold every row to its page

A declared gap excused any matching difference once it was occurring, so
one adapter's known limitation could hide the other adapter being wrong at
the same step. A gap now explains a difference only where the holder's own
run shows the gap on that same step or document and the other adapter's
run is clean there.

For that to be checkable, the page rule covers every action row, not only
navigations: row-replays-its-page requires a navigate, click or fill row to
replay the document the browser was on when that action completed, so a
fill stamped after a later navigation is a finding of its own.
---
 ARCHITECTURE.md                            |   2 +-
 docs/ADAPTERS.md                           |   6 +-
 packages/conformance/src/agreement.ts      | 101 +++++++++++++++++----
 packages/conformance/src/allowlist.ts      |   2 +-
 packages/conformance/src/checker.ts        |  60 ++++++++----
 packages/conformance/src/constants.ts      |   2 +-
 packages/conformance/src/rule-guide.ts     |   6 +-
 packages/conformance/src/types.ts          |  10 ++
 packages/conformance/tests/checker.test.ts |  17 +++-
 9 files changed, 157 insertions(+), 49 deletions(-)

diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md
index cd5ce812..fd718d02 100644
--- a/ARCHITECTURE.md
+++ b/ARCHITECTURE.md
@@ -190,7 +190,7 @@ The DOM-walking scripts run in the page via `browser.execute`, so — like `scri
 
 ### `packages/conformance`: cross-adapter conformance suite
 
-Test-only and never published or bundled. Each adapter runs one scenario (open `/login`, type, submit to `/secure`, log out, then a navigation that fails) as its own process, against a fake W3C WebDriver server that models two pages and records what really happened in the browser: which documents were born and when, and which navigations failed. The adapter reports into a recording backend that stands in for the dashboard, reached through the same reuse handshake a rerun uses, so no adapter gains a code path for being tested. `src/checker.ts` then judges the recorded frame stream against behavioural rules, for example "a navigation row replays the page it navigated to" and "every document gets exactly one anchor at its birth time". Every adapter is checked by the same rules, so a capture fix that lands in one language and not another fails CI.
+Test-only and never published or bundled. Each adapter runs one scenario (open `/login`, type, submit to `/secure`, log out, then a navigation that fails) as its own process, against a fake W3C WebDriver server that models two pages and records what really happened in the browser: which documents were born and when, and which navigations failed. The adapter reports into a recording backend that stands in for the dashboard, reached through the same reuse handshake a rerun uses, so no adapter gains a code path for being tested. `src/checker.ts` then judges the recorded frame stream against behavioural rules, for example "a row replays the page the browser was on when its action completed" and "every document gets exactly one anchor at its birth time". Every adapter is checked by the same rules, so a capture fix that lands in one language and not another fails CI.
 
 Each scenario runs twice, with and without BiDi. The fake answers the BiDi commands the adapters send, and a registered preload puts the collector into every later document from birth, as in Chrome. A difference an adapter is allowed to show lives in `src/allowlist.ts` with a mandatory reason, and an entry that stops matching fails the run, so a closed gap forces its own removal.
 
diff --git a/docs/ADAPTERS.md b/docs/ADAPTERS.md
index 34f14f40..85708611 100644
--- a/docs/ADAPTERS.md
+++ b/docs/ADAPTERS.md
@@ -246,7 +246,7 @@ Defined in `src/checker.ts`, names in `RULES` (`src/constants.ts`):
 | `anchor-carries-birth-time` | Every anchor's `url` and `timestamp` match a document the fake created, at its birth time. |
 | `every-document-anchored` | Every document the fake created has an anchor. |
 | `one-anchor-per-document` | No document has more than one anchor. |
-| `navigation-row-shows-destination` | For each successful navigation row, the latest anchor at or before its `timestamp` is the destination url. |
+| `row-replays-its-page` | For each navigate, click or fill row, the latest anchor at or before its `timestamp` is the document the browser was on when that action completed: a navigation row shows its destination, and a fill stamped after a later navigation is caught. |
 | `failed-command-has-error-row` | Every navigation that failed in the browser has a row carrying `error`. |
 | `replace-targets-a-sent-row` | Every `replaceCommand.oldTimestamp` names a row already sent. |
 | `one-row-per-browser-action` | The number of `navigate`, `click` and `fill` rows equals what the fake browser received, after applying `replaceCommand` the way the dashboard does (shared `replaceCommand`: by `id`, then the last row with the old timestamp). |
@@ -254,13 +254,13 @@ Defined in `src/checker.ts`, names in `RULES` (`src/constants.ts`):
 
 ### Cross-adapter agreement
 
-The rules check each adapter against what the fake browser did. A second check needs no rules: within each mode, every adapter's stream is reduced to what a dashboard user sees (`src/normalize.ts`: each step's shared action name, target, outcome and the page it replays, the pages snapshotted, the run controls offered; timestamps, ids, ports and raw command names dropped) and compared with the others (`src/agreement.ts`). Any difference fails as one of `adapters-agree-on-actions`, `-on-errors`, `-on-pages`, `-on-snapshots` or `-on-run-controls`, unless a gap of either adapter declares it. This is what catches a difference no rule anticipated; the rules catch every adapter being wrong in the same way.
+The rules check each adapter against what the fake browser did. A second check needs no rules: within each mode, every adapter's stream is reduced to what a dashboard user sees (`src/normalize.ts`: each step's shared action name, target, typed text, outcome and the page it replays, the pages snapshotted, the run controls offered; timestamps, ids, ports and raw command names dropped) and compared with the others (`src/agreement.ts`). Any difference fails as one of `adapters-agree-on-actions`, `-on-errors`, `-on-pages`, `-on-snapshots` or `-on-run-controls`, unless a declared gap explains it. A gap explains a difference only where its holder's own run shows the gap on that same step or document and the other adapter's run is clean there, so one adapter's limitation cannot hide a second bug in the other. This is what catches a difference no rule anticipated; the rules catch every adapter being wrong in the same way.
 
 Navigation rows are recognised through `mapCommandToAction` (`method: 'navigate'`), with the url taken from a bare string arg or a W3C `{url}` arg, so name your navigation command accordingly.
 
 ### Reading a failure
 
-A failing test prints the `unexplained` violations, each `{rule, message, subject?}`, for example `get(http://127.0.0.1:53211/login) at 1760000000412 replays no document` under `navigation-row-shows-destination`. Each run also writes `packages/conformance/out/<adapter>-<bidi|no-bidi>.json` (frames, ground truth, violations, output) and rebuilds `packages/conformance/out/index.html`, a report with each run's documents, anchors and rows on one timeline and the violations placed on the event they concern (`src/report.ts`, `src/report-html.ts`, `src/timeline.ts`). The report opens with "Do the adapters agree?": per mode, a column per adapter and a row per step, differing rows highlighted. A failing run opens with a "Where to look" block: for each unexplained rule, what it means, its usual cause, and which of the responsibilities in section 2 it tests, linked to that section (`src/rule-guide.ts`). It names no adapter's files: the section says what the responsibility requires, and your adapter's own structure says where it lives. The directory is gitignored; CI uploads it as the `conformance-report` artifact when the job fails. A failing `exitCode` assertion includes the scenario's full output.
+A failing test prints the `unexplained` violations, each `{rule, message, subject?}`, for example `get(http://127.0.0.1:53211/login) at 1760000000412 replays no document; the browser was on http://127.0.0.1:53211/login` under `row-replays-its-page`. Each run also writes `packages/conformance/out/<adapter>-<bidi|no-bidi>.json` (frames, ground truth, violations, output) and rebuilds `packages/conformance/out/index.html`, a report with each run's documents, anchors and rows on one timeline and the violations placed on the event they concern (`src/report.ts`, `src/report-html.ts`, `src/timeline.ts`). The report opens with "Do the adapters agree?": per mode, a column per adapter and a row per step, differing rows highlighted. A failing run opens with a "Where to look" block: for each unexplained rule, what it means, its usual cause, and which of the responsibilities in section 2 it tests, linked to that section (`src/rule-guide.ts`). It names no adapter's files: the section says what the responsibility requires, and your adapter's own structure says where it lives. The directory is gitignored; CI uploads it as the `conformance-report` artifact when the job fails. A failing `exitCode` assertion includes the scenario's full output.
 
 ### Allowlist entries
 
diff --git a/packages/conformance/src/agreement.ts b/packages/conformance/src/agreement.ts
index 1547a234..3d9e55e4 100644
--- a/packages/conformance/src/agreement.ts
+++ b/packages/conformance/src/agreement.ts
@@ -1,15 +1,18 @@
 import { gapsFor } from './allowlist.js'
 import { RULES } from './constants.js'
-import { normalizeRun } from './normalize.js'
+import { normalizeRun, pathOf } from './normalize.js'
 import type {
   AdapterId,
   Divergence,
   NormalizedRun,
   NormalizedStep,
   RuleId,
-  RunReport
+  RunReport,
+  Violation
 } from './types.js'
 
+type Add = (rule: RuleId, message: string, step?: number) => void
+
 /** Every adapter compared against the first, within one mode: no per-behaviour rule is needed to spot a difference. */
 export function compareRuns(runs: RunReport[]): Divergence[] {
   const [reference, ...others] = [...runs].sort((a, b) =>
@@ -34,17 +37,22 @@ function compareTwo(
   b: NormalizedRun
 ): Divergence[] {
   const out: Divergence[] = []
-  const add = (rule: RuleId, message: string) =>
+  const add: Add = (rule, message, step) =>
     out.push({
       rule,
       adapters,
+      step,
       message: `${adapters.join(' vs ')}: ${message}`
     })
   const actionsOf = (r: NormalizedRun) =>
     r.steps.map((s) => `${s.action} ${s.target}`)
   const firstDiff = firstDifference(actionsOf(a), actionsOf(b))
   if (firstDiff !== undefined) {
-    add(RULES.agreeOnActions, describeAt(firstDiff, actionsOf(a), actionsOf(b)))
+    add(
+      RULES.agreeOnActions,
+      describeAt(firstDiff, actionsOf(a), actionsOf(b)),
+      firstDiff
+    )
   }
   const aligned = Math.min(firstDiff ?? a.steps.length, b.steps.length)
   for (let i = 0; i < aligned; i++) {
@@ -66,14 +74,21 @@ function compareStep(
   i: number,
   a: NormalizedStep,
   b: NormalizedStep,
-  add: (rule: RuleId, message: string) => void
+  add: Add
 ): void {
   const where = `step ${i + 1} (${a.action} ${a.target})`
+  if (a.input !== b.input) {
+    add(
+      RULES.agreeOnActions,
+      `${where} types ${JSON.stringify(a.input)} vs ${JSON.stringify(b.input)}`,
+      i
+    )
+  }
   if (a.outcome !== b.outcome) {
-    add(RULES.agreeOnErrors, `${where}: ${a.outcome} vs ${b.outcome}`)
+    add(RULES.agreeOnErrors, `${where}: ${a.outcome} vs ${b.outcome}`, i)
   }
   if (a.page !== b.page) {
-    add(RULES.agreeOnPages, `${where} shows ${a.page} vs ${b.page}`)
+    add(RULES.agreeOnPages, `${where} shows ${a.page} vs ${b.page}`, i)
   }
 }
 
@@ -91,24 +106,74 @@ function describeAt(i: number, a: string[], b: string[]): string {
   return `step ${i + 1} is ${a[i] ?? '(nothing)'} vs ${b[i] ?? '(nothing)'} (${a.length} vs ${b.length} steps)`
 }
 
-/** A divergence is explained when either adapter declares a gap for it in this mode. */
+/** A divergence is explained only by a gap occurring on that very subject, with the other adapter clean there. */
 export function judgeDivergences(
   divergences: Divergence[],
   runs: RunReport[]
 ): { unexplained: Divergence[]; explained: Divergence[] } {
-  // A gap excuses a difference only while it is occurring, i.e. its holder's own run shows it.
-  const occurring = (id: AdapterId) => {
-    const run = runs.find((r) => r.adapter === id)
-    return run
-      ? gapsFor(id, run.bidi).filter((g) =>
-          run.violations.some((v) => g.rules.includes(v.rule))
-        )
-      : []
-  }
+  const readable = runs.filter((r) => !r.checkerError)
+  const normalized = new Map(
+    readable.map((r) => [r.adapter, normalizeRun(r.frames)] as const)
+  )
   const explainedBy = (d: Divergence) =>
-    d.adapters.some((id) => occurring(id).some((g) => g.rules.includes(d.rule)))
+    d.adapters.some((holder) => {
+      const run = readable.find((r) => r.adapter === holder)
+      const other = readable.find(
+        (r) => r.adapter === d.adapters.find((id) => id !== holder)
+      )
+      return run && other ? gapExplains(d, run, other, normalized) : false
+    })
   return {
     unexplained: divergences.filter((d) => !explainedBy(d)),
     explained: divergences.filter(explainedBy)
   }
 }
+
+// The holder's gap must show on the same step or document, or a second bug in the other adapter would hide behind it.
+function gapExplains(
+  d: Divergence,
+  holder: RunReport,
+  other: RunReport,
+  normalized: Map<AdapterId, NormalizedRun>
+): boolean {
+  const gapRules = new Set(
+    gapsFor(holder.adapter, holder.bidi)
+      .filter((g) => g.rules.includes(d.rule))
+      .flatMap((g) => g.rules)
+  )
+  const shown = holder.violations.filter((v) => gapRules.has(v.rule))
+  if (!shown.length) {
+    return false
+  }
+  const step = d.step
+  if (d.rule === RULES.agreeOnPages && step !== undefined) {
+    const at = (run: RunReport) => normalized.get(run.adapter)?.steps[step]?.at
+    return (
+      shown.some((v) => onRow(v, at(holder))) &&
+      !other.violations.some((v) => onRow(v, at(other)))
+    )
+  }
+  if (d.rule === RULES.agreeOnSnapshots) {
+    const unanchored = shown
+      .filter((v) => v.rule === RULES.documentAnchored)
+      .flatMap((v) => (v.subject?.url ? [pathOf(v.subject.url)] : []))
+    const holderPages = [
+      ...(normalized.get(holder.adapter)?.snapshots ?? []),
+      ...unanchored
+    ].sort()
+    const otherPages = [
+      ...(normalized.get(other.adapter)?.snapshots ?? [])
+    ].sort()
+    return (
+      sameList(holderPages, otherPages) &&
+      !other.violations.some((v) => v.subject?.kind === 'document')
+    )
+  }
+  return true
+}
+
+const onRow = (v: Violation, at: number | undefined) =>
+  at !== undefined && v.subject?.kind === 'row' && v.subject.timestamp === at
+
+const sameList = (a: string[], b: string[]) =>
+  a.length === b.length && a.every((x, i) => x === b[i])
diff --git a/packages/conformance/src/allowlist.ts b/packages/conformance/src/allowlist.ts
index 2e02b4e0..1f4dac5f 100644
--- a/packages/conformance/src/allowlist.ts
+++ b/packages/conformance/src/allowlist.ts
@@ -6,7 +6,7 @@ export const KNOWN_GAPS: KnownGap[] = [
     bidi: false,
     rules: [
       'every-document-anchored',
-      'navigation-row-shows-destination',
+      'row-replays-its-page',
       'adapters-agree-on-pages',
       'adapters-agree-on-snapshots'
     ],
diff --git a/packages/conformance/src/checker.ts b/packages/conformance/src/checker.ts
index e0b535a9..c29a4e3a 100644
--- a/packages/conformance/src/checker.ts
+++ b/packages/conformance/src/checker.ts
@@ -10,6 +10,7 @@ import {
 
 import { ACTION_METHODS, RULES, SCOPES } from './constants.js'
 import type {
+  ActionMethod,
   GroundTruth,
   RecordedStream as Stream,
   Violation,
@@ -25,7 +26,7 @@ export function checkConformance(
     ...metadataFirst(stream),
     ...completionStamp(stream, truth),
     ...anchors(stream, truth),
-    ...navigationShowsDestination(stream),
+    ...rowReplaysPage(stream, truth),
     ...failureRecorded(stream, truth),
     ...replaceTargetsRow(stream),
     ...rowPerAction(stream, truth),
@@ -111,7 +112,11 @@ function anchors(stream: Stream, truth: GroundTruth): Violation[] {
       out.push({
         rule: RULES.anchorBirthTime,
         message: `anchor for ${anchor.url} at ${anchor.timestamp} matches no document born then`,
-        subject: { kind: 'anchor', timestamp: anchor.timestamp }
+        subject: {
+          kind: 'anchor',
+          timestamp: anchor.timestamp,
+          url: anchor.url
+        }
       })
       continue
     }
@@ -122,38 +127,57 @@ function anchors(stream: Stream, truth: GroundTruth): Violation[] {
       out.push({
         rule: RULES.documentAnchored,
         message: `document ${doc.url} born at ${doc.bornAt} has no anchor`,
-        subject: { kind: 'document', timestamp: doc.bornAt }
+        subject: { kind: 'document', timestamp: doc.bornAt, url: doc.url }
       })
     } else if (counts[i] > 1) {
       out.push({
         rule: RULES.anchorOnce,
         message: `document ${doc.url} born at ${doc.bornAt} has ${counts[i]} anchors`,
-        subject: { kind: 'document', timestamp: doc.bornAt }
+        subject: { kind: 'document', timestamp: doc.bornAt, url: doc.url }
       })
     }
   })
   return out
 }
 
-function navigationShowsDestination(stream: Stream): Violation[] {
-  const out: Violation[] = []
-  for (const row of stream.rows) {
-    const target = navigationTarget(row)
-    if (!target || row.error) {
-      continue
+// Every action row replays the document the browser was on when that action completed, not only navigations.
+function rowReplaysPage(stream: Stream, truth: GroundTruth): Violation[] {
+  const seen: Record<ActionMethod, number> = { navigate: 0, click: 0, fill: 0 }
+  return stream.rows.flatMap((row): Violation[] => {
+    const method = actionMethodOf(row)
+    if (!method) {
+      return []
+    }
+    const completed = truth.actions[method][seen[method]++]
+    const current = truth.documents
+      .filter((d) => completed !== undefined && d.bornAt <= completed)
+      .at(-1)
+    // An extra row is rowPerAction's finding, and a row before any document has nothing to replay.
+    if (completed === undefined || !current) {
+      return []
     }
     const shown = stream.anchors
       .filter((a) => a.timestamp <= row.timestamp)
       .at(-1)
-    if (shown?.url !== target) {
-      out.push({
-        rule: RULES.navigationShowsDestination,
-        message: `${row.command}(${target}) at ${row.timestamp} replays ${shown?.url ?? 'no document'}`,
-        ...rowSubject(row)
-      })
+    if (shown?.url === current.url) {
+      return []
     }
-  }
-  return out
+    const target = navigationTarget(row) ?? row.selector ?? ''
+    return [
+      {
+        rule: RULES.rowReplaysPage,
+        message: `${row.command}(${target}) at ${row.timestamp} replays ${shown?.url ?? 'no document'}; the browser was on ${current.url}`,
+        ...rowSubject(row)
+      }
+    ]
+  })
+}
+
+function actionMethodOf(row: CommandLog): ActionMethod | undefined {
+  const method = mapCommandToAction(row.command)?.method
+  return (ACTION_METHODS as readonly string[]).includes(method ?? '')
+    ? (method as ActionMethod)
+    : undefined
 }
 
 function failureRecorded(stream: Stream, truth: GroundTruth): Violation[] {
diff --git a/packages/conformance/src/constants.ts b/packages/conformance/src/constants.ts
index 532ec556..faf980c6 100644
--- a/packages/conformance/src/constants.ts
+++ b/packages/conformance/src/constants.ts
@@ -19,7 +19,7 @@ export const RULES = {
   anchorBirthTime: 'anchor-carries-birth-time',
   documentAnchored: 'every-document-anchored',
   anchorOnce: 'one-anchor-per-document',
-  navigationShowsDestination: 'navigation-row-shows-destination',
+  rowReplaysPage: 'row-replays-its-page',
   failureRecorded: 'failed-command-has-error-row',
   errorCarriesBrowserMessage: 'error-row-carries-browser-message',
   replaceTargetsRow: 'replace-targets-a-sent-row',
diff --git a/packages/conformance/src/rule-guide.ts b/packages/conformance/src/rule-guide.ts
index 0396a4d2..ca25b3ea 100644
--- a/packages/conformance/src/rule-guide.ts
+++ b/packages/conformance/src/rule-guide.ts
@@ -34,11 +34,11 @@ export const RULE_GUIDE: Record<RuleId, RuleGuide> = {
       'The collector was injected twice into one document, resetting its once-per-document guard.',
     responsibility: 'collector'
   },
-  'navigation-row-shows-destination': {
+  'row-replays-its-page': {
     meaning:
-      'Replaying a navigation row shows the page it left, or no page, instead of the page it loaded.',
+      'Replaying a row shows a page other than the one the browser was on when its action completed: the page it left, a later page, or no page at all.',
     cause:
-      'The row is stamped at invocation rather than completion, or the destination was never anchored (check every-document-anchored first).',
+      'The row is stamped at a moment other than its completion, or the page was never anchored (check every-document-anchored first).',
     responsibility: 'command-interception'
   },
   'failed-command-has-error-row': {
diff --git a/packages/conformance/src/types.ts b/packages/conformance/src/types.ts
index e2602890..08ef2fa7 100644
--- a/packages/conformance/src/types.ts
+++ b/packages/conformance/src/types.ts
@@ -36,6 +36,8 @@ export type RuleId = (typeof RULES)[keyof typeof RULES]
 export interface ViolationSubject {
   kind: 'row' | 'anchor' | 'document'
   timestamp: number
+  /** The document or anchor concerned, so a gap can be scoped to it. */
+  url?: string
 }
 
 export interface Violation {
@@ -59,9 +61,13 @@ export interface NormalizedStep {
   /** Shared's action name (`Page.navigate`, `Element.fill`), so adapters' command names compare equal. */
   action: string
   target: string
+  /** The text a fill typed, as the user sees it, whatever shape the binding packaged it in. */
+  input?: string
   outcome: string
   /** The page a replay of this step shows. */
   page: string
+  /** The row's timestamp: never compared, but how a violation on this step is found. */
+  at: number
 }
 
 export interface NormalizedRun {
@@ -74,6 +80,8 @@ export interface NormalizedRun {
 /** Two adapters told different stories about the same scenario. */
 export interface Divergence extends Violation {
   adapters: [AdapterId, AdapterId]
+  /** Index of the step concerned, when the difference is on one step. */
+  step?: number
 }
 
 /** How the conformance suite launches one adapter's scenario. */
@@ -136,6 +144,8 @@ export interface RunReport {
   stale: KnownGap[]
   frames: WireFrame[]
   output: string
+  /** Set when the checker could not read the stream; the frames are kept so the cause can be seen. */
+  checkerError?: string
 }
 
 interface TimelineEventBase {
diff --git a/packages/conformance/tests/checker.test.ts b/packages/conformance/tests/checker.test.ts
index e33b4d32..81a4e9fc 100644
--- a/packages/conformance/tests/checker.test.ts
+++ b/packages/conformance/tests/checker.test.ts
@@ -84,10 +84,7 @@ describe('checkConformance', () => {
     const frames = conformingStream()
     frames[5] = { scope: 'commands', data: [row('get', [SECURE], 290, 290)] }
     expect(rules(frames)).toEqual(
-      expect.arrayContaining([
-        RULES.navigationShowsDestination,
-        RULES.completionStamp
-      ])
+      expect.arrayContaining([RULES.rowReplaysPage, RULES.completionStamp])
     )
   })
 
@@ -250,4 +247,16 @@ describe('checkConformance', () => {
     frames[2] = { scope: 'mutations', data: [anchor(LOGIN, 99)] }
     expect(rules(frames)).toContain(RULES.anchorBirthTime)
   })
+
+  // The reviewer's case: a fill stamped after a later navigation replays that page, with its timestamps consistent.
+  it('flags a row stamped after a later navigation, which replays a page the browser was not on', () => {
+    const frames = [
+      ...conformingStream(),
+      { scope: 'commands', data: [row('sendKeys', ['x'], 240, 310)] }
+    ]
+    const typed = { ...truth, actions: { ...truth.actions, fill: [250] } }
+    expect(checkConformance(frames, typed).map((v) => v.rule)).toEqual([
+      RULES.rowReplaysPage
+    ])
+  })
 })

From 1f74553d8123a00eafe4f46d6785e0ef2d0ad413 Mon Sep 17 00:00:00 2001
From: Vishnu Vardhan <vishnu.p@browserstack.com>
Date: Tue, 13 Oct 2026 13:32:08 +0530
Subject: [PATCH 16/18] test(conformance): keep the recorded run when the
 checker cannot read it

A checker that threw on a malformed frame replaced the recorded frames, ground truth and output with empty values. The run is kept and the checker's error recorded beside it.
---
 packages/conformance/src/harness.ts           | 53 ++++++++++++++-----
 packages/conformance/src/report-html.ts       | 25 +++++++--
 .../conformance/tests/conformance.test.ts     |  6 ++-
 packages/conformance/tests/fakes.test.ts      | 23 +++++++-
 4 files changed, 89 insertions(+), 18 deletions(-)

diff --git a/packages/conformance/src/harness.ts b/packages/conformance/src/harness.ts
index 2a847a0c..dcf3b730 100644
--- a/packages/conformance/src/harness.ts
+++ b/packages/conformance/src/harness.ts
@@ -12,7 +12,12 @@ import { judge } from './allowlist.js'
 import { checkConformance } from './checker.js'
 import { FakeWebDriver } from './fake-webdriver.js'
 import { RecordingBackend } from './recording-backend.js'
-import type { AdapterScenario, RunReport, ScenarioRun } from './types.js'
+import type {
+  AdapterId,
+  AdapterScenario,
+  RunReport,
+  ScenarioRun
+} from './types.js'
 
 /** Runs a scenario process against the fakes, reached through the rerun reuse handshake so no adapter gains a test path. */
 export async function runScenario(
@@ -60,11 +65,19 @@ export async function runAdapter(
   bidi: boolean
 ): Promise<RunReport> {
   const launch = adapter.prepare()
+  let run: ScenarioRun
   try {
-    const run = await runScenario(launch.command, launch.args, {
+    run = await runScenario(launch.command, launch.args, {
       env: launch.env,
       bidi
     })
+  } catch (err) {
+    return unrunReport(adapter.id, bidi, String(err))
+  } finally {
+    launch.cleanup?.()
+  }
+  // A checker that throws on a malformed frame must not take the recorded evidence with it.
+  try {
     const violations = checkConformance(run.frames, run.truth)
     return {
       adapter: adapter.id,
@@ -77,20 +90,34 @@ export async function runAdapter(
     return {
       adapter: adapter.id,
       bidi,
-      exitCode: null,
-      output: String(err),
-      frames: [],
-      truth: {
-        documents: [],
-        failedNavigations: [],
-        actions: { navigate: [], click: [], fill: [] }
-      },
+      ...run,
       violations: [],
       unexplained: [],
-      stale: []
+      stale: [],
+      checkerError: String(err)
     }
-  } finally {
-    launch.cleanup?.()
+  }
+}
+
+function unrunReport(
+  adapter: AdapterId,
+  bidi: boolean,
+  output: string
+): RunReport {
+  return {
+    adapter,
+    bidi,
+    exitCode: null,
+    output,
+    frames: [],
+    truth: {
+      documents: [],
+      failedNavigations: [],
+      actions: { navigate: [], click: [], fill: [] }
+    },
+    violations: [],
+    unexplained: [],
+    stale: []
   }
 }
 
diff --git a/packages/conformance/src/report-html.ts b/packages/conformance/src/report-html.ts
index a3a651fd..208f84da 100644
--- a/packages/conformance/src/report-html.ts
+++ b/packages/conformance/src/report-html.ts
@@ -3,7 +3,13 @@ import { RESPONSIBILITIES } from './constants.js'
 import { renderAgreement } from './report-agreement.js'
 import { RULE_GUIDE } from './rule-guide.js'
 import { buildTimeline } from './timeline.js'
-import type { KnownGap, RunReport, TimelineEvent, Violation } from './types.js'
+import type {
+  KnownGap,
+  RunReport,
+  Timeline,
+  TimelineEvent,
+  Violation
+} from './types.js'
 
 const STYLE = `
 :root{color-scheme:light dark;--bg:#fff;--fg:#1d1f23;--muted:#5f6670;--line:#d9dde3;--panel:#f5f7f9;--pass:#17723a;--fail:#b3261e;--warn:#8a5a00;--doc:#3355aa;--anchor:#6a3fa0}
@@ -60,7 +66,10 @@ ${sorted.length ? `<h2>Each adapter against the rules</h2>\n${sorted.map(renderR
 
 export function runPassed(run: RunReport): boolean {
   return (
-    run.exitCode === 0 && run.unexplained.length === 0 && run.stale.length === 0
+    run.exitCode === 0 &&
+    !run.checkerError &&
+    run.unexplained.length === 0 &&
+    run.stale.length === 0
   )
 }
 
@@ -75,7 +84,7 @@ export function escapeHtml(text: string): string {
 
 function renderRun(run: RunReport): string {
   const passed = runPassed(run)
-  const timeline = buildTimeline(run)
+  const timeline = safeTimeline(run)
   const unexplained = new Set(run.unexplained.map(violationKey))
   const gaps = gapsFor(run.adapter, run.bidi)
   const renderViolations = (violations: Violation[]) =>
@@ -89,6 +98,7 @@ function renderRun(run: RunReport): string {
 <span class="badge ${passed ? 'pass">PASS' : 'fail">FAIL'}</span>
 <span class="counts">exit ${escapeHtml(String(run.exitCode))}, ${timeline.events.length} events, ${run.violations.length} violations, ${run.unexplained.length} unexplained, ${run.stale.length} stale gaps</span></summary>
 <div class="body">
+${run.checkerError ? `<p class="fail"><strong>Checker failed</strong>: ${escapeHtml(run.checkerError)}</p>` : ''}
 ${renderWhereToLook(run)}
 ${timeline.unplaced.length ? `<p>Run-level violations:</p>${renderViolations(timeline.unplaced)}` : ''}
 ${run.stale.map(renderStale).join('\n')}
@@ -103,6 +113,15 @@ ${rows}
 </details>`
 }
 
+// A stream the checker could not read has no timeline; the header, the error and the output still show.
+function safeTimeline(run: RunReport): Timeline {
+  try {
+    return buildTimeline(run)
+  } catch {
+    return { origin: 0, events: [], unplaced: run.violations }
+  }
+}
+
 function renderEvent(
   event: TimelineEvent,
   origin: number,
diff --git a/packages/conformance/tests/conformance.test.ts b/packages/conformance/tests/conformance.test.ts
index 067c53bd..02c912d1 100644
--- a/packages/conformance/tests/conformance.test.ts
+++ b/packages/conformance/tests/conformance.test.ts
@@ -31,6 +31,10 @@ describe.each(ADAPTERS.map((a) => a.id))('%s', (id) => {
     (bidi) => {
       const run = reportFor(id, bidi)
       expect(run?.exitCode, run?.output).toBe(0)
+      expect(
+        run?.checkerError,
+        'the checker could not read this stream'
+      ).toBeUndefined()
       expect(run?.truth.documents.length).toBe(3)
       expect(run?.unexplained).toEqual([])
       expect(run?.stale, 'a known gap no longer occurs: remove it').toEqual([])
@@ -42,7 +46,7 @@ describe('adapters agree', () => {
   it.skipIf(active.size < 2).each(MODES)(
     'tell the same story for the same scenario (bidi: %s)',
     (bidi) => {
-      const runs = reports.filter((r) => r.bidi === bidi)
+      const runs = reports.filter((r) => r.bidi === bidi && !r.checkerError)
       const { unexplained } = judgeDivergences(compareRuns(runs), runs)
       expect(unexplained).toEqual([])
     }
diff --git a/packages/conformance/tests/fakes.test.ts b/packages/conformance/tests/fakes.test.ts
index 3920cb84..56919dcd 100644
--- a/packages/conformance/tests/fakes.test.ts
+++ b/packages/conformance/tests/fakes.test.ts
@@ -1,10 +1,12 @@
 import { afterEach, describe, expect, it } from 'vitest'
 import WebSocket from 'ws'
 
+import { REUSE_ENV, WS_PATHS } from '@wdio/devtools-shared'
+
 import { checkConformance } from '../src/checker.js'
 import { RULES } from '../src/constants.js'
 import { FakeWebDriver } from '../src/fake-webdriver.js'
-import { runScenario } from '../src/harness.js'
+import { runAdapter, runScenario } from '../src/harness.js'
 import type { WireFrame } from '../src/types.js'
 
 /** The one line every real collector bundle carries: it assigns its global. */
@@ -122,3 +124,22 @@ describe('the harness', () => {
     expect(Array.isArray(run.frames)).toBe(true)
   })
 })
+
+describe('runAdapter', () => {
+  // Regression: a checker that threw on a malformed frame replaced the recorded run with empty values.
+  it('keeps the recorded frames when the checker cannot read them', async () => {
+    const script = `const WebSocket = require('ws');
+const ws = new WebSocket('ws://' + process.env.${REUSE_ENV.HOST} + ':' + process.env.${REUSE_ENV.PORT} + '${WS_PATHS.worker}?runId=x');
+ws.on('open', () => ws.send(JSON.stringify({ scope: 'commands', data: {} }), () => ws.close()));`
+    const report = await runAdapter(
+      {
+        id: 'selenium-devtools',
+        ready: () => true,
+        prepare: () => ({ command: process.execPath, args: ['-e', script] })
+      },
+      false
+    )
+    expect(report.checkerError).toBeDefined()
+    expect(report.frames).toEqual([{ scope: 'commands', data: {} }])
+  })
+})

From 98ea0f411380a2548046f274a90cf1594eec2ec1 Mon Sep 17 00:00:00 2001
From: Vishnu Vardhan <vishnu.p@browserstack.com>
Date: Tue, 13 Oct 2026 13:47:54 +0530
Subject: [PATCH 17/18] test(conformance): a navigation row must name the page
 the browser loaded

Generalising the page rule to every action row dropped the check that a navigation's reported url is the document the browser loaded, so two adapters both reporting the wrong destination agreed with each other and with the anchors. It is back as navigation-row-names-its-destination, read off the same row-to-completion mapping.
---
 docs/ADAPTERS.md                           |  1 +
 packages/conformance/src/checker.ts        | 62 ++++++++++++++++------
 packages/conformance/src/constants.ts      |  1 +
 packages/conformance/src/rule-guide.ts     |  7 +++
 packages/conformance/tests/checker.test.ts |  9 ++++
 5 files changed, 65 insertions(+), 15 deletions(-)

diff --git a/docs/ADAPTERS.md b/docs/ADAPTERS.md
index 85708611..ed3110d7 100644
--- a/docs/ADAPTERS.md
+++ b/docs/ADAPTERS.md
@@ -247,6 +247,7 @@ Defined in `src/checker.ts`, names in `RULES` (`src/constants.ts`):
 | `every-document-anchored` | Every document the fake created has an anchor. |
 | `one-anchor-per-document` | No document has more than one anchor. |
 | `row-replays-its-page` | For each navigate, click or fill row, the latest anchor at or before its `timestamp` is the document the browser was on when that action completed: a navigation row shows its destination, and a fill stamped after a later navigation is caught. |
+| `navigation-row-names-its-destination` | A successful navigation row's url (bare, or W3C `{url}`) is the document the browser loaded when it completed. |
 | `failed-command-has-error-row` | Every navigation that failed in the browser has a row carrying `error`. |
 | `replace-targets-a-sent-row` | Every `replaceCommand.oldTimestamp` names a row already sent. |
 | `one-row-per-browser-action` | The number of `navigate`, `click` and `fill` rows equals what the fake browser received, after applying `replaceCommand` the way the dashboard does (shared `replaceCommand`: by `id`, then the last row with the old timestamp). |
diff --git a/packages/conformance/src/checker.ts b/packages/conformance/src/checker.ts
index c29a4e3a..363a3930 100644
--- a/packages/conformance/src/checker.ts
+++ b/packages/conformance/src/checker.ts
@@ -27,6 +27,7 @@ export function checkConformance(
     ...completionStamp(stream, truth),
     ...anchors(stream, truth),
     ...rowReplaysPage(stream, truth),
+    ...navigationNamesDestination(stream, truth),
     ...failureRecorded(stream, truth),
     ...replaceTargetsRow(stream),
     ...rowPerAction(stream, truth),
@@ -142,24 +143,13 @@ function anchors(stream: Stream, truth: GroundTruth): Violation[] {
 
 // Every action row replays the document the browser was on when that action completed, not only navigations.
 function rowReplaysPage(stream: Stream, truth: GroundTruth): Violation[] {
-  const seen: Record<ActionMethod, number> = { navigate: 0, click: 0, fill: 0 }
-  return stream.rows.flatMap((row): Violation[] => {
-    const method = actionMethodOf(row)
-    if (!method) {
-      return []
-    }
-    const completed = truth.actions[method][seen[method]++]
-    const current = truth.documents
-      .filter((d) => completed !== undefined && d.bornAt <= completed)
-      .at(-1)
-    // An extra row is rowPerAction's finding, and a row before any document has nothing to replay.
-    if (completed === undefined || !current) {
-      return []
-    }
+  return completedActions(stream, truth).flatMap(({ row, completed }) => {
+    const current = currentDocumentAt(truth, completed)
     const shown = stream.anchors
       .filter((a) => a.timestamp <= row.timestamp)
       .at(-1)
-    if (shown?.url === current.url) {
+    // A row before any document has nothing to replay.
+    if (!current || shown?.url === current.url) {
       return []
     }
     const target = navigationTarget(row) ?? row.selector ?? ''
@@ -173,6 +163,48 @@ function rowReplaysPage(stream: Stream, truth: GroundTruth): Violation[] {
   })
 }
 
+// The page a successful navigation row names is the one the browser had loaded when it completed.
+function navigationNamesDestination(
+  stream: Stream,
+  truth: GroundTruth
+): Violation[] {
+  return completedActions(stream, truth).flatMap(
+    ({ row, method, completed }) => {
+      const target = navigationTarget(row)
+      const loaded = currentDocumentAt(truth, completed)
+      if (method !== 'navigate' || row.error || !target || !loaded) {
+        return []
+      }
+      return loaded.url === target
+        ? []
+        : [
+            {
+              rule: RULES.navigationNamesDestination,
+              message: `${row.command} names ${target}; the browser loaded ${loaded.url}`,
+              ...rowSubject(row)
+            }
+          ]
+    }
+  )
+}
+
+// The nth row of an action kind is the nth such action the browser completed; an extra row is rowPerAction's finding.
+function completedActions(
+  stream: Stream,
+  truth: GroundTruth
+): Array<{ row: CommandLog; method: ActionMethod; completed: number }> {
+  const seen: Record<ActionMethod, number> = { navigate: 0, click: 0, fill: 0 }
+  return stream.rows.flatMap((row) => {
+    const method = actionMethodOf(row)
+    const completed = method && truth.actions[method][seen[method]++]
+    return method && completed !== undefined ? [{ row, method, completed }] : []
+  })
+}
+
+function currentDocumentAt(truth: GroundTruth, at: number) {
+  return truth.documents.filter((d) => d.bornAt <= at).at(-1)
+}
+
 function actionMethodOf(row: CommandLog): ActionMethod | undefined {
   const method = mapCommandToAction(row.command)?.method
   return (ACTION_METHODS as readonly string[]).includes(method ?? '')
diff --git a/packages/conformance/src/constants.ts b/packages/conformance/src/constants.ts
index faf980c6..e32678ad 100644
--- a/packages/conformance/src/constants.ts
+++ b/packages/conformance/src/constants.ts
@@ -20,6 +20,7 @@ export const RULES = {
   documentAnchored: 'every-document-anchored',
   anchorOnce: 'one-anchor-per-document',
   rowReplaysPage: 'row-replays-its-page',
+  navigationNamesDestination: 'navigation-row-names-its-destination',
   failureRecorded: 'failed-command-has-error-row',
   errorCarriesBrowserMessage: 'error-row-carries-browser-message',
   replaceTargetsRow: 'replace-targets-a-sent-row',
diff --git a/packages/conformance/src/rule-guide.ts b/packages/conformance/src/rule-guide.ts
index ca25b3ea..3b27d66e 100644
--- a/packages/conformance/src/rule-guide.ts
+++ b/packages/conformance/src/rule-guide.ts
@@ -41,6 +41,13 @@ export const RULE_GUIDE: Record<RuleId, RuleGuide> = {
       'The row is stamped at a moment other than its completion, or the page was never anchored (check every-document-anchored first).',
     responsibility: 'command-interception'
   },
+  'navigation-row-names-its-destination': {
+    meaning:
+      'A navigation row names a page other than the one the browser loaded for it.',
+    cause:
+      'The url the row carries is read from the wrong argument, or rewritten by the binding before capture.',
+    responsibility: 'command-interception'
+  },
   'failed-command-has-error-row': {
     meaning:
       'A command failed in the browser, but no row carries the error, so the dashboard shows it as a success or not at all.',
diff --git a/packages/conformance/tests/checker.test.ts b/packages/conformance/tests/checker.test.ts
index 81a4e9fc..7dd657f7 100644
--- a/packages/conformance/tests/checker.test.ts
+++ b/packages/conformance/tests/checker.test.ts
@@ -259,4 +259,13 @@ describe('checkConformance', () => {
       RULES.rowReplaysPage
     ])
   })
+
+  it('flags a navigation row naming a page the browser did not load', () => {
+    const frames = conformingStream()
+    frames[5] = {
+      scope: 'commands',
+      data: [row('get', [{ url: 'http://fake/other' }], 330, 340)]
+    }
+    expect(rules(frames)).toEqual([RULES.navigationNamesDestination])
+  })
 })

From 9485829f28b53a0ab5034265419cb0c27ad980cd Mon Sep 17 00:00:00 2001
From: Vishnu Vardhan <vishnu.p@browserstack.com>
Date: Tue, 13 Oct 2026 13:47:54 +0530
Subject: [PATCH 18/18] test(conformance): refuse a row without the fields the
 rules read

A fill row with args that were not an array passed the checker and then crashed normalisation, which took the whole HTML report down. The checker now reports such a row as a clear error where it reads the stream; the harness keeps the frames beside it and the report renders every other run.
---
 packages/conformance/src/checker.ts        | 39 ++++++++++++++++++----
 packages/conformance/tests/checker.test.ts | 12 +++++++
 packages/conformance/tests/fakes.test.ts   |  2 +-
 packages/conformance/tests/report.test.ts  | 14 ++++++++
 4 files changed, 59 insertions(+), 8 deletions(-)

diff --git a/packages/conformance/src/checker.ts b/packages/conformance/src/checker.ts
index 363a3930..a6acaf38 100644
--- a/packages/conformance/src/checker.ts
+++ b/packages/conformance/src/checker.ts
@@ -35,29 +35,54 @@ export function checkConformance(
   ]
 }
 
-// Frames are cast per scope: each scope's payload shape is shared's contract.
+// The rules read three fields off every row, so a frame that lacks them is reported rather than guessed at.
 export function readStream(frames: WireFrame[]): Stream {
   let rows: CommandLog[] = []
   const anchors: TraceMutation[] = []
-  for (const { scope, data } of frames) {
+  frames.forEach(({ scope, data }, i) => {
     if (scope === SCOPES.commands) {
-      rows.push(...(data as CommandLog[]))
+      rows.push(...rowsOf(data, i))
     } else if (scope === SCOPES.replaceCommand) {
       // The dashboard's own rule, so the rows judged are the rows a user sees.
       const { oldTimestamp, command } = data as ReplaceCommandWsPayload
-      rows = replaceCommand(rows, oldTimestamp, command)
+      rows = replaceCommand(rows, oldTimestamp, rowsOf([command], i)[0])
     } else if (scope === SCOPES.mutations) {
       anchors.push(
-        ...(data as TraceMutation[]).filter(
-          (m) => m.type === 'childList' && m.url !== undefined
+        ...arrayOf(data, i).filter(
+          (m): m is TraceMutation =>
+            (m as TraceMutation).type === 'childList' &&
+            (m as TraceMutation).url !== undefined
         )
       )
     }
-  }
+  })
   anchors.sort((a, b) => a.timestamp - b.timestamp)
   return { frames, rows, anchors }
 }
 
+function arrayOf(data: unknown, frame: number): unknown[] {
+  if (!Array.isArray(data)) {
+    throw new Error(`frame #${frame} carries ${typeof data}, not an array`)
+  }
+  return data
+}
+
+function rowsOf(data: unknown, frame: number): CommandLog[] {
+  const rows = arrayOf(data, frame) as Partial<CommandLog>[]
+  for (const row of rows) {
+    if (
+      typeof row?.command !== 'string' ||
+      !Array.isArray(row.args) ||
+      typeof row.timestamp !== 'number'
+    ) {
+      throw new Error(
+        `commands frame #${frame} carries a row without command, args[] and timestamp: ${JSON.stringify(row).slice(0, 120)}`
+      )
+    }
+  }
+  return rows as CommandLog[]
+}
+
 function metadataFirst({ frames }: Stream): Violation[] {
   const metadata = frames.findIndex((f) => f.scope === SCOPES.metadata)
   const commands = frames.findIndex((f) => f.scope === SCOPES.commands)
diff --git a/packages/conformance/tests/checker.test.ts b/packages/conformance/tests/checker.test.ts
index 7dd657f7..deae4037 100644
--- a/packages/conformance/tests/checker.test.ts
+++ b/packages/conformance/tests/checker.test.ts
@@ -268,4 +268,16 @@ describe('checkConformance', () => {
     }
     expect(rules(frames)).toEqual([RULES.navigationNamesDestination])
   })
+
+  // The checker throws rather than guessing, and the harness keeps the frames beside the error.
+  it('refuses a row without the fields every rule reads', () => {
+    const frames = [
+      ...conformingStream(),
+      {
+        scope: 'commands',
+        data: [{ command: 'sendKeys', args: {}, timestamp: 400 }]
+      }
+    ]
+    expect(() => checkConformance(frames, truth)).toThrow(/args/)
+  })
 })
diff --git a/packages/conformance/tests/fakes.test.ts b/packages/conformance/tests/fakes.test.ts
index 56919dcd..8819f02b 100644
--- a/packages/conformance/tests/fakes.test.ts
+++ b/packages/conformance/tests/fakes.test.ts
@@ -139,7 +139,7 @@ ws.on('open', () => ws.send(JSON.stringify({ scope: 'commands', data: {} }), ()
       },
       false
     )
-    expect(report.checkerError).toBeDefined()
+    expect(report.checkerError).toContain('not an array')
     expect(report.frames).toEqual([{ scope: 'commands', data: {} }])
   })
 })
diff --git a/packages/conformance/tests/report.test.ts b/packages/conformance/tests/report.test.ts
index 6989e2c7..5fb035b3 100644
--- a/packages/conformance/tests/report.test.ts
+++ b/packages/conformance/tests/report.test.ts
@@ -146,4 +146,18 @@ describe('renderReport', () => {
   it('shows no guidance for a passing run', () => {
     expect(renderReport([run()])).not.toContain('Where to look')
   })
+
+  // Regression: one run the checker could not read took the whole report down with it.
+  it('still renders every other run when one stream could not be read', () => {
+    const html = renderReport([
+      run({
+        checkerError:
+          'commands frame #1 carries a row without command, args[] and timestamp',
+        frames: [{ scope: 'commands', data: {} }]
+      }),
+      run({ adapter: 'selenium-devtools-py' })
+    ])
+    expect(html).toContain('Checker failed')
+    expect(html).toContain('selenium-devtools-py')
+  })
 })