cdp-toolkit 1.9.0 → 1.9.4

package/CHANGELOG.md

@@ -5,6 +5,512 @@ All notable changes to cdp-toolkit are documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.9.4] - 2026-08-11
+
+Firefox gains a second mode: **attach**. Until now `--browser firefox` always spawned a
+throwaway-profile Firefox — a login wall for anything needing a real, already-authenticated
+session. `--connect <port|host:port|ws-url>` (or env `CDP_FIREFOX_ENDPOINT`) instead connects to
+a Firefox **you** already started with `--remote-debugging-port`, so tools see your real logged-in
+profile. This process never launches or kills that browser: dispose only ends the BiDi session
+(`session.end`), never the process. Also fixes a doc-nit (README/CONTRACT overclaimed "Firefox
+cannot be attached to at all" — the real, narrower limitation is that you cannot relaunch the
+`firefox` binary with the debug flag against an already-running instance) and a real hang (a
+second attach against a Firefox that already has an active BiDi session used to hang forever;
+it now fails fast with an actionable error).
+
+### Added
+
+- **`--connect <endpoint>` / `CDP_FIREFOX_ENDPOINT`** — Firefox attach mode. `<endpoint>` accepts
+  three spellings, all normalized to a ws URL: a bare port (`9223`), `host:port`
+  (`127.0.0.1:9223`), or a full `ws://`/`wss://` URL. Flag beats env, mirroring
+  `--browser`/`CDP_BROWSER` precedence. An endpoint **implies** the Firefox backend on its own —
+  there is nothing else it could mean — and errors against an explicit `--browser chrome` /
+  `CDP_BROWSER=chrome` rather than silently picking one side.
+- `src/backend.ts`: `normalizeBidiEndpoint`, `resolveFirefoxEndpoint`, `stripConnectFlag`,
+  `resolveBackend` (the single backend-selection entry point `cli.ts`/`mcp.ts` now both call —
+  returns `{kind, endpoint?}`), and `startFirefoxSession`/`getOrCreateFirefoxSession` now accept
+  an `{ endpoint }` to attach instead of launch.
+- `src/bidi/client.ts`: `connectBidiSessionUrl(wsUrl, opts?)` — connects directly to a ws URL,
+  no port-to-URL construction. `connectBidiSession(port, opts)` is now a thin wrapper over it
+  (kept exported, unchanged behavior).
+- `src/bidi/driver.ts`: `createFirefoxDriverForEndpoint(wsUrl, opts?)` — the attach-mode driver
+  constructor. The driver's connection identity moved from a bare `port: number` to a ws
+  `endpoint: string`, so an attach endpoint can carry a different host/port/path than a launched
+  Firefox's `ws://127.0.0.1:<port>/session`.
+- `firefox:attach:smoke` script (`test/firefox-attach-smoke.ts`) — drives the real attach path
+  against an out-of-band-spawned Firefox: attach, read a page, dispose (Firefox stays alive), a
+  second attach cycle to the same Firefox (proves `session.end` freed the slot), and confirms
+  `resolveBackend` auto-implies `firefox` from `--connect` alone.
+- `test/backend-attach.test.ts` — pure-unit coverage of `normalizeBidiEndpoint`,
+  `resolveFirefoxEndpoint`, `stripConnectFlag`, and `resolveBackend`, including the
+  `--browser chrome` + `--connect` conflict.
+
+### Fixed
+
+- **A second attach against a Firefox with an already-active BiDi session used to hang forever.**
+  Firefox allows exactly one active WebDriver BiDi session at a time; a colliding `session.new`
+  fails with the raw wire message `Maximum number of active sessions`, which reached no caller
+  as an error — it hung. `getConnection` (`src/bidi/driver.ts`) now catches that specific message
+  and raises a clear, actionable error naming the endpoint and the fix (close the other client,
+  or restart Firefox; a client killed without a clean dispose, e.g. `SIGKILL`, can leave a
+  session Firefox does not reap on its own).
+- **Attach-mode dispose was undefined behavior before this release** (the mode did not exist):
+  `BidiBrowserDriver.dispose()` now sends `session.end` before closing the socket, which is what
+  actually frees Firefox's single session slot for the next attach — closing the socket alone
+  does not. Launch-mode dispose is unaffected: the spawned process is still killed after the
+  driver disposes, same as before.
+- **`src/bidi/launch.ts` doc-nit** (the issue's explicit ask, code unchanged): the header/footer
+  said Firefox "cannot be attached to at all." That overstated a real, narrower fact — you cannot
+  *relaunch* the `firefox` binary with `--remote-debugging-port` against an already-running
+  instance and have it take effect (the relaunch hands off and exits, opening no port; still true,
+  still verified against Firefox 153.0.3). Attaching to a port a Firefox process was *originally*
+  launched with — by this toolkit or by hand — always worked and is now this release's first-class
+  path. README.md and CONTRACT.md carried the same overclaim and are corrected too.
+
+### Notes
+
+- Tool count unchanged at **45**; no tool added, renamed, or removed. Both Firefox modes expose
+  the same tool set as before (see README's "Tool availability is filtered per backend").
+- The CLI is one process per invocation either way: an attach-mode CLI call still launches no
+  process and kills none, it just skips `launchFirefox` entirely. Multi-step attach workflows
+  still want the MCP server, same reasoning as launch mode.
+
+## [1.9.3] - 2026-08-10
+
+`cli.ts` had **no `--help` handling at all.** `--help` fell through the generic
+`--key value` branch into `args.help = true`, and the named tool ran with that
+as an inert extra property; `-h` doesn't even start with `--`, so it fell all
+the way to the positional-token branch and was silently dropped once a tool
+name was already set. Either way, **the tool ran.** Measured live this
+session: `cdp take_screenshot --help` executed a real capture of whatever tab
+happened to be active and wrote a 1.2 MB PNG to `/tmp/cdp-toolkit` — a "tell
+me, don't do it" discovery gesture that silently photographed what the user
+was looking at. Reproduced again here with the safe, non-capturing
+`list_pages --help` against a `CDP_BASE` pointed at a closed port: pre-fix it
+printed `{"error":"Unable to connect. Is the computer able to access the
+url?"}` and exited 1 — proof the tool dispatched and tried to reach the
+browser instead of printing help. Post-fix, the identical invocation against
+the same dead port prints usage and exits 0, and a directory listing of the
+artifact dir taken before and after is byte-identical: no file, no browser
+touch.
+
+### Fixed
+
+- **`--help`/`-h` now short-circuit before any tool dispatch, recognised
+  anywhere in argv** (not just as the first token), and are never treated as
+  a tool argument or a tool name. With no tool named, `cdp --help`/`-h` prints
+  the existing top-level usage banner (now also documenting the flag itself).
+  With a tool named, `cdp <tool> --help` prints that tool's argument list —
+  name, type, required/optional, description — read directly from
+  `MANIFEST`'s `inputSchema` (`src/manifest.ts`), the exact JSON Schema the
+  MCP server advertises via `tools/list`, so there is no second
+  hand-maintained argument list to drift from it.
+- An unknown tool name alongside `--help` (`cdp nope --help`) is reported as
+  `{"error":"unknown tool 'nope'. ..."}` and exits 1 — the same message the
+  CLI already gives for `cdp nope` without `--help` — rather than silently
+  falling back to top-level usage as though the name had been accepted.
+- **Decision, stated explicitly:** an unknown `--flag` passed to a *known*
+  tool still passes through as a tool argument, unchanged from pre-1.9.3
+  behavior. Every `inputSchema` already declares `additionalProperties:
+  false`, but neither `cli.ts` nor `mcp.ts` has ever enforced that — each tool
+  validates its own args at runtime, extra keys are typically just ignored,
+  and an existing caller may already depend on that leniency for something
+  harmless. Rejecting unknown flags here would diverge the CLI from the MCP
+  server (whose validation this release does not touch) to fix a problem this
+  bug did not create. `--help`/`-h` are instead recognised by name,
+  specifically, ahead of generic flag parsing — narrow enough that it needs
+  none of that broader, riskier call.
+
+### Added
+
+- `test/cli-help.test.ts` (6 tests): spawns the real CLI as a subprocess with
+  `CDP_BASE` pointed at a closed port, so any invocation that still reaches
+  tool dispatch fails loudly with a connection error instead of silently
+  succeeding. Watched fail against the pre-fix code first — 5 of 6 red on
+  exit code 1 instead of 0 — before confirming green post-fix.
+
+### Notes
+
+- Tool count unchanged at **45**; no tool added, renamed, or removed.
+  `take_screenshot` is not among the files this release touches.
+- 748 pass / 0 fail across 22 files, up from 742/21. `bun run typecheck` clean.
+
+## [1.9.2] - 2026-08-10
+
+`take_screenshot` grows four arguments — `scale`, `renderWidth`/`renderHeight`,
+`tile` — and stops being able to hang the tab it is capturing. The constraint
+worth learning from this release: **Chrome cannot encode a screenshot larger
+than 16384 device px on either side, and past that it does not refuse politely
+— `Page.captureScreenshot` never answers, and because `captureBeyondViewport`
+resizes the renderer to the clip for the length of the capture, a call that
+never returns never puts it back.** Output px are `ceil(css × scale ×
+devicePixelRatio)`, so on an ordinary ratio-2 display that ceiling arrives at
+about 8192 CSS px — a long article, a chat log, a docs page. A plain no-flag
+`take_screenshot` of a 9000 CSS px page timed out (probed with an 8 s command
+timeout) and left the tab wedged at 1390×9000, with every later capture on it
+timing out too. It now returns a 2780×18000 px file in 1 second, as two
+stitched bands. Tool count
+stays 45 — no new tool, `take_screenshot` grew arguments. Five commits landed
+it in sequence, on top of two measurement passes that drove a live
+Chrome 151.0.7922.76 and wrote no code — the encode cap and the band-artifact
+hunt. Every number below comes off a measurement, and where a measurement
+contradicted the brief that ordered the work, the measurement is what is
+written down.
+
+### Added
+
+- **`scale` — a per-capture output multiplier**, a finite number greater than
+  0 and at most 8 (default 1), Chrome only (capability `screenshot.scale`).
+  Measured exact on a live tab: a 2780×2128 default capture at `scale 3` is
+  8340×6384, a `--fullPage` at `scale 2` is 5560×13000, a 400×250 CSS element
+  at `scale 4` is 3200×2000 — `sips` agrees with the reported size on 9 of 9
+  artifacts, PNG and JPEG alike. It re-renders, it does not upsample, and it
+  changes nothing the page can see: `devicePixelRatio` read 2 and
+  `innerWidth`/`innerHeight` read 1390×1064 both before and after a `scale 3`
+  capture. Firefox refuses it rather than silently returning a 1x image the
+  caller could not tell apart from the one they wanted —
+  `browsingContext.captureScreenshot` has no scale parameter, and the refusal
+  points at `emulate {deviceScaleFactor}` instead.
+
+- **`renderWidth`/`renderHeight` — emulate a viewport for exactly one capture,
+  then put the previous one back.** Required together, integers in
+  `[1, 16384]` CSS px, and declared by **both** backends (capability
+  `screenshot.renderSize`) — unlike `scale`, this is not a Chrome-only
+  argument. A 1390×1064 tab captured at 1920×1080 yields 3840×2160 device px
+  and reads back at 1390×1064 afterwards; captured at 420×900 it is
+  **byte-identical** (sha256 `93ffca74…`) to the same page genuinely emulated
+  at 420×900, media query flipped and all. That is the difference from `scale`
+  in one sentence: `scale` re-renders the same layout at more pixels,
+  `renderWidth`/`renderHeight` change what the page *believes* for one
+  capture. The restore holds on the success path, on the throwing path, and
+  over a caller's prior `emulate` (a tab emulated at 777×555 is 777×555 again
+  afterwards, not the real device). Two honest limits ride in the result
+  rather than in a comment: the restore can only put back an override **this
+  toolkit** applied — one set by the DevTools UI, another client, or an older
+  build leaves no record and is reset to the real device — and a capture that
+  TIMES OUT cannot be restored at all, because the `finally` runs while
+  Chrome's own command is still executing and re-resizes the page behind it.
+  `renderRestored: false` (plus `renderRestoreError`) is what the caller gets
+  when the tab is still emulated and they must fix it themselves.
+
+- **`tile` — vertical band capture, stitched losslessly, and AUTO by
+  default.** Three-valued: omitted means one shot when the projection fits and
+  bands when it does not; `false` never bands and refuses instead (the exact
+  pre-1.9.2 behaviour); `true` always bands, even when one shot would have
+  fitted. Only `true` costs a capability (`screenshot.tile`, Chrome only).
+  The headline, a plain call with no flags on a 140,982 CSS px page:
+  **2780×281964 px, 18 bands, 10,818,058 bytes, 17–18 s**, tab healthy
+  afterwards (`[innerWidth, innerHeight, devicePixelRatio]` = `[1390, 1064,
+  2]`, `scrollY` 0) and two runs byte-identical. 281964 is 140982 × 2 exactly:
+  the whole document, nothing dropped. A banded capture is PNG-only and cannot
+  also `returnBase64`; both combinations are refused in 21–31 ms measured,
+  before a single band is captured, with a message naming the band count and
+  the region that forced the decision. Tiling is **vertical only** — a projected WIDTH
+  past the cap is refused (naming the largest scale, or renderWidth, that
+  would fit), not split into a grid, because PNG scanlines are the unit that
+  can be concatenated without decoding the image whole.
+
+- **New result fields.** `scale` is always present. `width`/`height` are
+  **decoded from the encoded bytes** (PNG IHDR, JPEG SOF marker walk) rather
+  than projected, and are **omitted entirely** when the bytes cannot be
+  decoded — absent beats invented. `renderSize`, `renderRestored` and
+  `renderRestoreError` accompany a render-size capture; `tiled: true` and
+  `bands: <n>` are present only on a banded one, so a caller always knows when
+  an image was assembled rather than captured.
+
+- **`src/png.ts`, a streaming lossless PNG band stitcher**, zero runtime
+  dependencies (`node:zlib` is a builtin). Peak RSS is **135.3 MB while
+  writing a 1.42 GB image** (368,640 rows) — 9× the raw pixels of a 157 MB one
+  for 11.7% more memory, because peak tracks band size, not image size (Bun's
+  own floor is 23.6 MB of that).
+  Its output is byte-identical under ffmpeg's raw decode to the source bands
+  concatenated, at every one of PNG's five row filters, and a 2-band stitch of
+  a page that fitted decodes to the identical sha256 as the single shot of the
+  same page. It carries `gAMA`/`cHRM`/`sRGB`/`iCCP`/`pHYs` from the first band
+  and throws on a mismatch: every Chrome capture measured carries an embedded
+  ICC profile, so a stitcher that dropped ancillary chunks — the obvious
+  default — would silently recolour every image it touched.
+
+### Changed
+
+- **Every capture now costs one `Page.getLayoutMetrics` round trip, including
+  the plain default one.** That is the change that closed the hazard. The
+  plain path was the one path that built no clip, so the encode guard never
+  ran on it, while `captureBeyondViewport: true` is hardcoded for every
+  capture — meaning an ordinary long page, hit with an ordinary flagless
+  screenshot, was already capturing beyond the viewport with nothing standing
+  between it and the hang. Nothing else about that path moved: it still sends
+  **no `clip` key at all**, and every step of this release A/B'd the common
+  path against its own parent commit's binaries on the same live tab —
+  default, `fullPage`, `scale 2`, `jpeg`, element-clip and `tile:false` all
+  came back byte-identical.
+
+- **`savePath` outside the artifact dir now works.** The destination directory
+  is created from the output path's own dirname rather than always
+  `CDP_ARTIFACT_DIR`; previously a `savePath` in a non-existent directory
+  failed `ENOENT` while `CDP_ARTIFACT_DIR` was created for nobody.
+
+- **The default filename's stamp is the capture's START**, not its end: a
+  banded capture writes as bands arrive and has no finished image to name a
+  file after, and one naming path is easier to trust than two.
+
+- **A new state-file type**, `${CDP_ARTIFACT_DIR}/viewport-<scheme>-<targetId>.json`,
+  a sibling of the lease and origin files. A render-size capture must restore
+  the caller's *previous* override, and a `PageDriver` lives for exactly one
+  call (under the CLI, one process), so the record has to outlive the
+  connection the same way a lease does — measured: an `emulate` override set
+  in one process is still in force when read from another.
+
+### Fixed
+
+- **An element-clipped `take_screenshot` returned the wrong region of the page
+  whenever the element was not already on screen.** `--selector` and `--uid`
+  both, at every page height tried. The mechanism is a frame mismatch worth
+  learning on its own: `DOM.getBoxModel` answers in the **viewport** frame (its
+  quad matched `getBoundingClientRect()` to the pixel every time), but
+  `captureBeyondViewport: true` — hardcoded on every capture here — makes
+  Chrome read `clip.x`/`clip.y` as **document** coordinates. The driver scrolled
+  the element into view with `DOM.scrollIntoViewIfNeeded` and then handed
+  Chrome the element's now-small *on-screen* y as if it were its position in
+  the document, so the capture landed within one viewport height of the top of
+  the page no matter how far down the element really was. Measured on
+  Chrome 151.0.7922.76, a 10,000 CSS px page with the target at y=5000: the
+  scroll settled at `scrollY` 4593 with `rectTop` 407, and the returned
+  2780×500 PNG was `document[407..657]` — a flat slab of page background with
+  no part of the element in it. Identical failure at the two sizes this bug was
+  first reported at, 16,578 px (`scrollY` 14593) and 140,982 px (`scrollY`
+  69593). Starting the same call from `scrollY` 4950 instead — element already
+  visible at `rectTop` 50, so the driver's own scroll is a no-op — returned
+  `document[50..300]`: the document's top banner for its first 100 CSS px, then
+  background, boundary on the predicted pixel. **The fix is the frame
+  conversion**: the page's scroll offset is added to the box-model quad, in CSS
+  px (`cssVisualViewport.pageX`/`pageY`), read **after** the scroll settles and
+  off the same single `Page.getLayoutMetrics` every capture already pays for —
+  reading it before the scroll would correct by 0 on a freshly navigated tab
+  and change nothing. Those same three page heights now return the element
+  itself, and the three starting scroll positions 0 / 4950 / 9000 return one
+  identical sha256 `54b96705…` instead of two different wrong images. `scale`
+  (5560×1000 at `scale 2`), `renderWidth`/`renderHeight` (1600×500 at 800×600,
+  `renderRestored: true`), `tile` and the `uid` path all ride the corrected
+  rect unchanged, and the short-page control — element inside the initial
+  viewport, no scroll needed, offset 0 — is byte-for-byte what it was.
+  **Two honest notes.** First, the units are a live trap: on a scrolled page
+  `visualViewport.pageX`/`pageY` come back in **CSS** px (700/4593) while
+  `clientWidth`/`clientHeight` on that very same rect are **device** px
+  (2780×2128), and only `layoutViewport` reports the offset in device px
+  (1400/9186) — so "no `css` prefix means device px" is false for exactly the
+  fields this fix reads, and a plausible implementation that divided them by
+  the pixel ratio would have halved the correction. Second, this release's own
+  regression check could not have caught it: the element-clip A/B recorded
+  under *Changed* above compared each commit against its parent's binaries and
+  came back byte-identical **because both sides were wrong the same way** — a
+  same-vs-same check is blind to a bug older than both of its arms.
+  `DOM.scrollIntoViewIfNeeded` was kept rather than dropped, and that was
+  measured too, not assumed: with `captureBeyondViewport` nothing has to be on
+  screen to be captured, but on a fixture whose target fills itself from an
+  `IntersectionObserver`, the capture with the scroll reads "LAZY CONTENT
+  LOADED" and the same capture without it returns the unloaded placeholder in
+  the correct region — the same caveat the tiling notes below record, from the
+  other side. WebDriver BiDi never had this defect: it passes
+  `clip: {type: "element"}` and does no coordinate arithmetic of its own.
+
+- **`emulate {clearOverrides: true}` reported `"cleared": true` while clearing
+  nothing.** Reproduced across three separate CLI processes: process A set
+  802×601, process B cleared and reported success, process C read back
+  `[802, 601]`. `Emulation.clearDeviceMetricsOverride` only reverts to the real
+  device when the clearing connection is also the connection that *set* the
+  override — and under this toolkit's per-call connection lifetime it
+  essentially never is, so this was the common case, not an edge case. The
+  driver now reads the tab's currently effective size, re-asserts that exact
+  size on its own connection (a value the caller cannot observe changing,
+  whose only job is to take ownership), and then clears; the same trace now
+  reads back `[1390, 1064]`, the real device. If any step of that sequence
+  throws, the call throws too rather than returning a false success, and the
+  viewport record is deliberately left in place so a later capture does not
+  read "no record" as "nothing to restore".
+
+### Measured, not assumed — the numbers this release ships on
+
+- **16384 device px per side, both axes, clipped and unclipped alike.**
+  16384×1600 encodes in 266 ms; 16400×1600 — sixteen pixels more — never
+  answers (60 s probe cap). With no `clip` key at all: 2560×16384 succeeds in
+  217 ms, 2560×24000 hangs. **It is not an area limit:** 8192×8192 (67,108,864
+  px) succeeds in 1.3 s while 16400×1600 (26,240,000 px, 2.6× less) hangs. The
+  cap is also in DEVICE px, so a CSS clip of 8200×800 at `deviceScaleFactor: 2`
+  hangs identically to asking for 16400×1600 directly.
+- **Band tiling is visually clean, and this was falsification-tested rather
+  than assumed.** A `position: fixed` header present in the top band appears
+  **zero** times in a band 8000 px down; a `position: sticky` header appears
+  only in the band containing its true document position. Seams are row-exact
+  — band A ends on ROW 039, band B begins on ROW 040, no duplicate, no gap.
+  Clipped bands are byte-identical across three different real scroll
+  positions, so a stitcher never has to manage scroll. `clip.y` is always CSS
+  px and `scale` only multiplies resolution, so the two compose without
+  rescaling offsets. Content-verified end to end on the 140,982 px page: all
+  **71** label bands land at exactly their expected rows across 9 bands and 8
+  seams.
+- **The honest caveat.** A page that loads content only on real scroll —
+  lazy images, virtualized lists, infinite scroll — renders **blank** in bands
+  the real viewport never reached. Measured directly: a page whose
+  `IntersectionObserver` had loaded 9 of 300 rows still reported 9 after a
+  deep-band capture, and the deep band was uniform `#222`.
+  `captureBeyondViewport` does not trigger an `IntersectionObserver`. This is
+  a property of the source page, not a bug in the stitch, and it is not
+  fixable here — which is exactly why an auto-tiled capture reports `tiled`,
+  so a caller knows to reason about it (pre-scroll the page, or disable
+  virtualization, before capturing).
+- **Two corrections to earlier internal notes, kept rather than quietly
+  dropped.** (1) At 140,982 CSS px the *old* code did not hang: it failed in
+  about a second with `Page.captureScreenshot: Page is too large.` and left
+  the tab healthy. The hang-and-wedge lives at *modest* overshoot — the 9000
+  CSS px page above. Both are failures, but "it hangs at 140,982" is not what
+  this Chrome build does. (2) A wedged tab is **not** recovered by
+  `emulate --clearOverrides`: measured in order, clearing reports success and
+  the tab stays 1390×9000, an explicit `emulate --width/--height` recovers it,
+  and clearing again puts it *back*. Only a reload actually clears it. The
+  renderer's real viewport is what the abandoned capture resized, so
+  "clear to the real device" lands on the wrong size.
+
+### Notes
+
+- Tool count is unchanged at **45**. `take_screenshot` grew four arguments;
+  no tool was added, renamed, or removed.
+- **Firefox/BiDi does not declare `screenshot.scale` or `screenshot.tile`**,
+  and for two different reasons stated plainly rather than dressed up as
+  design: `browsingContext.captureScreenshot` genuinely has no scale
+  parameter, while band tiling is *probably* implementable there
+  (`clip: {type: "box"}` exists) but every property it rests on — does a box
+  clip render past the viewport, is `clip.y` CSS px, do fixed elements repeat
+  per band, are seams pixel-exact — was measured on Chrome and nowhere else,
+  because no Firefox was driven for it. `screenshot.renderSize` **is**
+  declared by both. Auto-tiling never fires on a backend without
+  `screenshot.tile`, so Firefox behaviour is unchanged.
+- New tests: **117**, in `test/screenshot-scale.test.ts` (81) and
+  `test/png.test.ts` (36) — 736 pass / 0 fail across 21 files, up from 619.
+  Both new suites were mutation-checked rather than merely green: 13 deliberate
+  mutants of `src/png.ts` and 6 of the tiling arithmetic were each killed,
+  and the three mutants that survived are documented in the source as provably
+  equivalent rather than silently "fixed" later.
+- `docs/social-preview.html` and `docs/demo.tape` carry no version string and
+  needed no re-render for this release.
+
+## [1.9.1] - 2026-08-10
+
+`list_network_requests`, `get_network_request`, and `list_console_messages` now
+observe MV3 background service workers, not just pages: the outbound fetch a
+worker makes to a real backend is a first-class capture target, not something
+you have to fake with an `evaluate_script` monkeypatch. Tool count stays 45 —
+the three tools grow a `worker:` arm, no new tool. One seat (N1) landed it,
+every protocol claim below probed against a live Chrome 151 before being built
+on.
+
+### Added
+
+- **The three console/network reader tools accept `target: "worker:<substring>"`
+  or a bare worker target id**, alongside the page selectors they already took.
+  Chrome only (capability `worker.targets`) — Firefox refuses the arm from its
+  real capability set before launching a browser that could never have served
+  the call. The allowlist that grants the arm, `WORKER_CAPABLE_TOOLS` in
+  `src/workers.ts`, now names four tools (`evaluate_script` plus these three);
+  it is the single source of truth for both the refusal messages and
+  `test/manifest-grammar-drift.test.ts`'s exclusion property, so a fifth tool
+  cannot silently advertise `worker:` without a deliberate edit here.
+
+- **A worker capture LISTENS instead of reloading.** Measured on Chrome
+  151.0.7922.109: `Network.enable` and `Runtime.consoleAPICalled` work
+  identically on a direct worker session to how they work on a page — all four
+  events the recorder persists (`requestWillBeSent`, `responseReceived`,
+  `loadingFinished`, `loadingFailed`) arrive, and `Network.getResponseBody`
+  serves the body — but `Page.enable`/`Page.reload` **do not exist** on a
+  worker session (`-32601 'Page.enable' wasn't found`). A page capture is
+  reload-driven; a worker capture cannot be, so it opens the worker's own CDP
+  session and listens for `durationMs` instead. `captureWindow()`'s branch is
+  keyed off the resolved target's type, not the selector's shape, so a bare
+  worker id takes the listen path too.
+
+- **Recording a worker keeps it alive for the length of the capture — a
+  deliberate side effect, not a bug.** A held CDP session suppresses MV3 idle
+  eviction; measured in both directions with the same polling loop so
+  "stayed alive" isn't an artifact of how the poll works: with the recorder's
+  session held, the worker is still present in `/json/list` and still emits a
+  fresh `Network.requestWillBeSent` for a triggered fetch at t+60s; once the
+  session detaches, the same worker idle-evicts within ~30s. Documented in the
+  three tools' manifest descriptions and asserted in both directions by the
+  live smoke, not left implicit.
+
+- **`wake` (default `true` on a capture) is REFUSED on a read-only call and on
+  a bare target id, rather than accepted and ignored.** Measured: a worker
+  that idle-evicts and restarts comes back under a brand-new target id (probed
+  restart: `C43F0A18...` → `1F7D3C59...` for the same extension). The recorder
+  keys its buffer file by target id, so waking a worker on a *read* would hand
+  back a live worker with an empty buffer — "0 requests" for a capture that
+  really did record some, a zero shaped like an answer. A wake therefore only
+  makes sense when a capture is being started, and only from a
+  `worker:<substring>` selector, since an evicted worker's old id no longer
+  exists to name. The refusal messages (`workerWakeMisuseMessage`,
+  `workerBufferReadMissMessage` in `src/workers.ts`) teach the id-re-mint fact
+  rather than just rejecting the argument.
+
+- **Known limitation, stated rather than silently absent: a worker woken BY a
+  capture has already run its top-level code by the time the recorder
+  attaches**, so a fetch the worker makes at startup can be missed. Trigger
+  the request you want to observe (a message, an alarm) after the capture
+  starts rather than relying on the worker's own boot-time fetch. Fixing this
+  needs `Target.setAutoAttach{waitForDebuggerOnStart}` on a held browser
+  session, a different feature; the limitation is documented in
+  `recorder.ts`'s header and in the three manifest descriptions instead.
+
+- **`get_console_message` reads the same worker-keyed buffer (so its miss
+  message matches what it reads) but is deliberately NOT in
+  `WORKER_CAPABLE_TOOLS`** — it already resolved worker targets through the
+  1.9.0 arm, routing it through the read-path resolver only sharpens its miss
+  message; advertising it as worker-capable was out of scope, and the drift
+  test pins the advertised list at four.
+
+### Measured, not assumed — the protocol facts this release ships on
+
+- **`Page.enable`/`Page.reload` are `-32601` on a worker session** — the
+  single measurement that shapes the implementation: a worker window cannot
+  be reload-driven, so it listens.
+- **A held session suppresses MV3 idle eviction; detach restores it** —
+  confirmed in both directions with the same polling loop, including a
+  post-hold evaluate and a fresh `Network.requestWillBeSent` at t+60s, so
+  "alive" means genuinely live, not a stale listing entry.
+- **A worker's target id is re-minted on every restart, never stable** — this
+  is why `wake` is refused on reads and on bare ids rather than silently doing
+  the wrong thing.
+- **Two things a caller might reach for instead don't work, for ordinary
+  JavaScript reasons, not a service-worker-specific one.** A value bound at
+  module top level is not visible from `evaluate_script`'s global scope
+  (plain lexical scoping, identical in a page); assigning `self.fetch`
+  afterward cannot rebind a `fetch` reference the module already captured
+  (closure semantics, also identical in a page). `Network`-domain recording
+  on the worker's own session observes what the code ACTUALLY SENT and needs
+  neither. (An earlier field report attributing this to service-worker eval
+  semantics was a misdiagnosis of an outdated loaded extension build, not a
+  real capability gap — see the stale-build tip below.)
+
+### Notes
+
+- Tool count is unchanged at **45** — this release grew the `target` grammar
+  on three existing tools, not the tool list.
+- `docs/social-preview.html` and `docs/demo.tape` carry no version string and
+  needed no re-render for this release.
+- Before deep-debugging an extension that "the toolkit can't see": verify the
+  loaded build is current with
+  `evaluate_script {target:"worker:<id>", expression:"chrome.runtime.getManifest().version"}`.
+  An outdated unpacked build left over from a prior load mimics every symptom
+  in this release's "measured facts" section above.
+- New tests: 20 in `test/worker-capture.test.ts`, 3 more in
+  `test/manifest-grammar-drift.test.ts` (allowlist rescoped from an
+  evaluate_script-only exclusion to the four-tool `WORKER_CAPABLE_TOOLS`
+  allowlist), and new live scenarios in `test/extension-smoke.ts` covering the
+  worker fetch/console capture, the eviction pair in both directions, and the
+  capture-path wake (proven by the fixture's own start counter, `starts: 2 ->
+  3`, never by `ServiceWorker.startWorker`'s result, which reports empty
+  success even for a scope that doesn't exist) — 31/31 assertions, up from the
+  1.9.0 baseline of 20.
+
 ## [1.9.0] - 2026-08-09
 
 Four complaints from a field agent driving an MV3 extension, closed without adding
@@ -870,6 +1376,7 @@ First public release.
 - Zero runtime dependencies in the CDP/CLI layer (Node's global `WebSocket` + `fetch`). The MCP server adds only `@modelcontextprotocol/sdk`; `lighthouse_audit` is the sole non-CDP tool and shells out to `npx lighthouse`.
 - Runtime: Bun ≥ 1.1 (recommended) or Node ≥ 22 (for the global `WebSocket`). Requires Chrome/Chromium started with `--remote-debugging-port=9222`.
 
+[1.9.1]: https://github.com/sblattj/cdp-toolkit/releases/tag/v1.9.1
 [1.9.0]: https://github.com/sblattj/cdp-toolkit/releases/tag/v1.9.0
 [1.8.0]: https://github.com/sblattj/cdp-toolkit/releases/tag/v1.8.0
 [1.7.0]: https://github.com/sblattj/cdp-toolkit/releases/tag/v1.7.0