cdp-toolkit 1.9.1 → 1.9.5

package/src/cli.ts

@@ -23,17 +23,20 @@
  *   - --list  -> all tool names (one per line) to stdout, exit 0.
  */
 import { TOOLS, TOOL_NAMES, type ToolName } from "./index.ts";
-import { resolveBrowserKind, stripBrowserFlag, startFirefoxSession } from "./backend.ts";
+import { resolveBackend, stripBrowserFlag, stripConnectFlag, startFirefoxSession } from "./backend.ts";
 import { toolAvailability } from "./capabilities.ts";
 import { FIREFOX_TOOLS } from "./firefox-tools.ts";
 import { leaseFromArgs, withLeaseScope } from "./leases.ts";
+import { MANIFEST } from "./manifest.ts";
 
 const USAGE = `cdp-toolkit: raw single-target CDP, 29-tool chrome-devtools-mcp parity, plus a Firefox backend over WebDriver BiDi.
 
 Usage:
-  bun run src/cli.ts <tool> [--browser chrome|firefox] [--target <sel>] [--json '<obj>'] [--<key> <value> ...]
+  bun run src/cli.ts <tool> [--browser chrome|firefox] [--connect <port|host:port|ws-url>] [--target <sel>] [--json '<obj>'] [--<key> <value> ...]
   bun run src/cli.ts --list [--browser chrome|firefox]
   bun run src/cli.ts --capabilities [--browser chrome|firefox]
+  bun run src/cli.ts --help | -h                 # this message
+  bun run src/cli.ts <tool> --help | -h           # that tool's arguments, sourced from its schema
 
 Examples:
   bun run src/cli.ts list_pages
@@ -43,10 +46,24 @@ Examples:
   bun run src/cli.ts take_screenshot --target url:example --fullPage true
   bun run src/cli.ts --browser firefox take_snapshot
   bun run src/cli.ts --capabilities --browser firefox
+  bun run src/cli.ts take_screenshot --help
+  bun run src/cli.ts --connect 9223 take_snapshot     # attach to your own logged-in Firefox (implies --browser firefox)
+
+--help/-h is recognised ANYWHERE in argv, before any tool dispatch: it never touches the
+browser (no CDP connection, no lease, no file written) and is never passed through as a tool
+argument, even when it appears after a tool name.
 
 Backend selection: --browser chrome|firefox, else the CDP_BROWSER env var, else "chrome" (default,
-zero behavior change for existing users). Firefox is LAUNCHED per invocation (it cannot be attached
-to), used for exactly one tool call, then disposed before the process exits.
+zero behavior change for existing users). Firefox runs in one of two modes:
+  - LAUNCH (default): a fresh throwaway-profile Firefox is spawned for this one invocation, used
+    for exactly one tool call, then disposed (session ended, process killed) before the process
+    exits. This is a login wall for anything that needs your real session.
+  - ATTACH (--connect <port|host:port|ws-url>, or the CDP_FIREFOX_ENDPOINT env var): 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 Firefox; dispose only ends the BiDi session.
+    --connect implies --browser firefox and conflicts with an explicit --browser chrome. Firefox
+    allows only one active BiDi session at a time, so a client that dies without disposing cleanly
+    (e.g. SIGKILL) can leave the slot occupied until Firefox restarts.
 
 Target selector grammar: active | index:N | url:<substr> | title:<substr> | label:<name> | <targetId>
   plus worker:<substr> (Chrome only) for evaluate_script, list_network_requests, get_network_request
@@ -74,12 +91,13 @@ interface ParsedArgs {
   tool?: string;
   list: boolean;
   capabilities: boolean;
+  help: boolean;
   args: Record<string, unknown>;
 }
 
 /** Parse process argv (already sliced to drop the runtime + script, and with --browser already stripped). */
 function parseArgv(argv: string[]): ParsedArgs {
-  const out: ParsedArgs = { list: false, capabilities: false, args: {} };
+  const out: ParsedArgs = { list: false, capabilities: false, help: false, args: {} };
   // Collect flag pairs separately so --json can be merged BEFORE individual
   // flags override it, regardless of token order.
   let jsonObj: Record<string, unknown> | undefined;
@@ -95,6 +113,16 @@ function parseArgv(argv: string[]): ParsedArgs {
       out.capabilities = true;
       continue;
     }
+    // Recognised ANYWHERE in argv (not just as the first token), and BEFORE the
+    // generic "--key value" branch below, so --help/-h can never be swallowed as
+    // a tool argument (the bug: `take_screenshot --help` used to run the tool
+    // with args.help=true; `-h` doesn't even start with "--", so without this
+    // explicit check it fell through to the positional branch and, if a tool
+    // name was already set, was silently dropped and the tool ran anyway).
+    if (token === "--help" || token === "-h") {
+      out.help = true;
+      continue;
+    }
     if (token.startsWith("--")) {
       const key = token.slice(2);
       const next = argv[i + 1];
@@ -132,10 +160,78 @@ function isToolName(name: string): name is ToolName {
   return Object.prototype.hasOwnProperty.call(TOOLS, name);
 }
 
+/** A JSON-Schema property shape narrow enough for the fields --help prints. */
+interface HelpProp {
+  type?: string | string[];
+  enum?: unknown[];
+  description?: string;
+}
+
+/** "string", "string|array" (a union type array), or an enum rendered as "png|jpeg". */
+function formatType(prop: HelpProp | undefined): string {
+  if (!prop) return "any";
+  if (Array.isArray(prop.enum) && prop.enum.length > 0) return prop.enum.map(String).join("|");
+  if (Array.isArray(prop.type)) return prop.type.join("|");
+  return prop.type ?? "any";
+}
+
+/**
+ * Print one tool's usage sourced ENTIRELY from MANIFEST's inputSchema (src/manifest.ts) — the
+ * same JSON Schema the MCP server advertises via tools/list. This is a read of that single
+ * source of truth, not a second hand-maintained argument list that could drift from it.
+ */
+function printToolHelp(name: ToolName): void {
+  const spec = MANIFEST.find((t) => t.name === name);
+  if (!spec) {
+    // Every TOOLS entry has a MANIFEST entry (auditCoverage() in mcp.ts warns otherwise); this
+    // is a defensive fallback, not an expected path.
+    process.stdout.write(`${name}\n`);
+    return;
+  }
+  const required = new Set(spec.inputSchema.required ?? []);
+  const props = (spec.inputSchema.properties ?? {}) as Record<string, HelpProp>;
+  const keys = Object.keys(props);
+
+  const lines = [spec.name, "", spec.description, ""];
+  if (keys.length === 0) {
+    lines.push("Arguments: none.");
+  } else {
+    lines.push("Arguments:");
+    for (const key of keys) {
+      const prop = props[key];
+      const reqTag = required.has(key) ? "required" : "optional";
+      lines.push(`  --${key} <${formatType(prop)}> (${reqTag})`);
+      if (prop?.description) lines.push(`      ${prop.description}`);
+    }
+  }
+  lines.push("", `Usage: cdp ${spec.name} [--target <sel>] [--json '<obj>'] [--<key> <value> ...]`);
+  process.stdout.write(`${lines.join("\n")}\n`);
+}
+
 async function main(): Promise<number> {
   const rawArgv = process.argv.slice(2);
-  const browser = resolveBrowserKind(rawArgv);
-  const parsed = parseArgv(stripBrowserFlag(rawArgv));
+  const { kind: browser, endpoint } = resolveBackend(rawArgv);
+  const parsed = parseArgv(stripConnectFlag(stripBrowserFlag(rawArgv)));
+
+  // --help/-h short-circuits BEFORE any availability lookup or backend touch — no CDP
+  // connection, no lease, no file written. This must be the very first thing checked in
+  // main(), ahead of --list/--capabilities, so a --help gesture can never be downgraded
+  // into a real dispatch by any branch below it.
+  if (parsed.help) {
+    if (!parsed.tool) {
+      process.stdout.write(`${USAGE}\n`);
+      return 0;
+    }
+    if (!isToolName(parsed.tool)) {
+      process.stderr.write(
+        `${JSON.stringify({ error: `unknown tool '${parsed.tool}'. Run --list to see all ${TOOL_NAMES.length} tools.` })}\n`,
+      );
+      return 1;
+    }
+    printToolHelp(parsed.tool);
+    return 0;
+  }
+
   const availability = toolAvailability(browser);
   const availableSet = new Set(availability.available);
 
@@ -205,14 +301,15 @@ async function main(): Promise<number> {
       return 0;
     }
 
-    // Firefox: one process per invocation. Launch, run exactly one tool call, always dispose,
-    // even if the tool call itself throws, so the spawned Firefox process never leaks.
+    // Firefox: one process per invocation. Launch (or, with --connect/CDP_FIREFOX_ENDPOINT,
+    // attach), run exactly one tool call, always dispose, even if the tool call itself throws —
+    // in launch mode that reaps the spawned process; in attach mode it only ends the BiDi session.
     const neutralFn = FIREFOX_TOOLS[tool];
     if (!neutralFn) {
       process.stderr.write(`${JSON.stringify({ error: `tool '${tool}' has no Firefox implementation wired` })}\n`);
       return 1;
     }
-    const session = await startFirefoxSession();
+    const session = await startFirefoxSession({ endpoint });
     try {
       const result = await neutralFn(session.driver, parsed.args as never);
       process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);

package/src/driver.ts

@@ -56,7 +56,13 @@
  * breaks the CLI.
  */
 
+import { mkdir, readFile, unlink, writeFile } from "node:fs/promises";
+import { join } from "node:path";
 import type { ToolName } from "./index.ts";
+// leaseDir only, for the viewport-override record below. leases.ts imports nothing from this file
+// (node builtins only), so this is not a cycle; the record deliberately shares the lease directory
+// rather than minting a second state location.
+import { leaseDir } from "./leases.ts";
 import type { TargetSelector } from "./types.ts";
 
 /* ---------------------------------- uids ---------------------------------- */
@@ -133,6 +139,9 @@ export type Capability =
   | "emulate.networkConditions" // throttled or offline conditions
   | "screenshot.fullPage" // one-shot full scrollable page, not just the viewport
   | "screenshot.element" // capture clipped to a single element
+  | "screenshot.scale" // per-capture output-pixel multiplier; no permanent emulation change
+  | "screenshot.renderSize" // emulate a viewport for the duration of ONE capture, then put the old one back
+  | "screenshot.tile" // capture past the backend's one-image encode limit as vertical bands, stitched losslessly
   | "network.intercept" // fulfill, fail, or continue a matched request
   | "network.responseBodyPostHoc" // read a body for a request not armed in advance
   | "snapshot.accessibilityTree" // native a11y dump, not a DOM-walk approximation
@@ -344,6 +353,236 @@ export interface ScreenshotOptions {
   quality?: number;
   fullPage?: boolean; // requires "screenshot.fullPage"
   clip?: ElementLocator; // requires "screenshot.element"
+  scale?: number; // requires "screenshot.scale"; absent or 1 leaves the capture byte-for-byte as it was
+  /**
+   * Render this capture at an emulated viewport, then put the previous one back. Both fields are
+   * required TOGETHER (the tool layer enforces it; a driver trusts its caller) and both require
+   * Capability "screenshot.renderSize". Absent, the capture is byte-for-byte what it was.
+   *
+   * NOT the same knob as `scale`, and the difference is measured, not asserted. `scale` multiplies
+   * output pixels while the page keeps believing it is its old size: window.devicePixelRatio read 2
+   * both before and after a --scale 3 capture, and innerWidth/innerHeight stayed 1390x1064. This
+   * pair changes what the page BELIEVES for the length of one capture, so media queries flip and
+   * the document re-lays-out — which is the point (capture a responsive page at desktop 1920x1080
+   * from a tab that is not that size) and also why it must be undone afterwards.
+   *
+   * `deviceScaleFactor` and `mobile` are deliberately INHERITED from whatever override was already
+   * in place rather than reset: the caller asked to change the render SIZE, and silently dropping
+   * a device pixel ratio they set earlier would be a second, unrequested change.
+   */
+  renderWidth?: number; // requires "screenshot.renderSize"
+  renderHeight?: number; // requires "screenshot.renderSize"
+  /**
+   * Whether this capture may be taken as vertical BANDS and stitched, instead of as one image.
+   * Three-valued, and the middle value is the default:
+   *
+   *   undefined  AUTO. One shot when the projected output fits under the backend's per-image encode
+   *              limit, banded when it does not. A capture that fits is byte-for-byte the call it
+   *              always was — the same params on the wire, no clip synthesized that was not there
+   *              before — so auto costs the common path nothing but the layout-metrics round trip
+   *              the decision itself needs.
+   *   false      NEVER band. A capture past the limit is REFUSED by the encode guard instead. This
+   *              is the escape hatch back to the exact pre-tiling behaviour.
+   *   true       ALWAYS band, even when one shot would have fitted. Mainly so the banded path is
+   *              directly testable on an ordinary page; see the driver for why "always" is made to
+   *              mean at least two bands rather than a one-band no-op.
+   *
+   * AUTO IS THE DEFAULT BECAUSE THE ALTERNATIVE IS A WEDGED TAB, not because banding is free.
+   * Measured (see MAX_ENCODED_SIDE_PX in ../cdp/driver.ts): a plain capture of a document past the
+   * limit does not fail fast — Page.captureScreenshot never answers, and because captureBeyondViewport
+   * resizes the page to the clip for the length of the capture, the tab is left stuck at that size
+   * with every later screenshot timing out too.
+   *
+   * Requires Capability "screenshot.tile" only for `true`. `undefined` and `false` ask a backend for
+   * nothing it cannot already do.
+   */
+  tile?: boolean; // `true` requires "screenshot.tile"
+}
+
+/**
+ * A capture too big for one image, handed to the tool layer band by band.
+ *
+ * LAZY BY CONTRACT, not by convenience: the Nth band's Page.captureScreenshot runs only when the
+ * consumer pulls the Nth band, so a driver never holds two bands at once and a whole 1.4 GB image
+ * never exists in memory. Accumulating the bands into an array first would typecheck, work on a
+ * small page, and defeat the entire point of the streaming stitcher on a large one.
+ *
+ * VERTICAL ONLY, AND THAT IS A SCOPE DECISION RATHER THAN AN OVERSIGHT. Bands stack top to bottom
+ * because that is the one direction a PNG can be concatenated without decoding it whole: scanlines
+ * are the unit, so appending rows is cheap and appending columns is not. A region whose projected
+ * WIDTH alone is past the limit is therefore refused, naming the width, rather than silently
+ * truncated or split into a grid this stitcher cannot reassemble.
+ */
+export interface BandedCapture {
+  /** The bands, top to bottom, produced one at a time. */
+  bands: AsyncIterable<Uint8Array>;
+  /** How many bands the sequence will yield. Known before the first one is captured. */
+  bandCount: number;
+  /** Height of every band but the last, in CSS px. The last is the remainder. */
+  bandHeightCss: number;
+  /** The whole region being tiled, CSS px, in document coordinates. */
+  clip: { x: number; y: number; width: number; height: number };
+  /** Always "png": the stitch is a PNG-scanline concatenation, and there is no lossless JPEG one. */
+  format: "png";
+}
+
+/**
+ * The tool layer's half of a banded capture: consume the bands and return whatever was made of
+ * them. Called at most once per capture, BEFORE the first band is taken, so a consumer that cannot
+ * accept a banded capture at all (it was asked for JPEG, or for base64 of a 300 MB image) refuses
+ * by throwing here and no band is ever captured.
+ *
+ * This is why the driver takes a callback rather than returning the iterable: a banded capture may
+ * hold a viewport override for its whole duration, and the driver can only put that back once it
+ * knows the consumer is finished. Handing the iterable out would end the driver's call while the
+ * page was still emulated.
+ */
+export type BandConsumer<T> = (capture: BandedCapture) => Promise<T>;
+
+/** What a banded capture returns in place of bytes: the consumer's own answer, plus how it was split. */
+export interface TiledScreenshotResult<T> {
+  tiled: true;
+  format: "png";
+  bandCount: number;
+  bandHeightCss: number;
+  /** Whatever the BandConsumer returned — for take_screenshot, the stitcher's measured report. */
+  consumed: T;
+  /** Same three render-size fields a one-shot capture carries, same meaning. */
+  renderSize?: { width: number; height: number };
+  renderRestored?: boolean;
+  renderRestoreError?: string;
+}
+
+/** One capture, delivered whole or in bands. Discriminate with isTiledCapture. */
+export type CaptureDelivery<T> = ScreenshotResult | TiledScreenshotResult<T>;
+
+export function isTiledCapture<T>(delivery: CaptureDelivery<T>): delivery is TiledScreenshotResult<T> {
+  return (delivery as { tiled?: unknown }).tiled === true;
+}
+
+/**
+ * What a capture returns. `data`/`format` are the whole answer for an ordinary capture; the three
+ * render-size fields are present only when renderWidth/renderHeight were applied.
+ *
+ * `renderRestored:false` IS THE LOUD PART, and it is why this is a result shape rather than a bare
+ * byte buffer. A failed restore means the caller's page is still emulated at the render size after
+ * this call returns — a mutation they did not ask to keep — so it has to travel back with the image
+ * instead of being swallowed. On the THROWING path there is no result to carry it, so a driver
+ * appends the same fact to the error message instead (see CdpPageDriver.screenshot).
+ */
+export interface ScreenshotResult {
+  data: Uint8Array;
+  format: "png" | "jpeg";
+  /** The emulated viewport this capture ran at. Present only when renderWidth/renderHeight were given. */
+  renderSize?: { width: number; height: number };
+  /** Whether the previous viewport was put back. Present only when a render size was applied. */
+  renderRestored?: boolean;
+  /** Why the restore failed. Present only when renderRestored is false. */
+  renderRestoreError?: string;
+}
+
+/* --------------------- the viewport-override record (both drivers) --------------------- */
+
+/**
+ * The device-metrics override this toolkit last applied to a target, as a file under the lease
+ * directory. Written by PageDriver.emulate, removed by emulate{clearOverrides}, read by
+ * PageDriver.screenshot so a render-size capture can put back what it displaced.
+ *
+ * WHY A FILE AND NOT A FIELD ON THE DRIVER. The spec for this feature called for a private field on
+ * the page driver, and that is provably not enough here — MEASURED against Chrome/151.0.7922.76:
+ *
+ *   $ cli emulate --target T --width 800 --height 600     # one process, socket closes on exit
+ *   $ cli evaluate_script --target T ...innerWidth...     # a DIFFERENT process
+ *   "[800,600,2]"                                         # the override OUTLIVED the connection
+ *
+ * The CDP driver's LifetimeModel is "per-call": a PageDriver instance lives for exactly one tool
+ * call, so a field on it is empty by construction at the start of the screenshot call that needs
+ * it, and the override it must not destroy was set by a process that has already exited. Same
+ * reasoning leases.ts and origins.ts give for their own files, arrived at the same way.
+ *
+ * WHY THE RECORD IS LOAD-BEARING AND NOT A CONVENIENCE. Emulation.clearDeviceMetricsOverride does
+ * NOT mean "undo the override" — measured, twice, on the same tab:
+ *
+ *   fresh connection, never set an override, clear it   -> returns {}, page STAYS 800x600
+ *   fresh connection, set 1920x1080, then clear         -> page becomes 1390x1064, the REAL device
+ *
+ * So clearing is a no-op for an override this session did not set, and once a session DOES set one,
+ * clearing reverts to the physical device and takes any earlier override down with it. A
+ * render-size capture always sets one, so its clear always lands — which is exactly why restoring
+ * by clearing would silently destroy a caller's earlier `emulate` and why this record exists.
+ *
+ * WHAT IT CANNOT SEE, and this is a real limit rather than a caveat: an override applied by
+ * something that is not this toolkit — the DevTools UI, Puppeteer, another automation client, or a
+ * toolkit build older than this record — leaves no file, so a render-size capture restores by
+ * clearing and that foreign override is reset to the real device. There is no CDP or BiDi command
+ * that reads a device-metrics override back, so a driver genuinely cannot know it was there.
+ */
+export interface ViewportRecord {
+  width: number;
+  height: number;
+  /** CDP's Emulation.setDeviceMetricsOverride sense: 0 means "the real device's". */
+  deviceScaleFactor?: number;
+  mobile?: boolean;
+}
+
+/** Sibling of leases.ts's lease-<backend>-<targetId>.json, in the same directory and with the same
+ *  filename-safety policy. Keyed by the driver's uid SCHEME ("cdp" / "bidi") because a CDP targetId
+ *  and a BiDi context id are not disjoint by construction — the same reason lease files carry a
+ *  backend in the name. */
+export function viewportRecordFile(scheme: string, targetId: string): string {
+  return join(leaseDir(), `viewport-${scheme}-${targetId.replace(/[^A-Za-z0-9._-]/g, "_")}.json`);
+}
+
+/** The override this toolkit last applied to `targetId`, or undefined when it has applied none.
+ *  A missing, unreadable, or malformed file all read as undefined: "we do not know" is the honest
+ *  answer, and it is the one that makes the caller restore by clearing rather than by guessing. */
+export async function readViewportRecord(scheme: string, targetId: string): Promise<ViewportRecord | undefined> {
+  try {
+    const raw = JSON.parse(await readFile(viewportRecordFile(scheme, targetId), "utf8")) as Partial<ViewportRecord>;
+    if (typeof raw?.width !== "number" || typeof raw?.height !== "number") return undefined;
+    return {
+      width: raw.width,
+      height: raw.height,
+      ...(typeof raw.deviceScaleFactor === "number" ? { deviceScaleFactor: raw.deviceScaleFactor } : {}),
+      ...(typeof raw.mobile === "boolean" ? { mobile: raw.mobile } : {}),
+    };
+  } catch {
+    return undefined;
+  }
+}
+
+/** Record an override this toolkit just applied. Deliberately best-effort: emulate's job is to
+ *  emulate, and a full disk must not turn a working override into a thrown error. The cost of a
+ *  lost write is stated above — a later render-size capture restores by clearing instead. */
+export async function writeViewportRecord(scheme: string, targetId: string, rec: ViewportRecord): Promise<void> {
+  try {
+    await mkdir(leaseDir(), { recursive: true });
+    await writeFile(viewportRecordFile(scheme, targetId), JSON.stringify({ scheme, targetId, ...rec }), "utf8");
+  } catch {
+    /* best-effort, see above */
+  }
+}
+
+/**
+ * What a driver appends to a capture's error when the render-size restore ALSO failed. Shared by
+ * both drivers because the sentence is the caller's only warning that their page is still emulated,
+ * and it must not read differently depending on which browser stranded it. Says what is wrong AND
+ * how to undo it by hand, because at this point the toolkit has already failed to.
+ */
+export function renderRestoreFailureNote(size: { width: number; height: number }, why: string): string {
+  return (
+    `— AND the ${size.width}x${size.height} render-size override could NOT be restored (${why}), so this page is STILL ` +
+    `emulated at ${size.width}x${size.height}: put it back with emulate{width,height} or emulate{clearOverrides:true}.`
+  );
+}
+
+/** Forget the recorded override. Best-effort for the same reason, and a missing file is success. */
+export async function clearViewportRecord(scheme: string, targetId: string): Promise<void> {
+  try {
+    await unlink(viewportRecordFile(scheme, targetId));
+  } catch {
+    /* best-effort, see above */
+  }
 }
 
 /** Each optional field names the Capability it requires, if any. */
@@ -642,9 +881,21 @@ export interface PageDriver {
   setFiles(loc: ElementLocator, files: readonly string[]): Promise<void>;
 
   /* rendering */
-  /** Returns raw image bytes. Artifact naming and writing stay in the tool. */
-  screenshot(opts?: ScreenshotOptions): Promise<{ data: Uint8Array; format: "png" | "jpeg" }>;
-  /** Apply overrides. Returns the field names actually applied. */
+  /** Returns raw image bytes. Artifact naming and writing stay in the tool. Under
+   *  renderWidth/renderHeight it also reports the emulated size it ran at and whether the previous
+   *  viewport was put back — see ScreenshotResult.
+   *
+   *  `consumeBands` is how a caller says it can accept a capture too big to encode as one image
+   *  (see BandedCapture). Omitting it is a real and honest state, not a shortcut: a caller with
+   *  nowhere to put a band sequence gets the encode guard's refusal instead of a wedged tab, which
+   *  is exactly the pre-tiling behaviour. Supplying it lets the driver band the capture when the
+   *  projection demands it (the default) or when `tile:true` asks for it. The driver calls it at
+   *  most once and awaits it, so the whole capture — every band — is finished before this method
+   *  resolves and before any viewport override is put back. */
+  screenshot<T>(opts?: ScreenshotOptions, consumeBands?: BandConsumer<T>): Promise<CaptureDelivery<T>>;
+  /** Apply overrides. Returns the field names actually applied. An implementation that applies
+   *  device metrics MUST record them with writeViewportRecord (and clear the record under
+   *  clearOverrides), or a later render-size capture will restore by clearing and destroy them. */
   emulate(opts: EmulationOptions): Promise<{ applied: string[] }>;
 
   /* events */

package/src/manifest.ts

@@ -909,7 +909,7 @@ export const MANIFEST: ToolSpec[] = [
   },
   {
     "name": "take_screenshot",
-    "description": "Capture the viewport (default), the full scrollable page (fullPage), or a single element (uid or selector, exactly one and mutually exclusive) via raw CDP Page.captureScreenshot. Writes a PNG/JPEG under /tmp/cdp-toolkit (override with savePath) and returns {path,bytes,format,target}; raw base64 is only included when returnBase64 is set. quality applies to jpeg only.",
+    "description": "Capture the viewport (default), the full scrollable page (fullPage), or a single element (uid or selector, exactly one and mutually exclusive) via raw CDP Page.captureScreenshot — as one image when it fits, or as vertical bands stitched losslessly into one PNG when it does not (see tile). Writes a PNG/JPEG under /tmp/cdp-toolkit (override with savePath; its directory is created for you) and returns {path,bytes,format,target,scale} plus width/height MEASURED from the encoded bytes, which are omitted rather than guessed when the bytes cannot be decoded; renderSize/renderRestored (+renderRestoreError) accompany a renderWidth/renderHeight capture, tiled/bands a banded one. Raw base64 is only included when returnBase64 is set, and is refused on a banded capture. quality applies to jpeg only. Every capture costs one Page.getLayoutMetrics round trip, because Chrome does not refuse an oversized capture politely: past 16384 device px per side Page.captureScreenshot can simply never answer, and captureBeyondViewport leaves the tab resized to the clip, so the size is checked before the capture rather than after.",
     "inputSchema": {
       "type": "object",
       "properties": {
@@ -937,6 +937,22 @@ export const MANIFEST: ToolSpec[] = [
           "type": "boolean",
           "description": "Capture the full scrollable content height computed from Page.getLayoutMetrics, not just the viewport."
         },
+        "scale": {
+          "type": "number",
+          "description": "Output-pixel multiplier for this one capture: greater than 0, at most 8, default 1. Output px = ceil(css px x scale x devicePixelRatio), so on a ratio-2 display scale 3 is 6x the CSS size; the page is never told anything changed (devicePixelRatio and innerWidth/innerHeight read identically before and after). Chrome only (capability screenshot.scale) — WebDriver BiDi's browsingContext.captureScreenshot has no scale parameter, so under Firefox call emulate with deviceScaleFactor first and capture at scale 1. A projection past Chrome's 16384 device px per side is refused before the browser is dialled, naming the largest scale that fits."
+        },
+        "renderWidth": {
+          "type": "number",
+          "description": "Emulate this viewport width, in CSS px (integer, 1-16384), for the length of ONE capture, then put the previous viewport back. REQUIRED together with renderHeight. Not the same knob as scale: scale re-renders the same layout at more pixels, this changes what the page BELIEVES, so media queries flip and the document re-lays-out — which is how you capture a responsive page at 1920x1080 from a tab that is not that size. Declared by BOTH backends (capability screenshot.renderSize). The restore can only put back an override this toolkit itself applied: one set by the DevTools UI, another client, or a pre-1.9.2 build is invisible and gets reset to the real device. The result reports renderSize and renderRestored; renderRestored:false means the tab is STILL emulated and you have to fix it with emulate."
+        },
+        "renderHeight": {
+          "type": "number",
+          "description": "Emulate this viewport height, in CSS px (integer, 1-16384), for the length of one capture. Required together with renderWidth — a viewport is two numbers, and honouring one while inventing the other would render at a size you never named and never see in the result. Note a narrow renderWidth reflows most documents TALLER, which is the usual way a render-size capture trips the 16384-device-px encode limit."
+        },
+        "tile": {
+          "type": "boolean",
+          "description": "Whether this capture may be taken as vertical bands and stitched into one lossless PNG. Three-valued: omitted = AUTO (one shot when the projected output fits under Chrome's 16384 device px per side, bands when it does not — this is why a whole-page capture of a very long page now returns a file instead of hanging and wedging the tab); false = never band, refuse instead (the pre-1.9.2 behaviour); true = always band, even when one shot would have fitted. Only true costs a capability (screenshot.tile, Chrome only; Firefox was never driven for the band arithmetic). A banded capture is PNG-only and cannot also returnBase64, and only HEIGHT is tiled — a projected WIDTH past the limit is refused, not split, because bands are stitched by concatenating scanlines. Bands are a faithful crop of one document render: fixed and sticky elements do not repeat per band and seams are pixel-exact, but content the page only loads on real scroll (lazy images, virtualized lists) renders blank in bands the real viewport never reached, which is a property of the page and not of the stitch."
+        },
         "uid": {
           "type": "number",
           "description": "Element to clip to: a CDP backendDOMNodeId obtained from take_snapshot. Mutually exclusive with selector."
@@ -947,11 +963,11 @@ export const MANIFEST: ToolSpec[] = [
         },
         "savePath": {
           "type": "string",
-          "description": "Override the output file path. Default: /tmp/cdp-toolkit/screenshot-<id>-<stamp>.<ext>."
+          "description": "Override the output file path. Default: /tmp/cdp-toolkit/screenshot-<id>-<stamp>.<ext>, where the stamp is the capture's START (a banded capture writes as it goes and has no finished image to name a file after). The destination directory is created from this path's own dirname, so a savePath outside /tmp/cdp-toolkit works."
         },
         "returnBase64": {
           "type": "boolean",
-          "description": "Also return the raw base64 image bytes in the result, in addition to writing the file."
+          "description": "Also return the raw base64 image bytes in the result, in addition to writing the file. Refused on a banded capture (see tile): a stitched image runs to hundreds of megabytes and base64 inflates it by a third, into the caller's response — read the file at the returned path instead."
         }
       },
       "required": [],
@@ -960,7 +976,7 @@ export const MANIFEST: ToolSpec[] = [
   },
   {
     "name": "emulate",
-    "description": "Apply any subset of Chrome emulation overrides in one call: device metrics (width/height together, plus deviceScaleFactor/mobile), userAgent, cpuThrottlingRate (>=1), emulated media type + mediaFeatures, and networkConditions. Pass clearOverrides:true to reset every override to the browser default (ignores all other fields). Non-metrics overrides are session-scoped and reset when the per-call connection closes; device-metrics overrides persist on the target until cleared or the renderer navigates/reloads.",
+    "description": "Apply any subset of Chrome emulation overrides in one call: device metrics (width/height together, plus deviceScaleFactor/mobile), userAgent, cpuThrottlingRate (>=1), emulated media type + mediaFeatures, and networkConditions. Pass clearOverrides:true to reset every override to the browser default (ignores all other fields); as of 1.9.2 that genuinely clears a device-metrics override set by a DIFFERENT process (Emulation.clearDeviceMetricsOverride is a no-op unless the clearing connection also set the override, so the driver re-asserts the tab's current size on its own connection first, then clears — and throws rather than answering cleared:true if it cannot verify that). Non-metrics overrides are session-scoped and reset when the per-call connection closes; device-metrics overrides persist on the target until cleared or the renderer navigates/reloads.",
     "inputSchema": {
       "type": "object",
       "properties": {

package/src/mcp.ts

@@ -9,7 +9,9 @@
  * then fail with a clear error if the browser is unreachable.
  *
  * Launch: `bunx -y cdp-toolkit`  (or `bun run src/mcp.ts` from a checkout)
- * Config:  CDP_BASE (default http://127.0.0.1:9222), CDP_TIMEOUT_MS, CDP_ARTIFACT_DIR.
+ * Config:  CDP_BASE (default http://127.0.0.1:9222), CDP_TIMEOUT_MS, CDP_ARTIFACT_DIR,
+ *          CDP_FIREFOX_ENDPOINT (attach to a user-launched Firefox instead of spawning one;
+ *          see backend.ts's ATTACH mode).
  *
  * stdout is the JSON-RPC channel, all diagnostics go to stderr only.
  */
@@ -18,17 +20,19 @@ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
 import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
 import { TOOLS, TOOL_NAMES, BASE } from "./index.ts";
 import { MANIFEST } from "./manifest.ts";
-import { resolveBrowserKind, stripBrowserFlag, getOrCreateFirefoxSession, disposeFirefoxSession } from "./backend.ts";
+import { resolveBackend, getOrCreateFirefoxSession, disposeFirefoxSession } from "./backend.ts";
 import { disposeBrowserSession } from "./tools/browser-session.ts";
 import { toolAvailability } from "./capabilities.ts";
 import { FIREFOX_TOOLS } from "./firefox-tools.ts";
 import { leaseFromArgs, markLongLivedProcess, withLeaseScope } from "./leases.ts";
 
-const VERSION = "1.9.1";
+const VERSION = "1.9.5";
 
-// --browser is read once at startup (MCP has no per-call notion of backend): explicit flag,
-// else CDP_BROWSER env var, else "chrome" (zero behavior change for existing users/configs).
-const BROWSER = resolveBrowserKind(stripBrowserFlag(process.argv.slice(2)));
+// Backend + (Firefox only) attach endpoint are read once at startup (MCP has no per-call notion
+// of backend): --browser flag / CDP_BROWSER env, else "chrome" (zero behavior change for existing
+// users/configs); --connect flag / CDP_FIREFOX_ENDPOINT env selects Firefox ATTACH mode and
+// implies browser=firefox (resolveBackend, backend.ts).
+const { kind: BROWSER, endpoint: FIREFOX_ENDPOINT } = resolveBackend(process.argv.slice(2));
 const AVAILABILITY = toolAvailability(BROWSER);
 const AVAILABLE_NAMES = new Set<string>(AVAILABILITY.available);
 
@@ -90,7 +94,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
     const neutralFn = neutralDispatch[name];
     if (!neutralFn) return { content: [{ type: "text" as const, text: `unknown tool: ${name}` }], isError: true };
     try {
-      const session = await getOrCreateFirefoxSession();
+      const session = await getOrCreateFirefoxSession({ endpoint: FIREFOX_ENDPOINT });
       const result = await neutralFn(session.driver, args);
       return { content: [{ type: "text" as const, text: JSON.stringify(result, null, 2) }] };
     } catch (err) {
@@ -105,12 +109,17 @@ auditCoverage();
 // (CDP_REQUIRE_LEASE) safe to honor here and unsafe in cli.ts. See requireLease.
 markLongLivedProcess();
 await server.connect(new StdioServerTransport());
-console.error(`[cdp-toolkit] MCP server v${VERSION} ready, browser=${BROWSER}, ${AVAILABILITY.available.length} tools, CDP_BASE=${BASE}`);
+console.error(
+  `[cdp-toolkit] MCP server v${VERSION} ready, browser=${BROWSER}${FIREFOX_ENDPOINT ? ` (attach ${FIREFOX_ENDPOINT})` : ""}, ${AVAILABILITY.available.length} tools, CDP_BASE=${BASE}`,
+);
 
-// Firefox owns a real OS process (see bidi/launch.ts): it must be reaped on every shutdown path,
-// not just a clean exit. SIGINT/SIGTERM cover ctrl-C and a supervising client killing the server;
-// stdin 'close' covers the normal MCP shutdown (the client closes the stdio pipe). All three are
-// idempotent through disposeFirefoxSession(), and a no-op entirely when Firefox was never launched.
+// LAUNCH-mode Firefox owns a real OS process (see bidi/launch.ts): it must be reaped on every
+// shutdown path, not just a clean exit. ATTACH-mode Firefox (CDP_FIREFOX_ENDPOINT / --connect)
+// owns no process here — disposeFirefoxSession() below only ends its BiDi session (freeing
+// Firefox's single session slot) and closes the socket, leaving the user's browser running.
+// SIGINT/SIGTERM cover ctrl-C and a supervising client killing the server; stdin 'close' covers
+// the normal MCP shutdown (the client closes the stdio pipe). All three are idempotent through
+// disposeFirefoxSession(), and a no-op entirely when Firefox was never launched/attached.
 let shuttingDown = false;
 async function shutdown(): Promise<void> {
   if (shuttingDown) return;