refactor: unify timezone parameter naming across Python and JS wrappers

- Rename timezone_id → timezone in launch_context(), launch_persistent_context(),
  and launch_persistent_context_async() (Python)
- Extract _migrate_timezone_id() helper for deprecation compat (DRY)
- Always pop timezone_id from kwargs to prevent override via context_kwargs.update()
- Use FutureWarning (visible by default) instead of DeprecationWarning
- JS: deprecate timezoneId on LaunchContextOptions with runtime shim
- Extract migrateTimezoneId<T>() shared helper in playwright.ts (DRY)
- Bump version to 0.3.7 in _version.py and package.json
- Add 4 Python + 4 JS unit tests for deprecation compat behavior

js/README.md

@@ -97,7 +97,7 @@ const context = await launchContext({
   userAgent: 'Custom UA',
   viewport: { width: 1920, height: 1080 },
   locale: 'en-US',
-  timezoneId: 'America/New_York',
+  timezone: 'America/New_York',
 });
 
 // Persistent profile — stay logged in, bypass incognito detection, load extensions

js/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cloakbrowser",
-  "version": "0.3.6",
+  "version": "0.3.7",
   "description": "Stealth Chromium that passes every bot detection test. Drop-in Playwright/Puppeteer replacement with source-level fingerprint patches.",
   "type": "module",
   "main": "dist/index.js",

js/src/playwright.ts

@@ -9,6 +9,17 @@ import { DEFAULT_VIEWPORT, getDefaultStealthArgs } from "./config.js";
 import { ensureBinary } from "./download.js";
 import { parseProxyUrl } from "./proxy.js";
 
+/** @internal Migrate deprecated timezoneId → timezone, warn once. Exported for testing. */
+export function migrateTimezoneId<T extends { timezone?: string; timezoneId?: string }>(options: T): T {
+  if (options.timezoneId != null) {
+    console.warn("[cloakbrowser] timezoneId is deprecated, use timezone instead");
+    const merged = { ...options, timezone: options.timezone ?? options.timezoneId };
+    delete (merged as any).timezoneId;
+    return merged;
+  }
+  return options;
+}
+
 /**
  * Launch stealth Chromium browser via Playwright.
  *
@@ -62,6 +73,7 @@ export async function launch(options: LaunchOptions = {}): Promise<Browser> {
 export async function launchContext(
   options: LaunchContextOptions = {}
 ): Promise<BrowserContext> {
+  options = migrateTimezoneId(options);
   // Resolve geoip BEFORE launch() to avoid double-resolution
   const resolved = await maybeResolveGeoip(options);
   // Skip --fingerprint-timezone binary flag: it only applies to the default
@@ -117,6 +129,7 @@ export async function launchContext(
 export async function launchPersistentContext(
   options: LaunchPersistentContextOptions
 ): Promise<BrowserContext> {
+  options = migrateTimezoneId(options);
   const { chromium } = await import("playwright-core");
 
   const binaryPath = process.env.CLOAKBROWSER_BINARY_PATH || (await ensureBinary());

js/src/types.ts

@@ -33,7 +33,7 @@ export interface LaunchContextOptions extends LaunchOptions {
   viewport?: { width: number; height: number };
   /** Browser locale, e.g. "en-US". */
   locale?: string;
-  /** Timezone, e.g. "America/New_York". */
+  /** @deprecated Use `timezone` (inherited from LaunchOptions) instead. */
   timezoneId?: string;
   /** Color scheme preference — 'light', 'dark', or 'no-preference'. */
   colorScheme?: "light" | "dark" | "no-preference";

js/tests/config.test.ts

@@ -7,7 +7,7 @@ import {
   getBinaryDir,
   getDownloadUrl,
 } from "../src/config.js";
-import { _buildArgsForTest } from "../src/playwright.js";
+import { _buildArgsForTest, migrateTimezoneId } from "../src/playwright.js";
 
 describe("config", () => {
   it("CHROMIUM_VERSION matches expected format", () => {
@@ -98,3 +98,30 @@ describe("buildArgs timezone/locale", () => {
     expect(args.some(a => a.startsWith("--lang="))).toBe(false);
   });
 });
+
+describe("migrateTimezoneId deprecation", () => {
+  it("migrates timezoneId to timezone", () => {
+    const result = migrateTimezoneId({ timezoneId: "Europe/Paris" });
+    expect(result.timezone).toBe("Europe/Paris");
+    expect(result).not.toHaveProperty("timezoneId");
+  });
+
+  it("preserves explicit timezone over timezoneId", () => {
+    const result = migrateTimezoneId({ timezone: "UTC", timezoneId: "Europe/Paris" });
+    expect(result.timezone).toBe("UTC");
+    expect(result).not.toHaveProperty("timezoneId");
+  });
+
+  it("returns options unchanged when no timezoneId", () => {
+    const opts = { timezone: "UTC" };
+    const result = migrateTimezoneId(opts);
+    expect(result).toBe(opts); // same reference, no copy
+    expect(result.timezone).toBe("UTC");
+  });
+
+  it("returns options unchanged when neither is set", () => {
+    const opts = {};
+    const result = migrateTimezoneId(opts);
+    expect(result).toBe(opts);
+  });
+});