@rester159/blacktip 0.1.0 → 0.4.0

package/dist/behavioral/parsers.js

@@ -0,0 +1,223 @@
+/**
+ * Dataset parsers for behavioral calibration.
+ *
+ * The calibration scaffold (`./calibration.ts`) defines normalized
+ * `MouseMovement` and `TypingSession` shapes plus distribution fitters.
+ * What was missing through v0.2.0 was the bridge from real public datasets
+ * into those shapes — without parsers, the scaffold required every user
+ * to write their own ETL, which kept "Tier 2 behavioral calibration" on
+ * the deferred list.
+ *
+ * This module ships parsers for the two datasets we point users at
+ * most often:
+ *
+ *   1. **CMU Keystroke Dynamics** (Killourhy & Maxion, 2009).
+ *      Free for research. CSV format with columns `subject`, `sessionIndex`,
+ *      `rep`, then for the fixed phrase `.tie5Roanl` a tuple of
+ *      `H.<key>` (hold), `DD.<k1>.<k2>` (down-down latency), and
+ *      `UD.<k1>.<k2>` (up-down = flight time). 51 subjects × 8 sessions
+ *      × 50 repetitions = 20,400 phrases.
+ *
+ *   2. **Balabit Mouse Dynamics Challenge** (Antal & Egyed-Zsigmond, 2014).
+ *      Free for research. Per-session CSV with columns
+ *      `record_timestamp`, `client_timestamp`, `button`, `state`, `x`, `y`.
+ *      Each row is a single mouse event; consecutive `Mouse` rows
+ *      followed by a `Pressed` row form one movement.
+ *
+ * Plus a generic JSON loader for users with their own telemetry exported
+ * in the `MouseMovement` / `TypingSession` shapes directly.
+ *
+ * The parsers do NOT download the datasets — both have ToS that say "do
+ * not redistribute". Users acquire the data themselves and feed the file
+ * contents in as a string. We just turn raw text into normalized samples.
+ */
+// ── CMU Keystroke Dynamics ──
+/** The fixed phrase typed by every CMU subject. Used to map column index → key. */
+export const CMU_PHRASE = '.tie5Roanl';
+/**
+ * Parse the CMU Keystroke Dynamics CSV (DSL-StrongPasswordData.csv).
+ *
+ * Each row is one repetition of the phrase `.tie5Roanl` plus Return,
+ * yielding 11 keys, 11 hold-times, 10 down-down and 10 up-down latencies.
+ * We normalize each row into one `TypingSession` of 11 keystrokes.
+ *
+ * The CSV looks like:
+ *   subject,sessionIndex,rep,H.period,DD.period.t,UD.period.t,H.t,DD.t.i,UD.t.i,H.i,...
+ *   s002,1,1,0.1491,0.3979,0.2488,0.1069,0.1674,0.0605,...
+ *
+ * All time values are in **seconds** in the source file; we convert to
+ * milliseconds.
+ *
+ * Returns one `TypingSession` per CSV row. Pass these straight into
+ * `fitTypingDynamics()`.
+ */
+export function parseCmuKeystrokeCsv(csvText) {
+    const lines = csvText.trim().split(/\r?\n/);
+    if (lines.length < 2)
+        return [];
+    const header = lines[0].split(',').map((h) => h.trim());
+    // Build column index maps for the H.<key> (hold) and UD.<k1>.<k2> (flight) columns.
+    // We use UD (up-down) as flight time: time from previous key release to next key down.
+    const holdIdx = new Map(); // keyIndex → column
+    const flightIdx = new Map(); // keyIndex (1..n-1) → column
+    // The phrase keys, in order. The CMU dataset includes Return at the
+    // end, so the full key sequence is `.tie5Roanl` plus Enter (column
+    // labeled `Return` in the source).
+    const keys = [...CMU_PHRASE.split(''), 'Return'];
+    for (let i = 0; i < keys.length; i++) {
+        const key = cmuKeyLabel(keys[i]);
+        const colName = `H.${key}`;
+        const idx = header.indexOf(colName);
+        if (idx >= 0)
+            holdIdx.set(i, idx);
+    }
+    for (let i = 1; i < keys.length; i++) {
+        const prev = cmuKeyLabel(keys[i - 1]);
+        const cur = cmuKeyLabel(keys[i]);
+        const colName = `UD.${prev}.${cur}`;
+        const idx = header.indexOf(colName);
+        if (idx >= 0)
+            flightIdx.set(i, idx);
+    }
+    const sessions = [];
+    for (let rowIdx = 1; rowIdx < lines.length; rowIdx++) {
+        const cells = lines[rowIdx].split(',');
+        if (cells.length < 4)
+            continue;
+        const keystrokes = [];
+        for (let i = 0; i < keys.length; i++) {
+            const holdCol = holdIdx.get(i);
+            const flightCol = flightIdx.get(i);
+            const holdSec = holdCol != null ? parseFloat(cells[holdCol] ?? '') : NaN;
+            const flightSec = i === 0 ? 0 : flightCol != null ? parseFloat(cells[flightCol] ?? '') : NaN;
+            if (!Number.isFinite(holdSec))
+                continue;
+            keystrokes.push({
+                key: keys[i],
+                flightTimeMs: Number.isFinite(flightSec) ? Math.max(0, flightSec * 1000) : 0,
+                holdTimeMs: Math.max(0, holdSec * 1000),
+            });
+        }
+        if (keystrokes.length > 0) {
+            sessions.push({ keystrokes, phrase: CMU_PHRASE });
+        }
+    }
+    return sessions;
+}
+/**
+ * CMU's CSV uses specific labels for non-letter keys:
+ *   - `.` → `period`
+ *   - `5` → `five` (the dataset spells digits out)
+ *   - `R` (capital, requires Shift) → `Shift.r`
+ *   - Return → `Return`
+ *   - lowercase letters are bare
+ */
+function cmuKeyLabel(ch) {
+    if (ch === '.')
+        return 'period';
+    if (ch === '5')
+        return 'five';
+    if (ch === 'Return')
+        return 'Return';
+    if (ch === 'R')
+        return 'Shift.r';
+    return ch;
+}
+// ── Balabit Mouse Dynamics ──
+/**
+ * Parse a single Balabit Mouse Dynamics session CSV.
+ *
+ * Each row is one mouse event:
+ *   record_timestamp,client_timestamp,button,state,x,y
+ *   1424866316.93,0.000,NoButton,Move,1192,529
+ *   1424866316.99,0.064,NoButton,Move,1183,532
+ *   ...
+ *   1424866317.84,0.911,Left,Pressed,820,440
+ *
+ * We segment into movements: each contiguous run of `Move`/`Drag` rows
+ * followed by a `Pressed` row becomes one `MouseMovement`. The press row
+ * is the click target. Movements that don't end in a press are also
+ * recorded but with `endedWithClick: false` — these are navigation moves.
+ *
+ * Time is normalized to milliseconds since the first sample of the
+ * movement.
+ */
+export function parseBalabitMouseCsv(csvText) {
+    const lines = csvText.trim().split(/\r?\n/);
+    if (lines.length < 2)
+        return [];
+    // Header detection — Balabit ships either with or without a header row.
+    let startIdx = 0;
+    if (/[A-Za-z]/.test(lines[0].split(',')[0] ?? ''))
+        startIdx = 1;
+    const movements = [];
+    let current = [];
+    let currentStart = null;
+    const flush = (endedWithClick) => {
+        if (current.length >= 2) {
+            movements.push({ samples: current, endedWithClick });
+        }
+        current = [];
+        currentStart = null;
+    };
+    for (let i = startIdx; i < lines.length; i++) {
+        const cells = lines[i].split(',');
+        if (cells.length < 6)
+            continue;
+        const clientTs = parseFloat(cells[1] ?? '');
+        const state = (cells[3] ?? '').trim();
+        const x = parseFloat(cells[4] ?? '');
+        const y = parseFloat(cells[5] ?? '');
+        if (!Number.isFinite(clientTs) || !Number.isFinite(x) || !Number.isFinite(y))
+            continue;
+        const tMs = clientTs * 1000;
+        if (currentStart == null)
+            currentStart = tMs;
+        if (state === 'Move' || state === 'Drag') {
+            current.push({ timestampMs: tMs - currentStart, x, y });
+        }
+        else if (state === 'Pressed') {
+            // Treat the press location as the target.
+            current.push({
+                timestampMs: tMs - currentStart,
+                x,
+                y,
+                targetX: x,
+                targetY: y,
+                // Balabit doesn't ship target widths — leave undefined so the
+                // Fitts' Law fitter skips these and falls back to canonical values.
+            });
+            flush(true);
+        }
+        else if (state === 'Released') {
+            // End-of-click; ignore.
+        }
+        else {
+            // Scroll, etc. — terminate any in-flight movement.
+            flush(false);
+        }
+    }
+    // Flush trailing movement if any
+    flush(false);
+    return movements;
+}
+// ── Generic JSON loader ──
+/**
+ * Generic loader for users who already export their telemetry in the
+ * normalized shapes. Accepts JSON of the form:
+ *
+ *   { "movements": MouseMovement[], "sessions": TypingSession[] }
+ *
+ * Either field may be absent. Returns the parsed object with empty
+ * defaults filled in. This is the "bring your own data" path — most
+ * production users will write a tiny exporter on their own telemetry
+ * pipeline that emits this shape, then feed it through `fitFromSamples()`.
+ */
+export function parseGenericTelemetryJson(jsonText) {
+    const parsed = JSON.parse(jsonText);
+    return {
+        movements: Array.isArray(parsed.movements) ? parsed.movements : [],
+        sessions: Array.isArray(parsed.sessions) ? parsed.sessions : [],
+    };
+}
+//# sourceMappingURL=parsers.js.map

