@crouton-kit/capture 1.4.15 → 1.4.17

package/bin/capture

@@ -5910,6 +5910,7 @@ var targets_exports = {};
 __export(targets_exports, {
   AmbiguousPageTargetError: () => AmbiguousPageTargetError,
   closeTarget: () => closeTarget,
+  findResponsivePageTabByUrl: () => findResponsivePageTabByUrl,
   findTab: () => findTab,
   findTabById: () => findTabById,
   findTabByIdAcrossEndpoints: () => findTabByIdAcrossEndpoints,
@@ -6009,11 +6010,12 @@ function normalizeUrlForMatch(value) {
   try {
     const url = new URL(value);
     const path48 = url.pathname.replace(/\/+$/, "") || "/";
+    const hostname = url.hostname.toLowerCase();
+    const loopback = hostname === "localhost" || hostname === "127.0.0.1";
+    const port = url.port || (url.protocol === "http:" ? "80" : url.protocol === "https:" ? "443" : "");
     return {
       full: `${url.origin}${path48}${url.search}${url.hash}`.toLowerCase(),
-      // `host` (not `hostname`): two local dev servers on the same loopback
-      // address but different ports must not register as a host match.
-      host: url.host.toLowerCase(),
+      origin: `${url.protocol}//${loopback ? "loopback" : hostname}:${port}`,
       path: path48.toLowerCase()
     };
   } catch {
@@ -6025,14 +6027,11 @@ function scoreTabUrlMatch(tabUrl, requestedUrl) {
   const requested = normalizeUrlForMatch(requestedUrl);
   if (tab && requested) {
     if (tab.full === requested.full) return 100;
-    if (tab.host === requested.host && tab.path === requested.path) return 95;
-    if (tab.host === requested.host && tab.path.startsWith(requested.path)) return 90;
-    if (tab.host === requested.host && requested.path.startsWith(tab.path)) return 85;
-    if (tab.host === requested.host) return 70;
-    if (tab.full.includes(requested.full)) return 60;
-    if (tab.full.includes(requested.host)) return 50;
-    if (requested.full.includes(tab.full)) return 40;
-    return 0;
+    if (tab.origin !== requested.origin) return 0;
+    if (tab.path === requested.path) return 95;
+    if (tab.path.startsWith(requested.path)) return 90;
+    if (requested.path.startsWith(tab.path)) return 85;
+    return 70;
   }
   const tabLower = tabUrl.toLowerCase();
   const requestedLower = requestedUrl.toLowerCase();
@@ -6049,6 +6048,25 @@ async function findTabByIdAcrossEndpoints(targetId, preferredPort) {
   const ports = resolveSearchPorts(await detectCdpPortsAsync(), preferredPort);
   return findTabByIdInPorts(targetId, ports);
 }
+async function findResponsivePageTabByUrl(port, url) {
+  const pages = (await listTargets(port)).filter((target) => target.type === "page");
+  const scores = pages.map((target) => scoreTabUrlMatch(target.url, url));
+  const bestScore = Math.max(0, ...scores);
+  if (bestScore === 0) return null;
+  for (const target of pages.filter((_, index) => scores[index] === bestScore)) {
+    if (!target.webSocketDebuggerUrl) continue;
+    const client = new CDPClient(target.webSocketDebuggerUrl);
+    try {
+      await client.waitReady();
+      await client.send("Page.captureScreenshot", { format: "png" }, 5e3);
+      return target;
+    } catch {
+    } finally {
+      client.close();
+    }
+  }
+  return null;
+}
 async function findTabByUrlAcrossEndpoints(url, preferredPort) {
   const ports = resolveSearchPorts(await detectCdpPortsAsync(), preferredPort);
   let best = null;
@@ -10541,7 +10559,7 @@ function validateHarAppendBatch(value, source) {
   return { entries, incompleteLifecycles };
 }
 function captureVersion() {
-  const version = "1.4.15";
+  const version = "1.4.17";
   return typeof version === "string" && version.length > 0 ? version : "development";
 }
 function token() {
@@ -12643,7 +12661,7 @@ function wallTime(value) {
   }
 }
 function captureVersion2() {
-  const version = "1.4.15";
+  const version = "1.4.17";
   return typeof version === "string" && version.length > 0 ? version : "development";
 }
 function deepFreeze(value) {
@@ -15140,6 +15158,7 @@ async function start(parsed) {
     let bridgeSocket = null;
     let bridgePid = null;
     let cdpPort = null;
+    let targetWasOpened = false;
     let selectedBrowser = null;
     let endpointSelectionReason = null;
     try {
@@ -15166,22 +15185,28 @@ async function start(parsed) {
         }
       }
       if (url) {
+        let opened = false;
         try {
           target = await startWorld.openTab(cdpPort, url);
+          opened = true;
+          targetWasOpened = true;
         } catch (error4) {
           const message = error4 instanceof Error ? error4.message : String(error4);
-          if (message.toLowerCase().includes("not supported")) {
+          if (!message.toLowerCase().includes("not supported")) throw error4;
+          target = await startWorld.findResponsivePageTabByUrl?.(cdpPort, url) ?? null;
+          if (!target) {
             throw worldFailure(
-              `Target.createTarget is unsupported on port ${cdpPort}. Use an existing tab: \`capture tab list --port ${cdpPort}\`, then \`capture session start --target <target-id> --port ${cdpPort}\`.`,
+              `Target.createTarget is unsupported on port ${cdpPort}, and no matching existing page target answered a screenshot. Run \`capture tab list --port ${cdpPort}\` to inspect its targets.`,
               error4
             );
           }
-          throw error4;
         }
-        const openedPort = cdpPort;
-        const openedTargetId = target.id;
-        acquired.push({ label: "opened target", release: () => startWorld.closeTarget(openedPort, openedTargetId) });
-        pageLoadTimedOut = await startWorld.awaitTabReady(target, url);
+        if (opened) {
+          const openedPort = cdpPort;
+          const openedTargetId = target.id;
+          acquired.push({ label: "opened target", release: () => startWorld.closeTarget(openedPort, openedTargetId) });
+          pageLoadTimedOut = await startWorld.awaitTabReady(target, url);
+        }
       }
       if (hold) {
         const bridge = await startWorld.startBridge(dir, cdpPort);
@@ -15211,7 +15236,7 @@ async function start(parsed) {
       return;
     }
     const rows = [fact`bundle dir: ${dir}`];
-    if (target) rows.push(url ? fact`tab ${target.id} opened at ${url}` : fact`tab ${target.id} adopted at ${target.url}`);
+    if (target) rows.push(targetWasOpened ? fact`tab ${target.id} opened at ${url}` : fact`tab ${target.id} adopted at ${target.url}`);
     if (cdpPort !== null) rows.push(
       parsed.portSource === "env" ? fact`CDP endpoint on port ${cdpPort} selected from ambient CDP_PORT; --port overrides endpoint selection and --target overrides tab selection.` : parsed.port !== void 0 ? fact`CDP endpoint on port ${cdpPort} selected by explicit --port; --port overrides endpoint selection and --target overrides tab selection.` : fact`${selectedBrowser ?? "CDP endpoint"} on port ${cdpPort} auto-selected because it ${endpointSelectionReason ?? "was selected by automatic endpoint detection"}; capture-launched browser recency does not affect selection. --port overrides endpoint selection and --target overrides tab selection.`
     );
@@ -16128,10 +16153,10 @@ use when collecting or reading the traffic, logs, and artifacts of scoped work a
 
 input:
   --url <url>       Absolute URL to open in a fresh tab through CDP's
-                    Target.createTarget. Some endpoints, including Electron,
-                    expose existing tabs but reject Target.createTarget; on
-                    those endpoints --url cannot be used. Conflicts with
-                    --target.
+                    Target.createTarget. If an endpoint, including Electron,
+                    rejects Target.createTarget, capture adopts the matching
+                    existing page target that answers a screenshot. Conflicts
+                    with --target.
   --target <tab-id>  Existing page tab to adopt. Resolves a full target id or
                     an unambiguous prefix of at least four characters at the
                     selected CDP endpoint; start fails if it does not resolve.
@@ -16277,6 +16302,10 @@ effects:
         const { findTabById: findTabById2 } = await Promise.resolve().then(() => (init_targets(), targets_exports));
         return findTabById2(port, targetId);
       },
+      async findResponsivePageTabByUrl(port, url) {
+        const { findResponsivePageTabByUrl: findResponsivePageTabByUrl2 } = await Promise.resolve().then(() => (init_targets(), targets_exports));
+        return findResponsivePageTabByUrl2(port, url);
+      },
       async closeTarget(port, targetId) {
         const { closeTarget: closeTarget2 } = await Promise.resolve().then(() => (init_targets(), targets_exports));
         return closeTarget2(port, targetId);
@@ -267328,7 +267357,7 @@ I/O contract: flags and positionals on input; one rendered prose block on stdout
 A CDP-enabled browser must be running; \`capture tab list\` is the probe, and \`capture tab launch\` starts one capture owns and reaps when nothing is (never hand-roll a detached browser \u2014 nothing reaps that). Capture never signals a browser it did not start, so attaching to your own with --port is unchanged. CDP_PORT / CDP_TARGET pin the browser + tab for target-selecting commands \u2014 precedence: explicit flag > active session > env. \`session start\` adopts only an explicit --target.`;
 }
 function printVersion() {
-  const declared = "1.4.15";
+  const declared = "1.4.17";
   if (declared) {
     console.log(declared);
     return;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crouton-kit/capture",
-  "version": "1.4.15",
+  "version": "1.4.17",
   "description": "Browser automation and UI validation via CDP — session-based screenshots, HAR, a11y, click/type, and JS exec",
   "bin": {
     "capture": "./bin/capture"

package/src/cdp/targets.ts

@@ -149,15 +149,17 @@ export async function findUnambiguousPageTabInPorts(
   return candidates[0] ?? null;
 }
 
-function normalizeUrlForMatch(value: string): { full: string; host: string; path: string } | null {
+function normalizeUrlForMatch(value: string): { full: string; origin: string; path: string } | null {
   try {
     const url = new URL(value);
     const path = url.pathname.replace(/\/+$/, '') || '/';
+    const hostname = url.hostname.toLowerCase();
+    // Electron may expose a localhost page when the caller uses its equivalent IPv4 loopback URL.
+    const loopback = hostname === 'localhost' || hostname === '127.0.0.1';
+    const port = url.port || (url.protocol === 'http:' ? '80' : url.protocol === 'https:' ? '443' : '');
     return {
       full: `${url.origin}${path}${url.search}${url.hash}`.toLowerCase(),
-      // `host` (not `hostname`): two local dev servers on the same loopback
-      // address but different ports must not register as a host match.
-      host: url.host.toLowerCase(),
+      origin: `${url.protocol}//${loopback ? 'loopback' : hostname}:${port}`,
       path: path.toLowerCase(),
     };
   } catch {
@@ -171,14 +173,11 @@ export function scoreTabUrlMatch(tabUrl: string, requestedUrl: string): number {
 
   if (tab && requested) {
     if (tab.full === requested.full) return 100;
-    if (tab.host === requested.host && tab.path === requested.path) return 95;
-    if (tab.host === requested.host && tab.path.startsWith(requested.path)) return 90;
-    if (tab.host === requested.host && requested.path.startsWith(tab.path)) return 85;
-    if (tab.host === requested.host) return 70;
-    if (tab.full.includes(requested.full)) return 60;
-    if (tab.full.includes(requested.host)) return 50;
-    if (requested.full.includes(tab.full)) return 40;
-    return 0;
+    if (tab.origin !== requested.origin) return 0;
+    if (tab.path === requested.path) return 95;
+    if (tab.path.startsWith(requested.path)) return 90;
+    if (requested.path.startsWith(tab.path)) return 85;
+    return 70;
   }
 
   const tabLower = tabUrl.toLowerCase();
@@ -205,6 +204,28 @@ export async function findTabByIdAcrossEndpoints(
   return findTabByIdInPorts(targetId, ports);
 }
 
+export async function findResponsivePageTabByUrl(port: number, url: string): Promise<CDPTarget | null> {
+  const pages = (await listTargets(port)).filter((target) => target.type === 'page');
+  const scores = pages.map((target) => scoreTabUrlMatch(target.url, url));
+  const bestScore = Math.max(0, ...scores);
+  if (bestScore === 0) return null;
+
+  for (const target of pages.filter((_, index) => scores[index] === bestScore)) {
+    if (!target.webSocketDebuggerUrl) continue;
+    const client = new CDPClient(target.webSocketDebuggerUrl);
+    try {
+      await client.waitReady();
+      await client.send('Page.captureScreenshot', { format: 'png' }, 5_000);
+      return target;
+    } catch {
+      // Electron can expose a page target that never answers screenshot requests.
+    } finally {
+      client.close();
+    }
+  }
+  return null;
+}
+
 export async function findTabByUrlAcrossEndpoints(
   url: string,
   preferredPort?: number,

package/src/session/commands.ts

@@ -391,10 +391,10 @@ const START_USAGE = `capture session start [--url <url> | --target <tab-id>] [--
 
 input:
   --url <url>       Absolute URL to open in a fresh tab through CDP's
-                    Target.createTarget. Some endpoints, including Electron,
-                    expose existing tabs but reject Target.createTarget; on
-                    those endpoints --url cannot be used. Conflicts with
-                    --target.
+                    Target.createTarget. If an endpoint, including Electron,
+                    rejects Target.createTarget, capture adopts the matching
+                    existing page target that answers a screenshot. Conflicts
+                    with --target.
   --target <tab-id>  Existing page tab to adopt. Resolves a full target id or
                     an unambiguous prefix of at least four characters at the
                     selected CDP endpoint; start fails if it does not resolve.
@@ -563,6 +563,7 @@ export interface SessionStartWorld {
   detectCdpPort(): Promise<number | { port: number; app: string; selectionReason: string }>;
   openTab(port: number, url: string): Promise<CDPTarget>;
   findTabById(port: number, targetId: string): Promise<CDPTarget | null>;
+  findResponsivePageTabByUrl?(port: number, url: string): Promise<CDPTarget | null>;
   closeTarget(port: number, targetId: string): Promise<void>;
   /** Attach to the freshly-opened tab and wait for load; returns page-load-timed-out. */
   awaitTabReady(target: CDPTarget, url: string): Promise<boolean>;
@@ -588,6 +589,10 @@ const productionStartWorld: SessionStartWorld = {
     const { findTabById } = await import('../cdp/targets.js');
     return findTabById(port, targetId);
   },
+  async findResponsivePageTabByUrl(port, url) {
+    const { findResponsivePageTabByUrl } = await import('../cdp/targets.js');
+    return findResponsivePageTabByUrl(port, url);
+  },
   async closeTarget(port, targetId) {
     const { closeTarget } = await import('../cdp/targets.js');
     return closeTarget(port, targetId);
@@ -692,6 +697,7 @@ async function start(parsed: ParsedArgs): Promise<void> {
     let bridgeSocket: string | null = null;
     let bridgePid: number | null = null;
     let cdpPort: number | null = null;
+    let targetWasOpened = false;
     let selectedBrowser: string | null = null;
     let endpointSelectionReason: string | null = null;
 
@@ -723,22 +729,28 @@ async function start(parsed: ParsedArgs): Promise<void> {
       }
 
       if (url) {
+        let opened = false;
         try {
           target = await startWorld.openTab(cdpPort!, url);
+          opened = true;
+          targetWasOpened = true;
         } catch (error) {
           const message = error instanceof Error ? error.message : String(error);
-          if (message.toLowerCase().includes('not supported')) {
+          if (!message.toLowerCase().includes('not supported')) throw error;
+          target = await startWorld.findResponsivePageTabByUrl?.(cdpPort!, url) ?? null;
+          if (!target) {
             throw worldFailure(
-              `Target.createTarget is unsupported on port ${cdpPort}. Use an existing tab: \`capture tab list --port ${cdpPort}\`, then \`capture session start --target <target-id> --port ${cdpPort}\`.`,
+              `Target.createTarget is unsupported on port ${cdpPort}, and no matching existing page target answered a screenshot. Run \`capture tab list --port ${cdpPort}\` to inspect its targets.`,
               error,
             );
           }
-          throw error;
         }
-        const openedPort = cdpPort!;
-        const openedTargetId = target.id;
-        acquired.push({ label: 'opened target', release: () => startWorld.closeTarget(openedPort, openedTargetId) });
-        pageLoadTimedOut = await startWorld.awaitTabReady(target, url);
+        if (opened) {
+          const openedPort = cdpPort!;
+          const openedTargetId = target.id;
+          acquired.push({ label: 'opened target', release: () => startWorld.closeTarget(openedPort, openedTargetId) });
+          pageLoadTimedOut = await startWorld.awaitTabReady(target, url);
+        }
       }
 
       // Hold a CDP browser connection open for the session's lifetime so
@@ -778,7 +790,7 @@ async function start(parsed: ParsedArgs): Promise<void> {
     }
 
     const rows: FactLine[] = [fact`bundle dir: ${dir}`];
-    if (target) rows.push(url ? fact`tab ${target.id} opened at ${url}` : fact`tab ${target.id} adopted at ${target.url}`);
+    if (target) rows.push(targetWasOpened ? fact`tab ${target.id} opened at ${url}` : fact`tab ${target.id} adopted at ${target.url}`);
     if (cdpPort !== null) rows.push(
       parsed.portSource === 'env'
         ? fact`CDP endpoint on port ${cdpPort} selected from ambient CDP_PORT; --port overrides endpoint selection and --target overrides tab selection.`