@rester159/blacktip 0.1.0

package/dist/proxy-pool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"proxy-pool.js","sourceRoot":"","sources":["../src/proxy-pool.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAmBH;;;GAGG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG;IAC5B,UAAU,EAAE,CAAC,QAAgB,EAAE,QAAgB,EAAE,IAAY,EAAmB,EAAE,CAAC,CAAC;QAClF,EAAE,EAAE,cAAc,IAAI,EAAE;QACxB,QAAQ,EAAE,MAAM;QAChB,IAAI,EAAE,mBAAmB;QACzB,IAAI,EAAE,KAAK;QACX,QAAQ,EAAE,gBAAgB,QAAQ,SAAS,IAAI,EAAE;QACjD,QAAQ;QACR,IAAI,EAAE,CAAC,aAAa,EAAE,YAAY,CAAC;KACpC,CAAC;IACF,OAAO,EAAE,CAAC,QAAgB,EAAE,QAAgB,EAAmB,EAAE,CAAC,CAAC;QACjE,EAAE,EAAE,SAAS;QACb,QAAQ,EAAE,MAAM;QAChB,IAAI,EAAE,eAAe;QACrB,IAAI,EAAE,IAAI;QACV,QAAQ;QACR,QAAQ;QACR,IAAI,EAAE,CAAC,aAAa,EAAE,SAAS,CAAC;KACjC,CAAC;IACF,UAAU,EAAE,CAAC,QAAgB,EAAE,QAAgB,EAAmB,EAAE,CAAC,CAAC;QACpE,EAAE,EAAE,YAAY;QAChB,QAAQ,EAAE,MAAM;QAChB,IAAI,EAAE,qBAAqB;QAC3B,IAAI,EAAE,KAAK;QACX,QAAQ;QACR,QAAQ;QACR,IAAI,EAAE,CAAC,aAAa,EAAE,YAAY,CAAC;KACpC,CAAC;IACF,MAAM,EAAE,CAAC,UAA2B,EAAmB,EAAE,CAAC,UAAU;CAC5D,CAAC;AAEX;;GAEG;AACH,MAAM,UAAU,UAAU,CAAC,CAAkB;IAC3C,MAAM,IAAI,GAAG,CAAC,CAAC,QAAQ,IAAI,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,GAAG,kBAAkB,CAAC,CAAC,CAAC,QAAQ,CAAC,IAAI,kBAAkB,CAAC,CAAC,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC;IACpH,OAAO,GAAG,CAAC,CAAC,QAAQ,MAAM,IAAI,GAAG,CAAC,CAAC,IAAI,IAAI,CAAC,CAAC,IAAI,EAAE,CAAC;AACtD,CAAC;AAmBD,MAAM,OAAO,SAAS;IACZ,OAAO,GAAsB,EAAE,CAAC;IAChC,IAAI,GAAgB,EAAE,CAAC;IACvB,UAAU,GAAG,IAAI,GAAG,EAAkB,CAAC;IACvC,iBAAiB,GAAG,IAAI,GAAG,EAAkB,CAAC;IACrC,UAAU,CAAS;IACnB,QAAQ,CAAuC;IAEhE,YAAY,UAA6B,EAAE,EAAE,UAAuB,EAAE;QACpE,IAAI,CAAC,OAAO,GAAG,CAAC,GAAG,OAAO,CAAC,CAAC;QAC5B,IAAI,CAAC,UAAU,GAAG,OAAO,CAAC,UAAU,IAAI,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC;QAC5D,IAAI,CAAC,QAAQ,GAAG,OAAO,CAAC,QAAQ,IAAI,aAAa,CAAC;IACpD,CAAC;IAED,GAAG,CAAC,KAAsB;QACxB,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,KAAK,CAAC,EAAE,CAAC,EAAE,CAAC;YACjD,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QAC3B,CAAC;IACH,CAAC;IAED,MAAM,CAAC,OAAe;QACpB,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,OAAO,CAAC,CAAC;IAC9D,CAAC;IAED,IAAI;QACF,OAAO,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC;IAC7B,CAAC;IAED;;;OAGG;IACH,eAAe,CAAC,MAAc;QAC5B,IAAI,IAAI,CAAC,OAAO,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO,IAAI,CAAC;QAE3C,iEAAiE;QACjE,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QACvB,MAAM,MAAM,GAAG,IAAI,GAAG,CACpB,IAAI,CAAC,IAAI;aACN,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,KAAK,MAAM,IAAI,GAAG,GAAG,CAAC,CAAC,QAAQ,GAAG,IAAI,CAAC,UAAU,CAAC;aACxE,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,CACzB,CAAC;QACF,MAAM,QAAQ,GAAG,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;QAC/D,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO,IAAI,CAAC;QAEvC,IAAI,MAAuB,CAAC;QAC5B,QAAQ,IAAI,CAAC,QAAQ,EAAE,CAAC;YACtB,KAAK,QAAQ;gBACX,MAAM,GAAG,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,MAAM,EAAE,GAAG,QAAQ,CAAC,MAAM,CAAC,CAAE,CAAC;gBAChE,MAAM;YACR,KAAK,YAAY;gBACf,MAAM,GAAG,QAAQ,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,CAAC,EAAE,EAAE,CACnC,CAAC,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAClF,CAAC;gBACF,MAAM;YACR,KAAK,aAAa,CAAC;YACnB,OAAO,CAAC,CAAC,CAAC;gBACR,MAAM,OAAO,GAAG,IAAI,CAAC,iBAAiB,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC;gBACzD,MAAM,OAAO,GAAG,CAAC,OAAO,GAAG,CAAC,CAAC,GAAG,QAAQ,CAAC,MAAM,CAAC;gBAChD,IAAI,CAAC,iBAAiB,CAAC,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;gBAC5C,MAAM,GAAG,QAAQ,CAAC,OAAO,CAAE,CAAC;gBAC5B,MAAM;YACR,CAAC;QACH,CAAC;QAED,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;QAC1E,OAAO,MAAM,CAAC;IAChB,CAAC;IAED;;;OAGG;IACH,SAAS,CAAC,OAAe,EAAE,MAAc,EAAE,MAAe;QACxD,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC;YACb,OAAO;YACP,MAAM;YACN,QAAQ,EAAE,IAAI,CAAC,GAAG,EAAE;YACpB,MAAM;SACP,CAAC,CAAC;IACL,CAAC;IAED;;;OAGG;IACH,gBAAgB;QACd,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QACvB,MAAM,MAAM,GAAG,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC;QAChC,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,GAAG,CAAC,CAAC,QAAQ,GAAG,IAAI,CAAC,UAAU,CAAC,CAAC;QACxE,OAAO,MAAM,GAAG,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC;IACnC,CAAC;IAED;;OAEG;IACH,qBAAqB;QACnB,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QACvB,OAAO;YACL,OAAO,EAAE,CAAC,GAAG,IAAI,CAAC,OAAO,CAAC;YAC1B,UAAU,EAAE,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,GAAG,CAAC,CAAC,QAAQ,GAAG,IAAI,CAAC,UAAU,CAAC;YACvE,KAAK,EAAE,MAAM,CAAC,WAAW,CAAC,IAAI,CAAC,UAAU,CAAC,OAAO,EAAE,CAAC;SACrD,CAAC;IACJ,CAAC;CACF"}

