feat: add launchPersistentContext() to avoid incognito detection

js/src/index.ts

@@ -16,7 +16,7 @@
  */
 
 // Launch functions (Playwright API)
-export { launch, launchContext } from "./playwright.js";
+export { launch, launchContext, launchPersistentContext } from "./playwright.js";
 
 // Binary management
 export { ensureBinary, clearCache, binaryInfo, checkForUpdate } from "./download.js";
@@ -25,4 +25,4 @@ export { ensureBinary, clearCache, binaryInfo, checkForUpdate } from "./download
 export { CHROMIUM_VERSION, getDefaultStealthArgs } from "./config.js";
 
 // Types
-export type { LaunchOptions, LaunchContextOptions, BinaryInfo } from "./types.js";
+export type { LaunchOptions, LaunchContextOptions, LaunchPersistentContextOptions, BinaryInfo } from "./types.js";

js/src/playwright.ts

@@ -4,7 +4,7 @@
  */
 
 import type { Browser, BrowserContext } from "playwright-core";
-import type { LaunchOptions, LaunchContextOptions } from "./types.js";
+import type { LaunchOptions, LaunchContextOptions, LaunchPersistentContextOptions } from "./types.js";
 import { DEFAULT_VIEWPORT, getDefaultStealthArgs } from "./config.js";
 import { ensureBinary } from "./download.js";
 import { parseProxyUrl } from "./proxy.js";
@@ -88,6 +88,53 @@ export async function launchContext(
   return context;
 }
 
+/**
+ * Launch stealth browser with a persistent user profile (non-incognito).
+ * Uses Playwright's chromium.launchPersistentContext() under the hood.
+ *
+ * This avoids incognito detection by services like BrowserScan (-10% penalty)
+ * and enables session persistence (cookies, localStorage) across launches.
+ *
+ * @example
+ * ```ts
+ * import { launchPersistentContext } from 'cloakbrowser';
+ * const context = await launchPersistentContext({
+ *   userDataDir: './chrome-profile',
+ *   headless: false,
+ *   proxy: 'http://user:pass@host:port',
+ *   geoip: true,
+ * });
+ * const page = context.pages()[0] || await context.newPage();
+ * await page.goto('https://example.com');
+ * await context.close();
+ * ```
+ */
+export async function launchPersistentContext(
+  options: LaunchPersistentContextOptions
+): Promise<BrowserContext> {
+  const { chromium } = await import("playwright-core");
+
+  const binaryPath = process.env.CLOAKBROWSER_BINARY_PATH || (await ensureBinary());
+  const resolved = await maybeResolveGeoip(options);
+  const args = buildArgs({ ...options, ...resolved });
+
+  const context = await chromium.launchPersistentContext(options.userDataDir, {
+    executablePath: binaryPath,
+    headless: options.headless ?? true,
+    args,
+    ignoreDefaultArgs: ["--enable-automation"],
+    ...(options.proxy ? { proxy: parseProxyUrl(options.proxy) } : {}),
+    ...(options.userAgent ? { userAgent: options.userAgent } : {}),
+    viewport: options.viewport ?? DEFAULT_VIEWPORT,
+    ...(resolved.locale ? { locale: resolved.locale } : {}),
+    ...(resolved.timezone ? { timezoneId: resolved.timezone } : {}),
+    ...(options.colorScheme ? { colorScheme: options.colorScheme } : {}),
+    ...options.launchOptions,
+  });
+
+  return context;
+}
+
 // ---------------------------------------------------------------------------
 // Internal
 // ---------------------------------------------------------------------------

js/src/types.ts

@@ -34,6 +34,21 @@ export interface LaunchContextOptions extends LaunchOptions {
   colorScheme?: "light" | "dark" | "no-preference";
 }
 
+export interface LaunchPersistentContextOptions extends LaunchOptions {
+  /** Path to user data directory for persistent profile. */
+  userDataDir: string;
+  /** Custom user agent string. */
+  userAgent?: string;
+  /** Viewport size. */
+  viewport?: { width: number; height: number };
+  /** Browser locale for context, e.g. "en-US". */
+  locale?: string;
+  /** Timezone for context, e.g. "America/New_York". */
+  timezoneId?: string;
+  /** Color scheme preference. */
+  colorScheme?: "light" | "dark" | "no-preference";
+}
+
 export interface BinaryInfo {
   version: string;
   platform: string;