# HANDOFF.md — MotorSignal Hybrid v1 Architecture & Implementation Notice

## 1. Prototype Scope & Verification Disclaimer
This handoff package contains **visual and interaction design prototypes** retrieved from Stitch project `5138779337547529796` ("MotorSignal UI/UX Redesign Exploration"). These specifications establish layout hierarchy, typography, touch target boundaries, and user experience flows for the MotorSignal mobile client (target viewport: `390 × 844 px`).

**CRITICAL IMPLEMENTATION PRINCIPLE:**
Mockups represent target client UI. **Repository code and backend APIs are authoritative** regarding:
1. Actual binary telemetry storage formats (authoritative SQLite Drift Schema 7, R2 telemetry bundles).
2. Authoritative Telemetry Acquisition (frozen at 20 Hz / 50 ms via `TelemetryService`).
3. Sensor fusion (frozen in `SensorFusionService`; no independent lean-angle calculations).
4. Ride lifecycle and motion semantics (frozen in `RideStateMachine`; 3.0 MPH moving gate, kickstand isolation).
5. Cloud synchronization and offline sync architecture (`SyncManager`, `SyncOutbox`, `FirebaseSyncProvider`).
6. Authentication providers and entitlements (free vs pro capabilities).
7. Existing group ride visibility, roles, and join policies.

Do **not** implement speculative backend mechanisms or invent hardware capabilities based on UI mockups.

---

## 2. Inconsistency Resolutions & Corrections

1. **Replay Telemetry Retrieval Wording**:
   - Stitch Replay mockups contain the label `"100% Buffered (Local cache)"` or references to `"100% buffered in-memory"`.
   - *Resolution*: In production code and documentation, loading and status wording must reflect the actual telemetry retrieval pipeline (retrieving points from the local SQLite database or streaming/downloading the complete bundle from cloud storage/R2). Do not present speculative "100% buffered in-memory" messaging.

2. **Account Screen Sample Rates and Pro Restrictions**:
   - An older mockup displayed `Internal Phone IMU: Active (100Hz Gyro / Accel)` and claimed `Multi-sensor telemetry sync requires Pro subscription`.
   - *Resolution*: Discarded. The authoritative acquisition cadence is 20 Hz (50 ms). Basic telemetry acquisition and synchronization are not restricted by unsupported Pro paywalls; current entitlements and free/pro models documented in the repository are strictly preserved.

3. **Ride Visibility and Join Policies**:
   - Preserve all existing group ride visibility, membership, and join policies (public, unlisted, club-only, invite-only, host-approved join requests, participant lists, and role permissions). UI components adapt to these existing models without redefining policies.

4. **Canonical Token Reconciliation (#0B1326 vs #081326)**:
   - Stitch HTML templates occasionally used `#081326` or `#0B111E` for dark backgrounds.
   - *Resolution*: Canonical night surface canvas is strictly `#0B1326` as defined in `DESIGN.md`.

5. **Accessibility and Runtime Claims**:
   - Visual mockups demonstrate 200% text scaling and proclaim "Contrast Ratio: 18.2:1 (Calc sRGB)" and "Design Target: 48×48px Minimum Target Discipline".
   - *Resolution*: All accessibility, contrast, and runtime performance claims are treated as unverified until validated with unit/widget tests and on-device / emulator verification.

---

## 3. Phased Implementation Roadmap

### Phase 1: Mobile App Only (Current Implementation Target)
1. **Shared Day/Night Theme and Reusable Components**:
   - Canonical tokens (`#0B1326` night canvas, `#F8FAFC` day canvas, `#06B6D4` / `#0284C7` brand cyan, `#10B981` static green, `#F59E0B` / `#D97706` amber, `#EF4444` / `#DC2626` red).
   - Reusable cockpit telemetry card containers with 1px border.
   - Pinned riding action buttons with minimum 56dp height and 48dp touch bounds.
   - 6-destination bottom navigation bar with ≥48×48dp hitboxes.
   - Static (non-pulsing) recording status indicator.
2. **Riding Dashboard**:
   - High-contrast Speed hero with unit pill.
   - Telemetry metrics (Trip Distance, Elapsed Time, Lean Dynamics with neutral max lean, Elevation Gain, Braking G).
   - Live binding to authoritative `telemetryStreamProvider`, `rideStateMachineProvider`, and vehicle profile.
   - Scrollable telemetry container for accessibility text scales, maintaining pinned Pause and Finish controls.
3. **Authenticated Group Ride Hub**:
   - Decoupled meeting logistics row (Date, Time, Staging point) to prevent collision with action buttons.
   - Segmented Feed / Hub switcher with ≥48dp touch targets.
   - Ride cards supporting Host ("Manage Ride", "Open Hub") and Member ("Ride Details", "Leave Pack") states.
   - Binding to live `groupRideServiceProvider` and user state.

### Phase 2: Planned Client Roadmap (Future Implementation)
- 2-step Create Group Ride wizard (staging typeahead, date/time pickers, access review, QR rendezvous code).
- Route calculation engine loading and fallback states ("direct distance—not a road route").
- Share ride sheet with recipient dispatch (Clubs, rider DMs, GPX export).
- Explicit scoped deletion dialog (Local cache only vs Cloud & local deletion).

### Phase 3: Capabilities Requiring Further Discovery
- External BLE sensor GATT protocol integration.
- Two-factor authentication (2FA) setup flows.
- Dynamic telemetry streaming throttles.