package/dist/behavioral/parsers.js.map

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

package/dist/blacktip.d.ts

@@ -4,6 +4,8 @@ import type { Frame, ElementHandle as PlaywrightElementHandle } from 'patchright
 import { BehavioralEngine } from './behavioral-engine.js';
 import { ElementFinder } from './element-finder.js';
 import { Logger } from './logging.js';
+import { type FingerprintSnapshot, type IpReputationResult, type AkamaiTestResult, type AntiBotTestResult } from './diagnostics.js';
+import { type TlsRequest, type TlsResponse } from './tls-side-channel.js';
 import type { BlackTipConfig, ProfileConfig, ActionResult, NavigateResult, ScreenshotResult, WaitResult, TabInfo, FrameInfo, ClickOptions, TypeOptions, ScrollOptions, HoverOptions, SelectOptions, PressKeyOptions, UploadFileOptions, NavigateOptions, ScreenshotOptions, WaitForOptions, WaitForNavigationOptions, ExtractTextOptions, PageContentOptions } from './types.js';
 /**
  * BlackTip — Stealth browser instrument for AI agents.
@@ -53,6 +55,7 @@ export declare class BlackTip extends EventEmitter {
     private core;
     private engine;
     private finder;
+    private tlsChannel;
     private logger;
     private config;
     private customProfiles;
@@ -200,6 +203,89 @@ export declare class BlackTip extends EventEmitter {
         hidden: number;
         selectors: string[];
     }>;
+    /**
+     * Capture the active session's TLS, HTTP/2, and HTTP header fingerprint
+     * by navigating to tls.peet.ws/api/all and httpbin.org/headers.
+     *
+     * The most important field in the result is `headers.uaConsistent`. If
+     * that's `false`, you're emitting a User-Agent / Sec-Ch-Ua mismatch
+     * which Akamai / DataDome / PerimeterX will flag as a textbook spoofing
+     * tell. v0.2.0 fixed this for the default config; if you see it, your
+     * code is overriding the User-Agent in a way that doesn't update the
+     * client hint headers in lockstep.
+     */
+    captureFingerprint(): Promise<FingerprintSnapshot>;
+    /**
+     * Query the active session's egress IP and ASN, score it against
+     * known datacenter / residential ASN patterns, and return a structured
+     * result. Uses the free ipinfo.io endpoint.
+     *
+     * If `isDatacenter: true`, your IP is on a known cloud provider's
+     * range and Akamai will almost certainly flag it. Use a residential
+     * proxy or a different network.
+     */
+    checkIpReputation(): Promise<IpReputationResult>;
+    /**
+     * Visit an Akamai-protected URL and report the result with diagnosis.
+     * Recognizes the Akamai Access Denied error page format and extracts
+     * the reference number for triage.
+     *
+     * Use this in CI as a regression check, or interactively when you're
+     * trying to figure out why a specific target is blocking you.
+     */
+    testAgainstAkamai(url: string): Promise<AkamaiTestResult>;
+    /**
+     * Multi-vendor anti-bot probe. Recognises Akamai, DataDome, Cloudflare,
+     * PerimeterX/HUMAN, Imperva, Kasada, and Arkose. Reports both the
+     * vendors that served a block/challenge AND the vendor signals (cookies,
+     * scripts) present on a passing page — so you can verify the target is
+     * actually protected and BlackTip is sliding past it, not a false negative
+     * on an unprotected URL.
+     */
+    testAgainstAntiBot(url: string): Promise<AntiBotTestResult>;
+    /**
+     * Perform an HTTP request through the bogdanfinn/tls-client Go daemon
+     * with a real Chrome TLS ClientHello, real H2 frame settings, and real
+     * H2 frame order. Lazily spawns the daemon on first call and reuses it
+     * across subsequent calls in the same BlackTip session.
+     *
+     * Use this when an edge gates the very first request before BlackTip's
+     * browser has a usable session — make the gating request via the side
+     * channel, then call `bt.injectTlsCookies(resp)` to push the resulting
+     * cookies into the browser session before navigating.
+     *
+     * Requires the Go daemon binary at `native/tls-client/blacktip-tls[.exe]`.
+     * Build it once with: `cd native/tls-client && go build .`
+     */
+    fetchWithTls(req: TlsRequest): Promise<TlsResponse>;
+    /**
+     * Inject cookies returned by `fetchWithTls()` into the browser session
+     * so a subsequent `bt.navigate()` carries the same edge-issued tokens
+     * the gating request earned. The cookies are filtered to those whose
+     * domain matches the target URL's eTLD+1.
+     */
+    injectTlsCookies(resp: TlsResponse, targetUrl?: string): Promise<number>;
+    /**
+     * Visit a sequence of "normal" sites with realistic dwell times before
+     * the target navigation. Accumulates cookies, populates History API,
+     * and triggers the natural behavioral signals Akamai's profiler
+     * expects to see from a real user.
+     *
+     * Default sites are a small list of safe, fast-loading targets that
+     * don't run heavy detection themselves. Override `sites` to use your
+     * own list, e.g. industry-specific sites for the target you're warming
+     * up against.
+     *
+     * Pass an empty `sites: []` array to skip warming and just dwell on
+     * the current page (useful as a "let the page settle" pause).
+     */
+    warmSession(options?: {
+        sites?: string[];
+        dwellMsRange?: [number, number];
+    }): Promise<{
+        visited: string[];
+        durationMs: number;
+    }>;
     frame(selector: string): Promise<BlackTipFrame>;
     frames(): Promise<FrameInfo[]>;
     getTabs(): Promise<TabInfo[]>;

