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

@toolstackhq/cdpwright 1.1.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 +25 -7
package/dist/assert/expect.d.ts +1 -1
package/dist/assert/expect.js +1 -1
package/dist/{chunk-M5G6EMAS.js → chunk-PDUS6BDZ.js} +54 -20
package/dist/chunk-PDUS6BDZ.js.map +1 -0
package/dist/cli.js +373 -57
package/dist/cli.js.map +1 -1
package/dist/{expect-BY8vnFfi.d.ts → expect-CLal_AQd.d.ts} +2 -0
package/dist/index.d.ts +25 -4
package/dist/index.js +53 -4
package/dist/index.js.map +1 -1
package/package.json +1 -1
package/dist/chunk-M5G6EMAS.js.map +0 -1

package/dist/cli.js CHANGED Viewed

@@ -1323,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;
@@ -1442,9 +1447,19 @@ 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,
@@ -1463,6 +1478,7 @@ 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,
@@ -1476,26 +1492,37 @@ var Page = class {
   async pdf(options = {}) {
     const start = Date.now();
     this.events.emit("action:start", { name: "pdf", frameId: this.mainFrameId });
-    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
-    });
-    const buffer = Buffer.from(result.data, "base64");
-    if (options.path) {
-      const resolved = path2.resolve(options.path);
-      fs2.writeFileSync(resolved, buffer);
+    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 });
     }
-    const duration = Date.now() - start;
-    this.events.emit("action:end", { name: "pdf", frameId: this.mainFrameId, durationMs: duration });
     return buffer;
   }
   getEvents() {
@@ -1504,6 +1531,13 @@ var Page = class {
   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 });
@@ -1605,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);
@@ -1632,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 {
@@ -1651,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) {
@@ -1993,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);
@@ -2021,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) {
@@ -2463,22 +2519,89 @@ 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) \u2014 Chromium automation CLI
 Commands:
   download [options]       Download pinned Chromium snapshot
   install                  Alias for download
-  open <url>               Launch headed browser and navigate to URL
-  screenshot <url> -o f    Take a screenshot (PNG/JPEG)
-  pdf <url> -o file.pdf    Generate PDF of page (headless only)
-  eval <url> <script>      Run script in page, print result as JSON
+  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
@@ -2521,14 +2644,46 @@ function positionalArgs(args) {
   }
   return result;
 }
-async function withPage(url, options, fn) {
+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,
-    args,
+    maximize: options.maximize ?? false,
+    args: launchArgs(),
     logLevel: "warn"
   });
   try {
@@ -2555,19 +2710,24 @@ async function cmdOpen(rest) {
     process.exit(1);
   }
   const headless = resolveHeadless(rest, false);
-  const args = [];
-  if (process.platform === "linux") {
-    args.push("--no-sandbox", "--no-zygote", "--disable-dev-shm-usage");
-  }
   const browser = await automaton.launch({
     headless,
-    args,
+    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("Press Ctrl+C to close.");
+  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...");
@@ -2575,52 +2735,200 @@ async function cmdOpen(rest) {
     });
     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 url = positionalArgs(rest)[0];
+  const pos = positionalArgs(rest);
+  const url = pos[0];
   const output = flagValue(rest, "-o") || flagValue(rest, "--output");
-  if (!url || !output) {
-    console.error("Usage: cpw screenshot <url> -o <file> [--full-page]");
+  if (!output) {
+    console.error("Usage: cpw screenshot [url] -o <file> [--full-page]");
     process.exit(1);
   }
   const fullPage = hasFlag(rest, "--full-page");
-  const headless = resolveHeadless(rest, true);
   const format = output.endsWith(".jpeg") || output.endsWith(".jpg") ? "jpeg" : "png";
-  await withPage(url, { headless }, async (page) => {
-    await page.screenshot({ path: output, format, fullPage });
-  });
+  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 url = positionalArgs(rest)[0];
+  const pos = positionalArgs(rest);
+  const url = pos[0];
   const output = flagValue(rest, "-o") || flagValue(rest, "--output");
-  if (!url || !output) {
-    console.error("Usage: cpw pdf <url> -o <file>");
+  if (!output) {
+    console.error("Usage: cpw pdf [url] -o <file>");
     process.exit(1);
   }
-  await withPage(url, { headless: true }, async (page) => {
-    await page.pdf({ path: output, printBackground: true });
-  });
+  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 url = pos[0];
-  const script = pos[1];
-  if (!url || !script) {
-    console.error("Usage: cpw eval <url> <script>");
+  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();
+    }
   }
-  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);
-  });
 }
 async function cmdVersion() {
   const pkgPath = path5.resolve(path5.dirname(fileURLToPath(import.meta.url)), "../package.json");
@@ -2646,6 +2954,10 @@ async function cmdVersion() {
   } 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;
@@ -2659,8 +2971,12 @@ async function main() {
       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":