@toolstackhq/cdpwright 1.1.0 → 1.3.0

package/dist/cli.js

@@ -419,27 +419,77 @@ function serializeShadowDomHelpers() {
 // src/core/Locator.ts
 var Locator = class {
   frame;
-  selector;
-  options;
-  constructor(frame, selector, options = {}) {
+  query;
+  constructor(frame, query) {
     this.frame = frame;
-    this.selector = selector;
-    this.options = options;
+    this.query = query;
+  }
+  getEvents() {
+    return this.frame.getEvents();
+  }
+  getFrameId() {
+    return this.frame.id;
+  }
+  describe() {
+    switch (this.query.kind) {
+      case "selector":
+        return this.query.selector;
+      case "text":
+        return typeof this.query.text === "string" ? `text=${JSON.stringify(this.query.text)}` : `text=${this.query.text.toString()}`;
+      case "role":
+        return `role=${this.query.role}${this.query.options?.name ? ` name=${typeof this.query.options.name === "string" ? JSON.stringify(this.query.options.name) : this.query.options.name.toString()}` : ""}`;
+    }
   }
   async click(options = {}) {
-    return this.frame.click(this.selector, { ...this.options, ...options });
+    return this.frame.clickLocator(this.query, { ...this.queryTimeoutOptions(), ...options });
   }
   async dblclick(options = {}) {
-    return this.frame.dblclick(this.selector, { ...this.options, ...options });
+    return this.frame.dblclickLocator(this.query, { ...this.queryTimeoutOptions(), ...options });
   }
   async type(text, options = {}) {
-    return this.frame.type(this.selector, text, { ...this.options, ...options });
+    return this.frame.typeLocator(this.query, text, { ...this.queryTimeoutOptions(), ...options });
   }
   async exists() {
-    return this.frame.exists(this.selector, this.options);
+    return this.frame.existsLocator(this.query);
+  }
+  async isVisible() {
+    return this.frame.isVisibleLocator(this.query);
+  }
+  async isEnabled() {
+    return this.frame.isEnabledLocator(this.query);
+  }
+  async isChecked() {
+    return this.frame.isCheckedLocator(this.query);
   }
   async text() {
-    return this.frame.text(this.selector, this.options);
+    return this.frame.textLocator(this.query);
+  }
+  async value() {
+    return this.frame.valueLocator(this.query);
+  }
+  async attribute(name) {
+    return this.frame.attributeLocator(this.query, name);
+  }
+  async classes() {
+    return this.frame.classesLocator(this.query);
+  }
+  async css(property) {
+    return this.frame.cssLocator(this.query, property);
+  }
+  async hasFocus() {
+    return this.frame.hasFocusLocator(this.query);
+  }
+  async isInViewport(fully = false) {
+    return this.frame.isInViewportLocator(this.query, fully);
+  }
+  async isEditable() {
+    return this.frame.isEditableLocator(this.query);
+  }
+  async count() {
+    return this.frame.countLocator(this.query);
+  }
+  queryTimeoutOptions() {
+    return "options" in this.query && this.query.options?.timeoutMs ? { timeoutMs: this.query.options.timeoutMs } : {};
   }
 };
 
@@ -471,6 +521,9 @@ var Frame = class {
     this.url = meta.url;
     this.parentId = meta.parentId;
   }
+  getEvents() {
+    return this.events;
+  }
   async evaluate(fnOrString, ...args) {
     return this.evaluateInContext(fnOrString, args);
   }
@@ -487,7 +540,13 @@ var Frame = class {
     return this.querySelectorAllInternal(selector, options, true);
   }
   locator(selector, options = {}) {
-    return new Locator(this, selector, options);
+    return new Locator(this, { kind: "selector", selector, options });
+  }
+  getByText(text, options = {}) {
+    return new Locator(this, { kind: "text", text, options });
+  }
+  getByRole(role, options = {}) {
+    return new Locator(this, { kind: "role", role, options });
   }
   async click(selector, options = {}) {
     await this.performClick(selector, options, false);
@@ -922,6 +981,176 @@ var Frame = class {
     const box = await this.resolveElementBox(selector, options);
     return Boolean(box && box.visible);
   }
+  async clickLocator(query, options = {}) {
+    await this.performClickLocator(query, options, false);
+  }
+  async dblclickLocator(query, options = {}) {
+    await this.performClickLocator(query, options, true);
+  }
+  async typeLocator(query, text, options = {}) {
+    const start = Date.now();
+    const description = this.locatorDescription(query);
+    this.events.emit("action:start", { name: "type", selector: description, frameId: this.id, sensitive: options.sensitive });
+    await waitFor(async () => {
+      const box = await this.resolveLocatorElementBox(query, options);
+      if (!box || !box.visible) {
+        return false;
+      }
+      return true;
+    }, { timeoutMs: options.timeoutMs ?? this.defaultTimeout, description: `type ${description}` });
+    const focusExpression = this.buildLocatorExpression(query, `
+      if (!el) {
+        return;
+      }
+      el.focus();
+    `);
+    const focusParams = {
+      expression: focusExpression,
+      returnByValue: true
+    };
+    if (this.contextId) {
+      focusParams.contextId = this.contextId;
+    }
+    await this.session.send("Runtime.evaluate", focusParams);
+    await this.session.send("Input.insertText", { text });
+    const duration = Date.now() - start;
+    this.events.emit("action:end", { name: "type", selector: description, frameId: this.id, durationMs: duration, sensitive: options.sensitive });
+    this.logger.debug("Type", description, `${duration}ms`);
+  }
+  async existsLocator(query) {
+    return Boolean(await this.evalOnLocator(query, false, `
+      return Boolean(el);
+    `));
+  }
+  async isVisibleLocator(query) {
+    return this.evalOnLocator(query, false, `
+      if (!el) {
+        return null;
+      }
+      const rect = el.getBoundingClientRect();
+      const style = window.getComputedStyle(el);
+      return rect.width > 0 && rect.height > 0 && style.visibility !== "hidden" && style.display !== "none" && Number(style.opacity || "1") > 0;
+    `);
+  }
+  async isEnabledLocator(query) {
+    return this.evalOnLocator(query, false, `
+      if (!el) {
+        return null;
+      }
+      const disabled = Boolean(el.disabled) || el.hasAttribute("disabled");
+      const ariaDisabled = el.getAttribute && el.getAttribute("aria-disabled") === "true";
+      return !(disabled || ariaDisabled);
+    `);
+  }
+  async isCheckedLocator(query) {
+    return this.evalOnLocator(query, false, `
+      if (!el) {
+        return null;
+      }
+      const aria = el.getAttribute && el.getAttribute("aria-checked");
+      if (aria === "true") {
+        return true;
+      }
+      if (aria === "false") {
+        return false;
+      }
+      if ("checked" in el) {
+        return Boolean(el.checked);
+      }
+      return null;
+    `);
+  }
+  async textLocator(query) {
+    return this.evalOnLocator(query, false, `
+      if (!el) {
+        return null;
+      }
+      if (el instanceof HTMLInputElement) {
+        const type = (el.getAttribute("type") || "text").toLowerCase();
+        if (type === "button" || type === "submit" || type === "reset") {
+          return el.value || "";
+        }
+      }
+      return el.textContent || "";
+    `);
+  }
+  async valueLocator(query) {
+    return this.evalOnLocator(query, false, `
+      if (!el) {
+        return null;
+      }
+      if ("value" in el) {
+        return el.value ?? "";
+      }
+      return el.getAttribute("value");
+    `);
+  }
+  async attributeLocator(query, name) {
+    return this.evalOnLocator(query, false, `
+      if (!el || !(el instanceof Element)) {
+        return null;
+      }
+      return el.getAttribute(${JSON.stringify(name)});
+    `);
+  }
+  async classesLocator(query) {
+    return this.evalOnLocator(query, false, `
+      if (!el) {
+        return null;
+      }
+      if (!el.classList) {
+        return [];
+      }
+      return Array.from(el.classList);
+    `);
+  }
+  async cssLocator(query, property) {
+    return this.evalOnLocator(query, false, `
+      if (!el) {
+        return null;
+      }
+      const style = window.getComputedStyle(el);
+      return style.getPropertyValue(${JSON.stringify(property)}) || "";
+    `);
+  }
+  async hasFocusLocator(query) {
+    return this.evalOnLocator(query, false, `
+      if (!el) {
+        return null;
+      }
+      return document.activeElement === el;
+    `);
+  }
+  async isInViewportLocator(query, fully = false) {
+    return this.evalOnLocator(query, false, `
+      if (!el) {
+        return null;
+      }
+      const rect = el.getBoundingClientRect();
+      const viewWidth = window.innerWidth || document.documentElement.clientWidth;
+      const viewHeight = window.innerHeight || document.documentElement.clientHeight;
+      if (${fully ? "true" : "false"}) {
+        return rect.top >= 0 && rect.left >= 0 && rect.bottom <= viewHeight && rect.right <= viewWidth;
+      }
+      return rect.bottom > 0 && rect.right > 0 && rect.top < viewHeight && rect.left < viewWidth;
+    `);
+  }
+  async isEditableLocator(query) {
+    return this.evalOnLocator(query, false, `
+      if (!el) {
+        return null;
+      }
+      const disabled = Boolean(el.disabled) || el.hasAttribute("disabled");
+      const readOnly = Boolean(el.readOnly) || el.hasAttribute("readonly");
+      const ariaDisabled = el.getAttribute && el.getAttribute("aria-disabled") === "true";
+      return !(disabled || readOnly || ariaDisabled);
+    `);
+  }
+  async countLocator(query) {
+    return this.evalOnLocator(query, true, `
+      return elements.length;
+    `);
+  }
   async text(selector, options = {}) {
     return this.evalOnSelector(selector, options, false, `
       if (!el) {
@@ -1103,6 +1332,263 @@ var Frame = class {
       return !(disabled || readOnly || ariaDisabled);
     `);
   }
+  async performClickLocator(query, options, isDouble) {
+    const start = Date.now();
+    const actionName = isDouble ? "dblclick" : "click";
+    const description = this.locatorDescription(query);
+    this.events.emit("action:start", { name: actionName, selector: description, frameId: this.id });
+    const box = await waitFor(async () => {
+      const result = await this.resolveLocatorElementBox(query, options);
+      if (!result || !result.visible) {
+        return null;
+      }
+      return result;
+    }, { timeoutMs: options.timeoutMs ?? this.defaultTimeout, description: `${actionName} ${description}` });
+    const centerX = box.x + box.width / 2;
+    const centerY = box.y + box.height / 2;
+    await this.session.send("Input.dispatchMouseEvent", { type: "mouseMoved", x: centerX, y: centerY });
+    await this.session.send("Input.dispatchMouseEvent", { type: "mousePressed", x: centerX, y: centerY, button: "left", clickCount: 1, buttons: 1 });
+    await this.session.send("Input.dispatchMouseEvent", { type: "mouseReleased", x: centerX, y: centerY, button: "left", clickCount: 1, buttons: 0 });
+    if (isDouble) {
+      await this.session.send("Input.dispatchMouseEvent", { type: "mouseMoved", x: centerX, y: centerY });
+      await this.session.send("Input.dispatchMouseEvent", { type: "mousePressed", x: centerX, y: centerY, button: "left", clickCount: 2, buttons: 1 });
+      await this.session.send("Input.dispatchMouseEvent", { type: "mouseReleased", x: centerX, y: centerY, button: "left", clickCount: 2, buttons: 0 });
+    }
+    const duration = Date.now() - start;
+    this.events.emit("action:end", { name: actionName, selector: description, frameId: this.id, durationMs: duration });
+    this.logger.debug("Click", description, `${duration}ms`);
+  }
+  locatorDescription(query) {
+    switch (query.kind) {
+      case "selector":
+        return query.selector;
+      case "text":
+        return typeof query.text === "string" ? `text=${JSON.stringify(query.text)}` : `text=${query.text.toString()}`;
+      case "role":
+        return `role=${query.role}${query.options?.name ? ` name=${typeof query.options.name === "string" ? JSON.stringify(query.options.name) : query.options.name.toString()}` : ""}`;
+    }
+  }
+  async resolveLocatorElementBox(query, options) {
+    return this.evalOnLocator(query, false, `
+      if (!el) {
+        return null;
+      }
+      el.scrollIntoView({ block: "center", inline: "center" });
+      const rect = el.getBoundingClientRect();
+      const style = window.getComputedStyle(el);
+      return {
+        x: rect.x,
+        y: rect.y,
+        width: rect.width,
+        height: rect.height,
+        visible: rect.width > 0 && rect.height > 0 && style.visibility !== "hidden" && style.display !== "none" && Number(style.opacity || "1") > 0
+      };
+    `);
+  }
+  async evalOnLocator(query, all, body) {
+    const expression = this.buildLocatorExpression(query, body, all);
+    const params = {
+      expression,
+      returnByValue: true
+    };
+    if (this.contextId) {
+      params.contextId = this.contextId;
+    }
+    const result = await this.session.send("Runtime.evaluate", params);
+    return result.result.value;
+  }
+  buildLocatorExpression(query, body, all = false) {
+    const helpers = serializeShadowDomHelpers();
+    const serializedQuery = this.serializeLocatorQuery(query);
+    return `(function() {
+      const querySelectorAllDeep = ${helpers.querySelectorAllDeep};
+      const normalizeWhitespace = (value) => String(value ?? "").replace(/\\s+/g, " ").trim();
+      const cssEscape = (value) => {
+        if (typeof CSS !== "undefined" && CSS.escape) return CSS.escape(value);
+        return String(value).replace(/[^a-zA-Z0-9_-]/g, (c) => "\\\\" + c.charCodeAt(0).toString(16) + " ");
+      };
+      const textFromElement = (el) => {
+        if (!el) return "";
+        if (el instanceof HTMLInputElement) {
+          const type = (el.getAttribute("type") || "").toLowerCase();
+          if (type === "button" || type === "submit" || type === "reset" || type === "image") {
+            return el.value || el.getAttribute("alt") || "";
+          }
+        }
+        return el.textContent || "";
+      };
+      const isHidden = (el) => {
+        if (!el || !(el instanceof Element)) return true;
+        const style = window.getComputedStyle(el);
+        if (el.hidden || el.getAttribute("aria-hidden") === "true") return true;
+        return style.display === "none" || style.visibility === "hidden" || Number(style.opacity || "1") <= 0;
+      };
+      const getLabelText = (el) => {
+        if (!el || !(el instanceof Element)) return "";
+        const ariaLabel = el.getAttribute("aria-label");
+        if (ariaLabel) return normalizeWhitespace(ariaLabel);
+        const labelledBy = el.getAttribute("aria-labelledby");
+        if (labelledBy) {
+          const parts = labelledBy.split(/\\s+/).filter(Boolean).map((id) => document.getElementById(id)?.textContent || "");
+          const text = normalizeWhitespace(parts.join(" "));
+          if (text) return text;
+        }
+        if (el instanceof HTMLInputElement || el instanceof HTMLTextAreaElement || el instanceof HTMLSelectElement) {
+          if (el.id) {
+            const label = document.querySelector("label[for="" + cssEscape(el.id) + ""]");
+            if (label) {
+              const text = normalizeWhitespace(label.textContent || "");
+              if (text) return text;
+            }
+          }
+          const wrap = el.closest("label");
+          if (wrap) {
+            const text = normalizeWhitespace(wrap.textContent || "");
+            if (text) return text;
+          }
+        }
+        if (el instanceof HTMLImageElement) {
+          return normalizeWhitespace(el.getAttribute("alt") || el.getAttribute("title") || "");
+        }
+        return normalizeWhitespace(el.getAttribute("title") || "");
+      };
+      const getImplicitRole = (el) => {
+        if (!el || !(el instanceof Element)) return "";
+        const explicitRole = (el.getAttribute("role") || "").trim().split(/\\s+/)[0];
+        if (explicitRole) return explicitRole;
+        const tag = el.tagName.toLowerCase();
+        if (tag === "button") return "button";
+        if (tag === "summary") return "button";
+        if (tag === "a" && el.hasAttribute("href")) return "link";
+        if (tag === "input") {
+          const type = (el.getAttribute("type") || "text").toLowerCase();
+          if (type === "checkbox") return "checkbox";
+          if (type === "radio") return "radio";
+          if (type === "range") return "slider";
+          if (type === "submit" || type === "button" || type === "reset") return "button";
+          if (type === "file") return "button";
+          return "textbox";
+        }
+        if (tag === "textarea") return "textbox";
+        if (tag === "select") return "combobox";
+        if (tag === "img") return "img";
+        if (tag === "ul" || tag === "ol") return "list";
+        if (tag === "li") return "listitem";
+        if (tag === "table") return "table";
+        if (tag === "tr") return "row";
+        if (tag === "td") return "cell";
+        if (tag === "th") return "columnheader";
+        if (/^h[1-6]$/.test(tag)) return "heading";
+        if (tag === "option") return "option";
+        if (tag === "fieldset") return "group";
+        if (tag === "form") return "form";
+        if (el.hasAttribute("contenteditable")) return "textbox";
+        return explicitRole;
+      };
+      const matchText = (actual, expected, exact) => {
+        const normalizedActual = normalizeWhitespace(actual);
+        if (expected && expected.kind === "regex") {
+          const regex = new RegExp(expected.source, expected.flags);
+          return regex.test(normalizedActual);
+        }
+        const normalizedExpected = normalizeWhitespace(expected.value);
+        if (exact) {
+          return normalizedActual === normalizedExpected;
+        }
+        return normalizedActual.toLowerCase().includes(normalizedExpected.toLowerCase());
+      };
+      const matchName = (actual, expected, exact) => {
+        const normalizedActual = normalizeWhitespace(actual);
+        if (expected && expected.kind === "regex") {
+          const regex = new RegExp(expected.source, expected.flags);
+          return regex.test(normalizedActual);
+        }
+        const normalizedExpected = normalizeWhitespace(expected.value);
+        if (exact) {
+          return normalizedActual === normalizedExpected;
+        }
+        return normalizedActual.toLowerCase().includes(normalizedExpected.toLowerCase());
+      };
+      const query = ${serializedQuery};
+      const nodes = Array.from(querySelectorAllDeep(document, "*"));
+      const selectorMatches = () => {
+        if (query.kind !== "selector") {
+          return [];
+        }
+        if (query.selector.includes(">>>")) {
+          return querySelectorAllDeep(document, query.selector);
+        }
+        if (query.parsed?.type === "xpath") {
+          const result = document.evaluate(query.parsed.value, document, null, XPathResult.ORDERED_NODE_SNAPSHOT_TYPE, null);
+          const list = [];
+          for (let i = 0; i < result.snapshotLength; i += 1) {
+            const item = result.snapshotItem(i);
+            if (item instanceof Element) {
+              list.push(item);
+            }
+          }
+          return list;
+        }
+        return Array.from(document.querySelectorAll(query.selector));
+      };
+      const selectorMatchSet = selectorMatches();
+      const matches = nodes.filter((el) => {
+        if (!(el instanceof Element)) return false;
+        if (query.kind === "selector") {
+          return selectorMatchSet.includes(el);
+        }
+        if (query.kind === "text") {
+          const text = textFromElement(el);
+          return matchText(text, query.text, Boolean(query.options?.exact));
+        }
+        const role = getImplicitRole(el);
+        if (!role || role !== query.role) {
+          return false;
+        }
+        if (!query.options?.includeHidden && isHidden(el)) {
+          return false;
+        }
+        if (query.options?.name == null) {
+          return true;
+        }
+        const name = getLabelText(el) || textFromElement(el);
+        return matchName(name, query.options.name, Boolean(query.options?.exact));
+      });
+      const textMatches = query.kind === "text"
+        ? matches.filter((el) => !matches.some((other) => other !== el && el.contains(other)))
+        : matches;
+      const elements = ${all ? "textMatches" : "textMatches.slice(0, 1)"};
+      const el = elements[0] || null;
+      ${body}
+    })()`;
+  }
+  serializeLocatorQuery(query) {
+    switch (query.kind) {
+      case "selector":
+        return JSON.stringify({ kind: "selector", selector: query.selector, options: query.options, parsed: parseSelector(query.selector) });
+      case "text":
+        return JSON.stringify({
+          kind: "text",
+          text: this.serializeTextQuery(query.text),
+          options: query.options
+        });
+      case "role":
+        return JSON.stringify({
+          kind: "role",
+          role: query.role,
+          options: query.options ? {
+            ...query.options,
+            name: query.options.name != null ? this.serializeTextQuery(query.options.name) : void 0
+          } : void 0
+        });
+    }
+  }
+  serializeTextQuery(text) {
+    if (text instanceof RegExp) {
+      return { kind: "regex", source: text.source, flags: text.flags.replace("g", "") };
+    }
+    return { kind: "string", value: text };
+  }
   async performClick(selector, options, isDouble) {
     const start = Date.now();
     const actionName = isDouble ? "dblclick" : "click";
@@ -1323,6 +1809,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;
@@ -1375,7 +1866,13 @@ var Page = class {
     return null;
   }
   locator(selector) {
-    return new Locator(this.mainFrame(), selector);
+    return this.mainFrame().locator(selector);
+  }
+  getByText(text, options = {}) {
+    return this.mainFrame().getByText(text, options);
+  }
+  getByRole(role, options = {}) {
+    return this.mainFrame().getByRole(role, options);
   }
   async goto(url, options = {}) {
     ensureAllowedUrl(url, { allowFileUrl: options.allowFileUrl });
@@ -1442,9 +1939,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 +1970,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 +1984,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 +2023,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 +2131,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 +2162,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 +2198,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 +2540,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 +2569,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) {
@@ -2197,42 +2745,42 @@ var AssertionError = class extends Error {
 
 // src/assert/expect.ts
 var ElementExpectation = class _ElementExpectation {
-  frame;
-  selector;
+  target;
   options;
   negate;
   events;
-  constructor(frame, selector, options, negate, events) {
-    this.frame = frame;
-    this.selector = selector;
+  constructor(target, options, negate, events) {
+    this.target = target;
     this.options = options;
     this.negate = negate;
     this.events = events;
   }
   get not() {
-    return new _ElementExpectation(this.frame, this.selector, this.options, !this.negate, this.events);
+    return new _ElementExpectation(this.target, this.options, !this.negate, this.events);
   }
   async toExist() {
     return this.assert(async () => {
-      const exists = await this.frame.exists(this.selector, this.options);
+      const exists = await this.target.exists();
       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);
+      const visible = await this.target.isVisible();
+      if (visible == null) return this.negate ? true : false;
       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);
+      const visible = await this.target.isVisible();
+      if (visible == null) return this.negate ? true : false;
       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);
+      const enabled = await this.target.isEnabled();
       if (enabled == null) {
         return this.negate ? true : false;
       }
@@ -2241,7 +2789,7 @@ var ElementExpectation = class _ElementExpectation {
   }
   async toBeDisabled() {
     return this.assert(async () => {
-      const enabled = await this.frame.isEnabled(this.selector, this.options);
+      const enabled = await this.target.isEnabled();
       if (enabled == null) {
         return this.negate ? true : false;
       }
@@ -2251,7 +2799,7 @@ var ElementExpectation = class _ElementExpectation {
   }
   async toBeChecked() {
     return this.assert(async () => {
-      const checked = await this.frame.isChecked(this.selector, this.options);
+      const checked = await this.target.isChecked();
       if (checked == null) {
         return this.negate ? true : false;
       }
@@ -2260,7 +2808,7 @@ var ElementExpectation = class _ElementExpectation {
   }
   async toBeUnchecked() {
     return this.assert(async () => {
-      const checked = await this.frame.isChecked(this.selector, this.options);
+      const checked = await this.target.isChecked();
       if (checked == null) {
         return this.negate ? true : false;
       }
@@ -2271,7 +2819,7 @@ var ElementExpectation = class _ElementExpectation {
   async toHaveText(textOrRegex) {
     const expected = textOrRegex;
     return this.assert(async () => {
-      const text = await this.frame.text(this.selector, this.options);
+      const text = await this.target.text();
       if (text == null) {
         return this.negate ? true : false;
       }
@@ -2282,7 +2830,7 @@ var ElementExpectation = class _ElementExpectation {
   async toHaveExactText(textOrRegex) {
     const expected = textOrRegex;
     return this.assert(async () => {
-      const text = await this.frame.text(this.selector, this.options);
+      const text = await this.target.text();
       if (text == null) {
         return this.negate ? true : false;
       }
@@ -2293,7 +2841,7 @@ var ElementExpectation = class _ElementExpectation {
   async toContainText(textOrRegex) {
     const expected = textOrRegex;
     return this.assert(async () => {
-      const text = await this.frame.text(this.selector, this.options);
+      const text = await this.target.text();
       if (text == null) {
         return this.negate ? true : false;
       }
@@ -2304,7 +2852,7 @@ var ElementExpectation = class _ElementExpectation {
   async toHaveValue(valueOrRegex) {
     const expected = valueOrRegex;
     return this.assert(async () => {
-      const value = await this.frame.value(this.selector, this.options);
+      const value = await this.target.value();
       if (value == null) {
         return this.negate ? true : false;
       }
@@ -2315,7 +2863,7 @@ var ElementExpectation = class _ElementExpectation {
   async toHaveAttribute(name, valueOrRegex) {
     const expected = valueOrRegex;
     return this.assert(async () => {
-      const value = await this.frame.attribute(this.selector, name, this.options);
+      const value = await this.target.attribute(name);
       if (expected === void 0) {
         const exists = value != null;
         return this.negate ? !exists : exists;
@@ -2335,7 +2883,7 @@ var ElementExpectation = class _ElementExpectation {
   }
   async toHaveCount(expected) {
     return this.assert(async () => {
-      const count = await this.frame.count(this.selector, this.options);
+      const count = await this.target.count();
       const matches = count === expected;
       return this.negate ? !matches : matches;
     }, this.negate ? "Expected element count not to match" : "Expected element count to match", { expected });
@@ -2343,7 +2891,7 @@ var ElementExpectation = class _ElementExpectation {
   async toHaveClass(nameOrRegex) {
     const expected = nameOrRegex;
     return this.assert(async () => {
-      const classes = await this.frame.classes(this.selector, this.options);
+      const classes = await this.target.classes();
       if (classes == null) {
         return this.negate ? true : false;
       }
@@ -2353,7 +2901,7 @@ var ElementExpectation = class _ElementExpectation {
   }
   async toHaveClasses(expected) {
     return this.assert(async () => {
-      const classes = await this.frame.classes(this.selector, this.options);
+      const classes = await this.target.classes();
       if (classes == null) {
         return this.negate ? true : false;
       }
@@ -2364,7 +2912,7 @@ var ElementExpectation = class _ElementExpectation {
   async toHaveCss(property, valueOrRegex) {
     const expected = valueOrRegex;
     return this.assert(async () => {
-      const value = await this.frame.css(this.selector, property, this.options);
+      const value = await this.target.css(property);
       if (value == null) {
         return this.negate ? true : false;
       }
@@ -2375,7 +2923,7 @@ var ElementExpectation = class _ElementExpectation {
   }
   async toHaveFocus() {
     return this.assert(async () => {
-      const focused = await this.frame.hasFocus(this.selector, this.options);
+      const focused = await this.target.hasFocus();
       if (focused == null) {
         return this.negate ? true : false;
       }
@@ -2384,7 +2932,7 @@ var ElementExpectation = class _ElementExpectation {
   }
   async toBeInViewport(options = {}) {
     return this.assert(async () => {
-      const inViewport = await this.frame.isInViewport(this.selector, this.options, Boolean(options.fully));
+      const inViewport = await this.target.isInViewport(Boolean(options.fully));
       if (inViewport == null) {
         return this.negate ? true : false;
       }
@@ -2393,7 +2941,7 @@ var ElementExpectation = class _ElementExpectation {
   }
   async toBeEditable() {
     return this.assert(async () => {
-      const editable = await this.frame.isEditable(this.selector, this.options);
+      const editable = await this.target.isEditable();
       if (editable == null) {
         return this.negate ? true : false;
       }
@@ -2403,7 +2951,7 @@ var ElementExpectation = class _ElementExpectation {
   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 });
+    this.events.emit("assertion:start", { name: message, selector: this.target.label, frameId: this.target.frameId });
     let lastState;
     try {
       await waitFor(async () => {
@@ -2413,13 +2961,51 @@ var ElementExpectation = class _ElementExpectation {
       }, { 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 } });
+      this.events.emit("assertion:end", { name: message, selector: this.target.label, frameId: this.target.frameId, durationMs: duration2, status: "failed" });
+      throw new AssertionError(message, { selector: this.target.label, 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" });
+    this.events.emit("assertion:end", { name: message, selector: this.target.label, frameId: this.target.frameId, durationMs: duration, status: "passed" });
   }
 };
+function frameTarget(frame, selector, options) {
+  return {
+    label: selector,
+    frameId: frame.id,
+    exists: () => frame.exists(selector, options),
+    isVisible: () => frame.isVisible(selector, options),
+    isEnabled: () => frame.isEnabled(selector, options),
+    isChecked: () => frame.isChecked(selector, options),
+    text: () => frame.text(selector, options),
+    value: () => frame.value(selector, options),
+    attribute: (name) => frame.attribute(selector, name, options),
+    count: () => frame.count(selector, options),
+    classes: () => frame.classes(selector, options),
+    css: (property) => frame.css(selector, property, options),
+    hasFocus: () => frame.hasFocus(selector, options),
+    isInViewport: (fully = false) => frame.isInViewport(selector, options, fully),
+    isEditable: () => frame.isEditable(selector, options)
+  };
+}
+function locatorTarget(locator) {
+  return {
+    label: locator.describe(),
+    frameId: locator.getFrameId(),
+    exists: () => locator.exists(),
+    isVisible: () => locator.isVisible(),
+    isEnabled: () => locator.isEnabled(),
+    isChecked: () => locator.isChecked(),
+    text: () => locator.text(),
+    value: () => locator.value(),
+    attribute: (name) => locator.attribute(name),
+    count: () => locator.count(),
+    classes: () => locator.classes(),
+    css: (property) => locator.css(property),
+    hasFocus: () => locator.hasFocus(),
+    isInViewport: (fully = false) => locator.isInViewport(fully),
+    isEditable: () => locator.isEditable()
+  };
+}
 var ExpectFrame = class {
   frame;
   events;
@@ -2428,25 +3014,31 @@ var ExpectFrame = class {
     this.events = events;
   }
   element(selector, options = {}) {
-    return new ElementExpectation(this.frame, selector, options, false, this.events);
+    return new ElementExpectation(frameTarget(this.frame, selector, options), options, false, this.events);
   }
 };
-function expect(page) {
+function expect(target) {
+  if (target instanceof Locator) {
+    return new ElementExpectation(locatorTarget(target), {}, false, target.getEvents());
+  }
   return {
-    element: (selector, options = {}) => new ElementExpectation(page.mainFrame(), selector, options, false, page.getEvents()),
+    element: (selector, options = {}) => new ElementExpectation(frameTarget(target.mainFrame(), selector, options), options, false, target.getEvents()),
     frame: (options) => {
-      const frame = page.frame(options);
+      const frame = target.frame(options);
       if (!frame) {
         throw new AssertionError("Frame not found", { selector: JSON.stringify(options) });
       }
-      return new ExpectFrame(frame, page.getEvents());
+      return new ExpectFrame(frame, target.getEvents());
     }
   };
 }
-Page.prototype.expect = function(selector, options) {
+Page.prototype.expect = function(target, options) {
   const builder = expect(this);
-  if (selector) {
-    return builder.element(selector, options);
+  if (target instanceof Locator) {
+    return expect(target);
+  }
+  if (target) {
+    return builder.element(target, options);
   }
   return builder;
 };
@@ -2463,38 +3055,97 @@ 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:
+  screenshot <url> -o f    Take a screenshot (PNG/JPEG)
+  pdf <url> -o file.pdf    Generate visual PDF of page
+  html <url> -o file.html  Save the page HTML source
+  eval <url> <script>      Run JS in page, print result as JSON
   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
   version                  Print cdpwright and Chromium versions
 
-Download options:
-  --latest                 Download the latest Chromium revision
-  --mirror <url>           Custom mirror base URL
-  --url <url>              Exact zip URL override
-
-Common options:
+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
+  --headed                 Run in headed mode
+  -o, --output <file>      Output file path (for screenshot, html, pdf)
+  --full-page              Capture full scrollable page (for screenshot)
+  --latest                 Download the latest Chromium revision (for download)
+  --mirror <url>           Custom mirror base URL (for download)
+  --url <url>              Exact zip URL override (for download)
 
-PDF options:
-  -o, --output <file>      Output file path (required)
-  Note: pdf always runs headless (CDP limitation)`);
+Interactive session:
+  open <url>               Open browser and start a session
+  close                    Close the running session
+  When a session is running, commands accept no URL and operate on the
+  live page instead:  cpw screenshot -o shot.png | cpw eval "document.title"`);
 }
 function hasFlag(args, flag) {
   return args.includes(flag);
@@ -2521,14 +3172,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 +3238,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 +3263,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 +3482,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 +3499,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":