RelayTimer v1.8.1

RelayTimer is a React Progressive Web App (PWA) for managing relay races — specifically Hood to Coast (HTC), Reno Tahoe Odyssey (RTO), and similar 36-leg relay events. It runs entirely offline after the initial load. There are no network calls at runtime except for optional CartoDB map tiles.

Source of Truth (edit here)

C:\Users\garre\OneDrive\HTC_App\ClaudeCode Files\RelayTimer_v1.5\

Vite Project Root (run commands here)

C:\Users\garre\OneDrive\HTC_App\relay-timer\

Workflow

The app has 6 tabs (accessible via bottom navigation bar) plus a Start Screen (shown before race begins) and a Race Complete screen (shown when all 36 legs are finished).

Exchange Screen — Detailed

The Exchange tab is the primary screen van captains use during racing. Key UI elements:

Navigation Bar (always visible)

LegDetailModal

Triggered from Timeline, Runners (tap leg chip), or Exchange (tap Up Next queue). Contains leg minimap (read-only Leaflet), stats rows, elevation profile, pace source, delta vs forecast, start/finish time editors (drum pickers), Google Maps + Offline Directions buttons, and inline offline directions in a nested modal overlay.

AdjustPaceModal

Drum picker for min:sec pace override in the range 4:00–20:59/mi. Shows runner info, base pace, fatigue %, and live preview of projected finish time.

ReassignModal

Runner list with miles done/total and pace. Includes "+ Add new runner" option with name input (creates ad-hoc runner at 9:00/mi default). Reassigning clears any pace override or GPS observation for that leg.

Confirmation Dialogs

Architecture

All state lives in useRaceState.js using useState/useMemo/useCallback — no Redux, no external stores. The hook returns all state values, derived data, and handlers to the App shell, which passes them as props to screen components. Screen components are wrapped in React.memo; all handlers use useCallback for stable references.

State Shape

// Core race state (persisted to localStorage)
raceStartSec           // number | null — seconds since midnight
actuals                // { [legNumber]: { startSec?, finishSec? } }
legPaceOverrides       // { [legNumber]: secondsPerMile }
observedPaces          // { [legNumber]: { distanceMiles, rawSecPerMile, adjustedSecPerMile,
                       //   adjustmentSec, elapsedAtObservation, observedAtSec, capturedAt,
                       //   gpsAccuracyMeters, snapErrorFeet } }
runnerOverrides        // { [legNumber]: { runnerId } | { runnerName } }
paceModel              // { elevation_gain_penalty_sec_per_100ft, elevation_loss_benefit_sec_per_100ft,
                       //   fatigue_k, fatigue_L }

// UI state (not persisted)
nowSec                 // number — current time in seconds since midnight (ticks every 1s)
tab                    // "home" | "exchange" | "timeline" | "runners" | "gps" | "settings"
colorMode              // "auto" | "light" | "dark" (persisted separately)
selectedRaceId         // "htc_2026" | "rto_2026" (persisted separately)
lastLoggedLeg          // forecast object | null (for undo)
undoVisible            // boolean (auto-clears after 5 minutes)
swUpdated              // boolean (service worker update detected)

// Simulation state
simEnabled             // boolean
simSpeed               // 1 | 10 | 60 | 120 | 240
simNowSec              // number | null
simPaused              // boolean
effectiveNow           // derived: simEnabled ? simNowSec : nowSec

// Derived state (via useMemo)
runners                // Runner array with runnerOverrides applied
forecast               // 36-element forecast array from buildForecast
teamStatus             // Team status object from getTeamStatus

Forecast Pipeline

Each forecast entry includes status ("complete" | "active" | "upcoming"), status badge, estimated and actual start/finish/duration/pace, delta, pace source, fatigue multiplier, cumulative miles, and GPS observation fields when applicable.

Completed legs lock: When a leg has actual.finishSec, its actual finish becomes the cascade anchor for the next leg's start.

Active leg with GPS observation: Uses split-time projection — startSec + elapsedAtObservation + (remainingMiles × effectivePace) — instead of the standard pace × distance formula.

Pace Priority Chain

Fatigue Model

Exponential decay per runner based on cumulative miles run before each leg:

multiplier = 1 + k × (1 − e^(−cumulativeMiles / L))

A runner on their first leg always gets multiplier = 1.00. Tunable in Settings → Developer Tools.

Elevation Adjustment

adjustedPace = basePace + (gain/dist/100) × gainPenalty − (loss/dist/100) × lossBenefit

Defaults: +8 sec/mi per 100ft gain, −3 sec/mi per 100ft loss. Applied before fatigue multiplier. Floor of 60 sec/mi on the result.

Persistence

Time Handling

All times stored as seconds since midnight (not Unix timestamps). monotonicSec(prev, raceStart) handles midnight rollover by adding 86400 when raw time is less than previous by more than 6 hours. Overnight race start times and actual duration calculations also handle rollover.

Cache version: v2. Four caches:

Lifecycle

Install: Precaches app shell + all fonts, then calls skipWaiting().
Activate: Purges old caches (any not ending with current version), then claims clients.

Message Handlers

SKIP_WAITING → calls self.skipWaiting()
CACHE_TILES → bulk-downloads tile URLs, reports progress via CACHE_PROGRESS/CACHE_DONE

Update Detection

main.jsx listens for controllerchange (gated on hadController to skip first install). Dispatches sw-updated custom event. App shows green toast: "Update available — tap to reload."

Route Snapping (gpxUtils.js)

Live Map (LiveMapScreen.jsx)

Two rendering modes: Inline (320px/400px, embedded in GPS scroll view) and Full-screen (fills available space with panel at bottom).

