@rester159/blacktip 0.1.0

package/dist/cli.js

@@ -0,0 +1,226 @@
+#!/usr/bin/env node
+/**
+ * BlackTip CLI
+ *
+ * Server mode:     npx blacktip serve [--port 9779]
+ * Send command:    npx blacktip send "<js>" [--port 9779] [--pretty]
+ * Send from file:  npx blacktip send --file <path> [--port 9779] [--pretty]
+ * Send from stdin: echo "<js>" | npx blacktip send --stdin [--pretty]
+ * Batch commands:  npx blacktip batch <file.json> [--port 9779]
+ * Resume pause:    npx blacktip resume <pauseId> "<value>" [--port 9779]
+ * Exec (one-shot): npx blacktip exec "<js>"
+ *
+ * The server returns a JSON bundle for each command:
+ *   { ok, result?, url?, title?, screenshotPath?, screenshotB64?, durationMs, error? }
+ *
+ * --pretty formats the bundle but omits the screenshot payload so the
+ * console output is readable. The screenshot is still saved to disk.
+ */
+import { createConnection } from 'node:net';
+import { readFileSync } from 'node:fs';
+import { BlackTip } from './blacktip.js';
+const args = process.argv.slice(2);
+const command = args[0];
+const portIdx = args.indexOf('--port');
+const port = portIdx !== -1 ? parseInt(args[portIdx + 1], 10) : 9779;
+const pretty = args.includes('--pretty');
+function argValue(flag) {
+    const idx = args.indexOf(flag);
+    return idx !== -1 ? args[idx + 1] : undefined;
+}
+const DELIM = '\n__END__\n';
+/**
+ * Send a raw payload to the server and print the response(s).
+ * Returns when the connection closes or the final frame is received.
+ */
+async function sendAndPrint(payload, expectMultiple = false) {
+    return new Promise((resolve) => {
+        const client = createConnection({ port, host: '127.0.0.1' });
+        let buf = '';
+        let lastPrinted = false;
+        client.on('data', (chunk) => {
+            buf += chunk.toString();
+            while (buf.includes(DELIM)) {
+                const idx = buf.indexOf(DELIM);
+                const frame = buf.slice(0, idx);
+                buf = buf.slice(idx + DELIM.length);
+                printFrame(frame);
+                lastPrinted = true;
+                if (!expectMultiple) {
+                    client.destroy();
+                    resolve();
+                    return;
+                }
+            }
+        });
+        client.on('close', () => {
+            if (!lastPrinted && buf.length > 0)
+                printFrame(buf);
+            resolve();
+        });
+        client.on('error', () => {
+            console.error('Server not running. Start with: npx blacktip serve');
+            process.exit(1);
+        });
+        client.write(payload + DELIM);
+    });
+}
+function printFrame(frame) {
+    // Try to parse as JSON; if it parses, pretty-print (optionally
+    // stripping the huge base64 screenshot). Fall back to raw output.
+    let parsed;
+    try {
+        parsed = JSON.parse(frame);
+    }
+    catch {
+        process.stdout.write(frame + '\n');
+        return;
+    }
+    if (pretty && parsed && typeof parsed === 'object') {
+        const clone = { ...parsed };
+        if ('screenshotB64' in clone) {
+            const bytes = typeof clone.screenshotBytes === 'number' ? clone.screenshotBytes : clone.screenshotB64.length;
+            clone.screenshotB64 = `<${bytes} bytes, saved to ${clone.screenshotPath ?? 'disk'}>`;
+        }
+        process.stdout.write(JSON.stringify(clone, null, 2) + '\n');
+    }
+    else {
+        process.stdout.write(JSON.stringify(parsed) + '\n');
+    }
+}
+if (command === 'serve') {
+    const bt = new BlackTip({
+        headless: false,
+        logLevel: 'info',
+        deviceProfile: 'desktop-windows',
+        behaviorProfile: 'scraper',
+        timeout: 10000,
+        retryAttempts: 2,
+        screenResolution: { width: 1440, height: 900 },
+    });
+    bt.on('action', (e) => {
+        console.log(`[${e.action}] ${e.target} → ${e.outcome} (${e.duration}ms)`);
+    });
+    await bt.serve(port);
+    console.log(`BlackTip server ready on port ${port}`);
+    console.log(`Send commands: npx blacktip send "await bt.navigate('...')" --port ${port}`);
+}
+else if (command === 'send') {
+    // Three input sources:
+    //   1. Positional argument:   npx blacktip send "..."
+    //   2. --file <path>:          npx blacktip send --file cmd.js
+    //   3. --stdin:                echo "..." | npx blacktip send --stdin
+    let cmd;
+    const fileArg = argValue('--file');
+    const stdinFlag = args.includes('--stdin');
+    if (fileArg) {
+        cmd = readFileSync(fileArg, 'utf-8');
+    }
+    else if (stdinFlag) {
+        cmd = readFileSync(0, 'utf-8'); // read from stdin
+    }
+    else {
+        // Positional argument (everything after "send" that isn't a flag).
+        cmd = args.slice(1)
+            .filter((a, i, arr) => {
+            if (a === '--port' || a === '--file' || a === '--stdin' || a === '--pretty')
+                return false;
+            if (i > 0 && (arr[i - 1] === '--port' || arr[i - 1] === '--file'))
+                return false;
+            return true;
+        })
+            .join(' ');
+    }
+    if (!cmd || !cmd.trim()) {
+        console.error('Usage: npx blacktip send "<js>" | --file <path> | --stdin');
+        process.exit(1);
+    }
+    await sendAndPrint(cmd);
+}
+else if (command === 'batch') {
+    // Batch mode: read a JSON array of commands from a file and send them
+    // as a single BATCH request. Server runs them sequentially.
+    const filePath = args[1];
+    if (!filePath) {
+        console.error('Usage: npx blacktip batch <file.json>');
+        process.exit(1);
+    }
+    const raw = readFileSync(filePath, 'utf-8');
+    const parsed = JSON.parse(raw);
+    if (!Array.isArray(parsed)) {
+        console.error('batch file must contain a JSON array of command strings');
+        process.exit(1);
+    }
+    await sendAndPrint('BATCH\n' + JSON.stringify(parsed));
+}
+else if (command === 'resume') {
+    // Resume a paused command: npx blacktip resume <id> "<value>"
+    const id = args[1];
+    const value = args[2] ?? '';
+    if (!id) {
+        console.error('Usage: npx blacktip resume <pauseId> "<value>"');
+        process.exit(1);
+    }
+    await sendAndPrint(`RESUME ${id}\n${value}`);
+}
+else if (command === 'pending') {
+    // List currently-paused commands: npx blacktip pending
+    await sendAndPrint('LIST_PENDING');
+}
+else if (command === 'exec') {
+    // One-shot: launch browser, run command, close.
+    const cmd = args.slice(1).filter((a) => a !== '--port' && a !== String(port)).join(' ');
+    if (!cmd) {
+        console.error('Usage: npx blacktip exec "<js>"');
+        process.exit(1);
+    }
+    const bt = new BlackTip({ headless: false, timeout: 10000, retryAttempts: 2 });
+    await bt.launch();
+    try {
+        const fn = new Function('bt', `return (async () => { ${cmd} })();`);
+        const result = await fn(bt);
+        if (result !== undefined)
+            console.log(JSON.stringify(result));
+    }
+    catch (e) {
+        console.error('Error:', e instanceof Error ? e.message : e);
+    }
+    await bt.close();
+}
+else {
+    console.log(`BlackTip CLI
+
+Usage:
+  npx blacktip serve [--port 9779]
+    Start the TCP command server. Leaves a browser running.
+
+  npx blacktip send "<js>" [--port N] [--pretty]
+  npx blacktip send --file <path> [--pretty]
+  echo "<js>" | npx blacktip send --stdin [--pretty]
+    Send a single JS command to the running server. Returns a bundle:
+    { ok, result, url, title, screenshotPath, durationMs, ... }
+    Use --pretty for human-readable output with screenshot payload
+    replaced by a placeholder.
+
+  npx blacktip batch <file.json>
+    Run an array of commands sequentially. Server returns all bundles
+    in one response, stopping on first failure.
+
+  npx blacktip resume <pauseId> "<value>"
+    Resume a command that called bt.pauseForInput().
+
+  npx blacktip pending
+    List currently-paused commands with their prompts.
+
+  npx blacktip exec "<js>"
+    One-shot: launch a fresh browser, run the command, close.
+
+Examples:
+  npx blacktip serve
+  npx blacktip send "await bt.navigate('https://example.com')" --pretty
+  npx blacktip send --file login-flow.js --pretty
+  npx blacktip batch anthem-claim.json
+  npx blacktip resume pause-123456-78901 "116170"
+`);
+}
+//# sourceMappingURL=cli.js.map

