Repository navigation
Document browser location controls - #602
Conversation
3ff01b8 to
4dff833
Compare
![cursor[bot]](https://avatars.githubusercontent.com/in/1210556?s=60&v=4){kind=small}
There was a problem hiding this comment.
Cursor Bugbot has reviewed your changes using default effort and found 1 potential issue.
❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.
Reviewed by Cursor Bugbot for commit 032fb40. Configure here.
Location is set explicitly per session; omitted or cleared fields use the default for the browser's region. Proxy-based selection is not documented until it ships.
8d2b86a to
ad504ba
Compare
| The setting applies across browser contexts, pages, frames, workers, `Intl`, `navigator.language`, `navigator.languages`, and future `Accept-Language` headers. Updating it doesn't restart Chromium or reload pages. | ||
|
|
||
| <Note> | ||
| Location controls timezone and language behavior. It doesn't set geolocation coordinates, grant geolocation permission, change the system clock, translate browser UI, or guarantee a bot-detection outcome. KERNEL doesn't derive location from a browser's proxy; to match a proxy's country, set the location explicitly. |
There was a problem hiding this comment.
KERNEL doesn't derive location from a browser's proxy; to match a proxy's country, set the location explicitly.
just flagging - not sure we need to expose this internal language externally
|
|
||
| <CodeGroup> | ||
| ```typescript TypeScript | ||
| const browser = await kernel.browsers.update('01j8m3w6q2d7av9n5k4f1p8c', { |
There was a problem hiding this comment.
nit - can't remember if we typically hardcode a session id in our code examples like this
| ``` | ||
| </CodeGroup> | ||
|
|
||
| PATCH semantics are field-specific: |
There was a problem hiding this comment.
nits
- weird to say
PATCHrather than update - these should perhaps just be comments inlined in the code blocks rather than after the fact
| ## Read effective location | ||
|
|
||
| Browser responses include the effective values and where each came from: | ||
|
|
||
| ```json | ||
| { | ||
| "location": { | ||
| "timezone": "America/Los_Angeles", | ||
| "locale": "en-US", | ||
| "timezone_source": "override", | ||
| "locale_source": "metro" | ||
| } | ||
| } | ||
| ``` | ||
|
|
||
| `timezone_source` and `locale_source` are `override` for a value set on the session and `metro` for the default of the browser's region. The fields are independent, so their sources can differ. |
There was a problem hiding this comment.
seems unnecessary to expose basic API values in user docs
| - New pages, frames, workers, and network contexts start with the current location. | ||
| - Existing pages and workers receive the update without a reload. | ||
| - Existing `Intl` formatter objects and application-level caches can retain values captured before the update. Create a new formatter when you need the latest default. | ||
| - Future requests use the updated language preference. Requests already in flight aren't rewritten. | ||
| - Customer CDP emulation remains separate from the session default and can temporarily override what a particular target reports. | ||
| - Location overrides last only for the browser session, and profiles don't save them. | ||
| - A pooled browser released with `reuse: true` keeps its location for the next acquirer, as it keeps cookies and open tabs. Release with `reuse: false` to get a fresh browser. |
There was a problem hiding this comment.
should use to use plainer, human facing language. don't think these would necessarily make sense to a first time reader
Drop the proxy note and the response source values, show updates against the created browser's session ID with the update rules as code comments, and describe how changes take effect in plainer language.
There was a problem hiding this comment.
I think the last pending weirdness I see is we claim the default comes from the region but it's based on the location of the underlying host. I think it could surprise folks but I'm not sure how to best describe host placement tbh. Can be resolved after
There was a problem hiding this comment.
@tnsardesai - I missed this in the initial API review probably. I'm generally -1 to exposing metro language (idk if we've already leaked that in other places). I think we could s/metro/default for both source fields instead. Can be resolved outside of this PR
There was a problem hiding this comment.
hmm. yea that's fair! I don't have any strong opinions on this so okay with just replacing it with default! I can spin up a quick PR for it
This branch was successfully deployed
2 participants
What
browsers/location.mdx: setting, updating, clearing, and reading a browser session's timezone and locale.Why
How
null/Noneclears it to the region default.en-us→en-US,iw-IL→he-IL) and theinvalid_browser_locationerror.reuse: truekeeps its location, like cookies and tabs;reuse: falsegives a fresh browser.Context
Testing & Visuals
git diff --checkis clean.mintlify devwas not run locally.browsers/regionsis indocs.jsonnavigation. Is that intended?Note
Low Risk
Documentation-only changes with no runtime or API behavior in this repo.
Overview
Adds a Browser Location guide that documents how to set, update, clear, and read a session’s timezone and locale (region defaults vs per-field overrides via omit / string /
null/None), including validation/normalization,invalid_browser_location, response*_sourcefields, runtime scope (tabs,Intl, Playwright precedence), and poolreusebehavior—with TypeScript and Python examples.The Configure intro now links Location under “More browser settings” alongside Regions and related browser options.
Reviewed by Cursor Bugbot for commit 4d9d122. Bugbot is set up for automated code reviews on this repo. Configure here.