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/components/StepperHeader/StepperHeader.test.tsx

@@ -0,0 +1,25 @@
+import { FunctionComponent } from 'react';
+import { render, screen } from '@testing-library/react';
+import { ThemeProvider } from '../../theme';
+import StepperHeader, { StepperHeaderProps } from './StepperHeader';
+
+const STEPS = ['Phone', 'Verify', 'Profile'];
+
+const ComponentToTest: FunctionComponent<Partial<StepperHeaderProps>> = ({ steps = STEPS, activeStep = 0 }) => (
+  <ThemeProvider>
+    <StepperHeader steps={steps} activeStep={activeStep} />
+  </ThemeProvider>
+);
+
+describe('<StepperHeader/> component', () => {
+  it('renders every step label', () => {
+    render(<ComponentToTest />);
+    STEPS.forEach((label) => expect(screen.getByText(label)).toBeInTheDocument());
+  });
+
+  it('marks the active step', () => {
+    const { container } = render(<ComponentToTest activeStep={1} />);
+    // MUI flags the active step's icon with the Mui-active class.
+    expect(container.querySelector('.Mui-active')).toBeInTheDocument();
+  });
+});

client/src/components/StepperHeader/StepperHeader.tsx

@@ -0,0 +1,30 @@
+import { FunctionComponent } from 'react';
+import Stepper from '@mui/material/Stepper';
+import Step from '@mui/material/Step';
+import StepLabel from '@mui/material/StepLabel';
+
+export interface StepperHeaderProps {
+  /** Ordered step labels — already translated by the caller. */
+  steps: string[];
+  /** Zero-based index of the active step. */
+  activeStep: number;
+  /** Optional alternative-label layout (labels under the dots). Defaults to true. */
+  alternativeLabel?: boolean;
+}
+
+/**
+ * Progress header for multi-step flows (onboarding + verification). Wraps MUI Stepper;
+ * direction is handled by the RTL-aware theme, so it flips correctly at `/fa`.
+ * @component StepperHeader
+ */
+const StepperHeader: FunctionComponent<StepperHeaderProps> = ({ steps, activeStep, alternativeLabel = true }) => (
+  <Stepper activeStep={activeStep} alternativeLabel={alternativeLabel} sx={{ py: 2 }}>
+    {steps.map((label) => (
+      <Step key={label}>
+        <StepLabel>{label}</StepLabel>
+      </Step>
+    ))}
+  </Stepper>
+);
+
+export default StepperHeader;

client/src/components/StepperHeader/index.tsx

@@ -0,0 +1,4 @@
+import StepperHeader from './StepperHeader';
+
+export type { StepperHeaderProps } from './StepperHeader';
+export { StepperHeader as default, StepperHeader };