package/dist/snapshot.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Session snapshot/restore.
+ *
+ * Serializes the cookies, localStorage, sessionStorage, and current URL
+ * of a BlackTip session into a JSON blob. `restore` applies the snapshot
+ * to a BlackTip instance so you can:
+ *
+ *   - Migrate a logged-in session from one proxy to another.
+ *   - Promote a known-good session to a new BlackTip instance if the
+ *     current one crashes.
+ *   - Park a session overnight and resume tomorrow without re-logging in.
+ *
+ * NOT yet serialized: IndexedDB contents, Service Worker state, Cache
+ * Storage. Those are non-trivial and worth a future addition once a
+ * real target needs them (most auth sessions use cookies + localStorage,
+ * which is what we cover here).
+ */
+import type { BrowserCore } from './browser-core.js';
+export interface SessionSnapshot {
+    /** Schema version — bump on incompatible changes. */
+    version: 1;
+    /** Timestamp of when the snapshot was taken. */
+    capturedAt: string;
+    /** The URL the active page was on at capture time. */
+    url: string;
+    /** Browser cookies as a flat array of {name, value, domain, path, ...}. */
+    cookies: Array<{
+        name: string;
+        value: string;
+        domain: string;
+        path: string;
+        expires?: number;
+        httpOnly?: boolean;
+        secure?: boolean;
+        sameSite?: 'Lax' | 'None' | 'Strict';
+    }>;
+    /** localStorage keyed by origin. */
+    localStorageByOrigin: Record<string, Record<string, string>>;
+    /** sessionStorage keyed by origin. */
+    sessionStorageByOrigin: Record<string, Record<string, string>>;
+    /** Optional user label. */
+    label?: string;
+}
+export declare class SnapshotManager {
+    private core;
+    constructor(core: BrowserCore);
+    /**
+     * Capture the current session state. Reads cookies from the browser
+     * context and storage from the active page via evaluate.
+     */
+    capture(label?: string): Promise<SessionSnapshot>;
+    /**
+     * Apply a snapshot to the current BlackTip session. Sets cookies,
+     * navigates to the captured URL, then writes localStorage and
+     * sessionStorage for the origin.
+     */
+    restore(snapshot: SessionSnapshot): Promise<void>;
+}
+//# sourceMappingURL=snapshot.d.ts.map

