[P1] Establish app-wide loading, error, offline, and stale-data states

[postigodev]

Context

Frontend fetch helpers frequently return empty arrays or null data after network and API failures. Several routes then render those fallbacks as legitimate empty states, zero statistics, an empty meal plan, or a redirect away from a missing recipe.

During an outage, users can therefore believe that recipes, inventory, account data, or meal plans were deleted. The application needs a consistent state model that distinguishes absence of data from inability to load it.

Scope

• Define shared typed states for loading, empty, stale data, offline, temporary service failure, unauthorized, forbidden, not found, rate limited, and conflict.
• Preserve the last known valid data where it is safe and clearly label it as stale.
• Stop converting network errors and 5xx responses into valid empty collections.
• Map 404 to a not-found experience only when the backend definitively returned not found.
• Add route-level loading.tsx, error.tsx, and not-found.tsx coverage plus an appropriate global error boundary.
• Add reusable retry, offline, and service-unavailable components.
• Keep authentication expiration distinct from backend unavailability in coordination with [P0] Harden session lifecycle, refresh rotation, and outage behavior #91.
• Provide accessible live announcements for meaningful state changes and retries.
• Attach trace/request IDs to user-visible recoverable errors where available.
• Add tests for 401, 403, 404, 409, 429, 5xx, timeout, interrupted requests, and offline transitions.

Acceptance criteria

• A network/API outage cannot render as an authentic empty recipe, inventory, account, cart, or meal-plan state.
• Unauthorized, forbidden, not-found, rate-limit, conflict, and temporary-failure responses have distinct behavior.
• Routes expose loading, error, and not-found boundaries appropriate to the App Router.
• Recoverable failures offer retry without losing valid client state.
• Stale data is retained only when safe and visibly marked as stale.
• Error messages are accessible and include a supportable correlation ID where available.
• Automated tests cover the major status/network classes across dashboard, recipes, inventory, meal plan, carts, and account.
• Observability can distinguish genuine empty states from failed loads.

Related

• Session outage behavior: [P0] Harden session lifecycle, refresh rotation, and outage behavior #91.
• Dashboard consolidation: [P1] Consolidate dashboard loading and remove cart inventory N+1 #107.
• Cross-service and frontend observability: [P1] Add cross-service, frontend, and database observability #95.
• Browser validation: [P0] Add launch-critical validation and staging smoke tests to dev and release CI #77.

Out of scope

• Full authenticated offline editing.
• Hiding persistent data-integrity failures behind cached UI.