package/dist/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AAEA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EAAE,gBAAgB,EAAE,MAAM,UAAU,CAAC;AAC5C,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACvC,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAEzC,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;AACnC,MAAM,OAAO,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC;AAExB,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;AACvC,MAAM,IAAI,GAAG,OAAO,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,IAAI,CAAC,OAAO,GAAG,CAAC,CAAE,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;AACtE,MAAM,MAAM,GAAG,IAAI,CAAC,QAAQ,CAAC,UAAU,CAAC,CAAC;AAEzC,SAAS,QAAQ,CAAC,IAAY;IAC5B,MAAM,GAAG,GAAG,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;IAC/B,OAAO,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;AAChD,CAAC;AAED,MAAM,KAAK,GAAG,aAAa,CAAC;AAE5B;;;GAGG;AACH,KAAK,UAAU,YAAY,CAAC,OAAe,EAAE,cAAc,GAAG,KAAK;IACjE,OAAO,IAAI,OAAO,CAAO,CAAC,OAAO,EAAE,EAAE;QACnC,MAAM,MAAM,GAAG,gBAAgB,CAAC,EAAE,IAAI,EAAE,IAAI,EAAE,WAAW,EAAE,CAAC,CAAC;QAC7D,IAAI,GAAG,GAAG,EAAE,CAAC;QACb,IAAI,WAAW,GAAG,KAAK,CAAC;QAExB,MAAM,CAAC,EAAE,CAAC,MAAM,EAAE,CAAC,KAAK,EAAE,EAAE;YAC1B,GAAG,IAAI,KAAK,CAAC,QAAQ,EAAE,CAAC;YACxB,OAAO,GAAG,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC;gBAC3B,MAAM,GAAG,GAAG,GAAG,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;gBAC/B,MAAM,KAAK,GAAG,GAAG,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;gBAChC,GAAG,GAAG,GAAG,CAAC,KAAK,CAAC,GAAG,GAAG,KAAK,CAAC,MAAM,CAAC,CAAC;gBACpC,UAAU,CAAC,KAAK,CAAC,CAAC;gBAClB,WAAW,GAAG,IAAI,CAAC;gBACnB,IAAI,CAAC,cAAc,EAAE,CAAC;oBACpB,MAAM,CAAC,OAAO,EAAE,CAAC;oBACjB,OAAO,EAAE,CAAC;oBACV,OAAO;gBACT,CAAC;YACH,CAAC;QACH,CAAC,CAAC,CAAC;QAEH,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE,GAAG,EAAE;YACtB,IAAI,CAAC,WAAW,IAAI,GAAG,CAAC,MAAM,GAAG,CAAC;gBAAE,UAAU,CAAC,GAAG,CAAC,CAAC;YACpD,OAAO,EAAE,CAAC;QACZ,CAAC,CAAC,CAAC;QAEH,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE,GAAG,EAAE;YACtB,OAAO,CAAC,KAAK,CAAC,oDAAoD,CAAC,CAAC;YACpE,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QAClB,CAAC,CAAC,CAAC;QAEH,MAAM,CAAC,KAAK,CAAC,OAAO,GAAG,KAAK,CAAC,CAAC;IAChC,CAAC,CAAC,CAAC;AACL,CAAC;AAED,SAAS,UAAU,CAAC,KAAa;IAC/B,+DAA+D;IAC/D,kEAAkE;IAClE,IAAI,MAAe,CAAC;IACpB,IAAI,CAAC;QACH,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;IAC7B,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,KAAK,GAAG,IAAI,CAAC,CAAC;QACnC,OAAO;IACT,CAAC;IAED,IAAI,MAAM,IAAI,MAAM,IAAI,OAAO,MAAM,KAAK,QAAQ,EAAE,CAAC;QACnD,MAAM,KAAK,GAAG,EAAE,GAAI,MAAkC,EAAE,CAAC;QACzD,IAAI,eAAe,IAAI,KAAK,EAAE,CAAC;YAC7B,MAAM,KAAK,GAAG,OAAO,KAAK,CAAC,eAAe,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,eAAe,CAAC,CAAC,CAAE,KAAK,CAAC,aAAwB,CAAC,MAAM,CAAC;YACzH,KAAK,CAAC,aAAa,GAAG,IAAI,KAAK,oBAAoB,KAAK,CAAC,cAAc,IAAI,MAAM,GAAG,CAAC;QACvF,CAAC;QACD,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC;IAC9D,CAAC;SAAM,CAAC;QACN,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,GAAG,IAAI,CAAC,CAAC;IACtD,CAAC;AACH,CAAC;AAED,IAAI,OAAO,KAAK,OAAO,EAAE,CAAC;IACxB,MAAM,EAAE,GAAG,IAAI,QAAQ,CAAC;QACtB,QAAQ,EAAE,KAAK;QACf,QAAQ,EAAE,MAAM;QAChB,aAAa,EAAE,iBAAiB;QAChC,eAAe,EAAE,SAAS;QAC1B,OAAO,EAAE,KAAK;QACd,aAAa,EAAE,CAAC;QAChB,gBAAgB,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE;KAC/C,CAAC,CAAC;IAEH,EAAE,CAAC,EAAE,CAAC,QAAQ,EAAE,CAAC,CAAC,EAAE,EAAE;QACpB,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,MAAM,KAAK,CAAC,CAAC,MAAM,MAAM,CAAC,CAAC,OAAO,KAAK,CAAC,CAAC,QAAQ,KAAK,CAAC,CAAC;IAC5E,CAAC,CAAC,CAAC;IAEH,MAAM,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IACrB,OAAO,CAAC,GAAG,CAAC,iCAAiC,IAAI,EAAE,CAAC,CAAC;IACrD,OAAO,CAAC,GAAG,CAAC,sEAAsE,IAAI,EAAE,CAAC,CAAC;AAE5F,CAAC;KAAM,IAAI,OAAO,KAAK,MAAM,EAAE,CAAC;IAC9B,uBAAuB;IACvB,sDAAsD;IACtD,+DAA+D;IAC/D,sEAAsE;IACtE,IAAI,GAAuB,CAAC;IAE5B,MAAM,OAAO,GAAG,QAAQ,CAAC,QAAQ,CAAC,CAAC;IACnC,MAAM,SAAS,GAAG,IAAI,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAC;IAE3C,IAAI,OAAO,EAAE,CAAC;QACZ,GAAG,GAAG,YAAY,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;IACvC,CAAC;SAAM,IAAI,SAAS,EAAE,CAAC;QACrB,GAAG,GAAG,YAAY,CAAC,CAAC,EAAE,OAAO,CAAC,CAAC,CAAC,kBAAkB;IACpD,CAAC;SAAM,CAAC;QACN,mEAAmE;QACnE,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC;aAChB,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,GAAG,EAAE,EAAE;YACpB,IAAI,CAAC,KAAK,QAAQ,IAAI,CAAC,KAAK,QAAQ,IAAI,CAAC,KAAK,SAAS,IAAI,CAAC,KAAK,UAAU;gBAAE,OAAO,KAAK,CAAC;YAC1F,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,KAAK,QAAQ,IAAI,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,KAAK,QAAQ,CAAC;gBAAE,OAAO,KAAK,CAAC;YAChF,OAAO,IAAI,CAAC;QACd,CAAC,CAAC;aACD,IAAI,CAAC,GAAG,CAAC,CAAC;IACf,CAAC;IAED,IAAI,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,EAAE,EAAE,CAAC;QACxB,OAAO,CAAC,KAAK,CAAC,2DAA2D,CAAC,CAAC;QAC3E,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC;IAED,MAAM,YAAY,CAAC,GAAG,CAAC,CAAC;AAE1B,CAAC;KAAM,IAAI,OAAO,KAAK,OAAO,EAAE,CAAC;IAC/B,sEAAsE;IACtE,4DAA4D;IAC5D,MAAM,QAAQ,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC;IACzB,IAAI,CAAC,QAAQ,EAAE,CAAC;QACd,OAAO,CAAC,KAAK,CAAC,uCAAuC,CAAC,CAAC;QACvD,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC;IACD,MAAM,GAAG,GAAG,YAAY,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;IAC5C,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAa,CAAC;IAC3C,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;QAC3B,OAAO,CAAC,KAAK,CAAC,yDAAyD,CAAC,CAAC;QACzE,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC;IACD,MAAM,YAAY,CAAC,SAAS,GAAG,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC,CAAC;AAEzD,CAAC;KAAM,IAAI,OAAO,KAAK,QAAQ,EAAE,CAAC;IAChC,8DAA8D;IAC9D,MAAM,EAAE,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC;IACnB,MAAM,KAAK,GAAG,IAAI,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;IAC5B,IAAI,CAAC,EAAE,EAAE,CAAC;QACR,OAAO,CAAC,KAAK,CAAC,gDAAgD,CAAC,CAAC;QAChE,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC;IACD,MAAM,YAAY,CAAC,UAAU,EAAE,KAAK,KAAK,EAAE,CAAC,CAAC;AAE/C,CAAC;KAAM,IAAI,OAAO,KAAK,SAAS,EAAE,CAAC;IACjC,uDAAuD;IACvD,MAAM,YAAY,CAAC,cAAc,CAAC,CAAC;AAErC,CAAC;KAAM,IAAI,OAAO,KAAK,MAAM,EAAE,CAAC;IAC9B,gDAAgD;IAChD,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,KAAK,QAAQ,IAAI,CAAC,KAAK,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IACxF,IAAI,CAAC,GAAG,EAAE,CAAC;QACT,OAAO,CAAC,KAAK,CAAC,iCAAiC,CAAC,CAAC;QACjD,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC;IACD,MAAM,EAAE,GAAG,IAAI,QAAQ,CAAC,EAAE,QAAQ,EAAE,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,aAAa,EAAE,CAAC,EAAE,CAAC,CAAC;IAC/E,MAAM,EAAE,CAAC,MAAM,EAAE,CAAC;IAClB,IAAI,CAAC;QACH,MAAM,EAAE,GAAG,IAAI,QAAQ,CAAC,IAAI,EAAE,yBAAyB,GAAG,QAAQ,CAAC,CAAC;QACpE,MAAM,MAAM,GAAG,MAAM,EAAE,CAAC,EAAE,CAAC,CAAC;QAC5B,IAAI,MAAM,KAAK,SAAS;YAAE,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC,CAAC;IAChE,CAAC;IAAC,OAAO,CAAC,EAAE,CAAC;QACX,OAAO,CAAC,KAAK,CAAC,QAAQ,EAAE,CAAC,YAAY,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IAC9D,CAAC;IACD,MAAM,EAAE,CAAC,KAAK,EAAE,CAAC;AAEnB,CAAC;KAAM,CAAC;IACN,OAAO,CAAC,GAAG,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAiCb,CAAC,CAAC;AACH,CAAC"}