package/dist/snapshot.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"snapshot.d.ts","sourceRoot":"","sources":["../src/snapshot.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAErD,MAAM,WAAW,eAAe;IAC9B,qDAAqD;IACrD,OAAO,EAAE,CAAC,CAAC;IACX,gDAAgD;IAChD,UAAU,EAAE,MAAM,CAAC;IACnB,sDAAsD;IACtD,GAAG,EAAE,MAAM,CAAC;IACZ,2EAA2E;IAC3E,OAAO,EAAE,KAAK,CAAC;QACb,IAAI,EAAE,MAAM,CAAC;QACb,KAAK,EAAE,MAAM,CAAC;QACd,MAAM,EAAE,MAAM,CAAC;QACf,IAAI,EAAE,MAAM,CAAC;QACb,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,QAAQ,CAAC,EAAE,OAAO,CAAC;QACnB,MAAM,CAAC,EAAE,OAAO,CAAC;QACjB,QAAQ,CAAC,EAAE,KAAK,GAAG,MAAM,GAAG,QAAQ,CAAC;KACtC,CAAC,CAAC;IACH,oCAAoC;IACpC,oBAAoB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IAC7D,sCAAsC;IACtC,sBAAsB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IAC/D,2BAA2B;IAC3B,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,qBAAa,eAAe;IACd,OAAO,CAAC,IAAI;gBAAJ,IAAI,EAAE,WAAW;IAErC;;;OAGG;IACG,OAAO,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,CAAC;IAsCvD;;;;OAIG;IACG,OAAO,CAAC,QAAQ,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC;CA4BxD"}

package/dist/snapshot.js