Exchange proximity regime changes route and dot colors based on remaining distance: green (>1 mi) → yellow (<1 mi) → red (<0.3 mi). Badge shows proximity when regime is active.

Observation Flow

Each race JSON file follows schema v1.1.0. Supported races: htc_2026 and rto_2026. Selectable via Settings dropdown via RACE_REGISTRY.

{
  "_meta": { "schema_version": "1.1.0" },
  "race": {
    "id": "htc_2026",
    "name": "Hood to Coast",
    "short_name": "HTC",
    "total_legs": 36,
    "total_distance_miles": 196.7,
    "start_time": "2026-08-28T09:00:00",
    "accent_color": "#D64F1E",
    "banner_gradient": ["#2D4A35", "#1A6B3C", "#4A7C59"],
    "leg_map_pdf_base": "https://hoodtocoast.com/...HTC-Leg-{N}.pdf"
  },
  "pace_model": {
    "elevation_gain_penalty_sec_per_100ft": 8,
    "elevation_loss_benefit_sec_per_100ft": 3,
    "fatigue_k": 0.18,
    "fatigue_L": 45
  },
  "difficulty_reference": {
    "scale": {
      "1": { "label": "E",  "display": "Easy" },
      "2": { "label": "M",  "display": "Moderate" },
      "4": { "label": "MC", "display": "Moderate-Hard" },
      "6": { "label": "MD", "display": "Hard" }
    }
  },
  "legs": [
    {
      "leg_number": 1,
      "distance_miles": 6.26,
      "difficulty_rating": 6,
      "difficulty_label": "MD",
      "elevation_gain_ft": 0,
      "elevation_loss_ft": 2036,
      "time_of_day": "day",
      "exchange_zone": "Exchange 1",
      "exchange_lat": 45.304771,
      "exchange_lng": -121.759188,
      "van_waypoints": [{ "lat": 45.3, "lng": -121.7 }],
      "van_directions_offline": "Turn-by-turn text...",
      "image_url": "https://..."
    }
  ],
  "runners": [
    {
      "id": "htc_v1_1",
      "name": "Runner 1",
      "relay_pace_sec_per_mile": 540,
      "legs_assigned": [1, 7, 13, 19, 25, 31]
    }
  ]
}

Design System

Color palette: Mt. Hood / Pacific Northwest inspired. Light mode: forest greens (#2D4A35, #1A6B3C), meadow whites, earth accents (#D64F1E). Dark mode: deep navy (#0D1117, #131A24), bright greens (#27C97A), electric accents (#FF5C00).

Border radius: --r: 16px (generous rounding). Shadows: 3-tier system (sm, md, lg) with green-tinted shadows in light mode.

Color Mode

Three options via data-color-mode attribute on root <div>: auto (follows system), light, dark. Stored in localStorage as relay_color_mode.

Key CSS Classes

DrumColumn / TimeOfDayDrum

iOS-style scroll picker with momentum snapping. ITEM_H=44px, debounced scroll handler (80ms). Used for race start time, leg actual times, and pace override. TimeOfDayDrum uses 12-hour picker with AM/PM toggle.

ElevationProfile

SVG chart rendering pre-computed elevation data from legElevationProfiles.js. ViewBox: 400×96. Animated runner dot (opacity pulse: 1→0.15→1 at 1.2s). Gradient fill (green, 22%→4% opacity).

Two display modes: Default (elevation badge overlay in top corner) and hideBadge (info row above SVG with elevation left-aligned and notes right-aligned — used on Exchange screen).

CountdownCard

Large countdown timer with progress bar. Turns red/overdue showing "+M:SS" when estimated finish time passes. 2×2 grid: finish time, estimated miles done, current time, remaining miles.

RacePositionStrip

36 tiny responsive blocks for all legs. Colors: complete=green, active=pulsing accent, overdue=red pulse, upcoming=gray.

LegMiniMap

Read-only Leaflet map (all interaction disabled: no dragging, zoom, keyboard, tap). Green start dot, red end dot, green route polyline. 180px height, auto-fit bounds with 16px padding.

NavStatusPill

Colored badge in nav bar right section. States: neutral, overdue, ahead-strong (<−120s), ahead (<0s), on-pace (≤120s), behind (>120s).

DiffBadge / DeltaChip

DiffBadge: difficulty label with color class (E/M/MC/MD). DeltaChip: ▲/▼ duration with color class (ahead-strong/ahead/on-pace/behind).

CSV Export (27 columns)

Filename: relay_timer_{raceId}_{YYYYMMDD_HHMM}.csv

JSON Export

Filename: relay_timer_{raceId}_{YYYYMMDD_HHMM}.json. Complete state snapshot including raceStartSec, actuals, legPaceOverrides, observedPaces, runnerOverrides, and paceModel. Re-importable via "Load State from File" (auto-checkpoints current state before loading).

Development

cd C:\Users\garre\OneDrive\HTC_App\relay-timer
npm run dev          # Vite dev server at http://localhost:5173

Production Build

npm run build        # Output to relay-timer/dist/

Build output: ~369 KB JS (main) + ~162 KB (Leaflet chunk, lazy-loaded) + ~39 KB CSS

Deploy

Use /deployHTC skill which: (1) verifies version consistency between raceUtils.js and CLAUDE.md, (2) commits all changes, (3) pushes to GitHub, (4) Cloudflare Pages auto-deploys from GitHub.

Tests

node src/utils/forecastEngine.js   # 81 assertions covering:

test/GpxTrackerTestHarness.jsx has T1–T10 covering parse, haversine, snap, and pace calculations.

Developer-only feature under Settings → Developer Tools.

All handlers defined in useRaceState.js with useCallback: