# Location resolution and region switching Scope: native location store/useRegion, web region gate/store, manual selector, GPS attachment. Platform difference to respect: **native** (`user-ui`) keeps the browsing region **in memory only — never persisted**, re-derived each launch from the device location and/or the default address; **web** (`web-ui`) still **persists** it (`freshyo-region` in localStorage) and its gate resolves no location at all (it validates the saved id against `listRegions`, else shows the region selector). | ID | Priority | Action / input | Expected result | |---|---|---|---| | LOC-01 | P0 | Fresh signed-out/signed-in launch inside A. | One-shot resolution selects A; bound/catalog loads without mandatory login. | | LOC-02 | P1 | Permission denied/permanently denied/GPS unavailable. | A usable manual chooser (and, when a default address exists, that region); no silently "remembered" region, since none is persisted. | | LOC-03 | P1 | Coordinates outside all bounds; empty regions list. | Useful unavailable-service state, not endless spinner. | | LOC-04 | P0 | Delayed GPS A response after manual B selection. | Late automatic response cannot undo manual choice. | | LOC-05 | P1 | Location changes A→B while app remains open. | No unexpected continuous cart-clearing auto-switch. | | LOC-06 | P0 | Both A carts populated; request B switch, cancel then confirm. | Cancel preserves all; confirm clears regional carts/slots/coupons/address context and loads B. | | LOC-07 | P0 | Rapid A→B→A with delayed catalog responses. | Region-generation guard rejects stale B/A responses and mixed prices. | | LOC-08 | P1 | Relaunch after the region's service metadata changed/removed. | Region re-derived (nothing persisted); changed metadata revalidated; no stale cached context. | | LOC-09 | P1 | Cold launch physically in B with A carts. | One-shot resolution follows the anchored startup decision; region adoption does not clear the local cart; no silent mixed-region order. **Known open:** startup adoption can still wipe the cart (review #10); record a failure if observed. | | LOC-10 | P1 | U1 A/B addresses; default B while browsing A. | No automatic foreign default override; A browsing choice retained. | | LOC-11 | P0 | Explicit foreign-address switch confirm/cancel. | Same safe region-switch behavior and cleared regional state. | | LOC-12 | P1 | Saved address without a stored bound. | Bound is derived from the address coordinates; never a foreign region's bound; warnings accurate. | | LOC-13 | P1 | Shared location-store consumers mount/unmount repeatedly. | No duplicate listeners/resolutions or memory leaks affecting selection. | | LOC-14 | P2 | Browser refresh/SSR/private-mode. | No hydration crash; usable manual region selector. | | LOC-15 | P1 | Force-quit during confirmed switch/state clearing. | Relaunch coherent region and carts; no half-reset checkout. | | LOC-16 | P1 | Resolve request offline/timeout, then restore network. | Bounded retry; manual selection remains usable. | | LOC-17 | P2 | Emulator/mock-location environment vs physical device. | Supported location path without production-only/emulator-only assumptions. | | LOC-18 | P0 | Change region while submit request is pending. | No duplicate order or new-region UI falsely representing old-region order. | | LOC-19 | P0 | Cold launch (a) with a default address in the resolved region, (b) with the location resolving to another serviceable region, (c) with location off/out-of-area and a default address, (d) with no default address. | (a) use the default silently; (b) ask the user to choose; (c) use the default; (d) use the resolved region, else ask. | | LOC-20 | P1 | Set a region → force-quit → relaunch with location unavailable. | **Native:** nothing is persisted; the region is re-derived from the default address/location and a chooser appears when neither resolves. **Web:** the saved region is validated against `listRegions`; an invalid/deleted saved id falls back to the chooser. | | LOC-21 | P0 | Cold start adopts the first region while a local cart has items. | Adoption uses the non-clearing path (local cart preserved). Only an explicit switch away from an already-set region confirms and clears regional state. **Known open:** review finding #10 reports this can still clear the cart; record a failure rather than assuming the requirement is met. | | LOC-22 | P1 | Launch with location access denied, then with device location services off, then with permission granted but no fix. | Distinct messages ("access not granted" vs "services off" vs "couldn't get a fix") plus an "Open location settings" action, then an address-chooser fallback. | | LOC-23 | P1 | Signed out, no region resolves (location off/denied/out-of-area). | The chooser shows "Login to get existing addresses." with a Login action. Tapping it shows the login screen **in place** (the gate renders outside the navigator, so no route push), and after a successful login the chooser returns with the account's saved addresses selectable; backing out leaves region/cart untouched. | | LOC-24 | P2 | A region-gate screen (no region yet) offers any "go to another route" action. | The action works without a mounted navigator (inline screen/state change), because `LocationTestWrapper` / `FirstUserWrapper` / `HealthTestWrapper` replace the root ``; a `router.push`/`router.back` there must not silently no-op. | | LOC-25 | P1 | The device fix succeeds but the point is outside every bound, with and without a saved default address. | With a default address: that region is used. Without one: an explicit "outside our delivery area" state is shown on the chooser (not a bare chooser with no explanation), and a usable manual path remains. | Related: the cart's first-address gate for a signed-in user with zero addresses (even an empty cart) is [CART-23](cart.md); the signed-out address draft that syncs after login is [ADDR-25](addresses.md). Native manual switching is the address switcher sheet, not a region list (the region list selector is web-only). Open policy: exact cold-start/manual-choice precedence after a populated local cart. Do not label ambiguity PASS.