@@ -0,0 +1,91 @@
+/**
+ * Session snapshot/restore.
+ *
+ * Serializes the cookies, localStorage, sessionStorage, and current URL
+ * of a BlackTip session into a JSON blob. `restore` applies the snapshot
+ * to a BlackTip instance so you can:
+ *
+ *   - Migrate a logged-in session from one proxy to another.
+ *   - Promote a known-good session to a new BlackTip instance if the
+ *     current one crashes.
+ *   - Park a session overnight and resume tomorrow without re-logging in.
+ *
+ * NOT yet serialized: IndexedDB contents, Service Worker state, Cache
+ * Storage. Those are non-trivial and worth a future addition once a
+ * real target needs them (most auth sessions use cookies + localStorage,
+ * which is what we cover here).
+ */
+export class SnapshotManager {
+    core;
+    constructor(core) {
+        this.core = core;
+    }
+    /**
+     * Capture the current session state. Reads cookies from the browser
+     * context and storage from the active page via evaluate.
+     */
+    async capture(label) {
+        const page = this.core.getActivePage();
+        const url = page.url();
+        const cookies = await this.core.cookies();
+        // Storage must be read in-page. sessionStorage is per-origin and only
+        // reachable when we're on that origin. For multi-origin sessions the
+        // caller would need to navigate to each origin and call capture
+        // incrementally — this single-shot version covers the active origin.
+        const storageRaw = (await this.core.executeJS(`(() => {
+      const originKey = location.origin;
+      const readStorage = (store) => {
+        const out = {};
+        for (let i = 0; i < store.length; i++) {
+          const k = store.key(i);
+          if (k != null) out[k] = store.getItem(k) ?? '';
+        }
+        return out;
+      };
+      return {
+        origin: originKey,
+        local: readStorage(localStorage),
+        session: readStorage(sessionStorage),
+      };
+    })()`));
+        return {
+            version: 1,
+            capturedAt: new Date().toISOString(),
+            url,
+            cookies: cookies,
+            localStorageByOrigin: { [storageRaw.origin]: storageRaw.local },
+            sessionStorageByOrigin: { [storageRaw.origin]: storageRaw.session },
+            label,
+        };
+    }
+    /**
+     * Apply a snapshot to the current BlackTip session. Sets cookies,
+     * navigates to the captured URL, then writes localStorage and
+     * sessionStorage for the origin.
+     */
+    async restore(snapshot) {
+        if (snapshot.version !== 1) {
+            throw new Error(`Unsupported snapshot version: ${snapshot.version}`);
+        }
+        // Cookies first — they need to be in place before navigation so the
+        // page request carries them.
+        if (snapshot.cookies.length > 0) {
+            await this.core.setCookies(snapshot.cookies);
+        }
+        // Navigate to the captured URL.
+        if (snapshot.url) {
+            await this.core.navigate(snapshot.url, { waitUntil: 'domcontentloaded' });
+        }
+        // Write storage for each origin. The active page is now on one
+        // origin; we can only write to that origin's storage from here.
+        const page = this.core.getActivePage();
+        const currentOrigin = new URL(page.url()).origin;
+        const local = snapshot.localStorageByOrigin[currentOrigin] ?? {};
+        const session = snapshot.sessionStorageByOrigin[currentOrigin] ?? {};
+        await this.core.executeJS(`((localKv, sessionKv) => {
+      for (const [k, v] of Object.entries(localKv)) localStorage.setItem(k, v);
+      for (const [k, v] of Object.entries(sessionKv)) sessionStorage.setItem(k, v);
+    })(${JSON.stringify(local)}, ${JSON.stringify(session)})`);
+    }
+}
+//# sourceMappingURL=snapshot.js.map

package/dist/snapshot.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"snapshot.js","sourceRoot":"","sources":["../src/snapshot.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AA8BH,MAAM,OAAO,eAAe;IACN;IAApB,YAAoB,IAAiB;QAAjB,SAAI,GAAJ,IAAI,CAAa;IAAG,CAAC;IAEzC;;;OAGG;IACH,KAAK,CAAC,OAAO,CAAC,KAAc;QAC1B,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC,aAAa,EAAE,CAAC;QACvC,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QAEvB,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC;QAE1C,sEAAsE;QACtE,qEAAqE;QACrE,gEAAgE;QAChE,qEAAqE;QACrE,MAAM,UAAU,GAAG,CAAC,MAAM,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC;;;;;;;;;;;;;;;SAezC,CAAC,CAAuF,CAAC;QAE9F,OAAO;YACL,OAAO,EAAE,CAAC;YACV,UAAU,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;YACpC,GAAG;YACH,OAAO,EAAE,OAAqC;YAC9C,oBAAoB,EAAE,EAAE,CAAC,UAAU,CAAC,MAAM,CAAC,EAAE,UAAU,CAAC,KAAK,EAAE;YAC/D,sBAAsB,EAAE,EAAE,CAAC,UAAU,CAAC,MAAM,CAAC,EAAE,UAAU,CAAC,OAAO,EAAE;YACnE,KAAK;SACN,CAAC;IACJ,CAAC;IAED;;;;OAIG;IACH,KAAK,CAAC,OAAO,CAAC,QAAyB;QACrC,IAAI,QAAQ,CAAC,OAAO,KAAK,CAAC,EAAE,CAAC;YAC3B,MAAM,IAAI,KAAK,CAAC,iCAAiC,QAAQ,CAAC,OAAO,EAAE,CAAC,CAAC;QACvE,CAAC;QAED,oEAAoE;QACpE,6BAA6B;QAC7B,IAAI,QAAQ,CAAC,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YAChC,MAAM,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC;QAC/C,CAAC;QAED,gCAAgC;QAChC,IAAI,QAAQ,CAAC,GAAG,EAAE,CAAC;YACjB,MAAM,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,GAAG,EAAE,EAAE,SAAS,EAAE,kBAAkB,EAAE,CAAC,CAAC;QAC5E,CAAC;QAED,+DAA+D;QAC/D,gEAAgE;QAChE,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC,aAAa,EAAE,CAAC;QACvC,MAAM,aAAa,GAAG,IAAI,GAAG,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC,MAAM,CAAC;QACjD,MAAM,KAAK,GAAG,QAAQ,CAAC,oBAAoB,CAAC,aAAa,CAAC,IAAI,EAAE,CAAC;QACjE,MAAM,OAAO,GAAG,QAAQ,CAAC,sBAAsB,CAAC,aAAa,CAAC,IAAI,EAAE,CAAC;QAErE,MAAM,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC;;;SAGrB,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,KAAK,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;IAC7D,CAAC;CACF"}

