# Shell Module — Recipe (per FVW v8 §11.1)

**Module ID:** `oscar.shell`
**Module version:** 0.3.0
**Status:** Constitutional (per §01 mandatory artefacts)

---

## A. Product Description

**What this module is:** OscarShell + TopBar + 3-chip Dock + QuickPanel

**UI structure:** See C8 Shape Matrix in codex.

**States:** Module-specific.

### A.5 QuickPanel (v1.3.4)

**File:** `app/src/shell/QuickPanel.tsx`

A two-stage bottom sheet (Samsung One UI 6 quick panel pattern) that
replaces the previous two-drawer pattern (`<DrawerMenu variant="more">`
+ `<DrawerMenu variant="tools">`).

**Stages:**
- **Narrow** (280px) — drag handle, today's date, user name, two big
  status cards (Survey / Draft report), progress bar, 4 quick-capture
  tiles (Voice / Media / Pin / Calendar). One-tap to any of them.
- **Wide** (620px) — full tile grid in 3 tabs (Work / Capture / Me).
  Each tab has 4-5 tiles. Footer: Sign out + swipe hint.

**Gestures:**
- Tap the More button in the bottom dock → opens at narrow stage.
- Swipe up on the handle (or tap the handle) → expands to wide.
- Swipe down on the handle → collapses to narrow; drag further → dismisses.
- Tap the scrim or X button → dismisses.
- Press Esc → dismisses.

**Sovereign (FWV v8 §33.5):** No Mantine imports. No FVS imports.
Plain React + CSS custom properties. Same theme tokens as the rest
of the shell module.

**Pedagogical section (P1):** This module is part of Oscar's sovereign runtime.

---

## B. Structural Contract

### B.0 Reconstruction Mode Declaration (per §33, §33.5)

- **Mode:** Sovereign SPA Mode (per DO-001)
- **Target runtime:** React 18 + TypeScript + Vite
- **Module file extension:** .tsx + .ts
- **State management:** React hooks
- **Theme tokens:** CSS custom properties

### B.1 Inputs/Outputs

Module-specific. See codex.md C1 for full inventory.

### B.2 Interface Contract (R5)

Module-specific.

### B.3 Module Boundaries

Module OWNS: files in `app/src/shell/`

Module does NOT own: other modules' directories.

Module may import from:
- self (`./`, `../`)
- React, react-router-dom (per `package.json`)
- npm packages (Vite-compatible)

Module must NOT import from:
- Any FVS / `@fvs/*` package (sovereignty)
- Any Mantine package (Sovereign SPA Mode)

### B.4 Swap Test Instructions (R6)

To swap this module for an alternative implementation:
1. Satisfy the same codex.md contract (C1-C9)
2. Pass the same App-VP tests

### B.5 Portability Contract (P4)

Per §34 engine-agnostic truth: this Recipe Book describes behaviour without committing to React.

---

## C. Reconstruction Notes

### C.1 Evidence (source-line citations)

See `pact/extraction/runtime-inventory.md` for runtime inventory.

### C.2 Coverage Matrix Entries

See `pact/recipes/shell/coverage-matrix.md`.

### C.3 Visual Anchors

Module-specific.

### C.4 Behavioural Anchors

Module-specific.

---

## END OF RECIPE.MD