package/dist/element-finder.d.ts

@@ -0,0 +1,42 @@
+import type { Page, Frame, ElementHandle as PlaywrightElement } from 'patchright';
+import type { Logger } from './logging.js';
+import type { BoundingBox } from './types.js';
+export declare class ElementFinder {
+    private logger;
+    constructor(logger: Logger);
+    find(pageOrFrame: Page | Frame, selector: string, options?: {
+        timeout?: number;
+        visible?: boolean;
+    }): Promise<PlaywrightElement>;
+    findInFrames(page: Page, selector: string, options?: {
+        timeout?: number;
+        visible?: boolean;
+    }): Promise<{
+        element: PlaywrightElement;
+        frame: Page | Frame;
+    }>;
+    private looksLikeSelector;
+    private looksLikeXPath;
+    getBoundingBox(element: PlaywrightElement): Promise<BoundingBox | null>;
+    /**
+     * Find an element inside any open shadow root reachable from the document.
+     *
+     * Recursively walks the DOM and each encountered `shadowRoot`, testing
+     * CSS selector matches at every level. Modern component libraries
+     * (Lit, Stencil, Material Web Components, Ionic) wrap everything in
+     * shadow DOM, and Playwright's default CSS engine sometimes misses
+     * deeply-nested selectors. This walker is explicit and predictable.
+     *
+     * LIMITATION: closed shadow roots are opaque to JavaScript by design.
+     * Elements inside `attachShadow({mode: 'closed'})` are not reachable
+     * by any JS-only method; reaching them requires CDP `DOM.describeNode`
+     * with `pierce: true`, which is outside this method's scope. Open
+     * shadow roots (the overwhelming majority in practice) are fully
+     * supported.
+     */
+    findInShadowDom(pageOrFrame: Page | Frame, cssSelector: string, options?: {
+        timeout?: number;
+    }): Promise<PlaywrightElement>;
+    private notFound;
+}
+//# sourceMappingURL=element-finder.d.ts.map

