freshyo/docs/neo-region-refactor.md
2026-11-08 13:49:17 +05:30

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 where LocationTestWrapper is 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

  1. 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.
  2. 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.
  3. 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.
  4. Publish immediately: a persisted region renders as soon as it is hydrated; the device decision may switch it later.
  5. selectedAddressId is the active address, always. No read-time "default fallback". When it is non-null, region/bound/coords/name are derived from it.
  6. selectAddress(id) performs the region switch itself (cart stash/clear/restore, cache invalidation) and then sets the selection.
  7. changeRegion(regionId, boundId?) switches without an address and clears the selection.
  8. NeoAddressForm is a thin adapter that renders the existing AddressForm component.
  9. AddressSwitcherSheet mounts the new NeoAddressFlow.
  10. The 3 s location poll is kept while needsAddressFormFlow is up.
  11. The fixed-pin map is implemented as a ?fixed=1 mode on the existing web-ui /location-selector page.
  12. 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 listRegions is treated as no cache.
  • 8 s resolve timeout, then decide without the fix.
  • Addresses with regionId == null are 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
  • useRegionNeo may only be called by a component that LocationWrapperNeo renders. 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 getUserAddresses as a useQuery at the top and derives selectedAddress / fullAddress from 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) then setAddresses(...)) before selecting.
  • useNeoRegionBootstrap runs the launch decision. The wrapper calls it and then reads the store itself.
  • Every field except selectedAddressId / selectedAddress / fullAddress is guaranteed present in the returned object (selectedAddress and fullAddress are 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-confirmation is reachable only from row 6. Its predicate also enforces: origin === 'device', resolved.regionId !== cached.regionId, addresses.length > 0, no address in resolved.regionId.

3.6 Selection invariant

selectedAddressId is either null, or the id of an address whose regionId === regionId and boundId === 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:

  1. If useAuthOptional() == null → do nothing. This keeps instances above AuthProvider (through useGetEssentialConsts) as read-only consumers, so they cannot settle the launch decision without a user.
  2. const snapshot = await readNeoRegionSnapshot() once; if present, applyRegion({ ...snapshot, origin: 'cache', selectedAddressId: null }).
  3. startTracking() (existing locationStore, idempotent) — one fix, no movement tracking.
  4. Wait for the fix to settle: granted + coords, or denied / services-off / unavailable / error, or an 8 s timeout.
  5. listRegions starts as a useQuery on mount and getUserAddresses starts as the existing useQuery when auth settles — both in parallel with the fix. The decision gate waits for isFetched || isError on regions and (when signed in) addresses; run then reads their data instead of fetching.
  6. run starts the snapshot read and trpc.common.resolveRegionByLocation.fetch({ lat, lng }) together in one Promise.all; the resolve is null on failure. Round coords to 1e-5 for the request only.
  7. decideNeoRegion(...).
  8. 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 }) then setNeedsConfirmation(true) (region is already B; see decision 3).
  9. Set decisionStarted = true before run; 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: list addresses from the store; tapping one calls selectAddress(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: renders NeoAddressForm.
  • login: renders the existing Login screen in place (same as the old flow), returning to choose on 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 by PendingAddressSync after 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 ."
    • AddressForm gains one optional prop onBeforeSubmit?: () => Promise<boolean> | boolean (default true), checked in its onSubmit before any mutation. NeoAddressForm passes a handler that shows a BottomDialog with 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

  • NeoFixedPinMap at coords.
  • BottomDropdown listing addresses (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 / click listeners 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:

  1. if (from !== to) → stashRegionCarts(from), clearLocalCart('regular'), clearLocalCart('flash').
  2. Clear quick-delivery/checkout selections, tags, product/slot caches; remove region-scoped query keys.
  3. restoreRegionCarts(to).
  4. 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 (via StorageServiceCasual).
  • Snapshot: { regionId, boundId, regionName, coords, selectedAddress }.
  • The selected NeoAddress object 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 (changeRegion persists selectedAddress: null).
  • The persisted selection wins over the default when the decision runs, provided it still belongs to the chosen region.
  • Cleared only if regionId is missing from listRegions (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 — selectAddress switches when the region differs; changeRegion clears the selection; setAddresses clears 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 — swap useRegion/useAddressStore seeds for the neo store.
  • tests/lib/prominent-api-hooks.test.tsx, tests/lib/notifications.test.tsx — origin and 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.tsx and tests/lib/use-region.test.tsx continue 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

  1. change-log.txt entry (timestamped diff summary) — before any non-md/txt edit.
  2. neo-region-decision.ts.
  3. neo-region-cache.ts + neoRegionStore.ts + neo-region-switch.ts.
  4. useRegionNeo.ts.
  5. LocationWrapperNeo.tsx + NeoLoadingScreen.tsx.
  6. web-ui ?fixed=1 + NeoFixedPinMap.tsx + NeoConfirmLocation.tsx.
  7. NeoAddressFlow.tsx + NeoAddressForm.tsx (+ AddressForm.onBeforeSubmit).
  8. Migrate consumers (section 7) + PendingAddressSync.
  9. Mount in _layout.tsx, comment out LocationTestWrapper.
  10. Tests + helpers.
  11. Manual pass (section 14).

The app stays on the old wrapper until step 9, so every intermediate state is runnable.


14. Manual verification

  1. Fresh install, location on, inside bounds → children render; regionName correct; no flow screen.
  2. Fresh install, location off, no address → NeoAddressFlow; the 3 s poll recovers after enabling location.
  3. Fresh install, location off, logged in with a default address → app opens on the default's region, no flow.
  4. Guest adds an address → saved locally → region follows it → login → draft posted, selected, first = default.
  5. Cached A, device A → no switch.
  6. Cached A, device B, guest or no address → silent switch to B, no confirmation.
  7. Cached A, device B, address in B → switch to B with that address selected.
  8. 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.
  9. Add address out of bounds → submit blocked, "try selecting on the map" → map retry.
  10. Add address in another region → warning → confirm → switch + cart stashed/restored.
  11. Cart with no address → gate; save → selectAddress → cart shows fullAddress.
  12. Logout → addresses/selection cleared; region stays.

15. Risks / notes

  • Upper-tree consumers: useGetEssentialConsts runs above AuthProvider. useRegionNeo() returns null there 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; CartAddressGate polls 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.onBeforeSubmit is the only behavioural change to a shared old component; default true keeps the other three mounts identical.
  • Fixed-pin map is the only cross-app change; web-ui is otherwise untouched.
  • needsAddressFormFlow is 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 selectAddress switching, but no warning dialog).
  • Any backend or database change.
  • web-ui location-aware launch (RegionGate stays as-is).