RelayTimer v1.10.2

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.

RelayTimer is a single-repo, two-build-target monorepo. One Vite project root (relay-timer/) with two separate Vite configs producing two separate static sites from the same shared logic layer.

Build Targets & Deploy Destinations

Import Aliases

Both Vite configs define: @utils/ → src/utils/, @hooks/ → src/hooks/, @components/ → src/components/, @data/ → src/data/.

The iPad config additionally defines @phone/ → src/phone/, which lets the iPad build reuse HomeScreen.jsx, LiveMapScreen.jsx, and relayTimer.css without duplicating them.

Cross-Platform Discipline

The app has 6 tabs plus a Start Screen (before race) and a Race Complete screen (all 36 legs done). Navigation chrome differs by platform — bottom tab bar on phone, left sidebar on iPad — but screen behavior (state, handlers, forecast data) is identical; only layout/composition differs.

Navigation Chrome

LegDetailModal

Triggered from Timeline, Runners (tap leg chip), or Exchange (tap Up Next). Contains: handle bar, header, LegMiniMap (read-only route map), PDF link, stats rows, Elevation Profile, pace source/fatigue, observed distance, delta vs forecast, notes, Google Maps + Offline Directions + PDF buttons, and Start/Finish time editors.

AdjustPaceModal

Drum picker for pace override in range 4:00–20:59/mi. Shows runner info, base pace, fatigue %, and projected finish preview. Apply / Clear / Cancel.

ReassignModal

Runner list with miles/pace, "+ Add new runner" input (9:00/mi default), current-assignment label, Confirm Reassignment. Clears pace override and GPS observation for the reassigned leg.

Confirmation Dialogs

Architecture

All state lives in useRaceState.js (src/hooks/) using useState/useMemo/useCallback — no Redux, no external stores, and never forked per platform. Both src/phone/RelayTimer.jsx and src/ipad/RelayTimer.jsx call this hook and pass results down as props. Screen components use React.memo; handlers use useCallback.

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, tab, colorMode, selectedRaceId, lastLoggedLeg, undoVisible,
swUpdated, confirmSwitchRaceId, runnerLegModal

// Simulation state
simEnabled, simSpeed, simNowSec, simPaused
effectiveNow           // derived: simEnabled ? (simNowSec ?? raceStartSec ?? nowSec) : nowSec

// Derived state (via useMemo)
runners, forecast, teamStatus

Forecast Pipeline

Completed legs lock and cascade-anchor the next leg's start. Active leg with GPS observation uses split-time projection: startSec + elapsedAtObservation + (remainingMiles × effectivePace).

Pace Priority Chain

Fatigue Model

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

First leg for any runner 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

PWA Manifest Differences

Orientation Lock

Manifest orientation: landscape isn't always honored by Safari, so src/ipad/main.jsx supplements with the Screen Orientation API:

if (screen.orientation && screen.orientation.lock) {
  screen.orientation.lock('landscape').catch(() => {});
}

A CSS fallback in relayTimer.ipad.css shows a "rotate to landscape" overlay and hides .content-area when @media (orientation: portrait) matches. Real-hardware verification remains outstanding (Phase 4).

Safe Area Insets

relayTimer.ipad.css applies env(safe-area-inset-*) to .sidebar (top/bottom/left) and .top-bar (left/right) for iPad Pro models with Face ID camera housings.

Splash Screens (added v1.10.2)

Each is the app logo (favicon.svg, rasterized) centered on #131A24 background. Generated with a one-off sharp script (not a project dependency — installed temporarily, images generated, removed). No SW changes needed: the existing stale-while-revalidate handler covers any same-origin asset path.

Remaining Phase 4 Work

Shared by both builds — unchanged since v1.8.1. Cache version v2, four caches:

Unchanged since v1.8.1 — see src/utils/gpxUtils.js and src/phone/screens/LiveMapScreen.jsx (shared by both platforms via @phone alias).

Exchange-proximity color regime: green (>1 mi) → yellow (<1 mi) → red (<0.3 mi). GPX loading state is derived (v1.10.1 refactor for lint compliance) rather than reset via synchronous setState in an effect — this also closed a latent race condition where a slow stale GPX fetch could overwrite a newer one.

Unchanged since v1.8.1. Schema v1.1.0 JSON per race (htc_2026.json, rto_2026.json) — race metadata, pace model defaults, difficulty reference, 36 legs (exchange coordinates, van directions, elevation, PDF links), runner roster. See src/data/races/ — do not modify structure.

{
  "_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,
    "accent_color": "#D64F1E",
    "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 },
  "legs": [{ "leg_number": 1, "distance_miles": 6.26, "difficulty_label": "MD",
             "elevation_gain_ft": 0, "elevation_loss_ft": 2036,
             "exchange_lat": 45.304771, "exchange_lng": -121.759188, ... }],
  "runners": [{ "id": "htc_v1_1", "relay_pace_sec_per_mile": 540,
                "legs_assigned": [1, 7, 13, 19, 25, 31] }]
}

Two separate stylesheets: src/phone/relayTimer.css (design tokens + phone layout, also imported by iPad for shared components/colors) and src/ipad/relayTimer.ipad.css (iPad-only: sidebar, top bar, panel grids, orientation/safe-area). src/tokens.css independently duplicates some of the same custom properties — known duplication since v1.8.3, not yet consolidated (see BACKLOG).

Design system (fonts, color palette, border radius, shadows, color-mode switching via data-color-mode) is unchanged since v1.8.1.

Color palette: Mt. Hood / Pacific Northwest inspired. Light: forest greens (#2D4A35, #1A6B3C), earth accents (#D64F1E). Dark: deep navy (#0D1117, #131A24), bright greens (#27C97A), electric accents (#FF5C00). Three color modes via data-color-mode attribute: auto (follows system), light, dark. Stored in localStorage as relay_color_mode.

Unchanged since v1.8.1 (src/components/) except:

Unchanged since v1.8.1.

Development

cd C:\Users\garre\OneDrive\HTC_App\relay-timer
npm run dev          # Phone dev server — http://localhost:5173
npm run dev:ipad     # iPad dev server  — http://localhost:5174

Production Build

npm run build        # → dist/phone/
npm run build:ipad   # → dist/ipad/
npm run build:all    # both — used by /deployHTC before every deploy

Deploy

/deployHTC skill: (1) verifies version consistency across src/VERSION.js and CLAUDE.md, (2) commits all changes, (3) pushes to GitHub, (4) Cloudflare Pages auto-deploys both htc-app (phone) and htc-app-ipad (iPad) from the same push.

Tests

node src/utils/forecastEngine.js   # 81 assertions

test/GpxTrackerTestHarness.jsx has T1–T10 covering parse, haversine, snap, pace (shared logic, platform-agnostic).

Unchanged since v1.8.1 — Settings → Developer Tools, both platforms.

All defined in src/hooks/useRaceState.js with useCallback:

Shared (src/ — never platform-specific)

Phone (src/phone/)

iPad (src/ipad/)

iPad has no HomeScreen.jsx or LiveMapScreen.jsx — both imported directly from @phone.