package/dist/element-finder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"element-finder.d.ts","sourceRoot":"","sources":["../src/element-finder.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,KAAK,EAAE,aAAa,IAAI,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAClF,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AAC3C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AA8B9C,qBAAa,aAAa;IACZ,OAAO,CAAC,MAAM;gBAAN,MAAM,EAAE,MAAM;IAE5B,IAAI,CACR,WAAW,EAAE,IAAI,GAAG,KAAK,EACzB,QAAQ,EAAE,MAAM,EAChB,OAAO,CAAC,EAAE;QAAE,OAAO,CAAC,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,OAAO,CAAA;KAAE,GAChD,OAAO,CAAC,iBAAiB,CAAC;IA2GvB,YAAY,CAChB,IAAI,EAAE,IAAI,EACV,QAAQ,EAAE,MAAM,EAChB,OAAO,CAAC,EAAE;QAAE,OAAO,CAAC,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,OAAO,CAAA;KAAE,GAChD,OAAO,CAAC;QAAE,OAAO,EAAE,iBAAiB,CAAC;QAAC,KAAK,EAAE,IAAI,GAAG,KAAK,CAAA;KAAE,CAAC;IAyB/D,OAAO,CAAC,iBAAiB;IAQzB,OAAO,CAAC,cAAc;IAKhB,cAAc,CAAC,OAAO,EAAE,iBAAiB,GAAG,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC;IAM7E;;;;;;;;;;;;;;;OAeG;IACG,eAAe,CACnB,WAAW,EAAE,IAAI,GAAG,KAAK,EACzB,WAAW,EAAE,MAAM,EACnB,OAAO,CAAC,EAAE;QAAE,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,GAC7B,OAAO,CAAC,iBAAiB,CAAC;IA0C7B,OAAO,CAAC,QAAQ;CAGjB"}

