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/lib/api/types.ts

@@ -0,0 +1,44 @@
+/**
+ * Shared wire types for the server's response envelope and paginated lists.
+ *
+ * The server wraps every response in `ApiResult` (see the b0 swagger snapshot:
+ * `dev/contracts/openapi/swagger.v1.json` → `components.schemas.ApiResult`). The
+ * observed wire casing is **camelCase** (`isSuccess`, `statusCode`, `serverTimeUtc`),
+ * not the snake_case the routing convention implies — always mirror the published
+ * swagger, not an assumption.
+ *
+ * IMPORTANT: `clientFetch`/`serverFetch` currently return the raw response body, so a
+ * real `clientApi` call gets the whole `ApiEnvelope<T>` and must read `.data`. Use
+ * `unwrap()` for that. (Whether the fetch layer should unwrap centrally is filed in
+ * `dev/shared-working-context/frontend/requests/for-backend.md`.)
+ */
+
+export interface ApiEnvelope<T> {
+  isSuccess: boolean;
+  statusCode: number;
+  message?: string | null;
+  requestId?: string | null;
+  data?: T | null;
+}
+
+/** Reads the payload out of the server envelope, throwing if the call was not a success. */
+export function unwrap<T>(envelope: ApiEnvelope<T>): T {
+  if (!envelope?.isSuccess || envelope.data == null) {
+    throw new Error(envelope?.message ?? 'Request did not succeed');
+  }
+  return envelope.data;
+}
+
+/** Standard paginated list payload (api-conventions §Pagination). Verify field casing per contract. */
+export interface Paginated<T> {
+  items: T[];
+  total: number;
+  page: number;
+  pageSize: number;
+}
+
+/** Query params for a paginated list request. */
+export interface PageParams {
+  page?: number;
+  pageSize?: number;
+}