npm - @toolstackhq/cdpwright - Versions diffs - 1.0.0 → 1.2.0 - Mend

@toolstackhq/cdpwright 1.0.0 → 1.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (13) hide show

package/README.md +34 -9
package/dist/assert/expect.d.ts +1 -1
package/dist/assert/expect.js +1 -1
package/dist/{chunk-6BPF3IEU.js → chunk-PDUS6BDZ.js} +64 -3
package/dist/chunk-PDUS6BDZ.js.map +1 -0
package/dist/cli.js +856 -19
package/dist/cli.js.map +1 -1
package/dist/{expect-CY70zJc0.d.ts → expect-CLal_AQd.d.ts} +18 -0
package/dist/index.d.ts +25 -4
package/dist/index.js +73 -10
package/dist/index.js.map +1 -1
package/package.json +1 -1
package/dist/chunk-6BPF3IEU.js.map +0 -1

package/dist/cli.js CHANGED Viewed

@@ -1,10 +1,15 @@
 #!/usr/bin/env node
+// src/cli.ts
+import fs5 from "fs";
+import path5 from "path";
+import { fileURLToPath } from "url";
 // src/browser/ChromiumManager.ts
 import fs4 from "fs";
 import path4 from "path";
 import os2 from "os";
-import http from "http";
+import http2 from "http";
 import { spawn as spawn2 } from "child_process";
 // src/logging/Logger.ts
@@ -1318,6 +1323,11 @@ function ensureAllowedUrl(url, options = {}) {
 }
 // src/core/Page.ts
