[js] Align BiDi Generator with the low-level contract

[pujagani]

🔗 Related Issues

Related to docs/decisions/17786-bidi-low-level-behavioral-contract.md
(#17786).

💥 What does this PR do?

Replaces the BiDi TypeScript generator's per-domain output with classes
that extend the shared Domain base (bidi/domain.js) instead of standalone
modules with hand-rolled connection glue.

• Commands validate outbound
  params and parse inbound results through the runtime schema layer
  (defineRecord/defineEnum/defineUnion).

• Events are exposed as static EventDescriptor constants consumed via the generic Domain#addCallback(),
  replacing one hand-generated on() method per event.

• Brings the generated output in line with the low-level BiDi behavioral
  contract in docs/decisions/17786-bidi-low-level-behavioral-contract.md
  ([adr] Behavioral contract for the low-level WebDriver BiDi layer #17786).

🔧 Implementation Notes

🤖 AI assistance

• No substantial AI assistance used
• AI assisted (complete below)
  • Tool(s): Claude
  • What was generated:
  • I reviewed all AI output and can explain the change

🔄 Types of changes

• Cleanup (formatting, renaming)
• New feature (non-breaking change which adds functionality and tests!)
• Breaking change (fix or feature that would cause existing functionality to change)

[qodo-code-review]

PR Summary by Qodo

Align JavaScript BiDi generation with the low-level domain contract

✨ Enhancement 🧪 Tests ⚙️ Configuration changes 🕐 40+ Minutes

AI Description

• Generates schema-backed domain classes extending the shared low-level Domain base.
• Validates command parameters, results, and event payloads through runtime schemas.
• Replaces generated event methods with reusable static descriptors and generic callbacks.

Diagram

graph TD
  A["CDDL AST"] --> B["Schema Projector"] --> C["BiDi Generator"] --> D["Domain Classes"] --> E["Domain Base"] --> F["BiDi Connection"]
  D --> G["Schema Runtime"]
  H["Bazel Build"] --> C
  H --> E

Loading

High-Level Assessment

The following are alternative approaches to this PR:

1. Retain generator enhancement manifest

• ➕ Preserves deprecated convenience methods and compatibility aliases
• ➕ Reduces immediate migration work for existing generated API consumers
• ➖ Mixes high-level conveniences into the low-level protocol binding
• ➖ Continues maintaining hand-written code fragments outside the schema
• ➖ Weakens consistency with the documented cross-language contract

2. Keep cddl2ts type generation

• ➕ Reuses the previous TypeScript conversion dependency
• ➕ Minimizes custom type-emission logic
• ➖ Requires textual post-processing and prefix-based domain inference
• ➖ Separates compile-time types from runtime validation metadata
• ➖ Makes schema-faithful cross-domain references harder to maintain

3. Separate compatibility facade

• ➕ Keeps generated domains contract-faithful
• ➕ Allows deprecated convenience APIs to migrate independently
• ➕ Provides a clearer boundary between low-level and ergonomic APIs
• ➖ Introduces another maintained API layer
• ➖ Requires explicit packaging and migration planning

Recommendation: Use the PR's schema-driven Domain-based generator for the low-level binding. If deprecated conveniences must remain, preserve them in a separate handwritten compatibility facade rather than restoring manifest-injected generator fragments.

Files changed (9) +440 / -475

Enhancement (1) +359 / -418

generate_bidi.mjsGenerate schema-backed low-level BiDi domain classes +359/-418

Generate schema-backed low-level BiDi domain classes

• Replaces cddl2ts and manifest-driven customization with binding-neutral schema projection and direct TypeScript emission. Generated classes extend Domain, validate command and event payloads through runtime schemas, expose static event and enum descriptors, and include specification-linked documentation.

javascript/selenium-webdriver/generate_bidi.mjs

Tests (5) +40 / -38

browsing_context_test.jsExercise browsing-context event descriptors +6/-6

Exercise browsing-context event descriptors

• Migrates browsing-context event tests from generated on<Event> methods to Domain.addCallback with static event descriptors.

javascript/selenium-webdriver/test/bidi/generated/browsing_context_test.js

input_test.jsExercise the input file-dialog descriptor +1/-1

Exercise the input file-dialog descriptor

• Updates file-dialog event registration to use Input.FILE_DIALOG_OPENED through the generic callback API.

javascript/selenium-webdriver/test/bidi/generated/input_test.js

log_test.jsTest log events through the generic descriptor API +24/-22

Test log events through the generic descriptor API

• Replaces specialized log listener helpers with Log.ENTRY_ADDED subscriptions. Tests now filter console and JavaScript entries explicitly from the low-level event payload.

javascript/selenium-webdriver/test/bidi/generated/log_test.js

network_test.jsExercise static network event descriptors +7/-7

Exercise static network event descriptors

• Migrates network event integration tests to addCallback with generated static descriptors for requests, responses, and fetch errors.

javascript/selenium-webdriver/test/bidi/generated/network_test.js

script_test.jsExercise script realm event descriptors +2/-2

Exercise script realm event descriptors

• Updates realm-created and realm-destroyed tests to subscribe through Script's static descriptors and Domain.addCallback.

javascript/selenium-webdriver/test/bidi/generated/script_test.js

Other (3) +41 / -19

BUILD.bazelWire schema projection modules into BiDi generation +2/-2

Wire schema projection modules into BiDi generation

• Adds the AST normalization and schema projection modules to the generator's runtime data. Removes the cddl2ts dependency and obsolete enhancements manifest input.

javascript/selenium-webdriver/BUILD.bazel

BUILD.bazelRetain the private generator Bazel package +3/-11

Retain the private generator Bazel package

• Removes the deleted enhancement-manifest target while retaining the package marker required to load generate_bidi.bzl by label.

javascript/selenium-webdriver/private/BUILD.bazel

generate_bidi.bzlStage BiDi runtimes for generated TypeScript compilation +36/-6

Stage BiDi runtimes for generated TypeScript compilation

• Removes enhancement-manifest support from the generation rule. Copies Domain and serialization runtime files into Bazel's output tree so NodeNext can resolve generated relative imports during compilation.

javascript/selenium-webdriver/private/generate_bidi.bzl

[qodo-code-review]

Code Review by Qodo

🐞 Bugs (0) 📘 Rule violations (1) 📜 Skill insights (0)

1. Alias validation can regress unnoticed ⊘ Outdated 📘 Rule violation ☼ Reliability

Description

resolveAliasRuntime newly routes same-domain alias results through record or union parsing, but no
focused generator test asserts the emitted runtime binding or malformed-result rejection. Changes to
alias chains, declaration order, or runtime naming can therefore disable inbound validation while
existing browser happy-path assertions still pass.

Code

javascript/selenium-webdriver/generate_bidi.mjs[R919-920]

+        const resolved = resolveAliasRuntime(node, types)
+        if (resolved) runtimeByTsName.set(tsName, { ...resolved, fields: undefined })

Evidence

Compliance rule 4 requires focused automated coverage for behavioral changes. The added
alias-resolution branch changes generated command result validation, while the new serialization
tests cover numeric and boolean enum values rather than alias-chain generation or inbound aliased
results.

AGENTS.md: Include Focused Tests for Behavioral Changes
javascript/selenium-webdriver/generate_bidi.mjs[910-920]
javascript/selenium-webdriver/test/bidi/serialization/record_test.js[445-495]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
The generator now resolves same-domain aliases to record or union runtime bindings, but this behavior lacks focused automated coverage that would fail if generated commands stopped parsing aliased results.

## Fix Focus Areas
- javascript/selenium-webdriver/generate_bidi.mjs[841-853]
- javascript/selenium-webdriver/generate_bidi.mjs[910-920]

## Recommended Fix
Add a focused generator unit test using a schema with an alias chain ending in a record or union. Assert that the generated command invokes the resolved runtime binding's `fromWire()`, that valid results are parsed, and that malformed results raise a validation error.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

2. Alias loop comment repeats the code 📘 Rule violation ⚙ Maintainability

Description

resolveAliasRuntime annotates current = target with another alias — keep resolving, which
merely narrates the assignment and loop continuation. When alias traversal changes, this redundant
narration can drift from the loop condition instead of explaining why traversal is safe or
intentionally limited.

Code

javascript/selenium-webdriver/generate_bidi.mjs[851]

+    current = target // another alias — keep resolving

Evidence

Compliance rule 6 reserves comments for rationale rather than narration. The inline comment says
that assigning the next alias causes the loop to keep resolving, which is already evident from the
assignment and surrounding loop.

AGENTS.md: Comments Must Explain Rationale Rather Than Restate Code
javascript/selenium-webdriver/generate_bidi.mjs[841-853]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
The inline comment beside the alias-loop assignment restates the visible mechanics without documenting rationale, constraints, or intent.

## Fix Focus Areas
- javascript/selenium-webdriver/generate_bidi.mjs[851-851]

## Recommended Fix
Remove the inline comment. If a non-obvious traversal constraint needs documentation, replace it with a concise explanation of that constraint rather than narrating the assignment.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

Context sources

Review mode: ⚖️ Balanced: This push changes BiDi schema projection and domain-mapping behavior in the generator, creating meaningful generated-API and build-output risk, but is not dense or broad enough to warrant redundant review passes.

Tip of the day

💡 Did you know, you can keep summaries lean with Finding overflow, which tucks the rest behind 'View more'

More tips ↗ | Customize Qodo ↗ | Qodo docs ↗

Previous reviews

Review updated until commit 83659e5 ⚖️ Balanced

Results up to commit 0c050bf ⚖️ Balanced

🐞 Bugs (0) 📘 Rule violations (0) 📎 Requirement gaps (0) 🎨 UX issues (0) 🔗 Cross-repo conflicts (0) 📜 Skill insights (0)

1. Renamed fields cannot serialize ✓ Resolved 🐞 Bug ≡ Correctness

Description

Generated commands validate a typed JS-facing object but discard the constructed record and send the
original object, while defineRecord expects wire-keyed constructor input. Consequently,
setMediaFeaturesOverride({features: {prefersColorScheme: 'dark'}}) fails validation, and JS-facing
renamed fields cannot be correctly transmitted.

Code

javascript/selenium-webdriver/generate_bidi.mjs[R1023-1024]

+  if (paramsRuntime?.kind === 'record') {
+    lines.push(`    new ${paramsRuntime.runtimeName}(params)`)

Evidence

The projector deliberately creates distinct JS and wire names, and the emitted interface exposes
field.name. The runtime constructor instead checks and reads field.wire, while its toJSON() is
the mechanism that converts record instances back to wire names; generated methods construct such an
instance only for side effects and then send paramsCast. The real schema demonstrates this on
emulation.MediaFeatures, where prefersColorScheme maps to prefers-color-scheme and is nested
under setMediaFeaturesOverride parameters.

javascript/selenium-webdriver/project_bidi_schema.mjs[219-239]
javascript/selenium-webdriver/generate_bidi.mjs[755-765]
javascript/selenium-webdriver/bidi/serialization/record.js[214-237]
javascript/selenium-webdriver/bidi/serialization/record.js[309-325]
common/bidi/schema.json[5923-5943]
common/bidi/schema.json[5960-5969]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
Generated commands discard the record instance used for validation and send the original JS-facing parameter object. Align record construction with JS-facing field names and retain/send the validated record so `toJSON()` converts fields to their declared wire names, including nested records.

## Issue Context
The schema intentionally maps keys such as `prefers-color-scheme` to `prefersColorScheme`, but `defineRecord` currently reads constructor data through `field.wire`. The generator then discards that instance and sends the original object.

## Fix Focus Areas
- javascript/selenium-webdriver/generate_bidi.mjs[1017-1038]
- javascript/selenium-webdriver/bidi/serialization/record.js[214-325]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

2. Cross-domain validation is skipped ✓ Resolved 🐞 Bug ≡ Correctness

Description

Cross-domain schema dependencies are emitted only as import type, so their modules never execute
and register runtime types when consumers import a single generated domain. For example,
session.subscribe consequently accepts invalid contexts values without validating them as
browsing-context identifiers.

Code

javascript/selenium-webdriver/generate_bidi.mjs[715]

+    imports.push(`import type { ${[...names].sort().join(', ')} } from './${sourceFile}'`)

Evidence

The generator discovers nested cross-domain references but emits them exclusively with `import
type`, which is erased from generated JavaScript. Runtime records resolve referenced types through
the registry and return the supplied value unchanged when no registration exists;
session.SubscribeParameters.contexts concretely references browsingContext.BrowsingContext, so
importing only session skips element validation.

javascript/selenium-webdriver/generate_bidi.mjs[678-709]
javascript/selenium-webdriver/bidi/serialization/registry.js[18-32]
javascript/selenium-webdriver/bidi/serialization/record.js[88-112]
common/bidi/schema.json[641-650]
common/bidi/schema.json[2145-2175]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
Cross-domain imports are erased during TypeScript compilation, leaving referenced schemas absent from the shared runtime registry. Emit side-effect runtime imports or establish an equivalent deterministic registration mechanism while retaining type imports as needed.

## Issue Context
Runtime reference validation resolves types through a shared registry and explicitly skips validation when a type has not registered. Importing only the generated `session` module therefore does not load the `browsingContext` module needed to validate `session.SubscribeParameters.contexts`.

## Fix Focus Areas
- javascript/selenium-webdriver/generate_bidi.mjs[700-717]
- javascript/selenium-webdriver/bidi/serialization/registry.js[18-32]
- javascript/selenium-webdriver/bidi/serialization/record.js[88-112]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

Results up to commit 50586c4 ⚖️ Balanced

🐞 Bugs (0) 📘 Rule violations (0) 📎 Requirement gaps (0) 🎨 UX issues (0) 🔗 Cross-repo conflicts (0) 📜 Skill insights (0)

1. Boolean enums remain untypable ✓ Resolved 🐞 Bug ≡ Correctness

Description

The schema projector supports boolean literal enums, but defineEnum and TypeNode.enum now allow
only strings and numbers. A generated boolean enum or alias containing one will fail TypeScript
compilation despite being valid projector output.

Code

javascript/selenium-webdriver/bidi/serialization/enum.d.ts[32]

+export function defineEnum<T extends string | number>(name: string, values: readonly T[]): EnumEntry<T>

Evidence

The declarations restrict enum values to string | number, while literalPrimitive() classifies
all-boolean literals as boolean; enumNode() stores those values in enum, and projectType()
can emit them as first-class enum values. Therefore the declared runtime schema vocabulary is
narrower than the projector output it is intended to represent.

javascript/selenium-webdriver/bidi/serialization/enum.d.ts[18-32]
javascript/selenium-webdriver/bidi/serialization/record.d.ts[18-29]
javascript/selenium-webdriver/project_bidi_schema.mjs[122-140]
javascript/selenium-webdriver/project_bidi_schema.mjs[267-276]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
The schema projector can emit boolean literal enums, while the serialization declarations only accept string or number enum values. This makes valid projected schemas containing boolean choices fail TypeScript type checking.

## Issue Context
`literalPrimitive()` explicitly recognizes boolean literals, and both inline and named enum projection retain those boolean values. Runtime membership checking already works for booleans through `Set.has()` and `Array.includes()`.

## Fix Focus Areas
- javascript/selenium-webdriver/bidi/serialization/enum.d.ts[18-32]
- javascript/selenium-webdriver/bidi/serialization/enum.js[21-26]
- javascript/selenium-webdriver/bidi/serialization/record.d.ts[23-26]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

Results up to commit 4a45dbd ⚖️ Balanced

🐞 Bugs (0) 📘 Rule violations (0) 📎 Requirement gaps (0) 🎨 UX issues (0) 🔗 Cross-repo conflicts (0) 📜 Skill insights (0)

1. defineEnum primitives lack tests ✗ Dismissed 📘 Rule violation ☼ Reliability

Description

The widened enum contract now accepts numeric and boolean values, but the serialization tests
exercise only string enums. Numeric and boolean membership behavior—and the corresponding TypeScript
declarations—can regress without detection.

Code

javascript/selenium-webdriver/bidi/serialization/enum.d.ts[33]

+export function defineEnum<T extends string | number | boolean>(name: string, values: readonly T[]): EnumEntry<T>

Evidence

PR Compliance ID 5 requires focused tests for behavioral changes. The declaration now accepts
string, number, and boolean enum values, while the existing serialization fixture invokes
defineEnum only with strings.

AGENTS.md: Provide Focused Tests and Prefer Real API Contracts Over Mocks
javascript/selenium-webdriver/bidi/serialization/enum.d.ts[18-33]
javascript/selenium-webdriver/test/bidi/serialization/record_test.js[24-30]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
The enum serialization contract was expanded from string-only values to include numbers and booleans, but focused tests cover only a string enum.

## Issue Context
Add runtime membership tests for numeric and boolean enums and a TypeScript compilation check covering the widened `defineEnum` generic and `TypeNode.enum` declaration.

## Fix Focus Areas
- javascript/selenium-webdriver/bidi/serialization/enum.d.ts[18-33]
- javascript/selenium-webdriver/bidi/serialization/record.d.ts[23-27]
- javascript/selenium-webdriver/test/bidi/serialization/record_test.js[24-30]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

2. Aliased results bypass validation ✓ Resolved 🐞 Bug ≡ Correctness

Description

Commands whose result type is an alias fall through to the unchecked cast because aliases have no
entry in runtimeByTsName. For example, browser.createUserContext accepts a malformed result
missing required userContext instead of parsing it through the aliased browser.UserContextInfo
record.

Code

javascript/selenium-webdriver/generate_bidi.mjs[1061]

+    lines.push(`    return (await this.send('${methodStr}', ${sendArg})) as ${resultTypeName}`)

Evidence

The schema declares browser.createUserContext with result ref browser.CreateUserContextResult,
which is an alias to browser.UserContextInfo; that record requires userContext. The generator
gives aliases no runtime binding, so resultRuntime is undefined and focused line 1061 returns the
wire payload through an unchecked TypeScript cast rather than invoking the record's fromWire().

common/bidi/schema.json[14-24]
common/bidi/schema.json[2606-2620]
common/bidi/schema.json[2709-2714]
javascript/selenium-webdriver/generate_bidi.mjs[758-763]
javascript/selenium-webdriver/generate_bidi.mjs[1026-1061]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
Generated command methods do not validate results whose direct schema type is an alias. Resolve aliases to their underlying runtime record or union so these results use `fromWire()` rather than the unchecked cast path.

## Issue Context
`browser.createUserContext` returns `browser.CreateUserContextResult`, an alias to the required-field record `browser.UserContextInfo`. Because aliases are excluded from `runtimeByTsName`, malformed responses are currently returned as if valid.

## Fix Focus Areas
- javascript/selenium-webdriver/generate_bidi.mjs[758-763]
- javascript/selenium-webdriver/generate_bidi.mjs[1026-1061]
- common/bidi/schema.json[14-24]
- common/bidi/schema.json[2606-2620]
- common/bidi/schema.json[2709-2714]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

Results up to commit 7c5daf8 ⚖️ Balanced

🐞 Bugs (0) 📘 Rule violations (1) 📎 Requirement gaps (0) 🎨 UX issues (0) 🔗 Cross-repo conflicts (0) 📜 Skill insights (0)

1. Alias loop comment repeats the code 📘 Rule violation ⚙ Maintainability

Description

resolveAliasRuntime annotates current = target with another alias — keep resolving, which
merely narrates the assignment and loop continuation. When alias traversal changes, this redundant
narration can drift from the loop condition instead of explaining why traversal is safe or
intentionally limited.

Code

javascript/selenium-webdriver/generate_bidi.mjs[851]

+    current = target // another alias — keep resolving

Evidence

Compliance rule 6 reserves comments for rationale rather than narration. The inline comment says
that assigning the next alias causes the loop to keep resolving, which is already evident from the
assignment and surrounding loop.

AGENTS.md: Comments Must Explain Rationale Rather Than Restate Code
javascript/selenium-webdriver/generate_bidi.mjs[841-853]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
The inline comment beside the alias-loop assignment restates the visible mechanics without documenting rationale, constraints, or intent.

## Fix Focus Areas
- javascript/selenium-webdriver/generate_bidi.mjs[851-851]

## Recommended Fix
Remove the inline comment. If a non-obvious traversal constraint needs documentation, replace it with a concise explanation of that constraint rather than narrating the assignment.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

2. Alias validation can regress unnoticed ⊘ Outdated 📘 Rule violation ☼ Reliability

Description

resolveAliasRuntime newly routes same-domain alias results through record or union parsing, but no
focused generator test asserts the emitted runtime binding or malformed-result rejection. Changes to
alias chains, declaration order, or runtime naming can therefore disable inbound validation while
existing browser happy-path assertions still pass.

Code

javascript/selenium-webdriver/generate_bidi.mjs[R919-920]

+        const resolved = resolveAliasRuntime(node, types)
+        if (resolved) runtimeByTsName.set(tsName, { ...resolved, fields: undefined })

Evidence

Compliance rule 4 requires focused automated coverage for behavioral changes. The added
alias-resolution branch changes generated command result validation, while the new serialization
tests cover numeric and boolean enum values rather than alias-chain generation or inbound aliased
results.

AGENTS.md: Include Focused Tests for Behavioral Changes
javascript/selenium-webdriver/generate_bidi.mjs[910-920]
javascript/selenium-webdriver/test/bidi/serialization/record_test.js[445-495]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
The generator now resolves same-domain aliases to record or union runtime bindings, but this behavior lacks focused automated coverage that would fail if generated commands stopped parsing aliased results.

## Fix Focus Areas
- javascript/selenium-webdriver/generate_bidi.mjs[841-853]
- javascript/selenium-webdriver/generate_bidi.mjs[910-920]

## Recommended Fix
Add a focused generator unit test using a schema with an alias chain ending in a record or union. Assert that the generated command invokes the resolved runtime binding's `fromWire()`, that valid results are parsed, and that malformed results raise a validation error.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

[qodo-code-review]

Code review by qodo was updated up to the latest commit 50586c4

[qodo-code-review]

Code review by qodo was updated up to the latest commit 4a45dbd

[pujagani]

Failed tests are dotnet and not related to this PR.

[qodo-code-review]

2. Alias loop comment repeats the code 📘 Rule violation ⚙ Maintainability

resolveAliasRuntime annotates current = target with another alias — keep resolving, which
merely narrates the assignment and loop continuation. When alias traversal changes, this redundant
narration can drift from the loop condition instead of explaining why traversal is safe or
intentionally limited.

Agent Prompt

## Issue description
The inline comment beside the alias-loop assignment restates the visible mechanics without documenting rationale, constraints, or intent.

## Fix Focus Areas
- javascript/selenium-webdriver/generate_bidi.mjs[851-851]

## Recommended Fix
Remove the inline comment. If a non-obvious traversal constraint needs documentation, replace it with a concise explanation of that constraint rather than narrating the assignment.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

[qodo-code-review]

Code review by qodo was updated up to the latest commit 7c5daf8

[qodo-code-review]

Code review by qodo was updated up to the latest commit 83659e5