package/dist/types.d.ts

@@ -0,0 +1,243 @@
+export interface BlackTipConfig {
+    behaviorProfile?: string | ProfileConfig;
+    logLevel?: LogLevel;
+    timeout?: number;
+    retryAttempts?: number;
+    headless?: boolean;
+    proxy?: string;
+    deviceProfile?: string;
+    locale?: string;
+    timezone?: string;
+    screenResolution?: {
+        width: number;
+        height: number;
+    };
+    persistent?: boolean;
+    chromiumPath?: string;
+}
+export type LogLevel = 'debug' | 'info' | 'warn' | 'error';
+export interface ProfileConfig {
+    typingSpeedMs: [number, number];
+    pauseBetweenActionsMs: [number, number];
+    scrollSpeedMs: [number, number];
+    mouseMovementCurve: 'bezier' | 'linear';
+    clickDwellMs: [number, number];
+    readingWpm: [number, number];
+    mistakeRate: number;
+    recoveryBehavior: 'natural' | 'fast';
+    pasteThreshold: number;
+}
+export interface DeviceProfile {
+    name: string;
+    userAgent: string;
+    platform: string;
+    oscpu?: string;
+    hardwareConcurrency: number;
+    deviceMemory: number;
+    maxTouchPoints: number;
+    screenWidth: number;
+    screenHeight: number;
+    devicePixelRatio: number;
+    colorDepth: number;
+    vendor: string;
+    renderer: string;
+    webglVendor: string;
+    webglRenderer: string;
+    languages: string[];
+    plugins: PluginData[];
+    fonts: string[];
+}
+export interface PluginData {
+    name: string;
+    description: string;
+    filename: string;
+    mimeTypes: {
+        type: string;
+        suffixes: string;
+        description: string;
+    }[];
+}
+export interface ActionResult {
+    success: boolean;
+    duration: number;
+    retries: number;
+    error?: string;
+    errorCode?: string;
+}
+export interface NavigateResult {
+    success: boolean;
+    url: string;
+    status: number;
+    duration: number;
+    error?: string;
+}
+export interface ScreenshotResult {
+    data: Buffer;
+    format: 'png' | 'jpeg';
+    width: number;
+    height: number;
+    timestamp: string;
+}
+export interface WaitResult {
+    success: boolean;
+    duration: number;
+    error?: string;
+}
+export interface NavigateOptions {
+    waitUntil?: 'load' | 'domcontentloaded' | 'networkidle';
+    timeout?: number;
+}
+/**
+ * Action importance hint. Drives pre-action hesitation length and
+ * behavioral intensity. Pass `'high'` on consequential clicks like
+ * submit/pay/confirm buttons so BlackTip hesitates like a real user
+ * would before committing.
+ */
+export type ActionImportance = 'low' | 'normal' | 'high';
+export interface ClickOptions {
+    button?: 'left' | 'right' | 'middle';
+    count?: number;
+    timeout?: number;
+    importance?: ActionImportance;
+}
+export interface TypeOptions {
+    clearFirst?: boolean;
+    pressEnter?: boolean;
+    paste?: boolean;
+    timeout?: number;
+    importance?: ActionImportance;
+}
+export interface ScrollOptions {
+    direction?: 'up' | 'down' | 'left' | 'right';
+    amount?: number;
+    selector?: string;
+    smooth?: boolean;
+}
+export interface HoverOptions {
+    timeout?: number;
+}
+export interface SelectOptions {
+    timeout?: number;
+}
+export interface PressKeyOptions {
+    timeout?: number;
+}
+export interface UploadFileOptions {
+    method?: 'auto' | 'input' | 'dragdrop';
+    timeout?: number;
+}
+export interface ExtractTextOptions {
+    multiple?: boolean;
+}
+export interface WaitForOptions {
+    timeout?: number;
+    visible?: boolean;
+    hidden?: boolean;
+}
+export interface WaitForNavigationOptions {
+    waitUntil?: 'load' | 'domcontentloaded' | 'networkidle';
+    timeout?: number;
+}
+export interface ScreenshotOptions {
+    fullPage?: boolean;
+    format?: 'png' | 'jpeg';
+    quality?: number;
+    path?: string;
+}
+export interface PageContentOptions {
+    format?: 'text' | 'html';
+}
+export interface TabInfo {
+    index: number;
+    url: string;
+    title: string;
+    active: boolean;
+}
+export interface FrameInfo {
+    name: string;
+    url: string;
+    index: number;
+}
+export interface ActionEvent {
+    timestamp: string;
+    action: string;
+    target: string;
+    value?: string;
+    outcome: 'success' | 'failure';
+    duration: number;
+    retries: number;
+    behavioral?: BehavioralMetadata;
+    error?: string;
+    tabIndex?: number;
+}
+export interface BehavioralMetadata {
+    mousePathLength?: number;
+    mouseMoveDuration?: number;
+    clickDwell?: number;
+    preActionPause?: number;
+    postActionPause?: number;
+    typingDuration?: number;
+}
+export interface ErrorEvent {
+    timestamp: string;
+    code: string;
+    message: string;
+    url: string;
+    action: string;
+    attempts: number;
+    screenshot?: Buffer;
+    stack?: string;
+}
+export interface RetryEvent {
+    timestamp: string;
+    action: string;
+    target: string;
+    attempt: number;
+    maxAttempts: number;
+    strategy: RetryStrategy;
+    error: string;
+}
+export type RetryStrategy = 'standard' | 'wait' | 'reload' | 'altSelector' | 'scroll' | 'clearOverlays';
+export interface TabChangeEvent {
+    timestamp: string;
+    tabIndex: number;
+    url: string;
+    action: 'opened' | 'closed' | 'switched';
+}
+export interface LogEntry {
+    timestamp: string;
+    level: LogLevel;
+    message: string;
+    data?: Record<string, unknown>;
+}
+export declare const ErrorCodes: {
+    readonly TIMEOUT: "TIMEOUT";
+    readonly ELEMENT_NOT_FOUND: "ELEMENT_NOT_FOUND";
+    readonly NAVIGATION_FAILED: "NAVIGATION_FAILED";
+    readonly JS_ERROR: "JS_ERROR";
+    readonly UPLOAD_FAILED: "UPLOAD_FAILED";
+    readonly SESSION_EXPIRED: "SESSION_EXPIRED";
+    readonly BROWSER_CRASHED: "BROWSER_CRASHED";
+    readonly PROXY_ERROR: "PROXY_ERROR";
+    readonly FRAME_NOT_FOUND: "FRAME_NOT_FOUND";
+    readonly NOT_LAUNCHED: "NOT_LAUNCHED";
+};
+export type ErrorCode = typeof ErrorCodes[keyof typeof ErrorCodes];
+export interface Point {
+    x: number;
+    y: number;
+}
+export interface BoundingBox {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+export interface ElementHandle {
+    selector: string;
+    boundingBox: BoundingBox;
+    tagName: string;
+    isVisible: boolean;
+    frameIndex?: number;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

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

package/dist/types.js

@@ -0,0 +1,15 @@
+// ── Configuration ──
+// ── Error Codes ──
+export const ErrorCodes = {
+    TIMEOUT: 'TIMEOUT',
+    ELEMENT_NOT_FOUND: 'ELEMENT_NOT_FOUND',
+    NAVIGATION_FAILED: 'NAVIGATION_FAILED',
+    JS_ERROR: 'JS_ERROR',
+    UPLOAD_FAILED: 'UPLOAD_FAILED',
+    SESSION_EXPIRED: 'SESSION_EXPIRED',
+    BROWSER_CRASHED: 'BROWSER_CRASHED',
+    PROXY_ERROR: 'PROXY_ERROR',
+    FRAME_NOT_FOUND: 'FRAME_NOT_FOUND',
+    NOT_LAUNCHED: 'NOT_LAUNCHED',
+};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,sBAAsB;AA2PtB,oBAAoB;AAEpB,MAAM,CAAC,MAAM,UAAU,GAAG;IACxB,OAAO,EAAE,SAAS;IAClB,iBAAiB,EAAE,mBAAmB;IACtC,iBAAiB,EAAE,mBAAmB;IACtC,QAAQ,EAAE,UAAU;IACpB,aAAa,EAAE,eAAe;IAC9B,eAAe,EAAE,iBAAiB;IAClC,eAAe,EAAE,iBAAiB;IAClC,WAAW,EAAE,aAAa;IAC1B,eAAe,EAAE,iBAAiB;IAClC,YAAY,EAAE,cAAc;CACpB,CAAC"}

package/examples/01-basic-navigate.ts

@@ -0,0 +1,40 @@
+/**
+ * Basic navigation + extraction example.
+ *
+ * Run with: npx tsx examples/01-basic-navigate.ts
+ */
+
+import { BlackTip } from '@rester159/blacktip';
+
+async function main(): Promise<void> {
+  const bt = new BlackTip({
+    logLevel: 'info',
+    timeout: 10_000,
+    retryAttempts: 2,
+  });
+
+  await bt.launch();
+
+  try {
+    // Navigate and wait for the page to settle.
+    await bt.navigate('https://en.wikipedia.org/wiki/Playwright_(software)');
+    await bt.waitForStable({ networkIdleMs: 500, domIdleMs: 500 });
+
+    // Extract the article title and first paragraph.
+    const title = await bt.extractText('#firstHeading');
+    const firstParagraph = await bt.extractText('#mw-content-text .mw-parser-output > p');
+
+    console.log('Title:', title);
+    console.log('First paragraph:', String(firstParagraph).slice(0, 200), '...');
+
+    // Take a screenshot for the record.
+    await bt.screenshot({ path: 'wikipedia-playwright.png' });
+  } finally {
+    await bt.close();
+  }
+}
+
+main().catch((e) => {
+  console.error(e);
+  process.exit(1);
+});

package/examples/02-login-with-mfa.ts

@@ -0,0 +1,68 @@
+/**
+ * Login flow with MFA — demonstrates pauseForInput.
+ *
+ * This runs BlackTip in serve mode, then sends commands from the same
+ * file for simplicity. In a real agent setup, the driving logic lives
+ * in your agent framework and sends commands over the TCP protocol.
+ *
+ * Run with: npx tsx examples/02-login-with-mfa.ts
+ */
+
+import { BlackTip } from '@rester159/blacktip';
+import * as readline from 'node:readline/promises';
+
+async function main(): Promise<void> {
+  const bt = new BlackTip({
+    logLevel: 'info',
+    timeout: 15_000,
+    retryAttempts: 2,
+    behaviorProfile: 'human',
+  });
+
+  await bt.launch();
+
+  // Listen for pause events and prompt the user via stdin.
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  bt.on('btPause', async (info: { id: string; prompt: string }) => {
+    const answer = await rl.question(`\n[BlackTip] ${info.prompt}\n> `);
+    // Resume by directly resolving the pending entry.
+    const registry = (bt as unknown as { _pauseRegistry?: Map<string, { resolve: (v: string) => void }> })._pauseRegistry;
+    registry?.get(info.id)?.resolve(answer);
+    registry?.delete(info.id);
+  });
+
+  // Set up the pause registry without going through serve mode.
+  (bt as unknown as { _pauseRegistry: Map<string, unknown> })._pauseRegistry = new Map();
+
+  try {
+    await bt.navigate('https://example-site-with-mfa.com/login');
+
+    await bt.type('input[name="email"]', 'you@example.com', { paste: true });
+    await bt.type('input[name="password"]', process.env.DEMO_PASSWORD ?? '', { paste: true });
+    await bt.click('button[type="submit"]');  // auto-importance applies
+
+    await bt.waitForText('Enter verification code', { timeout: 10_000 });
+
+    // Pause and ask the user for the MFA code. The 'btPause' listener
+    // above prompts via readline and resumes.
+    const code = await bt.pauseForInput({
+      prompt: 'Enter the 6-digit code sent to your phone',
+      validate: /^\d{6}$/,
+      timeoutMs: 300_000,
+    });
+
+    await bt.type('input[name="code"]', code, { paste: true });
+    await bt.click('button[type="submit"]');
+
+    await bt.waitForStable();
+    console.log('Logged in, current URL:', (await bt.screenshot()).timestamp, '/', await bt.executeJS('location.href'));
+  } finally {
+    rl.close();
+    await bt.close();
+  }
+}
+
+main().catch((e) => {
+  console.error(e);
+  process.exit(1);
+});

package/examples/03-agent-serve-mode.md

@@ -0,0 +1,98 @@
+# Example 3 — Agent driving BlackTip in serve mode
+
+This is the pattern used by the BlackTip design: an LLM agent in one process, a BlackTip server in another, and one-command-at-a-time interaction.
+
+## Start the server
+
+```bash
+npx blacktip serve --port 9779
+```
+
+The server launches a real Chrome window and listens for TCP commands.
+
+## Send commands
+
+```bash
+# Single command with pretty output (screenshot path shown, not raw base64)
+npx blacktip send "await bt.navigate('https://example.com')" --pretty
+
+# Command from a file — no shell escaping needed
+echo 'await bt.type("#email", "you@example.com", { paste: true })' > cmd.js
+npx blacktip send --file cmd.js --pretty
+
+# Command from stdin
+echo 'return await bt.inspect("#submit-button")' | npx blacktip send --stdin --pretty
+
+# Batch: run many commands sequentially, stop on first failure
+cat > flow.json <<'EOF'
+[
+  "await bt.navigate('https://example.com/login')",
+  "await bt.waitForStable()",
+  "await bt.type('#email', 'you@example.com', {paste: true})",
+  "await bt.type('#password', 'secret', {paste: true})",
+  "await bt.click('#submit')",
+  "await bt.waitForText('Welcome')"
+]
+EOF
+npx blacktip batch flow.json
+```
+
+## Response format
+
+Every `send` returns a JSON bundle:
+
+```json
+{
+  "ok": true,
+  "result": "... whatever the JS command returned, if anything",
+  "url": "https://example.com/",
+  "title": "Example Domain",
+  "screenshotPath": "shot.png",
+  "screenshotB64": "iVBORw0KGgoAAAA...",
+  "screenshotBytes": 41234,
+  "durationMs": 432
+}
+```
+
+With `--pretty`, the `screenshotB64` field is replaced by a placeholder so the console output is readable. The PNG is still saved to `shot.png` (or whatever `screenshotPath` you configured).
+
+## Handling MFA
+
+When a command calls `bt.pauseForInput()`, the server sends a pause frame:
+
+```json
+{"ok": true, "paused": true, "pauseId": "pause-1712345678-12345", "prompt": "Enter the SMS code"}
+```
+
+The `send` command that triggered the pause blocks on the client side until you resume. From a second terminal:
+
+```bash
+npx blacktip resume pause-1712345678-12345 "116170"
+```
+
+The paused command continues executing with the value you provided.
+
+## Listing pending pauses
+
+```bash
+npx blacktip pending
+```
+
+Useful in long-running flows with multiple potential pause points.
+
+## Agent decision loop (pseudocode)
+
+```
+start server
+navigate to target
+loop:
+  send one command
+  parse the bundle
+  look at the screenshot (base64 or on disk)
+  decide the next action based on what you see
+  if uncertain, ask the user
+  if the action is destructive (submit, pay, delete), summarize and confirm first
+  send the next command
+```
+
+The crucial rule: **never pre-script a multi-step sequence.** Look, decide, act, repeat. Pages change between steps and pre-scripted flows fail on the first surprise.