cdpify 0.4.0__tar.gz → 0.5.0__tar.gz

cdpify-0.5.0/CHANGELOG.md

@@ -0,0 +1,214 @@
+# Changelog
+
+All notable changes to this project are documented here.
+Breaking changes are listed first in each release.
+
+## [0.5.0] - Unreleased
+
+Release preparation; the publication date will be recorded when 0.5.0 ships.
+See the [migration guide](README.md#upgrading-from-040) before upgrading.
+
+### Breaking changes
+
+- Renamed the error module from `cdpify.exceptions` to `cdpify.error`.
+  Update imports such as `from cdpify.exceptions import CDPCommandError` to
+  `from cdpify.error import CDPCommandError`. The old module is removed;
+  error classes remain available from the root package (`from cdpify import
+  CDPCommandError`) with the same behavior and inheritance.
+- Optional `any` fields now default to `UNSET`, distinguishing omission from
+  JSON `null`. For example, `CallArgument()` omits `value`, while
+  `CallArgument(value=None)` sends `{"value": null}`. Ordinary optional scalar
+  fields still use `None` to mean omitted. `UNSET` and `UnsetType` are public.
+- `decode_cdp` now raises `CDPDecodeError` for missing required fields, including
+  nested models. Unknown fields and future enum values remain supported. Use
+  `decode_cdp(Model, payload, strict=False)` for the previous tolerant behavior
+  that logs a warning and fills missing required fields with `None`.
+- Command timeouts now cover sending and receiving. The
+  `CdpClient(default_timeout=...)` setting is enforced for every transport and
+  inherited by session views. Omit the raw `execute(timeout=...)` argument to
+  inherit the default; pass `None` to disable it. Set `default_timeout=None` to
+  disable the client default entirely.
+- `WebSocketTransport` no longer accepts `default_timeout`; configure it on
+  `CdpClient` instead. Standalone transport calls have no deadline unless
+  `execute(timeout=seconds)` is specified. Generated methods retain only CDP's
+  own parameters; use `asyncio.timeout(seconds)` for an individual caller budget.
+- WebSocket compression is disabled by default for lower local latency. Pass
+  `compression="deflate"` to `CdpClient` or `WebSocketTransport` to opt into
+  compression when bandwidth matters more.
+- Bounded event buffers now default to `overflow="error"`: overflow terminates
+  only the affected stream and raises `CDPEventOverflowError` on its next read.
+  Pass `overflow="drop_oldest"` on the client, transport or subscription to keep
+  the old lossy behavior. The default queue size remains unlimited (`0`).
+
+### Added
+
+- Generated method docstrings include parameter descriptions, units and defaults
+  from the spec. Model fields retain their attribute documentation. Experimental
+  and deprecated markers are preserved on types, events and fields as well as
+  commands.
+- `listen_raw(method=None)` on clients and sessions, and `listen_all_raw()` on
+  clients, return `TransportEvent` values with wire names, parameter dictionaries
+  and session IDs. None matches every method in the selected scope.
+- Per-subscription overflow overrides and structured `CDPEventOverflowError`
+  details (`max_queue_size`, `dropped_events`). Overflow never blocks responses
+  or other subscriptions; failed listeners unregister immediately.
+- `compression`, `open_timeout` and `close_timeout` options for URL-based clients
+  and the standalone WebSocket transport. Connection timeouts are in seconds.
+- Reproducible codec, dispatch and optional Chrome round-trip benchmarks in
+  `benchmarks/runtime.py`; offline regeneration and generated-code drift checks
+  in `scripts/check_generated.py`.
+- CI checks the library and public API with Pyright and runs isolated headless
+  Chrome tests. Run those locally with `pytest -m integration` and optionally
+  `CHROME_PATH`; they are excluded from the default unit-test run.
+
+### Performance
+
+- Generated command methods build wire dictionaries directly, avoiding an
+  intermediate Params dataclass and reflective field traversal. Public Params
+  models and keyword-only command signatures are retained. Nested models still
+  serialize through the shared codec.
+- The orjson transport sends UTF-8 bytes directly as text frames and receives
+  bytes without first decoding to a Python string. This removes redundant
+  UTF-8 conversions while preserving the CDP wire format.
+
+## [0.4.0] - 2026-10-25
+
+### Breaking changes
+
+- Named protocol enums are now `StrEnum` subclasses instead of `Literal`
+  aliases. Use constants such as `ResourceType.FETCH` and
+  `CookieOperation.SET_COOKIE` in typed code. `decode_cdp` returns enum members,
+  including in nested models and collections. Unknown strings from newer CDP
+  versions remain instances of the corresponding enum with their original
+  `.value`; they are not added to its declared members. Inline enums remain
+  `Literal` annotations.
+- Matching event listeners now share one decoded model per incoming event and
+  event class, including `listen_all()`'s `ReceivedEvent.value`. Mutations are
+  visible to other listeners. Treat event data as read-only or make a
+  `copy.deepcopy(event)` before changing it privately.
+- All generated type aliases use `type` statements, including primitives and
+  arrays, e.g. `type FrameId = str` and `type Quad = list[float]`. Use them in
+  annotations; pass plain values such as `frame_id: FrameId = "F1"` instead of
+  calling `FrameId("F1")`. For runtime checks use `isinstance(value, str)` rather
+  than `isinstance(value, FrameId)`.
+- `Client` and `CDPSession` are renamed to `CdpClient` and `CdpSession`.
+  Update imports to `from cdpify import CdpClient, CdpSession` and calls to
+  `CdpClient(...)`. `client.session(...)` now returns `CdpSession`.
+- Exceptions follow Python naming: `CDPException` → `CDPError`,
+  `CDPConnectionException` → `CDPConnectionError`, `CDPCommandException` →
+  `CDPCommandError`, `CDPTimeoutException` → `CDPTimeoutError`. The old names
+  still work but emit a `DeprecationWarning` and will be removed in a future
+  release.
+- `CDPCommandError` takes `(method, code, message, data=None)` instead of the
+  raw error dict. Use `CDPCommandError.from_response(method, error)` to build
+  one from a CDP error payload. The message now names the failed method, e.g.
+  `Page.navigate failed with CDP error -32000: Cannot navigate to invalid URL`.
+- `listen()`, `listen_all()` and `CdpSession.listen()` are now regular methods
+  that return an `EventSubscription` instead of async generators. `async for`
+  and `aclose()` keep working. Code that relied on the generator type itself
+  (e.g. `inspect.isasyncgen`) or on `asend()`/`athrow()` must be updated.
+- `listen()`, `listen_all()` and `CdpSession.listen()` take the event class
+  instead of an event name plus class, and `timeout` is keyword-only:
+
+  ```python
+  # Before
+  client.listen(NetworkEvent.REQUEST_WILL_BE_SENT, RequestWillBeSentEvent)
+  client.listen(
+      event_name=NetworkEvent.REQUEST_WILL_BE_SENT,
+      event_type=RequestWillBeSentEvent,
+  )
+
+  # After
+  client.listen(RequestWillBeSentEvent)
+  ```
+
+  The CDP name comes from the new `__cdp_event__` class variable on generated
+  event classes. For custom dataclasses pass `event_name="Domain.event"`.
+- Calling a deprecated CDP command emits a `DeprecationWarning` instead of
+  logging a warning on every call. Python's default filters show it once per
+  call site; use `warnings.filterwarnings` or `-W` to change that. The
+  decorator is now `warnings.deprecated` (PEP 702) on Python 3.13+, so IDEs and
+  type checkers mark deprecated commands. `cdpify.shared.decorators.deprecated`
+  requires a message: `@deprecated("...")` instead of `@deprecated()`.
+
+### Added
+
+- Optional `max_queue_size` on `CdpClient`, `WebSocketTransport`, `listen()`,
+  `listen_all()`, and `CdpSession.listen()`. Zero keeps unlimited buffering;
+  bounded queues drop their oldest event instead of blocking command responses.
+  Subscriptions inherit the client limit unless overridden. Both subscriptions
+  and the standalone WebSocket transport expose `dropped_events` counters.
+- `cdpify[orjson]` enables optional `orjson` encoding and decoding in the WebSocket
+  transport, with automatic fallback to `json` and outgoing text frames.
+- Optional `CallbackTransport` protocol in `cdpify.transport` for direct event
+  delivery without a transport queue. Existing `Transport` implementations work
+  through their event iterator.
+- `EventSubscription` registers its handler as soon as `listen()` is called, so
+  events emitted before the first read are no longer lost. It supports
+  `async with` for deterministic cleanup and `await events.next(timeout=...)`
+  for waiting on a single event. `next()` raises `CDPStreamClosedError` once
+  the stream has ended.
+- Generated event classes expose their CDP method name as `__cdp_event__`,
+  e.g. `LoadEventFiredEvent.__cdp_event__ == "Page.loadEventFired"`.
+- `FindInPage` domain (`client.find_in_page`) from the latest CDP spec.
+
+### Changed
+
+- Generated `__cdp_event__` class variables refer to the domain's event enum,
+  e.g. `LoadingFailedEvent.__cdp_event__ is NetworkEvent.LOADING_FAILED`.
+- The root client and session views share the implementation of `listen()`.
+- CI runs tests on Ubuntu, Windows, and macOS with Python 3.12, 3.13, and 3.14,
+  including both JSON backends.
+- `CDPTimeoutError` also inherits from the built-in `TimeoutError`, so
+  `except TimeoutError` catches command timeouts.
+- Docstrings of generated type aliases follow the alias, so IDEs and Sphinx
+  show them on hover.
+- Generated fields only carry `metadata={"cdp_name": ...}` when the CDP name
+  differs from the Python name. Code that reads `field.metadata["cdp_name"]`
+  directly should fall back to `field.name`.
+
+### Fixed
+
+- Distributions include the `py.typed` marker so type checkers recognize the
+  installed package's inline annotations.
+- A connection closing while a command is being sent now raises
+  `CDPConnectionError` and does not leave an unobserved response-future exception.
+  Commands submitted after shutdown starts are rejected immediately.
+- Concurrent disconnects and browser-initiated closure now wait for the same
+  cleanup. Cancelling a disconnect waiter no longer interrupts socket cleanup
+  or masks cancellation with an error when detaching the event callback.
+- Bounded event streams close even when their buffers are full, preserving
+  buffered events on disconnect. Explicit subscription closure releases pending
+  events immediately. Subscriptions from an earlier connection stay closed
+  after reconnecting.
+- `decode_cdp` now decodes nested models behind `type X = ...` aliases instead
+  of leaving them as plain dicts.
+- `decode_cdp` logs a warning when a field annotation cannot be resolved,
+  instead of silently leaving nested values as plain dicts.
+- A malformed message from the browser no longer closes the WebSocket
+  connection. The message is logged and skipped.
+- Events sent with `"params": null` are delivered with empty params instead of
+  being dropped as malformed.
+- Event listeners (`listen()`, `listen_all()`, `CdpSession.listen()`) now end
+  when the transport event stream ends or the client disconnects. Previously
+  they waited forever unless a `timeout` was set. Events that were already
+  received are still delivered before the stream ends.
+- Array type aliases keep their element type instead of `list[Any]`, e.g.
+  `DOM.Quad = list[float]` and `Target.TargetFilter = list[FilterEntry]`.
+  Fields typed as `TargetFilter` now decode to `FilterEntry` objects instead
+  of plain dicts.
+- Generated fields and parameters whose CDP name is a Python keyword get a
+  trailing underscore (`or` → `or_`), so the generated code is valid again.
+
+### Performance
+
+- The default WebSocket transport delivers events directly to the router,
+  removing the intermediate queue and client event-loop task.
+- Event models are decoded lazily once per incoming event and target class,
+  then reused by matching listeners. Unread events are not decoded; caches are
+  released together with the buffered event instead of being retained globally.
+- `decode_cdp` builds a converter per field once per model instead of
+  inspecting type annotations for every value. Decoding typical Network
+  events is 4–7× faster (`ResponseReceivedEvent`: 56 µs → 7 µs).
+- `import cdpify` loads CDP domains lazily on first access. Import time drops
+  from ~790 ms to ~85 ms.

cdpify-0.5.0/MANIFEST.in

@@ -0,0 +1,2 @@
+include CHANGELOG.md
+include RELEASING.md

{cdpify-0.4.0 → cdpify-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cdpify
-Version: 0.4.0
+Version: 0.5.0
 Summary: A Python client for the Chrome DevTools Protocol (CDP) optimized for DX.
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.12
@@ -30,12 +30,14 @@ without working with raw JSON messages.
 
 - [Why cdpify?](#why-cdpify)
 - [Installation](#installation)
+- [Upgrading from 0.4.0](#upgrading-from-040)
 - [Quick start](#quick-start)
 - [Supported domains](#supported-domains)
 - [Listening for events](#listening-for-events)
 - [Working with target sessions](#working-with-target-sessions)
 - [Configuration](#configuration)
 - [Development](#development)
+- [Releasing](RELEASING.md)
 - [Resources](#resources)
 
 ## Why cdpify?
@@ -71,16 +73,45 @@ pip install "cdpify[websocket,orjson]"
 The transport automatically uses `orjson` when available and otherwise uses
 Python's standard `json` module. Outgoing WebSocket messages remain text frames.
 
+Generated methods expose only CDP parameters. Parameter docstrings preserve
+the spec's units, defaults and experimental/deprecated markers.
+
 Install the generator dependencies only when regenerating protocol modules:
 
 ```bash
 pip install "cdpify[generator]"
 ```
 
+## Upgrading from 0.4.0
+
+Version 0.5.0 includes breaking changes. Review these before updating:
+
+| Area | Update for 0.5.0 |
+| --- | --- |
+| Error imports | Replace `cdpify.exceptions` with `cdpify.error`, or import errors from `cdpify`. The old module is removed. |
+| Optional `Any` values | Use `UNSET` to omit a value. `None` now sends JSON `null`; ordinary optional scalar fields still omit `None`. |
+| Required response fields | Generated responses and typed events now raise `CDPDecodeError` when required fields are missing. For tolerant manual decoding, use `decode_cdp(Model, payload, strict=False)`. |
+| Command deadlines | Configure `default_timeout` on `CdpClient`, including for custom transports. The budget covers sending and receiving. `WebSocketTransport` no longer accepts `default_timeout`. |
+| Bounded event buffers | Overflow now raises `CDPEventOverflowError`. Set `overflow="drop_oldest"` to keep lossy buffering. The default buffer remains unlimited. |
+| WebSocket compression | Compression now defaults to `None`. Set `compression="deflate"` to enable it. |
+
+Generated methods accept only CDP parameters. For an individual caller deadline,
+wrap the call in `asyncio.timeout(seconds)`; a CDP parameter named `timeout`
+keeps the units and meaning defined by the protocol. The raw `execute()` method
+accepts a client timeout in seconds: omit it to inherit the client default or
+pass `None` to disable that deadline for the call.
+
+See the [0.5.0 changelog](CHANGELOG.md#050---unreleased) for the complete release
+notes, including raw event streams and performance changes.
+
 ## Quick start
 
 Start Chrome or Chromium with remote debugging enabled, then obtain a page's
-`webSocketDebuggerUrl` from `http://localhost:9222/json`.
+`webSocketDebuggerUrl` from `http://localhost:9222/json`. Launch with
+`--remote-debugging-port=9222 --user-data-dir=<dedicated-profile-directory>`
+and open a tab first. The scripts in [examples](examples) can launch Chrome
+with these options for you, for example `uv run python examples/navigate.py`
+from a development checkout.
 
 ```python
 import asyncio
@@ -88,18 +119,28 @@ import json
 from urllib.request import urlopen
 
 from cdpify import CdpClient
+from cdpify.domains.page import LoadEventFiredEvent
 
 
 def get_websocket_url() -> str:
     with urlopen("http://localhost:9222/json", timeout=5) as response:
-        return json.load(response)[0]["webSocketDebuggerUrl"]
+        return next(
+            target["webSocketDebuggerUrl"]
+            for target in json.load(response)
+            if target.get("type") == "page"
+        )
 
 
 async def main() -> None:
     ws_url = get_websocket_url()
 
     async with CdpClient(ws_url) as client:
-        await client.page.navigate(url="https://example.com")
+        await client.page.enable()
+        async with client.listen(LoadEventFiredEvent) as loaded:
+            navigation = await client.page.navigate(url="https://example.com")
+            if navigation.error_text:
+                raise RuntimeError(navigation.error_text)
+            await loaded.next(timeout=10)
 
         result = await client.runtime.evaluate(
             expression="document.title",
@@ -196,6 +237,7 @@ triggers, subscribe first and then send the command:
 from cdpify.domains.page.events import LoadEventFiredEvent
 
 
+await client.page.enable()
 async with client.listen(LoadEventFiredEvent) as events:
     await client.page.navigate(url="https://example.com")
     await events.next(timeout=10)
@@ -250,11 +292,15 @@ subscription has read or discarded the incoming event.
 ### Limiting buffered events
 
 Set `max_queue_size` on `CdpClient` to limit each listener's buffer. The default,
-`0`, is unlimited. A full buffer discards its oldest event so slow consumers do
-not block command responses. Override the limit for an individual subscription:
+`0`, is unlimited. A bounded buffer defaults to `overflow="error"`: if it fills,
+that subscription ends and its next read raises `CDPEventOverflowError`. Other
+subscriptions and command responses continue normally. This makes event loss
+explicit for protocols such as `Fetch.requestPaused` that require a response.
+
+For a stream where loss is acceptable, select `overflow="drop_oldest"`:
 
 ```python
-client = CdpClient(ws_url, max_queue_size=256)
+client = CdpClient(ws_url, max_queue_size=256, overflow="drop_oldest")
 
 async with client:
     async with client.listen(RequestWillBeSentEvent, max_queue_size=32) as events:
@@ -262,10 +308,26 @@ async with client:
         print(events.dropped_events)
 ```
 
-The same options apply to `listen_all()` and `CdpSession.listen()`. Passing `0`
-to a listener disables its limit. `events.dropped_events` counts events evicted
-by that listener's buffer. Disconnecting drains the remaining buffered events;
-`aclose()` releases them immediately.
+The same options apply to `listen_all()`, `CdpSession.listen()` and raw streams.
+Each listener can override both the limit and overflow policy. Passing `0`
+disables its limit. `events.dropped_events` counts discarded events. Disconnect
+drains healthy buffers; explicit closure and overflow errors release them.
+
+### Raw events
+
+Use raw subscriptions for events outside the generated spec, or to inspect wire
+parameter dictionaries without constructing typed models:
+
+```python
+async with tab.listen_raw("Future.event") as events:
+    event = await events.next(timeout=5)
+    print(event.method, event.session_id, event.params)
+```
+
+`client.listen_raw()` covers the root, `tab.listen_raw()` one session, and
+`client.listen_all_raw()` every scope. Omitting the method matches every event
+in that scope. Subscriptions register immediately and share the same lifetime,
+buffering and read-only data rules as typed streams.
 
 ## Working with target sessions
 
@@ -324,9 +386,43 @@ client = CdpClient(
     max_frame_size=100 * 1024 * 1024,
     default_timeout=30.0,
     max_queue_size=256,
+    overflow="error",
+    compression=None,
+    open_timeout=10.0,
+    close_timeout=10.0,
 )
 ```
 
+WebSocket compression is off by default to reduce local CPU work and latency.
+Set `compression="deflate"` when saving network bandwidth is preferable.
+`additional_headers`, `max_frame_size`, `compression`, `open_timeout` and
+`close_timeout` configure the URL-based WebSocket transport. Supplied custom
+transports own their connection settings.
+
+### Timeouts
+
+`default_timeout` is a total command budget in seconds, including sending and
+waiting for the response. It applies to root commands and session commands,
+including custom transports. `None` disables the default.
+
+For one call, or a group of calls, use Python's normal timeout context:
+
+```python
+async with asyncio.timeout(2):
+    result = await client.runtime.evaluate(expression="1 + 1")
+```
+
+A client deadline raises `CDPTimeoutError`; a shorter outer `asyncio.timeout()`
+raises the built-in `TimeoutError`. Both release the pending local request.
+Cancelling the wait does not automatically cancel work in Chrome.
+
+CDP parameters retain the spec's units. For example, `Runtime.evaluate(timeout=...)`
+limits execution inside Chrome in **milliseconds**; it is not the client budget.
+The raw `execute()` escape hatch also accepts `timeout=seconds`: omit it to
+inherit the client default or pass `None` to disable the deadline for that call.
+
+### Custom transports
+
 For another transport protocol, implement the exported `Transport` protocol
 and inject it directly:
 
@@ -342,8 +438,11 @@ WebSocket transport uses this path to avoid an intermediate event queue.
 Transports that implement only `Transport.events()` continue to work.
 
 When using `WebSocketTransport.events()` directly, its `max_queue_size` option
-sets the same drop-oldest limit on its transport buffer; `dropped_events` counts
-those evictions. A client-supplied custom transport manages its own buffer limits.
+sets the limit on its transport buffer with the same overflow policies. A
+client-supplied custom transport manages its own transport buffer limits.
+`WebSocketTransport` has no default command timeout; standalone calls can pass
+`execute(timeout=seconds)`. In the `Transport` contract, `timeout=None` means no
+deadline and cancellation releases resources associated with that request.
 
 For methods not covered by the generated API, use the low-level escape hatch:
 
@@ -370,10 +469,35 @@ than `FrameId("F1")`, and `isinstance(frame_id, str)` for a runtime check.
 
 ### When Chrome deviates from the spec
 
-Chrome does not always send every field the protocol marks as required.
-Instead of failing, cdpify logs a warning on the `cdpify.codec` logger and
-sets the missing field to `None`, even if its type says otherwise. Unknown
-fields from newer Chrome versions are ignored.
+Library error classes are available from `cdpify.error` and the root package:
+
+```python
+from cdpify.error import CDPCommandError, CDPDecodeError
+```
+
+Missing required fields raise `CDPDecodeError` with `model_type`,
+`missing_fields` and the enclosing wire-field `path`. Unknown fields are ignored
+and future enum values remain supported. Decoding checks required field
+presence; it does not perform full schema validation of primitive values.
+
+For a deliberately tolerant decode, use `decode_cdp(Model, payload, strict=False)`.
+This fills missing required fields with `None` and logs a warning, including
+nested models. When necessary, fetch the raw result with `execute()` and decode
+it explicitly with this policy.
+
+### Omitted values and JSON null
+
+Optional scalar parameters still use `None` to mean omitted. Optional `Any`
+fields use `UNSET` because JSON null is itself a valid value:
+
+```python
+from cdpify import UNSET, encode_cdp
+from cdpify.domains.runtime import CallArgument
+
+assert encode_cdp(CallArgument()) == {}
+assert encode_cdp(CallArgument(value=None)) == {"value": None}
+assert CallArgument().value is UNSET
+```
 
 Deprecated CDP commands still work but emit a `DeprecationWarning`. Use
 Python's warning filters to silence them or turn them into errors:
@@ -395,12 +519,38 @@ Install the project and its development dependencies with
 uv sync --dev
 uv run pytest
 uv run ruff check . --exclude cdpify/domains
+uv run ruff format --check . --exclude cdpify/domains
+uv run pyright
+uv run python scripts/check_generated.py
 ```
 
 Use `uv sync --dev --extra orjson` and `uv run --extra orjson pytest` to include
 the optional backend. CI installs this extra and tests both JSON backends on
 Ubuntu, Windows, and macOS with Python 3.12, 3.13, and 3.14.
 
+Run real Chrome coverage with `uv run --extra orjson pytest -m integration`.
+These tests launch an isolated headless browser. Set `CHROME_PATH` to select its
+executable. Integration tests are excluded from the default unit-test run.
+
+CI also checks the complete library and a public API sample with Pyright,
+verifies generated-code drift, and runs the integration suite against Chrome.
+Regenerate from the bundled specs with `uv run python scripts/check_generated.py --write`.
+
+Run reproducible microbenchmarks with:
+
+```bash
+uv run python benchmarks/runtime.py
+uv run --extra orjson python benchmarks/runtime.py --page-url ws://localhost:9222/devtools/page/...
+```
+
+Output is JSON with environment metadata and timings for encoding, decoding,
+typed calls and dispatch to several listener counts. An optional page endpoint
+adds real small-message and 1-MiB round trips, including p50 and p95 latency.
+The large case sends and receives a seeded Base64 payload. Add
+`--compression deflate` to compare compression on the same machine; installing
+or omitting the `orjson` extra selects the JSON backend. Timings are diagnostic
+and are not used as flaky CI pass/fail thresholds.
+
 To download the latest protocol definitions and regenerate all domain clients:
 
 ```bash
@@ -410,9 +560,13 @@ uv run python -m cdpify.generator
 Generate only selected domains by repeating `--domain`:
 
 ```bash
-uv run python -m cdpify.generator --domain Page --domain Runtime
+uv run python -m cdpify.generator --domain Page --domain Runtime --output-dir build/selected-domains
 ```
 
+Generation replaces the entire output directory, including for selected domains.
+Use a separate `--output-dir` for partial generation to keep the full bundled
+client intact. Selected domains may also reference types from other domains.
+
 Use `--spec-dir` and `--output-dir` to override where downloaded specifications
 and generated modules are written.
 
@@ -425,6 +579,8 @@ once a week and opens a pull request when generated code changes.
 - [Chrome DevTools Protocol documentation](https://chromedevtools.github.io/devtools-protocol/)
 - [Chrome DevTools Protocol repository](https://github.com/ChromeDevTools/devtools-protocol)
 - [Examples](examples)
+- [Changelog and migration notes](CHANGELOG.md)
+- [Release checklist](RELEASING.md)
 
 The code-generation approach was inspired by
 [`cdp-use`](https://github.com/browser-use/cdp-use).