package/dist/element-finder.js

@@ -0,0 +1,240 @@
+const CSS_TAG_NAMES = new Set([
+    // Structural
+    'div', 'span', 'section', 'article', 'aside', 'nav', 'header', 'footer',
+    'main', 'body', 'html', 'details', 'summary', 'dialog',
+    // Text
+    'p', 'h1', 'h2', 'h3', 'h4', 'h5', 'h6', 'blockquote', 'pre', 'code',
+    'em', 'strong', 'small', 'mark', 'time',
+    // Lists & tables
+    'ul', 'ol', 'li', 'dl', 'dt', 'dd',
+    'table', 'thead', 'tbody', 'tfoot', 'tr', 'td', 'th', 'caption', 'colgroup', 'col',
+    // Forms
+    'form', 'input', 'textarea', 'select', 'option', 'optgroup', 'button', 'label',
+    'fieldset', 'legend', 'datalist', 'output', 'meter', 'progress',
+    // Media & embeds
+    'img', 'picture', 'video', 'audio', 'canvas', 'svg', 'iframe', 'embed',
+    'object', 'source', 'track', 'map', 'area',
+    // Interactive
+    'a',
+]);
+const CSS_INDICATOR_CHARS = ['.', '#', '[', '>', ':', '+', '~', '=', '*'];
+/**
+ * Per-strategy timeout — short so we fail fast and try the next strategy.
+ * The overall timeout is the caller's budget; individual strategies get a slice.
+ */
+const STRATEGY_TIMEOUT_MS = 3000;
+export class ElementFinder {
+    logger;
+    constructor(logger) {
+        this.logger = logger;
+    }
+    async find(pageOrFrame, selector, options) {
+        const overallTimeout = options?.timeout ?? 15_000;
+        const visible = options?.visible ?? false;
+        const state = visible ? 'visible' : 'attached';
+        const triedStrategies = [];
+        const deadline = Date.now() + overallTimeout;
+        // Helper: time remaining, capped to per-strategy max
+        const strategyTimeout = () => Math.min(STRATEGY_TIMEOUT_MS, Math.max(500, deadline - Date.now()));
+        // 1. CSS selector — if input looks like one
+        if (this.looksLikeSelector(selector)) {
+            try {
+                const el = await pageOrFrame.waitForSelector(selector, { timeout: strategyTimeout(), state });
+                if (el) {
+                    this.logger.info('Element found via CSS selector', { selector });
+                    return el;
+                }
+            }
+            catch {
+                triedStrategies.push('CSS');
+                this.logger.debug('CSS strategy failed', { selector });
+            }
+            if (Date.now() >= deadline)
+                throw this.notFound(selector, triedStrategies);
+        }
+        // 2. XPath
+        if (this.looksLikeXPath(selector)) {
+            try {
+                const el = await pageOrFrame.waitForSelector(`xpath=${selector}`, { timeout: strategyTimeout(), state });
+                if (el) {
+                    this.logger.info('Element found via XPath', { selector });
+                    return el;
+                }
+            }
+            catch {
+                triedStrategies.push('XPath');
+                this.logger.debug('XPath strategy failed', { selector });
+            }
+            if (Date.now() >= deadline)
+                throw this.notFound(selector, triedStrategies);
+        }
+        // 3. Label association — runs BEFORE text match so that searching by
+        //    a label's visible text returns the associated input, not the label
+        //    element itself. Uses Playwright's getByLabel which handles for=,
+        //    nested inputs, and aria-labelledby uniformly.
+        try {
+            const locator = pageOrFrame.getByLabel(selector, { exact: true }).first();
+            await locator.waitFor({ state, timeout: strategyTimeout() });
+            const handle = await locator.elementHandle();
+            if (handle) {
+                this.logger.info('Element found via label association', { selector });
+                return handle;
+            }
+        }
+        catch {
+            triedStrategies.push('label');
+        }
+        if (Date.now() >= deadline)
+            throw this.notFound(selector, triedStrategies);
+        // 4. Exact text match
+        try {
+            const el = await pageOrFrame.waitForSelector(`text="${selector}"`, { timeout: strategyTimeout(), state });
+            if (el) {
+                this.logger.info('Element found via exact text', { selector });
+                return el;
+            }
+        }
+        catch {
+            triedStrategies.push('exact text');
+        }
+        if (Date.now() >= deadline)
+            throw this.notFound(selector, triedStrategies);
+        // 5. Case-insensitive text match
+        try {
+            const el = await pageOrFrame.waitForSelector(`text=${selector}`, { timeout: strategyTimeout(), state });
+            if (el) {
+                this.logger.info('Element found via text (case-insensitive)', { selector });
+                return el;
+            }
+        }
+        catch {
+            triedStrategies.push('text (case-insensitive)');
+        }
+        if (Date.now() >= deadline)
+            throw this.notFound(selector, triedStrategies);
+        // 6. ARIA label
+        try {
+            const el = await pageOrFrame.waitForSelector(`[aria-label="${selector}"]`, { timeout: strategyTimeout(), state });
+            if (el) {
+                this.logger.info('Element found via ARIA label', { selector });
+                return el;
+            }
+        }
+        catch {
+            triedStrategies.push('ARIA label');
+        }
+        if (Date.now() >= deadline)
+            throw this.notFound(selector, triedStrategies);
+        // 7. ARIA role (button)
+        try {
+            const el = await pageOrFrame.waitForSelector(`role=button[name="${selector}"]`, { timeout: strategyTimeout(), state });
+            if (el) {
+                this.logger.info('Element found via ARIA role', { selector });
+                return el;
+            }
+        }
+        catch {
+            triedStrategies.push('ARIA role');
+        }
+        throw this.notFound(selector, triedStrategies);
+    }
+    async findInFrames(page, selector, options) {
+        try {
+            const element = await this.find(page, selector, options);
+            return { element, frame: page };
+        }
+        catch {
+            this.logger.debug('Not found on main page, searching iframes...', { selector });
+        }
+        const frames = page.frames();
+        for (const frame of frames) {
+            if (frame === page.mainFrame())
+                continue;
+            try {
+                const element = await this.find(frame, selector, { ...options, timeout: 3000 });
+                this.logger.info('Element found in iframe', { selector, frameUrl: frame.url() });
+                return { element, frame };
+            }
+            catch {
+                // continue to next iframe
+            }
+        }
+        throw new Error(`Element not found in any frame: "${selector}". Searched main page and ${frames.length - 1} iframe(s).`);
+    }
+    looksLikeSelector(input) {
+        const trimmed = input.trim();
+        if (!trimmed)
+            return false;
+        if (CSS_INDICATOR_CHARS.some((ch) => trimmed.includes(ch)))
+            return true;
+        const firstWord = trimmed.split(/[\s.[#:>+~]/, 1)[0].toLowerCase();
+        return CSS_TAG_NAMES.has(firstWord);
+    }
+    looksLikeXPath(input) {
+        const trimmed = input.trim();
+        return trimmed.startsWith('/') || trimmed.startsWith('//');
+    }
+    async getBoundingBox(element) {
+        await element.scrollIntoViewIfNeeded().catch(() => { });
+        const box = await element.boundingBox();
+        return box ? { x: box.x, y: box.y, width: box.width, height: box.height } : null;
+    }
+    /**
+     * Find an element inside any open shadow root reachable from the document.
+     *
+     * Recursively walks the DOM and each encountered `shadowRoot`, testing
+     * CSS selector matches at every level. Modern component libraries
+     * (Lit, Stencil, Material Web Components, Ionic) wrap everything in
+     * shadow DOM, and Playwright's default CSS engine sometimes misses
+     * deeply-nested selectors. This walker is explicit and predictable.
+     *
+     * LIMITATION: closed shadow roots are opaque to JavaScript by design.
+     * Elements inside `attachShadow({mode: 'closed'})` are not reachable
+     * by any JS-only method; reaching them requires CDP `DOM.describeNode`
+     * with `pierce: true`, which is outside this method's scope. Open
+     * shadow roots (the overwhelming majority in practice) are fully
+     * supported.
+     */
+    async findInShadowDom(pageOrFrame, cssSelector, options) {
+        const timeout = options?.timeout ?? 5000;
+        const deadline = Date.now() + timeout;
+        // Poll until the element appears or the deadline passes. The walker
+        // runs in browser context via evaluateHandle; we pass the function
+        // body as a string so TypeScript doesn't typecheck it against Node
+        // globals (the DOM lib isn't in tsconfig).
+        const walkerScript = `((selector) => {
+      function walk(root) {
+        if (!root) return null;
+        if (root.matches && root.matches(selector)) return root;
+        if (typeof root.querySelector === 'function') {
+          const direct = root.querySelector(selector);
+          if (direct) return direct;
+        }
+        const all = typeof root.querySelectorAll === 'function' ? root.querySelectorAll('*') : [];
+        for (const el of all) {
+          if (el.shadowRoot) {
+            const found = walk(el.shadowRoot);
+            if (found) return found;
+          }
+        }
+        return null;
+      }
+      return walk(document);
+    })(${JSON.stringify(cssSelector)})`;
+        while (Date.now() < deadline) {
+            const handle = await pageOrFrame.evaluateHandle(walkerScript);
+            const element = handle.asElement();
+            if (element) {
+                this.logger.info('Element found via shadow DOM walker', { cssSelector });
+                return element;
+            }
+            await handle.dispose();
+            await new Promise((resolve) => setTimeout(resolve, 80));
+        }
+        throw new Error(`Element not found in shadow DOM: "${cssSelector}"`);
+    }
+    notFound(selector, tried) {
+        return new Error(`Element not found: "${selector}". Tried: ${tried.join(', ')}`);
+    }
+}
+//# sourceMappingURL=element-finder.js.map

package/dist/element-finder.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"element-finder.js","sourceRoot":"","sources":["../src/element-finder.ts"],"names":[],"mappings":"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"}

package/dist/evasion.d.ts

@@ -0,0 +1,39 @@
+import type { DeviceProfile } from './types';
+/**
+ * Generate all evasion scripts for a given device profile.
+ * Each script is a self-contained IIFE ready to be injected via
+ * `Page.addScriptToEvaluateOnNewDocument()`.
+ */
+/**
+ * Evasion script generator. With BlackTip v2 running on real Chrome
+ * (`channel: 'chrome'`) + patchright's CDP-level stealth patches, most of
+ * the original JS-shim evasion is unnecessary and some of it was actively
+ * creating signals (see L012 in planning/lessons.md for the chrome.runtime
+ * and launch-flag story).
+ *
+ * What we keep:
+ *   - canvasNoise: privacy/anti-tracking, adds plausible noise to canvas
+ *     rendering so we don't get a stable device-wide fingerprint.
+ *   - audioContextOverride: same story for audio fingerprint.
+ *
+ * What we removed (and why):
+ *   - chromeRuntime: real Chrome doesn't expose `chrome.runtime` on regular
+ *     pages — only on extension-accessible contexts. Our shim was adding
+ *     it everywhere, which CreepJS catches as `hasBadChromeRuntime: true`.
+ *     Let patchright + real Chrome handle `window.chrome` naturally.
+ *   - navigatorOverrides: real Chrome's navigator is already correct when
+ *     we use `channel: 'chrome'`. Overriding with profile values creates
+ *     mismatches (e.g., profile says hardwareConcurrency=8 but the actual
+ *     CPU has 16, and other APIs like Performance.now timing can reveal
+ *     the truth).
+ *   - pluginsAndMimeTypes: real Chrome populates navigator.plugins with
+ *     the real PDF viewer plugin. Our shim was adding fake plugins that
+ *     didn't match.
+ *   - permissionsOverride: real Chrome already returns 'prompt' for
+ *     notifications on most states. Shim only needed on headless Chromium.
+ *   - webglOverride: real Chrome reports the real GPU through ANGLE. Our
+ *     shim was replacing AMD Radeon with a profile string, making the
+ *     fingerprint inconsistent with the real DirectX pipeline signals.
+ */
+export declare function generateEvasionScripts(profile: DeviceProfile): string[];
+//# sourceMappingURL=evasion.d.ts.map

package/dist/evasion.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"evasion.d.ts","sourceRoot":"","sources":["../src/evasion.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAmd7C;;;;GAIG;AACH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,aAAa,GAAG,MAAM,EAAE,CAKvE"}