@skrillex1224/playwright-toolkit 3.0.15 → 3.0.17

package/index.d.ts

@@ -18,14 +18,29 @@ export interface StatusType {
     Failed: 'FAILED';
 }
 
+export interface ModeType {
+    Default: 'default';
+    Cloak: 'cloak';
+}
+
+export interface ToolkitModeStatic {
+    default: 'default';
+    cloak: 'cloak';
+}
+
+export type ToolkitMode = 'default' | 'cloak';
+
 export interface ConstantsModule {
     Code: CodeType;
     Status: StatusType;
+    Mode: ModeType;
+    mode: ToolkitModeStatic;
     PresetOfLiveViewKey: string;
     Device: {
         Desktop: 'desktop';
         Mobile: 'mobile';
     };
+    normalizeMode(value?: unknown, fallback?: ToolkitMode): ToolkitMode;
     normalizeDevice(value?: unknown, fallback?: RuntimeDevice): RuntimeDevice;
     ActorInfo: Record<string, ActorInfoItem>;
 }
@@ -33,7 +48,7 @@ export interface ConstantsModule {
 export type RuntimeDevice = 'desktop' | 'mobile';
 
 export interface ActorShareInfo {
-    mode: 'dom' | 'response';
+    mode: 'dom' | 'response' | 'custom';
     prefix: string;
     xurl: Array<string | string[]>;
 }
@@ -400,9 +415,9 @@ export interface CrawlerBaseOptions {
     requestHandlerTimeoutSecs: number;
     navigationTimeoutSecs: number;
     headless: boolean;
-    browserPoolOptions: {
-        useFingerprints: boolean;
-        fingerprintOptions: {
+    browserPoolOptions: Record<string, any> & {
+        useFingerprints?: boolean;
+        fingerprintOptions?: {
             fingerprintGeneratorOptions: Record<string, any>;
         };
     };
@@ -417,10 +432,6 @@ export interface CrawlerNavigationHook {
     (crawlingContext: any, gotoOptions: Record<string, any>): Promise<void> | void;
 }
 
-export interface LaunchHooks {
-    modifyPageOptions?: (pageOptions: Record<string, any>, context: { pageId: string; browserController: any }) => Promise<void> | void;
-}
-
 export interface GetPlaywrightCrawlerOptionsInput {
     customArgs?: string[];
     proxyConfiguration?: ProxyConfiguration;
@@ -432,7 +443,6 @@ export interface GetPlaywrightCrawlerOptionsInput {
     isRunningOnApify?: boolean;
     launcher?: any;
     runtimeState?: RuntimeEnvState | null;
-    hooks?: LaunchHooks;
     preNavigationHooks?: CrawlerNavigationHook[];
     postNavigationHooks?: CrawlerNavigationHook[];
 }
@@ -446,6 +456,25 @@ export interface LaunchModule {
     getPlaywrightCrawlerOptions(options?: GetPlaywrightCrawlerOptionsInput): PlaywrightCrawlerOptions;
 }
 
+export interface CloakGetPlaywrightCrawlerOptionsInput extends GetPlaywrightCrawlerOptionsInput {
+    cloakOptions?: Record<string, any>;
+    humanizeOptions?: boolean | Record<string, any>;
+    crawlerBaseOptions?: Partial<CrawlerBaseOptions>;
+    browserPoolOptions?: Record<string, any>;
+    launchContext?: Record<string, any>;
+    recommendedGotoOptions?: Record<string, any>;
+}
+
+export interface CloakPlaywrightCrawlerOptions extends PlaywrightCrawlerOptions {
+    cleanup?: () => Promise<void>;
+    closeActiveBrowsers?: () => Promise<void>;
+    forceTerminateActiveProcesses?: () => Promise<void>;
+}
+
+export interface CloakLaunchModule {
+    getPlaywrightCrawlerOptions(options?: CloakGetPlaywrightCrawlerOptionsInput): Promise<CloakPlaywrightCrawlerOptions>;
+}
+
 // =============================================================================
 // LiveView
 // =============================================================================
@@ -659,6 +688,8 @@ export interface ShareScreenCaptureOptions {
     restore?: boolean;
     /** 最大截图高度 (默认: 8000px) */
     maxHeight?: number;
+    /** 截图水印合成模式；默认取当前 toolkit mode，`cloak` 时走兼容分支。 */
+    mode?: 'default' | 'cloak';
     /** 返回 base64 字符串的最大字节数，默认 5MiB。 */
     maxBytes?: number;
     /** maxBytes 的别名。 */
@@ -845,6 +876,10 @@ export interface PlaywrightToolKit {
     };
 }
 
+export interface CloakPlaywrightToolKit extends PlaywrightToolKit {
+    Launch: CloakLaunchModule;
+}
+
 /** Browser/Extension version of the toolkit */
 export interface BrowserPlaywrightToolKit {
     Logger: LoggerModule;
@@ -859,3 +894,8 @@ export interface BrowserPlaywrightToolKit {
 }
 
 export declare function usePlaywrightToolKit(): PlaywrightToolKit;
+export declare function usePlaywrightToolKit(mode: 'default'): PlaywrightToolKit;
+export declare function usePlaywrightToolKit(mode: 'cloak'): CloakPlaywrightToolKit;
+export declare namespace usePlaywrightToolKit {
+    const Mode: ToolkitModeStatic;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skrillex1224/playwright-toolkit",
-  "version": "3.0.15",
+  "version": "3.0.17",
   "description": "一个在 Apify/Crawlee Actor 中启用实时截图视图的实用工具库。",
   "main": "dist/index.cjs",
   "module": "dist/index.js",
@@ -22,12 +22,14 @@
   },
   "scripts": {
     "build": "node build.js",
+    "postinstall": "node ./scripts/postinstall.js",
     "release": "npm run build && npm version patch && npm publish --registry https://registry.npmjs.org --access public --userconfig ../.npmrc",
     "prepublishOnly": "npm run build",
     "test": "echo \"Error: no test specified\" && exit 1"
   },
   "files": [
     "dist/",
+    "scripts/",
     "browser.d.ts",
     "index.d.ts",
     "README.md"
@@ -59,10 +61,16 @@
   },
   "peerDependencies": {
     "apify": "*",
+    "cloakbrowser": "*",
     "crawlee": "*",
     "ghost-cursor-playwright": "*",
     "playwright": "*"
   },
+  "peerDependenciesMeta": {
+    "cloakbrowser": {
+      "optional": true
+    }
+  },
   "devDependencies": {
     "esbuild": "^0.24.2"
   }

package/scripts/postinstall.js

@@ -0,0 +1,203 @@
+#!/usr/bin/env node
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+const SCRIPT_DIR = path.dirname(fileURLToPath(import.meta.url));
+const PACKAGE_ROOT = path.resolve(SCRIPT_DIR, '..');
+const PREFIX = '[playwright-toolkit:postinstall]';
+const SKIP_ENV = 'PLAYWRIGHT_TOOLKIT_SKIP_CLOAK_POSTINSTALL';
+
+const log = (message) => console.log(`${PREFIX} ${message}`);
+const warn = (message) => console.warn(`${PREFIX} ${message}`);
+
+const isTruthy = (value) => /^(1|true|yes|on)$/i.test(String(value || '').trim());
+
+const readTrimmedFile = (filePath) => {
+    try {
+        return fs.readFileSync(filePath, 'utf8').trim();
+    } catch {
+        return '';
+    }
+};
+
+const isBinaryReady = (binaryPath) => {
+    if (!binaryPath || !fs.existsSync(binaryPath)) {
+        return false;
+    }
+
+    if (process.platform === 'win32') {
+        return true;
+    }
+
+    try {
+        fs.accessSync(binaryPath, fs.constants.X_OK);
+        return true;
+    } catch {
+        return false;
+    }
+};
+
+function* walkParentDirs(startDir) {
+    let currentDir = path.resolve(startDir);
+    while (true) {
+        yield currentDir;
+
+        const parentDir = path.dirname(currentDir);
+        if (parentDir === currentDir) {
+            return;
+        }
+
+        currentDir = parentDir;
+    }
+}
+
+const findPackageRoot = (startDir, packageName) => {
+    for (const currentDir of walkParentDirs(startDir)) {
+        const packageJsonPath = path.join(currentDir, 'package.json');
+        if (!fs.existsSync(packageJsonPath)) {
+            continue;
+        }
+
+        try {
+            const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, 'utf8'));
+            if (packageJson?.name === packageName) {
+                return currentDir;
+            }
+        } catch {
+            // Ignore invalid JSON and keep walking.
+        }
+    }
+
+    return null;
+};
+
+const findInstalledCloakRoot = async () => {
+    try {
+        const resolvedEntryUrl = await import.meta.resolve('cloakbrowser');
+        const resolvedEntryPath = fileURLToPath(resolvedEntryUrl);
+        const packageRoot = findPackageRoot(path.dirname(resolvedEntryPath), 'cloakbrowser');
+        if (packageRoot) {
+            return packageRoot;
+        }
+    } catch {
+        // Fall back to filesystem lookup.
+    }
+
+    const searchRoots = [
+        process.env.INIT_CWD,
+        process.cwd(),
+        process.env.npm_config_local_prefix,
+        PACKAGE_ROOT,
+        SCRIPT_DIR,
+    ].filter(Boolean);
+
+    for (const searchRoot of new Set(searchRoots)) {
+        for (const currentDir of walkParentDirs(searchRoot)) {
+            const packageJsonPath = path.join(currentDir, 'node_modules', 'cloakbrowser', 'package.json');
+            if (fs.existsSync(packageJsonPath)) {
+                return path.dirname(packageJsonPath);
+            }
+        }
+    }
+
+    return null;
+};
+
+const clearStaleVersionMarkers = ({ cacheDir, expectedVersion, platformTag }) => {
+    let clearedMarkers = 0;
+
+    for (const markerName of [`latest_version_${platformTag}`, 'latest_version']) {
+        const markerPath = path.join(cacheDir, markerName);
+        const markerVersion = readTrimmedFile(markerPath);
+
+        if (!markerVersion || markerVersion === expectedVersion) {
+            continue;
+        }
+
+        fs.rmSync(markerPath, { force: true });
+        clearedMarkers += 1;
+        log(`Removed stale ${markerName}=${markerVersion} to keep cloakbrowser pinned to ${expectedVersion}.`);
+    }
+
+    return clearedMarkers;
+};
+
+const main = async () => {
+    if (isTruthy(process.env[SKIP_ENV])) {
+        log(`Skipped because ${SKIP_ENV} is set.`);
+        return;
+    }
+
+    const cloakRoot = await findInstalledCloakRoot();
+    if (!cloakRoot) {
+        log('cloakbrowser is not installed; skipping binary preinstall.');
+        return;
+    }
+
+    const [cloakModule, cloakConfig] = await Promise.all([
+        import(pathToFileURL(path.join(cloakRoot, 'dist', 'index.js')).href),
+        import(pathToFileURL(path.join(cloakRoot, 'dist', 'config.js')).href),
+    ]);
+
+    const localBinaryOverride = cloakConfig.getLocalBinaryOverride?.();
+    if (localBinaryOverride) {
+        if (!fs.existsSync(localBinaryOverride)) {
+            throw new Error(`CLOAKBROWSER_BINARY_PATH points to a missing file: ${localBinaryOverride}`);
+        }
+
+        log(`Using CLOAKBROWSER_BINARY_PATH=${localBinaryOverride}; skipping managed binary install.`);
+        return;
+    }
+
+    try {
+        cloakConfig.checkPlatformAvailable?.();
+    } catch (error) {
+        warn(`${error?.message || String(error)} Skipping managed binary install.`);
+        return;
+    }
+
+    const expectedVersion = cloakConfig.getChromiumVersion();
+    const platformTag = cloakConfig.getPlatformTag();
+    const cacheDir = cloakConfig.getCacheDir();
+    const expectedBinaryPath = cloakConfig.getBinaryPath(expectedVersion);
+
+    process.env.CLOAKBROWSER_AUTO_UPDATE = 'false';
+
+    const clearedMarkers = clearStaleVersionMarkers({
+        cacheDir,
+        expectedVersion,
+        platformTag,
+    });
+
+    if (isBinaryReady(expectedBinaryPath)) {
+        const suffix = clearedMarkers > 0 ? ' Cleared stale version markers.' : '';
+        log(`cloakbrowser ${expectedVersion} already available at ${expectedBinaryPath}.${suffix}`);
+        return;
+    }
+
+    log(`Installing cloakbrowser ${expectedVersion} for ${platformTag}...`);
+    const resolvedBinaryPath = await cloakModule.ensureBinary();
+
+    if (!isBinaryReady(expectedBinaryPath)) {
+        throw new Error(
+            `Expected cloakbrowser binary at ${expectedBinaryPath}, but it is still missing after ensureBinary() returned ${resolvedBinaryPath}.`,
+        );
+    }
+
+    if (path.resolve(resolvedBinaryPath) !== path.resolve(expectedBinaryPath)) {
+        warn(
+            `ensureBinary() returned ${resolvedBinaryPath}, expected ${expectedBinaryPath}. `
+            + 'The package-pinned binary is installed and stale version markers were cleared.',
+        );
+    }
+
+    log(`cloakbrowser ${expectedVersion} ready at ${expectedBinaryPath}.`);
+};
+
+main().catch((error) => {
+    const message = error?.stack || error?.message || String(error);
+    console.error(`${PREFIX} ${message}`);
+    process.exit(1);
+});