+function assertPdfBuffer(buffer) {
+  if (buffer.length < 5 || buffer.subarray(0, 5).toString("utf-8") !== "%PDF-") {
+    throw new Error("PDF generation failed: Chromium did not return a valid PDF");
+  }
+}
 var Page = class {
   session;
   logger;
@@ -1437,13 +1447,24 @@ var Page = class {
   async findLocators(options = {}) {
     return this.mainFrame().findLocators(options);
   }
+  async content() {
+    await this.waitForLoad();
+    return this.mainFrame().evaluate(() => {
+      const doctype = document.doctype;
+      const doctypeText = doctype ? `<!DOCTYPE ${doctype.name}${doctype.publicId ? ` PUBLIC "${doctype.publicId}"` : ""}${doctype.systemId ? ` "${doctype.systemId}"` : ""}>` : "<!doctype html>";
+      return `${doctypeText}
+${document.documentElement.outerHTML}`;
+    });
+  }
   async screenshot(options = {}) {
     const start = Date.now();
     this.events.emit("action:start", { name: "screenshot", frameId: this.mainFrameId });
+    await this.waitForLoad();
     const result = await this.session.send("Page.captureScreenshot", {
       format: options.format ?? "png",
       quality: options.quality,
-      fromSurface: true
+      fromSurface: true,
+      captureBeyondViewport: options.fullPage ?? false
     });
     const buffer = Buffer.from(result.data, "base64");
     if (options.path) {
@@ -1457,21 +1478,66 @@ var Page = class {
   async screenshotBase64(options = {}) {
     const start = Date.now();
     this.events.emit("action:start", { name: "screenshotBase64", frameId: this.mainFrameId });
+    await this.waitForLoad();
     const result = await this.session.send("Page.captureScreenshot", {
       format: options.format ?? "png",
       quality: options.quality,
-      fromSurface: true
+      fromSurface: true,
+      captureBeyondViewport: options.fullPage ?? false
     });
     const duration = Date.now() - start;
     this.events.emit("action:end", { name: "screenshotBase64", frameId: this.mainFrameId, durationMs: duration });
     return result.data;
   }
+  async pdf(options = {}) {
+    const start = Date.now();
+    this.events.emit("action:start", { name: "pdf", frameId: this.mainFrameId });
+    await this.waitForLoad();
+    await this.session.send("Emulation.setEmulatedMedia", { media: "screen" });
+    let buffer;
+    try {
+      const result = await this.session.send("Page.printToPDF", {
+        landscape: options.landscape ?? false,
+        printBackground: options.printBackground ?? true,
+        scale: options.scale,
+        paperWidth: options.paperWidth,
+        paperHeight: options.paperHeight,
+        marginTop: options.marginTop,
+        marginBottom: options.marginBottom,
+        marginLeft: options.marginLeft,
+        marginRight: options.marginRight,
+        pageRanges: options.pageRanges,
+        preferCSSPageSize: options.preferCSSPageSize
+      });
+      buffer = Buffer.from(result.data, "base64");
+      assertPdfBuffer(buffer);
+      if (options.path) {
+        const resolved = path2.resolve(options.path);
+        fs2.writeFileSync(resolved, buffer);
+      }
+    } finally {
+      try {
+        await this.session.send("Emulation.setEmulatedMedia", { media: "" });
+      } catch {
+      }
+      const duration = Date.now() - start;
+      this.events.emit("action:end", { name: "pdf", frameId: this.mainFrameId, durationMs: duration });
+    }
+    return buffer;
+  }
   getEvents() {
     return this.events;
   }
   getDefaultTimeout() {
     return this.defaultTimeout;
   }
+  async waitForLoad(timeoutMs = this.defaultTimeout) {
+    const frame = this.mainFrame();
+    await waitFor(async () => {
+      const readyState = await frame.evaluate("document.readyState");
+      return readyState === "complete";
+    }, { timeoutMs, description: "page load" });
+  }
   buildFrameTree(tree) {
     const frame = this.ensureFrame(tree.frame.id);
     frame.setMeta({ name: tree.frame.name, url: tree.frame.url, parentId: tree.frame.parentId });
@@ -1573,12 +1639,16 @@ var Browser = class {
   events;
   cleanupTasks;
   contexts = /* @__PURE__ */ new Set();
-  constructor(connection, child, logger, events, cleanupTasks = []) {
+  wsEndpoint;
+  pid;
+  constructor(connection, child, logger, events, cleanupTasks = [], wsEndpoint = "") {
     this.connection = connection;
     this.process = child;
     this.logger = logger;
     this.events = events;
     this.cleanupTasks = cleanupTasks;
+    this.wsEndpoint = wsEndpoint;
+    this.pid = child?.pid ?? 0;
   }
   on(event, handler) {
     this.events.on(event, handler);
@@ -1600,6 +1670,23 @@ var Browser = class {
     await page.initialize();
     return page;
   }
+  /** Attach to an existing page by target ID. */
+  async attachPage(targetId) {
+    const { sessionId } = await this.connection.send("Target.attachToTarget", { targetId, flatten: true });
+    const session = this.connection.createSession(sessionId);
+    const page = new Page(session, this.logger, this.events);
+    await page.initialize();
+    return page;
+  }
+  /** List open page targets. */
+  async pages() {
+    const result = await this.connection.send("Target.getTargets");
+    return result.targetInfos.filter((t) => t.type === "page").map((t) => ({ targetId: t.targetId, url: t.url, title: t.title }));
+  }
+  /** Disconnect without killing the browser process. */
+  async disconnect() {
+    await this.connection.close();
+  }
   async disposeContext(contextId) {
     if (!contextId) return;
     try {
@@ -1619,7 +1706,7 @@ var Browser = class {
     } catch {
     }
     await this.connection.close();
-    if (!this.process.killed) {
+    if (this.process && !this.process.killed) {
       this.process.kill();
     }
     for (const task of this.cleanupTasks) {
@@ -1635,6 +1722,7 @@ var Browser = class {
 import fs3 from "fs";
 import path3 from "path";
 import os from "os";
+import http from "http";
 import https from "https";
 import { spawn } from "child_process";
 import yauzl from "yauzl";
@@ -1672,11 +1760,22 @@ function chromiumExecutableRelativePath(platform) {
   if (platform === "mac") return path3.join("chrome-mac", "Chromium.app", "Contents", "MacOS", "Chromium");
   return path3.join("chrome-win", "chrome.exe");
 }
+function httpGet(url) {
+  return url.startsWith("http://") ? http : https;
+}
+function resolveSnapshotBase() {
+  const mirror = process.env.CDPWRIGHT_DOWNLOAD_MIRROR;
+  if (mirror && mirror.trim()) {
+    return mirror.trim().replace(/\/+$/, "");
+  }
+  return SNAPSHOT_BASE;
+}
 async function fetchLatestRevision(platform) {
+  const base = resolveSnapshotBase();
   const folder = platformFolder(platform);
-  const url = `${SNAPSHOT_BASE}/${folder}/LAST_CHANGE`;
+  const url = `${base}/${folder}/LAST_CHANGE`;
   return new Promise((resolve, reject) => {
-    https.get(url, (res) => {
+    httpGet(url).get(url, (res) => {
       if (res.statusCode && res.statusCode >= 400) {
         reject(new Error(`Failed to fetch LAST_CHANGE: ${res.statusCode}`));
         return;
@@ -1701,7 +1800,9 @@ async function ensureDownloaded(options) {
   fs3.mkdirSync(revisionDir, { recursive: true });
   const folder = platformFolder(platform);
   const zipName = platform === "win" ? "chrome-win.zip" : platform === "mac" ? "chrome-mac.zip" : "chrome-linux.zip";
-  const downloadUrl = `${SNAPSHOT_BASE}/${folder}/${revision}/${zipName}`;
+  const explicitUrl = process.env.CDPWRIGHT_DOWNLOAD_URL?.trim();
+  const base = resolveSnapshotBase();
+  const downloadUrl = explicitUrl || `${base}/${folder}/${revision}/${zipName}`;
   const tempZipPath = path3.join(os.tmpdir(), `cdpwright-${platform}-${revision}.zip`);
   logger.info("Downloading Chromium snapshot", downloadUrl);
   await downloadFile(downloadUrl, tempZipPath, logger);
@@ -1718,7 +1819,7 @@ async function ensureDownloaded(options) {
 function downloadFile(url, dest, logger) {
   return new Promise((resolve, reject) => {
     const file = fs3.createWriteStream(dest);
-    https.get(url, (res) => {
+    httpGet(url).get(url, (res) => {
       if (res.statusCode && res.statusCode >= 400) {
         reject(new Error(`Failed to download: ${res.statusCode}`));
         return;
@@ -1947,6 +2048,7 @@ var ChromiumManager = class {
     }
     if (options.maximize) {
       args.push("--start-maximized");
+      args.push("--window-size=1920,1080");
     }
     if (options.args) {
       args.push(...options.args);
@@ -1975,7 +2077,7 @@ var ChromiumManager = class {
         logger.info(`Assertion ${payload.name}`, ...args2);
       });
     }
-    const browser = new Browser(connection, child, logger, events, cleanupTasks);
+    const browser = new Browser(connection, child, logger, events, cleanupTasks, wsEndpoint);
     return browser;
   }
   resolveCacheRoot(platform) {
@@ -2112,7 +2214,7 @@ function toHttpVersionUrl(wsUrl) {
 }
 function fetchWebSocketDebuggerUrl(versionUrl) {
   return new Promise((resolve, reject) => {
-    http.get(versionUrl, (res) => {
+    http2.get(versionUrl, (res) => {
       if (res.statusCode && res.statusCode >= 400) {
         reject(new Error(`Failed to fetch /json/version: ${res.statusCode}`));
         return;
@@ -2135,9 +2237,727 @@ function fetchWebSocketDebuggerUrl(versionUrl) {
   });
 }
+// src/assert/AssertionError.ts
+var AssertionError = class extends Error {
+  selector;
+  timeoutMs;
+  lastState;
+  constructor(message, options = {}) {
+    super(message);
+    this.name = "AssertionError";
+    this.selector = options.selector;
+    this.timeoutMs = options.timeoutMs;
+    this.lastState = options.lastState;
+  }
+};
+// src/assert/expect.ts
+var ElementExpectation = class _ElementExpectation {
+  frame;
+  selector;
+  options;
+  negate;
+  events;
+  constructor(frame, selector, options, negate, events) {
+    this.frame = frame;
+    this.selector = selector;
+    this.options = options;
+    this.negate = negate;
+    this.events = events;
+  }
+  get not() {
+    return new _ElementExpectation(this.frame, this.selector, this.options, !this.negate, this.events);
+  }
+  async toExist() {
+    return this.assert(async () => {
+      const exists = await this.frame.exists(this.selector, this.options);
+      return this.negate ? !exists : exists;
+    }, this.negate ? "Expected element not to exist" : "Expected element to exist");
+  }
+  async toBeVisible() {
+    return this.assert(async () => {
+      const visible = await this.frame.isVisible(this.selector, this.options);
+      return this.negate ? !visible : visible;
+    }, this.negate ? "Expected element not to be visible" : "Expected element to be visible");
+  }
+  async toBeHidden() {
+    return this.assert(async () => {
+      const visible = await this.frame.isVisible(this.selector, this.options);
+      return this.negate ? visible : !visible;
+    }, this.negate ? "Expected element not to be hidden" : "Expected element to be hidden");
+  }
+  async toBeEnabled() {
+    return this.assert(async () => {
+      const enabled = await this.frame.isEnabled(this.selector, this.options);
+      if (enabled == null) {
+        return this.negate ? true : false;
+      }
+      return this.negate ? !enabled : enabled;
+    }, this.negate ? "Expected element not to be enabled" : "Expected element to be enabled");
+  }
+  async toBeDisabled() {
+    return this.assert(async () => {
+      const enabled = await this.frame.isEnabled(this.selector, this.options);
+      if (enabled == null) {
+        return this.negate ? true : false;
+      }
+      const disabled = !enabled;
+      return this.negate ? !disabled : disabled;
+    }, this.negate ? "Expected element not to be disabled" : "Expected element to be disabled");
+  }
+  async toBeChecked() {
+    return this.assert(async () => {
+      const checked = await this.frame.isChecked(this.selector, this.options);
+      if (checked == null) {
+        return this.negate ? true : false;
+      }
+      return this.negate ? !checked : checked;
+    }, this.negate ? "Expected element not to be checked" : "Expected element to be checked");
+  }
+  async toBeUnchecked() {
+    return this.assert(async () => {
+      const checked = await this.frame.isChecked(this.selector, this.options);
+      if (checked == null) {
+        return this.negate ? true : false;
+      }
+      const unchecked = !checked;
+      return this.negate ? !unchecked : unchecked;
+    }, this.negate ? "Expected element not to be unchecked" : "Expected element to be unchecked");
+  }
+  async toHaveText(textOrRegex) {
+    const expected = textOrRegex;
+    return this.assert(async () => {
+      const text = await this.frame.text(this.selector, this.options);
+      if (text == null) {
+        return this.negate ? true : false;
+      }
+      const matches = expected instanceof RegExp ? new RegExp(expected.source, expected.flags.replace("g", "")).test(text) : text.includes(expected);
+      return this.negate ? !matches : matches;
+    }, this.negate ? "Expected element text not to match" : "Expected element text to match", { expected });
+  }
+  async toHaveExactText(textOrRegex) {
+    const expected = textOrRegex;
+    return this.assert(async () => {
+      const text = await this.frame.text(this.selector, this.options);
+      if (text == null) {
+        return this.negate ? true : false;
+      }
+      const matches = expected instanceof RegExp ? new RegExp(expected.source, expected.flags.replace("g", "")).test(text) : text === expected;
+      return this.negate ? !matches : matches;
+    }, this.negate ? "Expected element text not to match exactly" : "Expected element text to match exactly", { expected });
+  }
+  async toContainText(textOrRegex) {
+    const expected = textOrRegex;
+    return this.assert(async () => {
+      const text = await this.frame.text(this.selector, this.options);
+      if (text == null) {
+        return this.negate ? true : false;
+      }
+      const matches = expected instanceof RegExp ? new RegExp(expected.source, expected.flags.replace("g", "")).test(text) : text.includes(expected);
+      return this.negate ? !matches : matches;
+    }, this.negate ? "Expected element text not to contain" : "Expected element text to contain", { expected });
+  }
+  async toHaveValue(valueOrRegex) {
+    const expected = valueOrRegex;
+    return this.assert(async () => {
+      const value = await this.frame.value(this.selector, this.options);
+      if (value == null) {
+        return this.negate ? true : false;
+      }
+      const matches = expected instanceof RegExp ? new RegExp(expected.source, expected.flags.replace("g", "")).test(value) : value === expected;
+      return this.negate ? !matches : matches;
+    }, this.negate ? "Expected element value not to match" : "Expected element value to match", { expected });
+  }
+  async toHaveAttribute(name, valueOrRegex) {
+    const expected = valueOrRegex;
+    return this.assert(async () => {
+      const value = await this.frame.attribute(this.selector, name, this.options);
+      if (expected === void 0) {
+        const exists = value != null;
+        return this.negate ? !exists : exists;
+      }
+      if (value == null) {
+        return this.negate ? true : false;
+      }
+      const matches = expected instanceof RegExp ? new RegExp(expected.source, expected.flags.replace("g", "")).test(value) : value === expected;
+      return this.negate ? !matches : matches;
+    }, this.negate ? "Expected element attribute not to match" : "Expected element attribute to match", { expected, name });
+  }
+  async toHaveId(idOrRegex) {
+    return this.toHaveAttribute("id", idOrRegex);
+  }
+  async toHaveName(nameOrRegex) {
+    return this.toHaveAttribute("name", nameOrRegex);
+  }
+  async toHaveCount(expected) {
+    return this.assert(async () => {
+      const count = await this.frame.count(this.selector, this.options);
+      const matches = count === expected;
+      return this.negate ? !matches : matches;
+    }, this.negate ? "Expected element count not to match" : "Expected element count to match", { expected });
+  }
+  async toHaveClass(nameOrRegex) {
+    const expected = nameOrRegex;
+    return this.assert(async () => {
+      const classes = await this.frame.classes(this.selector, this.options);
+      if (classes == null) {
+        return this.negate ? true : false;
+      }
+      const matches = expected instanceof RegExp ? classes.some((value) => new RegExp(expected.source, expected.flags.replace("g", "")).test(value)) : classes.includes(expected);
+      return this.negate ? !matches : matches;
+    }, this.negate ? "Expected element class not to match" : "Expected element class to match", { expected });
+  }
+  async toHaveClasses(expected) {
+    return this.assert(async () => {
+      const classes = await this.frame.classes(this.selector, this.options);
+      if (classes == null) {
+        return this.negate ? true : false;
+      }
+      const matches = expected.every((value) => classes.includes(value));
+      return this.negate ? !matches : matches;
+    }, this.negate ? "Expected element classes not to match" : "Expected element classes to match", { expected });
+  }
+  async toHaveCss(property, valueOrRegex) {
+    const expected = valueOrRegex;
+    return this.assert(async () => {
+      const value = await this.frame.css(this.selector, property, this.options);
+      if (value == null) {
+        return this.negate ? true : false;
+      }
+      const actual = value.trim();
+      const matches = expected instanceof RegExp ? new RegExp(expected.source, expected.flags.replace("g", "")).test(actual) : actual === expected;
+      return this.negate ? !matches : matches;
+    }, this.negate ? "Expected element css not to match" : "Expected element css to match", { expected, property });
+  }
+  async toHaveFocus() {
+    return this.assert(async () => {
+      const focused = await this.frame.hasFocus(this.selector, this.options);
+      if (focused == null) {
+        return this.negate ? true : false;
+      }
+      return this.negate ? !focused : focused;
+    }, this.negate ? "Expected element not to have focus" : "Expected element to have focus");
+  }
+  async toBeInViewport(options = {}) {
+    return this.assert(async () => {
+      const inViewport = await this.frame.isInViewport(this.selector, this.options, Boolean(options.fully));
+      if (inViewport == null) {
+        return this.negate ? true : false;
+      }
+      return this.negate ? !inViewport : inViewport;
+    }, this.negate ? "Expected element not to be in viewport" : "Expected element to be in viewport");
+  }
+  async toBeEditable() {
+    return this.assert(async () => {
+      const editable = await this.frame.isEditable(this.selector, this.options);
+      if (editable == null) {
+        return this.negate ? true : false;
+      }
+      return this.negate ? !editable : editable;
+    }, this.negate ? "Expected element not to be editable" : "Expected element to be editable");
+  }
+  async assert(predicate, message, details = {}) {
+    const timeoutMs = this.options.timeoutMs ?? 3e4;
+    const start = Date.now();
+    this.events.emit("assertion:start", { name: message, selector: this.selector, frameId: this.frame.id });
+    let lastState;
+    try {
+      await waitFor(async () => {
+        const result = await predicate();
+        lastState = result;
+        return result;
+      }, { timeoutMs, description: message });
+    } catch {
+      const duration2 = Date.now() - start;
+      this.events.emit("assertion:end", { name: message, selector: this.selector, frameId: this.frame.id, durationMs: duration2, status: "failed" });
+      throw new AssertionError(message, { selector: this.selector, timeoutMs, lastState: { lastState, ...details } });
+    }
+    const duration = Date.now() - start;
+    this.events.emit("assertion:end", { name: message, selector: this.selector, frameId: this.frame.id, durationMs: duration, status: "passed" });
+  }
+};
+var ExpectFrame = class {
+  frame;
+  events;
+  constructor(frame, events) {
+    this.frame = frame;
+    this.events = events;
+  }
+  element(selector, options = {}) {
+    return new ElementExpectation(this.frame, selector, options, false, this.events);
+  }
+};
+function expect(page) {
+  return {
+    element: (selector, options = {}) => new ElementExpectation(page.mainFrame(), selector, options, false, page.getEvents()),
+    frame: (options) => {
+      const frame = page.frame(options);
+      if (!frame) {
+        throw new AssertionError("Frame not found", { selector: JSON.stringify(options) });
+      }
+      return new ExpectFrame(frame, page.getEvents());
+    }
+  };
+}
+Page.prototype.expect = function(selector, options) {
+  const builder = expect(this);
+  if (selector) {
+    return builder.element(selector, options);
+  }
+  return builder;
+};
+Object.defineProperty(Page.prototype, "find", {
+  get: function() {
+    return {
+      locators: (options) => this.findLocators(options)
+    };
+  }
+});
+// src/index.ts
+var automaton = {
+  async launch(options = {}) {
+    const manager = new ChromiumManager(options.logger);
+    return manager.launch(options);
+  },
+  async connect(wsEndpoint, options = {}) {
+    const logger = options.logger ?? new Logger(options.logLevel ?? "warn");
+    const connection = new Connection(wsEndpoint, logger);
+    await connection.waitForOpen();
+    const events = new AutomationEvents();
+    const logEvents = options.logEvents ?? true;
+    const logActions = options.logActions ?? true;
+    const logAssertions = options.logAssertions ?? true;
+    if (logEvents && logActions) {
+      events.on("action:end", (payload) => {
+        const selector = payload.sensitive ? void 0 : payload.selector;
+        const args = [];
+        if (selector) args.push(selector);
+        if (typeof payload.durationMs === "number") args.push(`${payload.durationMs}ms`);
+        logger.info(`Action ${payload.name}`, ...args);
+      });
+    }
+    if (logEvents && logAssertions) {
+      events.on("assertion:end", (payload) => {
+        const args = [];
+        if (payload.selector) args.push(payload.selector);
+        if (typeof payload.durationMs === "number") args.push(`${payload.durationMs}ms`);
+        logger.info(`Assertion ${payload.name}`, ...args);
+      });
+    }
+    return new Browser(connection, null, logger, events, [], wsEndpoint);
+  }
+};
 // src/cli.ts
+function sessionFilePath() {
+  const platform = detectPlatform();
+  const cacheRoot = defaultCacheRoot(platform);
+  return path5.join(cacheRoot, "session.json");
+}
+function writeSession(info) {
+  const filePath = sessionFilePath();
+  fs5.mkdirSync(path5.dirname(filePath), { recursive: true });
+  fs5.writeFileSync(filePath, JSON.stringify(info));
+}
+function readSession() {
+  const filePath = sessionFilePath();
+  if (!fs5.existsSync(filePath)) return null;
+  try {
+    const data = JSON.parse(fs5.readFileSync(filePath, "utf-8"));
+    if (!data.wsEndpoint || !data.pid) return null;
+    try {
+      process.kill(data.pid, 0);
+    } catch {
+      clearSession();
+      return null;
+    }
+    return data;
+  } catch {
+    return null;
+  }
+}
+function clearSession() {
+  const filePath = sessionFilePath();
+  try {
+    fs5.unlinkSync(filePath);
+  } catch {
+  }
+}
 function printHelp() {
-  console.log("cdpwright (cpw) download [--latest]");
+  console.log(`cdpwright (cpw) \u2014 Chromium automation CLI
+Commands:
+  download [options]       Download pinned Chromium snapshot
+  install                  Alias for download
+  open <url>               Launch browser session and navigate to URL
+  close                    Close the running browser session
+  screenshot [url] -o f    Take a screenshot (PNG/JPEG)
+  html [url] -o file.html  Save the page HTML source
+  pdf [url] -o file.pdf    Generate PDF of page (headless only)
+  eval [url] <script>      Run script in page, print result as JSON
+  version                  Print cdpwright and Chromium versions
+Session:
+  'open' starts a browser and saves a session. Other commands auto-connect
+  to the running session when no URL is given. 'close' shuts it down.
+Download options:
+  --latest                 Download the latest Chromium revision
+  --mirror <url>           Custom mirror base URL
+  --url <url>              Exact zip URL override
+Common options:
+  --headless               Run in headless mode (default for screenshot, pdf, eval)
+  --headed                 Run in headed mode (default for open)
+Screenshot options:
+  -o, --output <file>      Output file path (required)
+  --full-page              Capture full scrollable page
+PDF options:
+  -o, --output <file>      Output file path (required)
+  Note: pdf always runs headless (CDP limitation)`);
+}
+function hasFlag(args, flag) {
+  return args.includes(flag);
+}
+function flagValue(args, flag) {
+  const index = args.indexOf(flag);
+  if (index === -1 || index + 1 >= args.length) return void 0;
+  return args[index + 1];
+}
+var VALUE_FLAGS = ["--mirror", "--url", "-o", "--output"];
+function resolveHeadless(args, defaultValue) {
+  if (hasFlag(args, "--headed")) return false;
+  if (hasFlag(args, "--headless")) return true;
+  return defaultValue;
+}
+function positionalArgs(args) {
+  const result = [];
+  for (let i = 0; i < args.length; i++) {
+    if (args[i].startsWith("-")) {
+      if (VALUE_FLAGS.includes(args[i])) i++;
+      continue;
+    }
+    result.push(args[i]);
+  }
+  return result;
+}
+function launchArgs() {
+  const args = [];
+  if (process.platform === "linux") {
+    args.push("--no-sandbox", "--no-zygote", "--disable-dev-shm-usage");
+  }
+  return args;
+}
+function pngDimensions(buffer) {
+  if (buffer.length < 24) {
+    throw new Error("Invalid PNG screenshot");
+  }
+  if (buffer.readUInt32BE(0) !== 2303741511 || buffer.readUInt32BE(4) !== 218765834) {
+    throw new Error("Invalid PNG screenshot");
+  }
+  return {
+    width: buffer.readUInt32BE(16),
+    height: buffer.readUInt32BE(20)
+  };
+}
+async function connectToSession() {
+  const session = readSession();
+  if (!session) {
+    console.error("No running session. Start one with: cpw open <url>");
+    process.exit(1);
+  }
+  const browser = await automaton.connect(session.wsEndpoint);
+  const targets = await browser.pages();
+  if (targets.length === 0) {
+    console.error("Session has no open pages.");
+    await browser.disconnect();
+    process.exit(1);
+  }
+  const page = await browser.attachPage(targets[0].targetId);
+  return { browser, page };
+}
+async function withPage(url, options, fn) {
+  const browser = await automaton.launch({
+    headless: options.headless ?? true,
+    maximize: options.maximize ?? false,
+    args: launchArgs(),
+    logLevel: "warn"
+  });
+  try {
+    const page = await browser.newPage();
+    await page.goto(url, { waitUntil: "load" });
+    return await fn(page, browser);
+  } finally {
+    await browser.close();
+  }
+}
+async function cmdDownload(rest) {
+  const latest = hasFlag(rest, "--latest");
+  const mirrorFlag = flagValue(rest, "--mirror");
+  if (mirrorFlag) process.env.CDPWRIGHT_DOWNLOAD_MIRROR = mirrorFlag;
+  const urlFlag = flagValue(rest, "--url");
+  if (urlFlag) process.env.CDPWRIGHT_DOWNLOAD_URL = urlFlag;
+  const manager = new ChromiumManager();
+  await manager.download({ latest });
+}
+async function cmdOpen(rest) {
+  const url = positionalArgs(rest)[0];
+  if (!url) {
+    console.error("Usage: cpw open <url>");
+    process.exit(1);
+  }
+  const headless = resolveHeadless(rest, false);
+  const browser = await automaton.launch({
+    headless,
+    args: launchArgs(),
+    logLevel: "warn"
+  });
+  const page = await browser.newPage();
+  await page.goto(url, { waitUntil: "load" });
+  writeSession({
+    wsEndpoint: browser.wsEndpoint,
+    pid: browser.pid || process.pid
+  });
+  console.log(`Browser open at ${url}`);
+  console.log(`Session saved. Run commands in another terminal:`);
+  console.log(`  npx cpw screenshot -o shot.png`);
+  console.log(`  npx cpw eval "document.title"`);
+  console.log(`  npx cpw close`);
+  console.log(`
+Press Ctrl+C to close.`);
+  await new Promise((resolve) => {
+    process.on("SIGINT", () => {
+      console.log("\nClosing browser...");
+      resolve();
+    });
+    process.on("SIGTERM", () => resolve());
+  });
+  clearSession();
+  try {
+    await browser.close();
+  } catch {
+  }
+}
+async function cmdClose() {
+  const session = readSession();
+  if (!session) {
+    console.error("No running session.");
+    process.exit(1);
+  }
+  try {
+    const browser = await automaton.connect(session.wsEndpoint);
+    await browser.close();
+  } catch {
+    try {
+      process.kill(session.pid, "SIGTERM");
+    } catch {
+    }
+  }
+  clearSession();
+  console.log("Session closed.");
+}
+async function cmdScreenshot(rest) {
+  const pos = positionalArgs(rest);
+  const url = pos[0];
+  const output = flagValue(rest, "-o") || flagValue(rest, "--output");
+  if (!output) {
+    console.error("Usage: cpw screenshot [url] -o <file> [--full-page]");
+    process.exit(1);
+  }
+  const fullPage = hasFlag(rest, "--full-page");
+  const format = output.endsWith(".jpeg") || output.endsWith(".jpg") ? "jpeg" : "png";
+  if (url) {
+    const headless = resolveHeadless(rest, true);
+    await withPage(url, { headless }, async (page) => {
+      await page.screenshot({ path: output, format, fullPage });
+    });
+  } else {
+    const { browser, page } = await connectToSession();
+    try {
+      await page.screenshot({ path: output, format, fullPage });
+    } finally {
+      await browser.disconnect();
+    }
+  }
+  console.log(`Screenshot saved to ${output}`);
+}
+async function cmdHtml(rest) {
+  const pos = positionalArgs(rest);
+  const url = pos[0];
+  const output = flagValue(rest, "-o") || flagValue(rest, "--output");
+  if (!output) {
+    console.error("Usage: cpw html [url] -o <file>");
+    process.exit(1);
+  }
+  const writeHtml = async (page) => {
+    const html = await page.content();
+    fs5.writeFileSync(path5.resolve(output), html, "utf-8");
+  };
+  if (url) {
+    const headless = resolveHeadless(rest, true);
+    await withPage(url, { headless }, async (page) => {
+      await writeHtml(page);
+    });
+  } else {
+    const { browser, page } = await connectToSession();
+    try {
+      await writeHtml(page);
+    } finally {
+      await browser.disconnect();
+    }
+  }
+  console.log(`HTML saved to ${output}`);
+}
+async function cmdPdf(rest) {
+  const pos = positionalArgs(rest);
+  const url = pos[0];
+  const output = flagValue(rest, "-o") || flagValue(rest, "--output");
+  if (!output) {
+    console.error("Usage: cpw pdf [url] -o <file>");
+    process.exit(1);
+  }
+  const renderVisualPdf = async (browser, page) => {
+    const screenshot = await page.screenshotBase64({ format: "png" });
+    const screenshotSize = pngDimensions(Buffer.from(screenshot, "base64"));
+    const context = await browser.newContext();
+    try {
+      const helperPage = await context.newPage();
+      const imageDataUrl = `data:image/png;base64,${screenshot}`;
+      const screenshotDimensions = await helperPage.evaluate((dataUrl) => {
+        document.open();
+        document.write(`<!doctype html>
+<html>
+  <head>
+    <meta charset="utf-8">
+    <style>
+      html, body {
+        margin: 0;
+        padding: 0;
+        overflow: hidden;
+        background: #fff;
+      }
+      img {
+        display: block;
+        width: 100%;
+        height: auto;
+      }
+    </style>
+  </head>
+  <body>
+    <img id="shot" alt="page screenshot">
+  </body>
+</html>`);
+        document.close();
+        const img = document.getElementById("shot");
+        if (!(img instanceof HTMLImageElement)) {
+          throw new Error("Failed to create PDF preview image");
+        }
+        return new Promise((resolve, reject) => {
+          img.onload = () => {
+            resolve({ width: img.naturalWidth || 0, height: img.naturalHeight || 0 });
+          };
+          img.onerror = () => reject(new Error("Failed to load screenshot image"));
+          img.src = dataUrl;
+        });
+      }, imageDataUrl);
+      await helperPage.pdf({
+        path: output,
+        printBackground: true,
+        paperWidth: Math.max((screenshotDimensions?.width ?? screenshotSize.width) / 96, 1),
+        paperHeight: Math.max((screenshotDimensions?.height ?? screenshotSize.height) / 96, 1),
+        marginTop: 0,
+        marginBottom: 0,
+        marginLeft: 0,
+        marginRight: 0,
+        scale: 1,
+        preferCSSPageSize: false
+      });
+    } finally {
+      await context.close();
+    }
+  };
+  if (url) {
+    await withPage(url, { headless: true, maximize: true }, async (page, browser) => {
+      await renderVisualPdf(browser, page);
+    });
+  } else {
+    const { browser, page } = await connectToSession();
+    try {
+      await renderVisualPdf(browser, page);
+    } finally {
+      await browser.disconnect();
+    }
+  }
+  console.log(`PDF saved to ${output}`);
+}
+async function cmdEval(rest) {
+  const pos = positionalArgs(rest);
+  const session = readSession();
+  let url;
+  let script;
+  if (pos.length >= 2) {
+    url = pos[0];
+    script = pos[1];
+  } else if (pos.length === 1 && session) {
+    script = pos[0];
+  } else if (pos.length === 1) {
+    console.error("Usage: cpw eval <url> <script>\n       cpw eval <script>   (when a session is running)");
+    process.exit(1);
+    return;
+  } else {
+    console.error("Usage: cpw eval [url] <script>");
+    process.exit(1);
+    return;
+  }
+  if (url) {
+    const headless = resolveHeadless(rest, true);
+    await withPage(url, { headless }, async (page) => {
+      const result = await page.evaluate(script);
+      const output = result === void 0 ? "undefined" : JSON.stringify(result, null, 2);
+      console.log(output);
+    });
+  } else {
+    const { browser, page } = await connectToSession();
+    try {
+      const result = await page.evaluate(script);
+      const output = result === void 0 ? "undefined" : JSON.stringify(result, null, 2);
+      console.log(output);
+    } finally {
+      await browser.disconnect();
+    }
+  }
+}
+async function cmdVersion() {
+  const pkgPath = path5.resolve(path5.dirname(fileURLToPath(import.meta.url)), "../package.json");
+  let version = "unknown";
+  try {
+    const pkg = JSON.parse(fs5.readFileSync(pkgPath, "utf-8"));
+    version = pkg.version;
+  } catch {
+  }
+  console.log(`cdpwright v${version}`);
+  console.log(`Pinned revision: ${PINNED_REVISION}`);
+  const platform = detectPlatform();
+  const cacheRoot = defaultCacheRoot(platform);
+  const revision = resolveRevision(process.env.CDPWRIGHT_REVISION);
+  const execPath = path5.join(cacheRoot, platform, revision, chromiumExecutableRelativePath(platform));
+  if (fs5.existsSync(execPath)) {
+    try {
+      const ver = await chromiumVersion(execPath);
+      console.log(`Chromium: ${ver}`);
+    } catch {
+      console.log(`Chromium: installed at ${execPath}`);
+    }
+  } else {
+    console.log("Chromium: not installed (run 'cpw install')");
+  }
+  const session = readSession();
+  if (session) {
+    console.log(`Session: active (pid ${session.pid})`);
+  }
 }
 async function main() {
   const [, , command, ...rest] = process.argv;
@@ -2145,14 +2965,31 @@ async function main() {
     printHelp();
     process.exit(0);
   }
-  if (command !== "download") {
-    console.error(`Unknown command: ${command}`);
-    printHelp();
-    process.exit(1);
+  switch (command) {
+    case "download":
+    case "install":
+      return cmdDownload(rest);
+    case "open":
+      return cmdOpen(rest);
+    case "close":
+      return cmdClose();
+    case "screenshot":
+      return cmdScreenshot(rest);
+    case "html":
+      return cmdHtml(rest);
+    case "pdf":
+      return cmdPdf(rest);
+    case "eval":
+      return cmdEval(rest);
+    case "version":
+    case "--version":
+    case "-v":
+      return cmdVersion();
+    default:
+      console.error(`Unknown command: ${command}`);
+      printHelp();
+      process.exit(1);
   }
-  const latest = rest.includes("--latest");
-  const manager = new ChromiumManager();
-  await manager.download({ latest });
 }
 main().catch((err) => {
   console.error(err instanceof Error ? err.message : String(err));