30 KiB
Neo Region Store — Implementation Plan
Status: ready to implement. Nothing in this plan has been applied yet.
Scope: apps/user-ui (plus one apps/web-ui route). Old code is left in place and commented out at its mount point only. No deletions, no git operations, no migrations, no test runs.
1. Goal
Replace the current region/location logic with a single new source of truth:
neoRegionStore— Zustand store holding the resolved region, bound, coords, selected address and the two flow flags.useRegionNeo— the only hook any screen may use. It runs the chart's decision internally and returns the store's data.LocationWrapperNeo— mounted whereLocationTestWrapperis today; renders children only when the hook can return the required data.needsAddressFormFlow— the whole address fallback (choose / add / login).needsAddressConfirmation— map with a fixed pin, address dropdown, "keep this location", "add new address".
Every current useRegion consumer is migrated to useRegionNeo. The old useRegion, LocationTestWrapper, LocationFallbackFlow, regionStore, addressStore and region-switch.ts stay in the repo, unused/commented at mount sites.
2. Settled decisions
- Saved address always wins when the app has no cached region: if any saved address exists, its region/bound is used; the device fix only decides when the user has no address.
- Cached region + device in a different region:
- address exists in the new region → use that address;
- guest, or no addresses at all → go ahead with the new region (no confirmation);
- addresses exist but none in the new region →
needsAddressConfirmation.
- No pending candidate, no hydration flag, no status enum. The region returned by the hook is the region. A change is a change; a confirmation only offers a way back.
- Publish immediately: a persisted region renders as soon as it is hydrated; the device decision may switch it later.
selectedAddressIdis the active address, always. No read-time "default fallback". When it is non-null, region/bound/coords/name are derived from it.selectAddress(id)performs the region switch itself (cart stash/clear/restore, cache invalidation) and then sets the selection.changeRegion(regionId, boundId?)switches without an address and clears the selection.NeoAddressFormis a thin adapter that renders the existingAddressFormcomponent.AddressSwitcherSheetmounts the newNeoAddressFlow.- The 3 s location poll is kept while
needsAddressFormFlowis up. - The fixed-pin map is implemented as a
?fixed=1mode on the existingweb-ui/location-selectorpage. - Adding an address in a different region shows a warning and then follows the region-switch flow.
Defaults accepted:
fullAddress=addressLine1, addressLine2, city(empties skipped).- Guest draft is auto-selected after login; first address is default (server-side).
- Logout clears addresses + selection; region/bound/coords persist.
- A persisted region missing from
listRegionsis treated as no cache. - 8 s resolve timeout, then decide without the fix.
- Addresses with
regionId == nullare filtered out of the chooser. - The existing form validation and "Set as default" checkbox are kept.
3. Contracts
3.1 useRegionNeo return
export type NeoCoords = { latitude: number; longitude: number }
export interface NeoRegionData {
regionId: number
boundId: number
regionName: string
coords: NeoCoords
selectedAddressId: number | null
selectedAddress: NeoAddress | null // the full address object
fullAddress: string | null // the formatted one-line string
isCache: boolean
changeRegion: (regionId: number, boundId?: number | null) => Promise<void>
selectAddress: (id: number) => Promise<void>
}
export function useRegionNeo(): NeoRegionData // never null
export function useNeoRegionBootstrap(): void // orchestration, mounted by the wrapper
useRegionNeomay only be called by a component thatLocationWrapperNeorenders. It returns the store's data directly and throws if the store has no complete region (a misuse, not a normal state).- The hook calls
getUserAddressesas auseQueryat the top and derivesselectedAddress/fullAddressfrom that data (falling back to the store while it loads).selectAddress(id)is the store action: async only because a cross-region switch awaits the cart stash, and it never calls the address API. A component that creates or edits an address must refresh the list itself (utils.user.address.getUserAddresses.fetch(undefined)thensetAddresses(...)) before selecting. useNeoRegionBootstrapruns the launch decision. The wrapper calls it and then reads the store itself.- Every field except
selectedAddressId/selectedAddress/fullAddressis guaranteed present in the returned object (selectedAddressandfullAddressare null iff there is no address in the region). isCache === (origin === 'cache').
3.2 Store state
apps/user-ui/src/store/neoRegionStore.ts
type NeoOrigin = 'device' | 'cache' | 'address' | 'manual'
interface NeoRegionState {
regionId: number | null
boundId: number | null
regionName: string | null
coords: NeoCoords | null
origin: NeoOrigin | null
addresses: NeoAddress[]
selectedAddressId: number | null
needsAddressFormFlow: boolean
needsAddressConfirmation: boolean
// single internal write path — used by the hook, never returned by useRegionNeo
applyRegion: (data: {
regionId: number
boundId: number
regionName: string
coords: NeoCoords
origin: NeoOrigin
selectedAddressId: number | null
}) => void // validates the selection against the region, persists, clears both flags
// other internal actions
setAddresses: (addresses: NeoAddress[]) => void // also clears an invalid selection
openAddressFlow: () => void
closeAddressFlow: () => void
setNeedsConfirmation: (value: boolean) => void
resetForLogout: () => void
// public actions
changeRegion: (regionId: number, boundId?: number | null) => Promise<void>
selectAddress: (id: number) => Promise<void>
}
fullAddress is derived in the hook from addresses.find(a => a.id === selectedAddressId); it is not duplicated in the store.
applyRegion is the only place that writes the five region fields plus the selection, so the invariant in §3.6 cannot be bypassed. The persisted snapshot is read by readNeoRegionSnapshot() (in neo-region-cache.ts), not by a store method — the hook reads it once and feeds it to applyRegion with origin: 'cache'.
3.3 origin / isCache
| origin | meaning |
|---|---|
device |
region/bound taken from the live fix |
cache |
no usable fix; persisted snapshot kept |
address |
region/bound taken from a saved address |
manual |
changeRegion without an address |
isCache is origin === 'cache'. NotifRegionSync uses origin === 'device' for "record the tracked region".
3.4 Pure decision function
apps/user-ui/src/lib/neo-region-decision.ts
export interface NeoAddressSummary {
id: number
regionId: number | null
boundId: number | null
isDefault: boolean
latitude: number | null
longitude: number | null
}
export type NeoDecision =
| { action: 'ready'; regionId: number; boundId: number; origin: NeoOrigin; selectedAddressId: number | null }
| { action: 'needs-address-flow' }
| { action: 'needs-confirmation'; regionId: number; boundId: number }
export function decideNeoRegion(input: {
cached: { regionId: number; boundId: number; regionName: string; coords: NeoCoords } | null
fix: NeoCoords | null
resolved: { regionId: number; boundId: number } | null // null = off / out of every bound
isAuthenticated: boolean
addresses: NeoAddressSummary[]
}): NeoDecision
3.5 Decision table
a(region) = an address with regionId === region; defaultAddr = the address with isDefault.
| # | cached | fix / resolved | auth + addresses | Decision |
|---|---|---|---|---|
| 1 | A | no fix or resolved == null |
any | ready(A, A.bound, 'cache', default in A ?? null) |
| 2 | none | no fix / resolved == null |
default exists | ready(default.region, default.bound, 'address', default.id) |
| 3 | none | no fix / resolved == null |
guest / no address | needs-address-flow |
| 4 | A | resolved B, B == A | any | ready(A, B.bound, 'device', default in A ?? null) |
| 5 | A | resolved B, B ≠ A | address in B | ready(B, a(B).bound, 'address', a(B).id) |
| 6 | A | resolved B, B ≠ A | authenticated, addresses exist, none in B | needs-confirmation(B, B.bound) |
| 7 | A | resolved B, B ≠ A | guest or zero addresses | ready(B, B.bound, 'device', null) |
| 8 | none | resolved B | guest / zero addresses | ready(B, B.bound, 'device', null) |
| 9 | none | resolved B | any address | ready(defaultAddr.region, defaultAddr.bound, 'address', defaultAddr.id) (decision 2) |
Notes:
- Row 9 uses the default address; if none is flagged (data anomaly), the lowest id is used.
- Rows 1 and 4 preserve an already-valid explicit selection if one exists; otherwise they select the default in that region.
needs-confirmationis reachable only from row 6. Its predicate also enforces:origin === 'device',resolved.regionId !== cached.regionId,addresses.length > 0, no address inresolved.regionId.
3.6 Selection invariant
selectedAddressIdis eithernull, or the id of an address whoseregionId === regionIdandboundId === boundId.
Enforced only in the store:
| Moment | Effect |
|---|---|
| Decision adopts an address | selectedAddressId = that id |
| Decision adopts device/cache with no address in the region | selectedAddressId = null |
changeRegion |
clears the selection |
selectAddress(id) |
switches to the address's region/bound if needed, then selects |
selectAddress with an address outside the current region |
allowed — it performs the switch |
setAddresses refetch no longer contains the id |
clears the selection |
| Logout | clears addresses + selection |
Address list contains regionId == null |
filtered out before storing |
4. New files
| File | Responsibility |
|---|---|
apps/user-ui/src/lib/neo-address.ts |
NeoCoords / NeoAddress, toNeoAddress, addressCoords, formatNeoAddress. |
apps/user-ui/src/lib/neo-region-decision.ts |
Pure decision function (section 3.4/3.5). No React, no store, no network. |
apps/user-ui/src/lib/neo-region-switch.ts |
Cart/cache side effects for a region change, lifted from region-switch.ts minus every useRegionStore write. Signature: applyRegionSwitch(fromRegionId | null, toRegionId, queryClient): Promise<void>. |
apps/user-ui/src/lib/neo-region-cache.ts |
readNeoRegionSnapshot() / writeNeoRegionSnapshot() / clearNeoRegionSnapshot() over StorageServiceCasual, key freshyo_neo_region_v1. Snapshot = { regionId, boundId, regionName, coords }. |
apps/user-ui/src/store/neoRegionStore.ts |
Store (section 3.2). Holds the data; applyRegion persists the snapshot; exposes the actions. |
apps/user-ui/src/hooks/useRegionNeo.ts |
useNeoRegionBootstrap (orchestration, section 5) + useRegionNeo (non-null selector for wrapper children). |
apps/user-ui/components/LocationWrapperNeo.tsx |
The gate (section 6.1). |
apps/user-ui/src/components/location/neo/NeoLoadingScreen.tsx |
Spinner + "Finding your region…". |
apps/user-ui/src/components/location/neo/NeoAddressFlow.tsx |
Whole fallback: choose saved address / add / login. |
apps/user-ui/src/components/location/neo/NeoAddressForm.tsx |
Adapter over the existing AddressForm + cross-region warning. |
apps/user-ui/src/components/location/neo/NeoConfirmLocation.tsx |
Map + pin + dropdown + actions. |
apps/user-ui/src/components/location/neo/NeoFixedPinMap.tsx |
WebView around /location-selector?...&fixed=1. |
apps/user-ui/tests/lib/neo-region-decision.test.ts |
The 9-row table. |
apps/user-ui/tests/lib/neo-region-store.test.ts |
Selection invariant + selectAddress/changeRegion. |
apps/user-ui/tests/components/neo-location-wrapper.test.tsx |
Four render branches. |
5. useNeoRegionBootstrap orchestration
Module-level guards (not store fields):
let snapshotRead: Promise<NeoRegionSnapshot | null> | null = null
let decisionStarted = false
Effect, in order:
- If
useAuthOptional() == null→ do nothing. This keeps instances aboveAuthProvider(throughuseGetEssentialConsts) as read-only consumers, so they cannot settle the launch decision without a user. const snapshot = await readNeoRegionSnapshot()once; if present,applyRegion({ ...snapshot, origin: 'cache', selectedAddressId: null }).startTracking()(existinglocationStore, idempotent) — one fix, no movement tracking.- Wait for the fix to settle:
granted+ coords, ordenied/services-off/unavailable/error, or an 8 s timeout. listRegionsstarts as auseQueryon mount andgetUserAddressesstarts as the existinguseQuerywhen auth settles — both in parallel with the fix. The decision gate waits forisFetched || isErroron regions and (when signed in) addresses;runthen reads their data instead of fetching.runstarts the snapshot read andtrpc.common.resolveRegionByLocation.fetch({ lat, lng })together in onePromise.all; the resolve isnullon failure. Round coords to 1e-5 for the request only.decideNeoRegion(...).- Apply. If the decision's region differs from the published one, run
applyRegionSwitch(previous, next, queryClient)first — a decision that moves region is a real switch (cart stash/clear + cache invalidation):ready→applyRegion({ regionId, boundId, regionName, coords, origin, selectedAddressId }); it persists the snapshot and clears both flags.needs-address-flow→openAddressFlow().needs-confirmation→applyRegion({ B, origin: 'device', selectedAddressId: null })thensetNeedsConfirmation(true)(region is already B; see decision 3).
- Set
decisionStarted = truebeforerun; the auth-change and recovery-poll paths reset it deliberately.
Address subscription: every getUserAddresses result → setAddresses(...) (filters null-region rows, validates the selection).
Polling: while needsAddressFormFlow is true and the location is unusable (denied, services-off, unavailable, error), every 3 s call probe(); on a false → true transition, reset decisionStarted, clear the flag and re-run the effect. When the flow is up only because the user has no address, the fix already exists, so polling is skipped (otherwise it would re-decide and flicker every 3 s). Same recovery behaviour as LocationTestWrapper today, moved into the hook.
changeRegion:
previous = get().regionId
await applyRegionSwitch(previous, regionId, queryClient)
applyRegion({ regionId, boundId: boundId ?? regionFromList.effectiveBoundId, regionName, coords: regionCentre, origin: 'manual', selectedAddressId: null })
persist snapshot; setNeedsConfirmation(false)
selectAddress(id):
address = get().addresses.find(a => a.id === id)
if (!address || address.regionId == null) return
if (address.regionId !== get().regionId) await applyRegionSwitch(get().regionId, address.regionId, queryClient)
boundId = address.boundId ?? await resolveBound(address.regionId, address.coords) ?? effectiveBoundId
applyRegion({ regionId, boundId, regionName, coords: address.coords, origin: 'address', selectedAddressId: id })
persist snapshot; setNeedsConfirmation(false)
The hook re-exports both actions from the store so useRegionNeo().changeRegion === store.changeRegion.
6. Components
6.1 LocationWrapperNeo
useNeoRegionBootstrap()
const regionId = useNeoRegionStore(s => s.regionId)
const boundId = useNeoRegionStore(s => s.boundId)
const regionName = useNeoRegionStore(s => s.regionName)
const coords = useNeoRegionStore(s => s.coords)
const needsForm = useNeoRegionStore(s => s.needsAddressFormFlow)
const needsConfirm = useNeoRegionStore(s => s.needsAddressConfirmation)
if (needsForm) return <NeoAddressFlow />
if (regionId == null || boundId == null || regionName == null || coords == null) {
return <NeoLoadingScreen />
}
if (needsConfirm) return <NeoConfirmLocation />
return <>{children}</>
The wrapper never calls useRegionNeo; it reads the store directly. That is what makes the hook's non-null contract true: every component that calls it is rendered by this gate, after the four region fields exist. The fallback screens (NeoAddressFlow, NeoAddressForm, and the shared AddressForm) also read the store directly, because they are rendered before a region exists.
Mounted inside AuthProvider, directly replacing LocationTestWrapper (which is commented out).
6.2 NeoAddressFlow (the whole fallback)
Modes: 'choose' | 'add' | 'login' (same shape as the old flow, new implementation).
choose: listaddressesfrom the store; tapping one callsselectAddress(id)and closes (the modal case) / lets the wrapper render children (the gate case). A lone address auto-opens once.- If unauthenticated, the list is empty; renders a login entry point, plus add.
add: rendersNeoAddressForm.login: renders the existingLoginscreen in place (same as the old flow), returning tochooseon success.- Manual opens (location bar / switcher) set
needsAddressFormFlow = true; the wrapper shows the same surface. No device re-check is forced.
6.3 NeoAddressForm
Renders the existing AddressForm with:
draftMode={!isAuthenticated}onResolvedRegion→ stored in local state (used for the warning + success handling)onSuccess(addressId?):addressId != null→await selectAddress(addressId)- draft (no id) →
await changeRegion(resolved.regionId, resolved.boundId)(the draft is posted byPendingAddressSyncafter login) - clear
needsAddressFormFlow
- Cross-region warning: when
onResolvedRegion.regionId !== store.regionId, render an inline warning: "This address is in . Saving will switch your region and clear your cart for ."AddressFormgains one optional proponBeforeSubmit?: () => Promise<boolean> | boolean(defaulttrue), checked in itsonSubmitbefore any mutation.NeoAddressFormpasses a handler that shows aBottomDialogwith Continue/Cancel when the region differs. The other three mounts are unaffected.
Note: the old form already implements the chart's add-address logic — device fix prefilled, map picker via LocationMapStep, resolveBound gate, "outside delivery area → try selecting on the map", submit disabled until serviceable. No new form logic is written.
6.4 NeoConfirmLocation
NeoFixedPinMapatcoords.BottomDropdownlistingaddresses(foreign regions included), current selection highlighted.- "Keep this location" →
setNeedsConfirmation(false). - Picking an address →
selectAddress(id)(which switches, clears the flag). - "Add new address" →
setNeedsConfirmation(false);openAddressFlow().
6.5 NeoFixedPinMap + web-ui ?fixed=1
NeoFixedPinMap renders WebView at:
${WEB_UI_BASE_URL}/location-selector?lat=<lat>&lng=<lng>&fixed=1
In apps/web-ui/src/routes/location-selector.tsx, when fixed=1:
- marker created at the given point,
draggable: false; - no
dragstart/dragend/clicklisteners that rewrite the point; - Continue button hidden;
- the map may still pan/zoom; the pin does not move.
This is the only web-ui change.
7. Modified files
| File | Change |
|---|---|
app/_layout.tsx |
Comment out <LocationTestWrapper>; add <LocationWrapperNeo> in the same position (inside AuthProvider). |
src/components/AddressForm.tsx |
Reads regionId / boundId from the neo store directly (it is also shown in the fallback, before a region exists); adds the optional onBeforeSubmit prop. Behaviour otherwise unchanged. |
src/hooks/prominent-api-hooks.ts |
Reads boundId / regionId / selectedAddressId from the neo store directly (it runs above AuthProvider, outside the wrapper). |
app/(drawer)/(tabs)/me/index.tsx |
region?.name → regionName. |
components/cart-page.tsx |
useRegion → useRegionNeo; selectedAddressId + setSelectedAddressId → selectedAddressId + selectAddress; addresses from the store for the gate condition. |
components/checkout-page.tsx |
useRegion → useRegionNeo. |
components/CheckoutAddressSelector.tsx |
Read selectedAddressId from the hook; drop the selectedAddress/onAddressSelect props; selection → selectAddress; add-address modal success → selectAddress. Remove the local auto-select-default effect (the decision now owns it). |
components/CheckoutAddressDisplay.tsx |
Render fullAddress; no tRPC query, no useAddressStore, no selected ?? default fallback. |
components/PaymentAndOrderComponent.tsx |
regionId / boundId from the hook. |
components/ProductDetail.tsx |
regionId from the hook. |
components/QuickDeliveryAddressSelector.tsx |
regionId + selectedAddressId from the hook; setSelectedAddressId → selectAddress. |
src/components/LocationBar.tsx |
regionName + fullAddress from the hook; no tRPC, no useAddressStore. |
src/components/location/AddressSwitcherSheet.tsx |
Mount NeoAddressFlow instead of LocationFallbackFlow. |
src/components/NotifRegionSync.tsx |
regionId from the hook; origin === 'device' from the store instead of bound != null. |
components/CartAddressGate.tsx |
coords from the hook; on form success selectAddress(addressId) then onDone(). Keep its 3 s poll (or rely on the hook's poll — flag the duplicate and keep the gate's, which only runs when coords is null). |
src/components/PendingAddressSync.tsx |
After create: refetch addresses into the store, then selectAddress(created.id). |
apps/web-ui/src/routes/location-selector.tsx |
fixed=1 mode. |
tests/helpers/test-utils.tsx |
Add seedNeoRegion({regionId, boundId, regionName, coords, addresses, selectedAddressId}). |
tests/helpers/reset.ts |
Reset the neo store between tests. |
Untouched (kept deliberately): src/hooks/useRegion.ts, src/store/regionStore.ts, src/store/addressStore.ts, src/lib/region-switch.ts, components/LocationTestWrapper.tsx, src/components/location/LocationFallbackFlow.tsx.
8. Region switching
neo-region-switch.ts copies the body of confirmRegionSwitch minus the old store write:
if (from !== to)→stashRegionCarts(from),clearLocalCart('regular'),clearLocalCart('flash').- Clear quick-delivery/checkout selections, tags, product/slot caches; remove region-scoped query keys.
restoreRegionCarts(to).queryClient.invalidateQueries().
The store then writes regionId/boundId/regionName/coords/origin; selection is cleared by changeRegion and set by selectAddress.
confirmRegionSwitch stays untouched for the old code paths; nothing new imports it.
9. Persistence
- Key:
freshyo_neo_region_v1(viaStorageServiceCasual). - Snapshot:
{ regionId, boundId, regionName, coords, selectedAddress }. - The selected
NeoAddressobject is cached too. On hydration it is seeded as a provisional address and selected, so the location bar / checkout can render it before the live address list arrives; the live list then replaces it and clears the selection if the address no longer exists. - Applying the persisted snapshot uses
origin: 'cache'and does not touch the flags. - Written on every
ready/changeRegion/selectAddress(changeRegionpersistsselectedAddress: null). - The persisted selection wins over the default when the decision runs, provided it still belongs to the chosen region.
- Cleared only if
regionIdis missing fromlistRegions(then re-decide as no-cache).
10. Polling
The hook owns the 3 s probe. It runs only while needsAddressFormFlow is true and re-runs the decision when the device becomes usable. CartAddressGate keeps its own poll only for the "no fix yet on the cart" case; this is noted as the one duplicated poll.
11. Consumer migration details
| Consumer | Fields used | Notes |
|---|---|---|
me/index.tsx |
regionName |
subtitle text |
cart-page.tsx |
regionId, selectedAddressId, addresses |
gate condition = addresses.length === 0 |
checkout-page.tsx |
regionId, selectedAddressId |
route guard + the order's address |
CheckoutAddressSelector.tsx |
regionId, selectedAddressId |
drop props; selectAddress |
CheckoutAddressDisplay.tsx |
fullAddress |
no fallback lookup |
PaymentAndOrderComponent.tsx |
regionId, boundId |
flash eligibility |
ProductDetail.tsx |
regionId |
query enabled |
QuickDeliveryAddressSelector.tsx |
regionId, selectedAddressId |
same-region warning uses regionId |
LocationBar.tsx |
regionName, fullAddress |
sheet opens the new flow |
NotifRegionSync.tsx |
regionId, origin |
origin === 'device' |
prominent-api-hooks.ts |
regionId, boundId, selectedAddressId |
must work above AuthProvider |
AddressForm.tsx |
regionId, boundId |
store selectors (fallback-safe) |
useAddressStore remains in the tree but nothing writes it after this change. LocationFallbackFlow and LocationTestWrapper become unreferenced.
12. Tests
New:
neo-region-decision.test.ts— one test per row of the table, plus the confirmation predicate (guest / no address / address in B / same region).neo-region-store.test.ts—selectAddressswitches when the region differs;changeRegionclears the selection;setAddressesclears a vanished selection; logout clears addresses/selection.neo-location-wrapper.test.tsx— loading / flow / confirmation / children.
Updated (not run):
tests/helpers/test-utils.tsx,tests/helpers/reset.ts— seed/reset the neo store.tests/pages/cart.test.tsx,tests/pages/checkout.test.tsx,tests/pages/home.test.tsx,tests/pages/me-hub.test.tsx,tests/pages/addresses.test.tsx,tests/pages/payment-and-order.test.tsx,tests/pages/flash-checkout.test.tsx— swapuseRegion/useAddressStoreseeds for the neo store.tests/lib/prominent-api-hooks.test.tsx,tests/lib/notifications.test.tsx—originand hook nullability.tests/components/checkout-address.test.tsx,quick-delivery-address-selector.test.tsx,address-form.test.tsx— new selection source.tests/components/location-components.test.tsxandtests/lib/use-region.test.tsxcontinue to test the old, still-present components/hook; leave them alone unless they import a changed file.
Per AGENTS: tests are written/updated alongside the code but not executed unless requested.
13. Build order
change-log.txtentry (timestamped diff summary) — before any non-md/txt edit.neo-region-decision.ts.neo-region-cache.ts+neoRegionStore.ts+neo-region-switch.ts.useRegionNeo.ts.LocationWrapperNeo.tsx+NeoLoadingScreen.tsx.- web-ui
?fixed=1+NeoFixedPinMap.tsx+NeoConfirmLocation.tsx. NeoAddressFlow.tsx+NeoAddressForm.tsx(+AddressForm.onBeforeSubmit).- Migrate consumers (section 7) +
PendingAddressSync. - Mount in
_layout.tsx, comment outLocationTestWrapper. - Tests + helpers.
- Manual pass (section 14).
The app stays on the old wrapper until step 9, so every intermediate state is runnable.
14. Manual verification
- Fresh install, location on, inside bounds → children render;
regionNamecorrect; no flow screen. - Fresh install, location off, no address →
NeoAddressFlow; the 3 s poll recovers after enabling location. - Fresh install, location off, logged in with a default address → app opens on the default's region, no flow.
- Guest adds an address → saved locally → region follows it → login → draft posted, selected, first = default.
- Cached A, device A → no switch.
- Cached A, device B, guest or no address → silent switch to B, no confirmation.
- Cached A, device B, address in B → switch to B with that address selected.
- Cached A, device B, addresses only in A → confirmation screen: dropdown populated; "Keep" stays on B; picking A switches back; "Add new" opens the flow.
- Add address out of bounds → submit blocked, "try selecting on the map" → map retry.
- Add address in another region → warning → confirm → switch + cart stashed/restored.
- Cart with no address → gate; save →
selectAddress→ cart showsfullAddress. - Logout → addresses/selection cleared; region stays.
15. Risks / notes
- Upper-tree consumers:
useGetEssentialConstsruns aboveAuthProvider.useRegionNeo()returnsnullthere until the wrapper populates the store; the query already tolerates a null bound. No orchestration runs without auth. - Double poll: the hook polls while the fallback is up;
CartAddressGatepolls when the cart has no fix. Accepted for now. - Two switches in row 6: the device switch happens before the confirmation renders; choosing an address switches again. Cart stashing makes this safe;
confirmRegionSwitch's contract (ask before switching) is not honoured for the device switch by design. AddressForm.onBeforeSubmitis the only behavioural change to a shared old component; defaulttruekeeps the other three mounts identical.- Fixed-pin map is the only cross-app change;
web-uiis otherwise untouched. needsAddressFormFlowis used both by the launch decision and by manual opens (location bar); manual opens never reset the decision.
16. Out of scope
- Deleting the old hook/store/components.
- Rewriting the address book (
me/addresses) onto the neo store. - Cross-region warning in the checkout add-address modal (it inherits
selectAddressswitching, but no warning dialog). - Any backend or database change.
- web-ui location-aware launch (
RegionGatestays as-is).