cdp-toolkit 1.9.1 → 1.9.5

package/CHANGELOG.md

@@ -5,6 +5,440 @@ 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.5] - 2026-08-11
+
+**Documentation and stale code-comment clarifications; NO behavior changes since 1.9.4.** Two
+updates. First, the Firefox `fullPage` screenshot gap that 1.9.2's docs hedged as "unmeasured" is
+now resolved: measured against a real Firefox 153.0.3 through the shipped CLI in attach mode, a
+20,000px-tall page captured with `take_screenshot --fullPage true` came back as a single
+1366×20000 PNG at scale 1 — verified complete top-to-bottom (a marker at y=0, a marker at y=20000,
+an unbroken ruler through the middle, no truncation). Firefox has no equivalent of Chrome's
+16384-device-px encode cap, so `browsingContext.captureScreenshot(origin:"document")` returns the
+whole long page in one BiDi call and never needs the band-tiling Chrome's cap requires — tiling
+exists solely to route around that cap, and Firefox doesn't have one, so `screenshot.tile` is a
+non-issue for Firefox correctness rather than a gap. `screenshot.scale` remains a genuine,
+unrelated Firefox gap: BiDi's `captureScreenshot` has no scale parameter at all, so Firefox
+captures stay 1x only. That same measured result also replaces three stale "unmeasured"/"probably
+implementable" comments in `src/bidi/driver.ts` describing `screenshot.tile` — comments only, no
+logic changed, since `screenshot.tile` was already correctly left undeclared and `tile:true`
+already correctly refused on Firefox; only the *reasoning* in the comments was stale. Second, this
+release also gives a changelog entry to doc-only additions that landed on top of 1.9.4 without one:
+Linux and remote-over-SSH attach guidance, and a `claude mcp add` one-liner, both in README.md's
+setup instructions.
+
+### Added
+
+- README.md: Linux and remote-over-SSH `--connect`/`CDP_FIREFOX_ENDPOINT`
+  attach guidance, and a `claude mcp add cdp-toolkit --scope user -- bun run
+  "$(pwd)/src/mcp.ts"` one-liner in the quick-start block.
+
+### Changed
+
+- README.md's "Honest capability gaps" list and CONTRACT.md's `screenshot.ts`
+  module row: the Firefox `tile:true`/`screenshot.tile` hedge ("unmeasured
+  gap... probably implementable") is replaced with the measured result above.
+  `scale`'s status is unchanged and still called out as a genuine gap.
+- `src/bidi/driver.ts`: three comment blocks (the `BIDI_CAPABILITIES` header
+  comment, the `capture()` method's `tile:true` refusal comment, and the
+  per-capability doc-comment list) rewritten from "unmeasured"/"probably
+  implementable" to the measured result above. No capability declarations, no
+  refusal logic, and no error-message text changed — comments only.
+
+### Notes
+
+- Tool count unchanged at **45**; no tool added, renamed, or removed.
+- Version bump only: `package.json` and `src/mcp.ts`'s `VERSION` constant move
+  1.9.4 → 1.9.5. No runtime behavior changed anywhere in this release.
+
+## [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

package/CONTRACT.md

@@ -68,15 +68,72 @@ export async function click(args: ClickArgs): Promise<unknown>;
 
 ## Artifact + state locations
 
-- Artifacts (PNG, trace, heapsnapshot, lighthouse report): write under `ARTIFACT_DIR` = `process.env.CDP_ARTIFACT_DIR ?? "/tmp/cdp-toolkit"`. `mkdir -p` it. Filenames: `<tool>-<targetIdShort>-<isoish>.<ext>` where you derive a stamp from `Date.now()` at call time (allowed in normal runtime; only the Workflow *script* sandbox forbids it, modules run normally).
+- Artifacts (PNG, trace, heapsnapshot, lighthouse report): write under `ARTIFACT_DIR` = `process.env.CDP_ARTIFACT_DIR ?? "/tmp/cdp-toolkit"`. `mkdir -p` it. Filenames: `<tool>-<targetIdShort>-<isoish>.<ext>` where you derive a stamp from `Date.now()` at call time (allowed in normal runtime; only the Workflow *script* sandbox forbids it, modules run normally). **`mkdir -p` the DIRNAME OF THE PATH BEING WRITTEN, not `ARTIFACT_DIR` unconditionally** (1.9.2): a tool taking a caller-supplied destination (`take_screenshot`'s `savePath`) otherwise creates a directory nobody writes to and then fails `ENOENT` on the one that matters.
 - Selected-target state file (for `select_page`): `process.env.CDP_STATE_DIR ?? "/tmp/cdp-toolkit"` + `/selected`. Contains a bare targetId. `resolveTarget` does NOT read it; tools may read it as a fallback default if you choose, but the simplest correct behavior is fine.
 - Recorder buffers: `${ARTIFACT_DIR}/rec-<targetId>.jsonl`.
 - Screencast spool: `${ARTIFACT_DIR}/screencast-<targetIdShort>-<isoish>/` holding `frame-NNNNNN.jpg|png` plus the generated `frames.ffconcat`. Deleted on a successful encode; **kept, and named in the error, when ffmpeg fails**, so the frames can be re-encoded by hand instead of lost. Output video: `${ARTIFACT_DIR}/screen-recording-<targetIdShort>-<isoish>.mp4`.
 - Lease files: `${ARTIFACT_DIR}/lease-<backend>-<targetId>.json`, one per leased tab, backend is `chrome` or `firefox`. Written with the `wx` exclusive-create flag so two simultaneous claims cannot both win. Keyed by backend plus id because a CDP targetId and a BiDi context id are not disjoint by construction. Carries an `auto?: boolean` field (absent, and read as `false`, on any record older than 1.7.0): `true` means the gate itself acquired it under `CDP_REQUIRE_LEASE` and it is usable by any call from the owning pid with no token; `false` means it was claimed explicitly (`claim_page` or `new_page{claim:true}`) and demands its token even from that same pid.
+- Viewport records (`src/driver.ts`, added 1.9.2): `${ARTIFACT_DIR}/viewport-<scheme>-<targetId>.json`, one per target whose device-metrics override this toolkit applied, written by both drivers' `emulate()` and cleared by a confirmed `clearOverrides`. Keyed by uid scheme for the same reason lease files are keyed by backend: a CDP targetId and a BiDi context id are not disjoint by construction. It exists because `take_screenshot`'s `renderWidth`/`renderHeight` must restore the caller's PREVIOUS override, and neither a private field nor the connection can hold that: a `PageDriver` is `lifetime: "per-call"` (under the CLI, one process per call) while a device-metrics override **outlives the connection that set it** — measured, an override set in one process reads back in another. Note the honest limit this record defines: the driver can only restore an override it recorded, so one applied by the DevTools UI, another client, or a pre-1.9.2 build leaves no file and a render-size capture resets it to the real device. There is no CDP or BiDi command that reads a device-metrics override back, so a driver genuinely cannot discover it.
 - Origin files (`src/origins.ts`): `${ARTIFACT_DIR}/origin-<backend>-<targetId>.json`, one per tab this toolkit itself created (never written for a tab merely claimed). Same exclusive-create discipline as lease files, same directory, and it deliberately OUTLIVES the lease: `release_page`, expiry, and reclamation never touch it, only the tab closing does (reaped on the next `list_pages`/`list_origins` read). This is what `release_page` and reap both consult to decide whether closing a given tab is this toolkit's call to make; see `src/reap.ts`'s header for the four conditions that gate a reap close. As of 1.8.0 an `expired` lease qualifies for that close only past `ttlMs + CDP_REAP_GRACE_MS` (default 45 extra minutes) — `list_leases`' `stale`/reclaimable reading is unchanged at `ttlMs`; only the destructive close moved later. `dead-pid` is unaffected by grace.
 - Beacon sessions (`src/activity.ts`, `src/cdp/driver.ts`): a `BeaconSessions` pool of held Chrome connections, one per tab with an installed activity beacon, bounded at 32 with oldest-first eviction — the same module-scope pattern `recorder.ts`/`network_mock.ts` already use for their own persistent per-target sessions. Exists only because `Page.addScriptToEvaluateOnNewDocument`'s registration dies with the connection that made it (verified against a live browser, not assumed), so surviving navigation under this toolkit's per-call lifetime requires holding a connection open; eviction degrades (the current document's listeners keep answering, only the next navigation's re-arm is lost) rather than breaking. Firefox needs no equivalent: its `LifetimeModel` is `"session"`, so a `script.addPreloadScript` registration on the one memoized BiDi connection per port already lives as long as that connection does.
 - The browser-session connection (`src/tools/browser-session.ts`): one lazily-opened, module-scoped connection to the CDP browser endpoint (not a page endpoint), held open for the process's life, backing `wait_for_download` and `grant_permissions`. Opened only on first use of either tool, so a session that never touches downloads or permissions pays nothing. Exists because `Browser.setDownloadBehavior` and `Browser.grantPermissions` were measured — probed against a real browser before either tool was written — to NOT persist past the arming/granting client's disconnect, which this toolkit's per-call connection lifetime would otherwise hit on every single call. Both tools are therefore MCP-server-only capabilities, the same category as `performance_start_trace`/`stop_screen_recording`'s persistent-connection requirement, for the same underlying reason.
 
+## Firefox backend: launch vs. attach (`src/backend.ts`, `src/bidi/driver.ts`)
+
+The Firefox/BiDi backend runs in one of two modes, selected by `resolveBackend(argv, env)`
+(`src/backend.ts`) and shared by `cli.ts` and `mcp.ts`. The two modes differ in exactly one
+thing — process ownership — and that difference must never blur:
+
+- **LAUNCH** (default, no endpoint resolved): `startFirefoxSession()` calls `launchFirefox()`
+  (`src/bidi/launch.ts`), which owns the spawned process end to end. `dispose()` closes the BiDi
+  driver **then** kills the process, in that order, so no invocation can leak a process.
+- **ATTACH** (an endpoint was resolved): `startFirefoxSession({ endpoint })` calls
+  `createFirefoxDriverForEndpoint(wsUrl)` (`src/bidi/driver.ts`) directly — no `launchFirefox`,
+  no process handle at all. `dispose()` is `driver.dispose()` only: it sends `session.end` (see
+  below) then closes the socket. **It must never call a process `close()`; there is no process
+  to close.** The Firefox the user started outlives every attach session against it.
+
+**Config surface** (`resolveFirefoxEndpoint`, `normalizeBidiEndpoint`, `resolveBackend` in
+`src/backend.ts`):
+
+- env `CDP_FIREFOX_ENDPOINT`, CLI flag `--connect <endpoint>` — flag beats env (same precedence
+  as `--browser`/`CDP_BROWSER`). An empty env value counts as unset, so an exported-but-blank
+  `CDP_FIREFOX_ENDPOINT` does not force attach mode.
+- `<endpoint>` accepts three spellings, all normalized by `normalizeBidiEndpoint` to a ws URL:
+  bare port (`9223` → `ws://127.0.0.1:9223/session`), `host:port` (`127.0.0.1:9223` → same
+  shape), or a full `ws://`/`wss://` URL (used verbatim; a bare origin with no path or `/` gets
+  `/session` appended, since Firefox serves BiDi there). Invalid input (bad URL, non-numeric,
+  port outside 1–65535) throws with the accepted spellings named in the message rather than
+  reaching the transport as an opaque connect timeout.
+- An endpoint **implies** `kind: "firefox"` in the returned `BackendSelection` — there is nothing
+  else `--connect`/`CDP_FIREFOX_ENDPOINT` could mean. `resolveBackend` throws
+  (`"--connect / CDP_FIREFOX_ENDPOINT is a Firefox attach option and is not valid with the
+  chrome backend"`) when an endpoint is present **and** the browser was explicitly set to chrome
+  (`--browser chrome` or `CDP_BROWSER=chrome`); an endpoint alongside no explicit `--browser` (or
+  an explicit `--browser firefox`) silently selects Firefox as always.
+- `stripConnectFlag` mirrors `stripBrowserFlag`: `cli.ts` strips `--connect <value>` out of argv
+  before tool-arg parsing so it never reaches a tool's own args.
+
+**The single-BiDi-session constraint.** Firefox allows exactly one active WebDriver BiDi session
+per process; a second `session.new` against the same Firefox fails with `session.new: Maximum
+number of active sessions` (verified against Firefox 153.0.3). `getConnection` in
+`src/bidi/driver.ts` catches that specific message and rethrows via the local `driverError`
+helper (code `"disconnected"`) naming the endpoint and explaining the fix (close the other
+client, or restart Firefox), instead of letting the raw wire message reach the caller. Closing the BiDi socket alone does
+**not** free the slot — only `session.end` does, which is why `BidiBrowserDriver.dispose()`
+sends `session.end` (best-effort, swallowing any error — harmless if the socket is already gone)
+**before** closing the connection. A client that dies without a clean dispose (e.g. `SIGKILL`)
+leaves the slot occupied until Firefox restarts: this toolkit does not and cannot force-end a
+session it does not own, since there is no id to end. This is why a colliding attach now fails
+fast with an actionable error instead of hanging forever (the pre-1.9.4 behavior).
+
+**Driver identity moved from port to endpoint.** `BidiBrowserDriver` is keyed by a BiDi ws
+endpoint string (`this.endpoint`), not a `port: number`: a launched Firefox's endpoint is
+`ws://127.0.0.1:${port}/session` (via `createFirefoxDriver(port)`), while an attach endpoint may
+carry a different host, port, or path entirely (via `createFirefoxDriverForEndpoint(wsUrl)`).
+Both funnel into the same `connections: Map<string, BidiConnection>` keyed by that string. Any
+future change to connection identity must account for both call shapes.
+
 ## The element-reference scheme (READ if you touch snapshot or input)
 
 A `Uid` **is** a CDP `backendDOMNodeId` (a number). This makes refs stateless:
@@ -114,7 +171,7 @@ A `Uid` **is** a CDP `backendDOMNodeId` (a number). This makes refs stateless:
 | `src/tools/evaluate.ts` | `evaluate_script`→`evaluateScript` | `Runtime.enable` + `Runtime.evaluate` (`returnByValue`, `awaitPromise`). Support optional `args` via `Runtime.callFunctionOn` on a uid/selector. Surface `exceptionDetails` as thrown error. |
 | `src/tools/snapshot.ts` | `take_snapshot`→`takeSnapshot` **+ export `resolveUid`** | a11y tree + ref scheme above. |
 | `src/tools/input.ts` | `click`→`click`, `hover`→`hover`, `drag`→`drag`, `fill`→`fill`, `fill_form`→`fillForm`, `type_text`→`typeText`, `press_key`→`pressKey`, `upload_file`→`uploadFile` | imports `resolveUid` from `./snapshot.ts`. `hover`=mouseMoved. `drag`=press→move→release. `fill`/`type_text`=focus + `Input.insertText` (fast) or `dispatchKeyEvent`. `press_key`=`Input.dispatchKeyEvent` (support modifiers + named keys). `upload_file`=`DOM.setFileInputFiles` on resolved node. `fill_form`=array of {uid|selector,value}. |
-| `src/tools/screenshot.ts` | `take_screenshot`→`takeScreenshot` | `Page.captureScreenshot`. Support `{ format:'png'|'jpeg', quality, fullPage, uid?/selector? (element clip via getBoxModel), savePath? }`. Write to ARTIFACT_DIR, return `{ path, bytes, format }` and optionally base64 when `{ returnBase64:true }`. |
+| `src/tools/screenshot.ts` | `take_screenshot`→`takeScreenshot` | `Page.captureScreenshot`. Support `{ format:'png'|'jpeg', quality, fullPage, uid?/selector? (element clip via getBoxModel), savePath? }`. Write to ARTIFACT_DIR, return `{ path, bytes, format }` and optionally base64 when `{ returnBase64:true }`. **As of 1.9.2 also `scale` (Chrome-only capability `screenshot.scale`, rides `clip.scale`), `renderWidth`/`renderHeight` (BOTH backends, `screenshot.renderSize`, an `Emulation.setDeviceMetricsOverride` held for one capture and undone in a `finally` against the viewport record above), and `tile` (three-valued, `true` costs `screenshot.tile`).** Firefox declares neither `screenshot.scale` (BiDi's `captureScreenshot` has no scale parameter, so Firefox captures are always 1x) nor `screenshot.tile` — but the tile gap is moot, not a limitation: Firefox has no Chrome-style 16384-device-px encode cap to band around, so `browsingContext.captureScreenshot(origin:"document")` returns an arbitrarily long `fullPage` capture in one shot. Measured against Firefox 153.0.3: a 20,000px-tall page came back as a single 1366×20000 PNG at scale 1, verified complete top-to-bottom (no truncation). Two rules the size arithmetic imposes on anyone touching this path. **(a) Guard the projection, not the knob:** output px are `ceil(css × scale × devicePixelRatio)`, Chrome cannot encode past 16384 device px per side, and past that `Page.captureScreenshot` NEVER ANSWERS while `captureBeyondViewport` (hardcoded true) leaves the renderer resized to the clip — a wedged tab a `finally` cannot undo, because the client-side timeout fires while Chrome's command is still running. So `Page.getLayoutMetrics` is fetched and the projection checked on EVERY capture, including the plain no-clip one; a guard conditioned on the feature that motivated it (`scale !== 1`) has already let two wedges through. **(b) Bands are lazy and vertical:** past the cap the driver hands the tool layer a `BandedCapture` whose Nth `Page.captureScreenshot` runs only when the Nth band is pulled (accumulating them into an array would typecheck, pass on a small page, and hold 1.4 GB on a large one), stitched by `stitchPngBandsToFile` in `src/png.ts` — a zero-dependency streaming PNG stitcher (`node:zlib`), not an MCP tool and deliberately absent from the `TOOLS` registry. Vertical only: PNG scanlines are the one axis concatenable without decoding the image, so an over-WIDE projection is refused, never split. |
 | `src/tools/emulation.ts` | `emulate`→`emulate`, `resize_page`→`resizePage` | `Emulation.setDeviceMetricsOverride` (width,height,deviceScaleFactor,mobile), `Emulation.setUserAgentOverride`, `Emulation.setCPUThrottlingRate`, `Emulation.setEmulatedMedia`, `Network`-based throttling via `Network.emulateNetworkConditions`. `resize_page` = device metrics width/height. |
 | `src/tools/dialogs.ts` | `handle_dialog`→`handleDialog` | `Page.enable`, subscribe `Page.javascriptDialogOpening`, respond with `Page.handleJavaScriptDialog({ accept, promptText })`. Support a "wait for next dialog then handle" mode and an "auto-handle for N ms" mode. |
 | `src/tools/recorder.ts` + `src/tools/console.ts` + `src/tools/network.ts` | console: `list_console_messages`→`listConsoleMessages`, `get_console_message`→`getConsoleMessage`; network: `list_network_requests`→`listNetworkRequests`, `get_network_request`→`getNetworkRequest` | **Owned by one agent.** `recorder.ts` exports `startRecorder(target, {network,console}): Promise<{stop()}>` that opens a persistent `openPage` conn, enables `Network`+`Runtime`(+`Log`), and appends events to `rec-<targetId>.jsonl`. console/network `list_*` read that file (and support a one-shot `{ reload:true, durationMs }` mode that records fresh by reloading the page and capturing for a window, then returns). `get_*` filter by id/url. Document the recorder model at the top of `recorder.ts`. **As of 1.9.1, the same three tools also accept a `worker:<substring>` target** (Chrome only, capability `worker.targets`; MV3 service/shared workers), resolved via `resolveRecorderTarget`/`resolveWorkerSelector` in `src/workers.ts` rather than `resolveTarget`. Because `Page.enable`/`Page.reload` do not exist on a worker session (measured: `-32601`), `captureWindow()` skips the reload for a worker-typed resolution and LISTENS on the held connection for `durationMs` instead — keyed off the resolved target's type, not the selector's shape, so a bare worker id takes the same branch as a `worker:` selector. Holding that session is a deliberate side effect, the same pattern as the beacon sessions below: it SUPPRESSES the worker's MV3 idle eviction for as long as the capture runs (measured: alive and still emitting events at 60s held, evicted ~30s after detach). `wake` (default `true` on a capture) restarts an evicted worker first, but is refused on a read-only call and on a bare target id, because a restart mints a NEW target id and the buffer is keyed by the old one — see `workerWakeMisuseMessage` in `src/workers.ts`. |