package/dist/blacktip.d.ts.map

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

package/dist/blacktip.js

@@ -4,6 +4,8 @@ import { BrowserCore } from './browser-core.js';
 import { BehavioralEngine, HUMAN_PROFILE, SCRAPER_PROFILE } from './behavioral-engine.js';
 import { ElementFinder } from './element-finder.js';
 import { Logger } from './logging.js';
+import { captureFingerprint as diagnosticsCaptureFingerprint, checkIpReputation as diagnosticsCheckIpReputation, testAgainstAkamai as diagnosticsTestAgainstAkamai, testAgainstAntiBot as diagnosticsTestAgainstAntiBot, } from './diagnostics.js';
+import { TlsSideChannel } from './tls-side-channel.js';
 const RETRY_STRATEGIES = ['standard', 'wait', 'reload', 'altSelector', 'scroll', 'clearOverlays'];
 /**
  * Text patterns that suggest an action is high-importance — submit,
@@ -90,6 +92,7 @@ export class BlackTip extends EventEmitter {
     core;
     engine;
     finder;
+    tlsChannel = null;
     logger;
     config;
     customProfiles = new Map();
@@ -127,9 +130,44 @@ export class BlackTip extends EventEmitter {
     async launch() {
         await this.core.launch();
         this.launched = true;
+        // IP reputation gate (v0.4.0). When `requireResidentialIp` is set,
+        // we run the same check as `bt.checkIpReputation()` and either warn
+        // or throw based on the verdict. The check itself navigates to
+        // ipinfo.io, so we do it after launch is complete.
+        const gate = this.config.requireResidentialIp;
+        if (gate) {
+            try {
+                const verdict = await diagnosticsCheckIpReputation(this);
+                if (verdict.isDatacenter) {
+                    const msg = `IP reputation gate: egress IP ${verdict.ip} (${verdict.org}) is on a known datacenter ASN. ${verdict.notes.join(' ')}`;
+                    if (gate === 'warn') {
+                        this.logger.warn(msg);
+                    }
+                    else {
+                        // 'throw' or boolean true
+                        await this.core.close();
+                        this.launched = false;
+                        throw new Error(msg);
+                    }
+                }
+            }
+            catch (err) {
+                // If the check itself fails (offline, etc.) and the gate is
+                // 'throw', we re-raise; if 'warn', we log and continue.
+                if (err instanceof Error && err.message.startsWith('IP reputation gate:'))
+                    throw err;
+                if (gate !== 'warn') {
+                    this.logger.warn(`IP reputation gate check failed (allowing launch): ${err instanceof Error ? err.message : String(err)}`);
+                }
+            }
+        }
         return BlackTip.agentGuide();
     }
     async close() {
+        if (this.tlsChannel) {
+            await this.tlsChannel.close().catch(() => undefined);
+            this.tlsChannel = null;
+        }
         await this.core.close();
         this.launched = false;
     }
@@ -900,6 +938,161 @@ export class BlackTip extends EventEmitter {
       return { hidden: count, selectors: hiddenSelectors };
     })()`);
     }
+    // ── Stealth diagnostics (v0.2.0) ──
+    /**
+     * Capture the active session's TLS, HTTP/2, and HTTP header fingerprint
+     * by navigating to tls.peet.ws/api/all and httpbin.org/headers.
+     *
+     * The most important field in the result is `headers.uaConsistent`. If
+     * that's `false`, you're emitting a User-Agent / Sec-Ch-Ua mismatch
+     * which Akamai / DataDome / PerimeterX will flag as a textbook spoofing
+     * tell. v0.2.0 fixed this for the default config; if you see it, your
+     * code is overriding the User-Agent in a way that doesn't update the
+     * client hint headers in lockstep.
+     */
+    async captureFingerprint() {
+        this.ensureLaunched();
+        return diagnosticsCaptureFingerprint(this);
+    }
+    /**
+     * Query the active session's egress IP and ASN, score it against
+     * known datacenter / residential ASN patterns, and return a structured
+     * result. Uses the free ipinfo.io endpoint.
+     *
+     * If `isDatacenter: true`, your IP is on a known cloud provider's
+     * range and Akamai will almost certainly flag it. Use a residential
+     * proxy or a different network.
+     */
+    async checkIpReputation() {
+        this.ensureLaunched();
+        return diagnosticsCheckIpReputation(this);
+    }
+    /**
+     * Visit an Akamai-protected URL and report the result with diagnosis.
+     * Recognizes the Akamai Access Denied error page format and extracts
+     * the reference number for triage.
+     *
+     * Use this in CI as a regression check, or interactively when you're
+     * trying to figure out why a specific target is blocking you.
+     */
+    async testAgainstAkamai(url) {
+        this.ensureLaunched();
+        return diagnosticsTestAgainstAkamai(this, url);
+    }
+    /**
+     * Multi-vendor anti-bot probe. Recognises Akamai, DataDome, Cloudflare,
+     * PerimeterX/HUMAN, Imperva, Kasada, and Arkose. Reports both the
+     * vendors that served a block/challenge AND the vendor signals (cookies,
+     * scripts) present on a passing page — so you can verify the target is
+     * actually protected and BlackTip is sliding past it, not a false negative
+     * on an unprotected URL.
+     */
+    async testAgainstAntiBot(url) {
+        this.ensureLaunched();
+        return diagnosticsTestAgainstAntiBot(this, url);
+    }
+    // ── TLS side-channel (v0.3.0) ──
+    /**
+     * Perform an HTTP request through the bogdanfinn/tls-client Go daemon
+     * with a real Chrome TLS ClientHello, real H2 frame settings, and real
+     * H2 frame order. Lazily spawns the daemon on first call and reuses it
+     * across subsequent calls in the same BlackTip session.
+     *
+     * Use this when an edge gates the very first request before BlackTip's
+     * browser has a usable session — make the gating request via the side
+     * channel, then call `bt.injectTlsCookies(resp)` to push the resulting
+     * cookies into the browser session before navigating.
+     *
+     * Requires the Go daemon binary at `native/tls-client/blacktip-tls[.exe]`.
+     * Build it once with: `cd native/tls-client && go build .`
+     */
+    async fetchWithTls(req) {
+        if (!this.tlsChannel) {
+            this.tlsChannel = await TlsSideChannel.spawn();
+        }
+        return this.tlsChannel.fetch(req);
+    }
+    /**
+     * Inject cookies returned by `fetchWithTls()` into the browser session
+     * so a subsequent `bt.navigate()` carries the same edge-issued tokens
+     * the gating request earned. The cookies are filtered to those whose
+     * domain matches the target URL's eTLD+1.
+     */
+    async injectTlsCookies(resp, targetUrl) {
+        this.ensureLaunched();
+        const targetHost = (() => {
+            if (!targetUrl)
+                return null;
+            try {
+                return new URL(targetUrl).hostname;
+            }
+            catch {
+                return null;
+            }
+        })();
+        const filtered = resp.cookies.filter((c) => {
+            if (!targetHost)
+                return true;
+            const cookieDomain = c.domain.replace(/^\./, '');
+            return targetHost === cookieDomain || targetHost.endsWith('.' + cookieDomain);
+        });
+        if (filtered.length === 0)
+            return 0;
+        await this.setCookies(filtered.map((c) => ({
+            name: c.name,
+            value: c.value,
+            domain: c.domain.startsWith('.') ? c.domain : '.' + c.domain,
+            path: c.path || '/',
+        })));
+        return filtered.length;
+    }
+    // ── Session warming (v0.2.0) ──
+    /**
+     * Visit a sequence of "normal" sites with realistic dwell times before
+     * the target navigation. Accumulates cookies, populates History API,
+     * and triggers the natural behavioral signals Akamai's profiler
+     * expects to see from a real user.
+     *
+     * Default sites are a small list of safe, fast-loading targets that
+     * don't run heavy detection themselves. Override `sites` to use your
+     * own list, e.g. industry-specific sites for the target you're warming
+     * up against.
+     *
+     * Pass an empty `sites: []` array to skip warming and just dwell on
+     * the current page (useful as a "let the page settle" pause).
+     */
+    async warmSession(options = {}) {
+        this.ensureLaunched();
+        const sites = options.sites ?? [
+            'https://www.google.com/',
+            'https://en.wikipedia.org/wiki/Special:Random',
+            'https://news.ycombinator.com/',
+        ];
+        const [dwellMin, dwellMax] = options.dwellMsRange ?? [3000, 7000];
+        const startedAt = Date.now();
+        const visited = [];
+        for (const url of sites) {
+            try {
+                await this.navigate(url);
+                // Random dwell to mimic human reading time
+                const dwell = Math.floor(dwellMin + Math.random() * (dwellMax - dwellMin));
+                // Simulate a small scroll during dwell — humans don't sit still
+                try {
+                    await this.scroll({ direction: 'down', amount: 200 + Math.floor(Math.random() * 400) });
+                }
+                catch { /* scroll may fail on some pages, harmless */ }
+                await this.sleep(dwell);
+                visited.push(url);
+            }
+            catch (err) {
+                this.logger.warn('warmSession site failed, continuing', {
+                    url,
+                    error: err instanceof Error ? err.message : String(err),
+                });
+            }
+        }
+        return { visited, durationMs: Date.now() - startedAt };
+    }
     // ── Iframe Support ──
     async frame(selector) {
         this.ensureLaunched();