frontend phase 0: app shells, design system & data/contract patterns

Turn the starter into the Balinyaar foundation for the three actor
experiences and lock in the patterns later phases copy.

- Cleanup: remove toastDemo namespace, placeholder home page, and the two
  dead icons; fix BottomBar to use usePathname (locale-aware active tab).
- Three actor shells under (private-routes), no layout above [locale]:
  customer (customer) group with the 5-tab bottom nav; nurse (/nurse) and
  admin (/admin) on the shared sidebar engine. Role model via constants/roles
  + useActorRole (defaults to customer until roles land in f1-b2).
- services/{domain} reference (patients) with a mock behind a config seam,
  hierarchical query keys, deliberate staleTime, and mutation invalidation;
  shared ApiEnvelope/Paginated wire types + unwrap() in lib/api/types.
- Money (integer-safe IRR/Toman) + Shamsi-date utils; toEnglishDigits helper.
- Shared composites, each tested: OtpInput, PhoneNumberField, StepperHeader,
  StatusChip, PlaceholderScreen.
- i18n: seed nav/common/shell/patients in both locales; document namespace
  conventions. Update client/CLAUDE.md Project Structure + fix ColorSchemeScript
  doc drift. Add phase report, STATUS, and REQ-001 (envelope/casing/pagination).

Gate: npm run check + test:ci green (72 tests); build green with NEXT_PUBLIC_API_URL.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

client/src/hooks/auth.ts

@@ -1,4 +1,5 @@
 import { useAuth } from '@/context/auth';
+import { APP_ROLES, DEFAULT_ROLE, type AppRole } from '@/constants';
 
 /**
  * True when the current session is authenticated.
@@ -11,3 +12,20 @@ export function useIsAuthenticated(): boolean {
   const [state] = useAuth();
   return state.isAuthenticated;
 }
+
+// Precedence when a user holds several roles: the highest-privilege shell wins.
+const ROLE_PRECEDENCE: AppRole[] = [APP_ROLES.ADMIN, APP_ROLES.NURSE, APP_ROLES.CUSTOMER];
+
+/**
+ * The actor experience the current session should see, read from the session roles.
+ *
+ * Roles are seeded by the server in f1-b2; until then sessions carry no roles and
+ * this returns DEFAULT_ROLE (customer) so the shells degrade gracefully. Route-group
+ * layouts use it to drive role-aware navigation and (later) access guards.
+ */
+export function useActorRole(): AppRole {
+  const [state] = useAuth();
+  const roles = state.currentUser?.roles;
+  if (!roles?.length) return DEFAULT_ROLE;
+  return ROLE_PRECEDENCE.find((role) => roles.includes(role)) ?? DEFAULT_ROLE;
+}