fix(geoip): warn when proxy is set per-context (geoip resolves at launch only)

[mvanhorn]

Summary

When geoip=True is set on launch_async() but a later new_context() gets its own proxy=, the per-context proxy doesn't trigger the geoip resolution path — timezone and locale stay set to whatever the launch resolved. This now warns once with a pointer at the fix shape, instead of silently looking detectable.

The warning is conservative: it doesn't promise behavior the binary patches don't deliver. The deeper "per-context timezone/locale spoofing" change is binary-side and out of scope for this PR.

What changed

• cloakbrowser/browser.py:44 — patches sync and async Browser.new_context() to detect the misconfiguration (geoip enabled at Browser level + proxy passed per-context) and emit a one-time warnings.warn(..., UserWarning).
• js/src/playwright.ts:47 — matching JS browser.newContext() warning.
• README.md and js/README.md — "GeoIP + multiple contexts" subsection documenting the limitation and how to avoid it.
• tests/test_context_geoip_warning.py + js/tests/launch.test.ts — warn-once, quiet-path (proxy on launch), quiet-path (no geoip), quiet-path (no secret).

Notes for #160

The thread accepted the maintainer's diagnosis but raised concern that something else might be off. This PR ships the diagnosis as a warning + docs so users hit a clear signal. If the deeper investigation turns up a per-context resolution bug beyond geoip, that's a separate change.

Testing

• Python: pytest tests/test_context_geoip_warning.py tests/test_launch_context.py tests/test_proxy.py — 79/79 passed
• python3 -m py_compile cloakbrowser/browser.py tests/test_context_geoip_warning.py — clean
• JS: npm ci blocked by sandbox network (ENOTFOUND registry.npmjs.org); JS test follows the existing shape, CI will exercise.

Refs #160

[Cloak-HQ]

Thanks for the PR and for documenting this limitation clearly.

The monkey-patching approach adds more complexity than needed for a warning. Two new functions (sync + async), duplicated _has_context_proxy helpers, and it still misses browser.new_page(proxy=...) which bypasses the patched new_context internally.

Simpler alternative: warn at launch time when geoip=True but no proxy is passed to launch. That's the actual misconfiguration moment from #160.

# In launch() / launch_async(), after maybe_resolve_geoip:
if geoip and not proxy:
    logger.warning(
        "geoip=True without proxy= at launch — timezone/locale will default to "
        "UTC/en-US. Per-context proxies don't trigger geoip resolution. Pass "
        "proxy= to launch() or set explicit timezone=/locale=."
    )

Same for JS. No new functions, no monkey-patching, covers all code paths including new_page. The README/docs additions are good as-is.

There's an edge case this doesn't cover: launch(proxy=A, geoip=True) then new_context(proxy=B) where B is a different region. But that's already documented by your README addition, so users have the info they need.

[mvanhorn]

Thanks - rewrote per the suggestion. Pushed 38197a2.

The branch was force-pushed: I reset to current main, dropped the monkey-patching, and reimplemented as a launch-time if geoip and not proxy: warn(...) inline in each public entry point (launch, launch_async, launch_persistent_context*, launch_context*). The launch_context* wrappers resolve geoip eagerly and call the lower-level launch() without forwarding geoip=, so the warning fires exactly once per user-facing call - no double-warning bug. Same pattern in js/src/playwright.ts across buildLaunchOptions, launchContext, and launchPersistentContext.

Covers browser.new_page(proxy=...) and any other post-launch context routing because the warning fires at launch regardless of what happens after. Tests in tests/test_geoip_launch_warning.py (pytest caplog) and js/tests/launch.test.ts (vitest console.warn spy) cover the fires-when-no-proxy and silent-when-proxy-set cases. README + js/README.md get short geoip-warnings subsections.

Let me know if you want anything tightened.

[mvanhorn]

Good call - switched to the launch-time warning approach you suggested and dropped the monkey-patching entirely. When geoip=True but no proxy is passed to launch, it now warns (your exact message) in launch()/launch_async() on the Python side and in buildLaunchOptions() on the JS side, so it covers every path including new_page. Kept the README limitation note. Rebased onto main.

Verified: the new warning tests pass (fires when geoip + no proxy, stays quiet when a launch proxy is set, both sync and async). I couldn't run the JS Vitest locally (no js/node_modules here), but the JS change is the same guarded console.warn.