TBT / JourneyHelper — Knockout → Angular Transition & Development Plan

Status: Fable 5 draft, tightened by Opus (final v1). Deltas from the draft are in “Opus tightening notes” immediately below; the frozen original is at transition-plan-draft-fable-v1.md. Inputs (source of truth): docs/ideas.md (feature backlog + [DECISION]s), docs/org-angular-standards.md (org patterns), review/style-and-architecture-themes.md (code DNA, risks R1–R10, constants inventory, custom.js triage), and current/ (Knockout code). Overriding value: simplicity — reusable components/services, minimal boilerplate, a well-written happy medium. No gold-plating.

Opus tightening notes (what changed from the draft)

The Fable 5 draft is strong and adopted almost wholesale. Five substantive tightenings:

1. Web Worker demoted to a measured contingency, not the default (§4.4). The draft (and ideas.md §4) justified the worker with “241k-point Turf scans” — but 241k is the whole-feed shape total (a sync/enrichment concern), not a per-fix cost. Per-fix nearestPointOnLine / lineSliceAlong run over a single route’s shape (hundreds–low-thousands of points) at ~1 Hz, comfortably a main-thread workload. Plan now: port the engine as pure functions on the main thread first; add the worker only if a real tablet measurement demands it (criteria in §4.4). This removes upfront worker-protocol boilerplate from Phase 1. → reaffirm as Q10.
2. Added an explicit parity checklist (§9.a) — cutover safety hinges on it, so it’s enumerated, not implied.
3. Phase 3 sliced into vertical, PR-sized deliverables (§10) rather than one monolithic UI phase.
4. Surfaced two ordering decisions for you (§11 Q10–Q11): the worker default above, and whether to pull nav-pill clamping (F6) forward into the Immediate horizon — it directly fixes the “looks like the wrong side of the road” complaint and is nearly free (reuses the proximity the engine already computes).
5. Minor: corrected the per-fix cost framing wherever “241k” appeared; everything else stands.

All ideas.md [DECISION]s are honoured; no hard constraint is violated.

1. Executive summary & goals

TBT (“JourneyHelper”) is an offline-capable, in-vehicle, landscape-tablet PWA giving bus drivers turn-by-turn guidance over pre-authorised route lines. Its special sauce is chainage / linear-referencing routing: GPS is projected onto the route shape; going off-route deliberately does not auto-reroute — the driver radios the OCC. We are rewriting the Knockout.js app in Angular to org standards, and using the rewrite to (a) pay down real defects (offline that doesn’t actually work, data-loss risks, leaks, hardcoded secrets) and (b) lay foundations the backlog needs (the position pipeline, config service, telemetry client, ScheduleSource).

Goals, in priority order:

1. Behavioural parity of the special sauce — chainage advance, forward-only look-ahead, off-route detection/halt, next-stop/next-turn selection — proven by golden regression tests written before the port.
2. A genuinely working offline PWA — today the service worker caches nothing (R3); Angular’s service worker delivers real offline for the first time. This is an upgrade, not a carry-over.
3. Org-standard Angular — components, Router + guards, Reactive Forms where forms exist, HttpClient (when the API arrives), RxJS, BehaviorSubject services for shared state, Angular Material — deviating only where simplicity dictates, with the deviation documented (§2.3).
4. Foundations for the backlog — the position pipeline, config service, Web Worker geo engine, telemetry outbox, and ScheduleSource interface are designed once so the Immediate/ Medium/Long features snap on as stages/implementations rather than rework.
5. Massive net simplification — delete ~1,200 lines of dead theme boilerplate (custom.js), the homegrown listener system, the runtime template loader, and the webpack setup.

Non-goals: pixel parity with the sticky-ui theme; NgRx or any state library; the /telemetry backend; custom indoor positioning; keeping Knockout alive in any hybrid form.

2. Guiding constraints

2.1 Principles (from ideas.md §0 — restated as tests we apply to every task)

• Simplicity first. If a task’s design section is longer than its implementation, cut the design.
• Preserve the special sauce — chainage routing + off-route → radio-the-OCC hand-off, unchanged in behaviour. Golden tests are the enforcement mechanism.
• Offline-first — the app must work with no connectivity (app shell + on-device GTFS).
• Non-distractive by design — driver UI informs, never pressures or alarms; nothing that would concern passengers (gentle colours, subtle audio, speed-gated interactions/panels).
• Design foundations for where we’re going (ideas.md §4), but build only what the current horizon needs.

2.2 Hard constraints (must-not-break)

• Offline PWA + installable.
• Chainage routing + off-route hand-off behaviour (no auto-reroute — ever, including in the long-term OCC-detour feature, where the OCC supplies the corridor).
• Landscape / in-vehicle tablet target.
• Runs from bundled/synced GTFS data (evolving: shifts moves to API; core GTFS stays on-device).
• Static-file deployable (evolving: optional API/telemetry endpoints; app still runs offline).
• Fixed thresholds live in the config service, not the UI: on-time panel trigger 2 km/h, interaction lock 10 km/h, off-route 50 m.
• Existing operational behaviours to carry over: screen wake-lock, GTFS version check → prompt → sync, RAIL mode (prefix-filtered route selection), the GPS-test/demo tooling (as the synthetic position source).

2.3 Org standards — adoption map and documented deviations

2.4 Engineering baseline

• Angular: latest stable at kickoff (v20+), standalone components (no NgModules), strict TypeScript, new control flow (@if/@for/@switch), Angular CLI (esbuild) — webpack is dropped.
• Zoneless: stay on zone.js for the parity build (one less variable); revisit zoneless after cutover — the architecture (signals + OnPush + imperative map) is already compatible.
• Testing: Vitest for unit/golden tests; Playwright for a thin e2e smoke (see §9).
• Lint/format: angular-eslint + Prettier, CI on every PR.
• Naming: camelCase app code; snake_case retained for GTFS field names only (they mirror the DB schema — the review’s verdict). Fix carried misspellings (accordian_clicked → onActivitySelected, activites/ → activities/).
• Repo layout: new code in tbt/next/ (working name) alongside tbt/current/; single Angular CLI workspace, no Nx (one app, no monorepo need).

3. Recommended migration strategy + rollback

3.1 Recommendation: greenfield port behind golden tests, feature-by-feature to parity, then hard cutover

Knockout and Angular cannot cleanly coexist in one page (both want to own the DOM/binding; a hybrid bridge would be pure throwaway plumbing in an app this size — ~3,900 lines of templates+VMs total). The app is small enough, and its core valuable enough, that the right shape is:

1. Scaffold a fresh Angular workspace (next/) with the engineering baseline above. Nothing from current/ is imported wholesale; libraries carry over as npm deps (MapLibre GL, Turf, Dexie, PapaParse).
2. Lock the special sauce first: build the golden-trace harness against the legacy JS engine, record fixtures, then port the chainage core to pure TypeScript until the goldens pass (§5). No UI work on navigation until this gate is green.
3. Port the headless core next (position pipeline, data layer, config) — it’s already framework-agnostic and ports near-1:1 into @Injectables.
4. Rebuild the UI feature-by-feature to parity in the new app (shell → map → sign-on/shift → navigation → admin/diagnostics), verifying each against the running legacy app side-by-side.
5. Hard cutover once the parity checklist (§10, M4) passes on a real tablet: the new build replaces the old at the production URL.

Why not strangler-fig / incremental in-page? The interop bridge (Knockout observables ↔︎ Angular inputs, two binding roots, double-loaded vendor bundles) would cost more than the entire UI port, be shipped to drivers as transitional risk, and then be deleted. Greenfield-with-golden-tests gives the same safety (behavioural lock on the part that matters) without the throwaway layer.

Why not big-bang without parity staging? The feature-by-feature parity sequence is the protection: each slice is verified against the live legacy app, and the legacy app remains the production system until the final gate.

3.2 Execution model

• Sonnet executes mechanical, well-specified ports (components, templates → Material, Dexie method carry-over, constants extraction). Tasks below marked [S].
• Opus/Fable executes the routing engine port, position pipeline, worker protocol, atomic sync, and anything touching golden-test behaviour. Marked [O].
• Human review on every PR; golden tests + lint + build are CI gates.

3.3 Rollback stance

• During transition: zero risk — legacy app stays untouched in production; the new app deploys to a staging URL (e.g. tbt-next.apps.sandytulloch.com) for tablet testing.
• At cutover: keep the legacy build deployed at a fallback URL for one full release cycle. Rollback = repoint the production URL. Because both apps are static-file deployable, this is a file swap.
• Data compatibility: the Angular app opens the same Dexie DB (tbt) at the same schema version (2), adding only additive versions (§4.5) — so a rollback finds its data intact. The GTFS payload is re-syncable by design, so even a worst-case wipe self-heals via the existing empty-DB detection → sync flow (kept in the new app). localStorage keys (JourneyHelper-gtfs-version, JourneyHelper-device-token) are reused unchanged.
• Service-worker rollback caveat: after cutover the Angular SW controls clients. Rollback requires the fallback deployment to include an SW-deregistering stub (or ngsw “safety worker”) at the same SW URL so old clients release cleanly. This is a one-file task — do it as part of the cutover checklist, not as an afterthought.

4. Target architecture

4.1 App shell, structure & routing

src/app/
  core/                        # singleton services, no components
    config/    config.service.ts, app-config.ts (typed defaults + constants inventory)
    position/  position.service.ts, sources/{geolocation,synthetic}.source.ts,
               stages/{accuracy-filter,bearing,interpolate,clamp}.ts, position.types.ts
    routing/   routing.service.ts            # Angular wrapper (thin)
    data/      db.service.ts (Dexie), gtfs-sync.service.ts,
               schedule/{schedule-source.ts, static-file.source.ts, api.source.ts(later)}
    map/       map.service.ts                # imperative MapLibre wrapper
    telemetry/ telemetry.service.ts, outbox.ts
    shell/     back-action.service.ts, theme.service.ts, connectivity.service.ts,
               interaction-lock.service.ts (Immediate horizon)
    error/     app-error-handler.ts, error-log.service.ts
  domain/                      # PURE TypeScript — no Angular imports (worker + test shared)
    chainage/  chainage-engine.ts, poi.ts, distance-format.ts
    geo.worker.ts              # worker entry wrapping the engine
  features/
    map/           map.component.ts (hosts the GL container + nav overlays)
    navigation/    nav-panel/, next-direction/, poi-list/, on-time-panel/ (Phase 5)
    sign-on/       pinpad/, shift-panel/, activity-list/, route-selection/
    admin/         admin-menu/, gtfs-sync-dialog/
    diagnostics/   diagnostic-panel/, error-log-dialog/, gps-test/
    shell/         app-shell.component.ts, header-bar/, settings-menu/, connectivity-banner/
  app.config.ts                # composition root (providers) — replaces app.js wiring
  app.routes.ts

• Routes: '' → AppShellComponent (map + panels); gps-test and diagnostics as lazy-loaded routes (they’re dev/ops tools — routing them keeps them out of the main bundle via loadComponent). An enrollmentGuard on the root only if Q2 resolves to “keep enrollment”.
• Back handling: BackActionService — a small stack service (push(action), pop()), the Angular-shaped version of the current appVM.back_actions. The header back button and the hardware/browser back (via a popstate hook) both drain it. Concept kept, appVM smell removed.
• Panels over routes: shift panel, route selection, on-time panel, settings are shell state (BehaviorSubject/signals in small services), rendered with @if/Material sidenav/bottom-sheet.

4.2 State management (where BehaviorSubject vs signals)

Rule of thumb: shared, written-by-services state → BehaviorSubject in an injectable (org standard); component-local and derived view state → signals; bridge with toSignal() at the component boundary. No NgRx, no component-to-component subjects.

Knockout → Angular mapping is mechanical: ko.observable → BehaviorSubject (shared) or signal (local); ko.computed → computed() or RxJS map/combineLatest; subscribe → toSignal/effect/async-free takeUntilDestroyed() subscriptions. valueHasMutated pokes disappear — immutable updates only.

4.3 The Position Pipeline (foundation ⭐ — unifies smoothing, clamping, depot, gps-test)

One explicit, ordered pipeline. Sources are swappable; stages are pure and individually testable; there are two outputs because honesty matters here:

                ┌──────────────────────── sources (one active) ───────────────────────┐
                │ GeolocationSource (watchPosition, high-accuracy)                     │
                │ SyntheticSource   (gps-test tool, demo mode, golden-test replay)     │
                └──────────────────────────────┬───────────────────────────────────────┘
                                        RawFix │
   stage 1  accuracyFilter   — reject Δdist/accuracy < 0.2 (config)                    
   stage 2  history+derive   — ring buffer (10, config); derive bearing, speed (m/s)   
                                               │
                             ══ truePosition$ ══╪══► RoutingService (worker), telemetry,
                                               │      diagnostics, geofences (depot, later)
   stage 3  interpolate      — dead-reckoning along route line between fixes (Phase 6; 
            (worker tick)      identity pass-through until then)                       
   stage 4  clampToRoute     — snap to route line **only when navigating AND on-route**;
                               release to true position when isOffRoute (Phase 6;      
                               identity until then)                                    
                                               │
                             ══ displayPosition$ ═══► MapService (nav disc), UI         

Interfaces (the contract to build against):

interface RawFix {
  timestamp: number; latitude: number; longitude: number;
  accuracy?: number; altitude?: number; heading?: number; speed?: number;
  source: 'gps' | 'synthetic';
}
interface Position extends RawFix {
  bearing: number | null;       // derived from history
  speedKmh: number;             // derived (GPS speed preferred, delta fallback)
  clamped: boolean;             // true only on displayPosition$ when snapped
}
interface PositionSource {
  readonly fixes$: Observable<RawFix>;
  readonly errors$: Observable<GeolocationPositionError>;
  start(): void; stop(): void;
}

Design points: - Routing always consumes truePosition$ (post-filter, pre-clamp). Clamping is presentation only ([DECISION]) and consumes RoutingState.isOffRoute — no cycle, because clamp output never feeds routing. - The legacy override() becomes PositionService.setSource(source) — the gps-test tool, demo mode, and golden-trace replay are all just SyntheticSource instances. The map-click override (mouse only) is kept as a dev affordance behind a feature flag. - The fixed 500 ms re-broadcast interval is dropped: emit on new fix now; the Phase 6 interpolator re-introduces a tick (in the worker) as the smoothing mechanism, which is what the interval was groping toward. - Depot mode is not a source — it’s an app mode triggered by a geofence detector on truePosition$ (Long horizon). The pipeline needs no change for it; that’s the point. - speedKmh on Position is what the on-time trigger (2 km/h) and interaction lock (10 km/h) consume — both become trivial map+debounce observers of the pipeline. - Fixes R8: sources/stages live in a PositionService with RxJS teardown; consumers use takeUntilDestroyed(); stop() cancels the watch. No listener arrays, no orphan intervals.

4.4 Routing engine placement (main thread; Web Worker as contingency)

• domain/chainage/ is pure TS, zero Angular imports — shared verbatim by the golden tests, the main thread, and (if built) the worker.
• Default = main thread. Per-fix nearestPointOnLine / lineSliceAlong run over the selected route’s shape (hundreds–low-thousands of points), not the 241k whole-feed total (that figure is a sync/enrichment cost, not a per-fix one). At ~1 Hz this is comfortably a main-thread workload. RoutingService feeds truePosition$ into the pure engine and exposes routingState$ (BehaviorSubject) — findProximity + findChainage (forward lineSliceAlong window) + POI-list advance → one RoutingState per fix.
• Worker is a measured contingency (task D7). Build geo.worker.ts only if the Phase 3 perf checkpoint shows p95 per-fix cost > ~16 ms (one frame) on the real tablet, or the F5 interpolation tick measurably janks. RoutingService is written so relocating the engine into a worker later is an internal change (same pure functions, same routingState$ contract, structured-clone the shape once on activity change). If built: a typed postMessage protocol (SetActivity, PositionInput, Reset → RoutingState) — no Comlink for three message types. Reaffirm as Q10.

4.5 Data layer

• DbService — the Dexie wrapper. Same DB name tbt; version chain:

  • version(2) — current schema verbatim (compound indices preserved: [trip_id+stop_id], [trip_id+stop_sequence], [shape_id+poi_sequence], [activity_id+shift_id]). This is the baseline so existing installs open cleanly (R1).
  • version(3) — additive: telemetry_outbox (&eventId,timestamp,eventType), error_log (++id,timestamp), meta (&key). No upgrade() needed for additive tables, but the version bump is written explicitly and an upgrade test (open a seeded v2 DB, assert GTFS rows survive) goes in CI. Any future schema change must ship an upgrade() + test — policy, not hope.

• Read API — port DataManager’s methods near-verbatim (they’re good): getEnrichedShapes (batch-then-join, now memoized per DB generation — invalidated on sync), getShiftActivities, getTrip/Route/Stop/StopTimes/Shape/Pois. Drop getShapesByPrefix (R10, dead/broken) — the RAIL prefix filter stays an in-memory filter over enriched shapes, as today. Fix R9 (N+1 in single-route-selection) by reusing getEnrichedShapes.

• GtfsSyncService — atomic sync (R2):

  1. Fetch + parse everything first (shapes.geojson + 6 CSVs via PapaParse, keeping the typeExceptions coercion map — today’s only validation layer), into memory. No DB writes yet.
  2. One Dexie rw transaction across all tables: clear + chunked bulkPut (1000 rows, config) + write meta.gtfs_version last, inside the transaction.
  3. Only after commit: update the in-memory caches and emit a dataGeneration$ tick — no location.reload(); consumers re-query reactively (review’s verdict).
  • Failure anywhere → transaction aborts → previous dataset fully intact; the progress dialog (Material) reports the error instead of silently closing.
  • Version check (version.txt + localStorage, cache-busted, SW-bypassed) and its trigger points (app init, sign-on) carry over as-is; keep confirm-before-destructive Material dialog.

• ScheduleSource (ideas.md [DECISION]) — the seam for GTFS-serving evolution:

  interface ScheduleSource {
    getActivities(id: string): Promise<Activity[]>;   // shiftID now; driverID later
  }

  • StaticFileSource (now): reads the synced shifts table — pure carry-over.
  • ApiSource (Medium): HttpClient + JWT against config.base_url, cache-then-network — persist the last-known allocation in Dexie so offline sign-on always works (must-not-break).
  • Selected by config/feature-flag; the sign-on flow only ever sees the interface.

4.6 Config service

• ConfigService: typed defaults compiled in (app-config.ts), overlaid by an optional assets/config.json fetched at APP_INITIALIZER (deploy-time editable without rebuild — preserves static-file deployability), overlaid by an optional remote config URL later (Medium, same shape). Missing/failed fetch → defaults; never block startup on config (offline-first).

• Seed inventory (from the review, all with these defaults):

  Key	Default	Notes
  routing.offRouteThresholdM	50	not UI-editable
  routing.lookAheadWindowM	50	forward chainage search window
  position.accuracyGateRatio	0.2	noise filter
  position.historySize	10	ring buffer
  position.interpolationTickMs	500	Phase 6 (replaces broadcast interval)
  ui.onTimeTriggerKmh / .onTimeDebounceMs	2 / 2000	Immediate
  ui.interactionLockKmh	10	Immediate
  ui.distanceRoundingTiers	5 m / 50 m / 0.1 km	display rounding
  ui.errorLogMax	100
  ui.gpsNotStartedTimeoutMs	2000	diagnostics
  map.defaultCenter	−27.528, 153.197	Brisbane
  map.themeStyles.{light,dark}	MapTiler UUIDs
  map.turnHighlight	0.05 km slice / 0.003 km buffer
  map.maptilerKey	out of source → config.json	R4: rotate + referrer-restrict
  gtfs.baseUrl	./gtfs_data/	becomes remote base_url (Medium)
  gtfs.syncChunkSize	1000
  api.baseUrl, telemetry.endpoint, telemetry.flushIntervalMs	unset / off	Medium
  flags.*	see §4.10

• Honesty note on keys: a static PWA cannot truly hide a key; the mitigation is rotation + MapTiler referrer/origin restriction (task in Phase 0) and keeping it out of the repo. The Google key (R5) dies with custom.js; rotate it anyway. Admin PIN (R6) → §11.

4.7 Map (imperative MapLibre service)

• MapService owns the maplibregl.Map instance and all GL objects (nav disc marker, POI marker, route_line layer, upcoming-turn extrusion). Angular owns the chrome; nothing binds into the canvas ([DECISION]).
• MapComponent provides the container div (ngAfterViewInit → mapService.attach(el)) and hosts the HTML overlays (next-direction banner, POI list) as ordinary components.
• Inputs to the service are observables/signals it subscribes to internally: displayPosition$ (disc + camera), routingState$ (next-stop marker, turn highlight), theme$ (style swap), and a padding signal — the jQuery $('#shift-panel-container').width() measurements become a small MapPaddingDirective using ResizeObserver on the panels (review: never DOM in services… except this service, whose whole job is the GL DOM).
• Carry over: plan view vs navigating view (pitch 60 / zoom 18 / line-width 20), fit-to-bounds, turn-highlight slice+buffer (constants from config). The turn-highlight turf.buffer over a 100 m slice is cheap — main thread is fine; only whole-shape scans go to the worker.

4.8 Service worker / offline (a real feature this time — R3)

• ng add @angular/pwa; ngsw-config.json:
  • App shell + assets: prefetch (installs the whole UI for offline).
  • assets/config.json: freshness, short timeout, cached fallback.
  • gtfs_data/** + version.txt: bypass/network-only — GTFS lives in IndexedDB via explicit sync; letting the SW cache 100 MB of CSVs would be double storage. Version checks must see the network truth (they already no-op gracefully offline).
  • Map tile/style requests (api.maptiler.com): network-only. Known caveat: map imagery is not available offline; navigation data (route line, POIs, chainage, guidance) is. This matches today’s reality; offline tile packs are a possible Long-horizon item, explicitly not now.
• App-update flow: SwUpdate → non-distractive “update available” affordance (apply on next idle at 0 km/h or on restart — never mid-drive).
• Verification is part of the deliverable: an e2e/manual gate that cold-starts the installed app in airplane mode through sign-on → activity select → simulated navigation (§9).

4.9 Telemetry client (Medium horizon; interface defined now)

• TelemetryService.emit(eventType, payload) — fire-and-forget, synchronous enqueue, never throws to callers (must never block/crash driver UX).
• Durable outbox: telemetry_outbox Dexie table (survives restarts/offline). Envelope per [DECISION]: { deviceID, timestamp, eventId (UUID), eventType, schemaVersion } + payload (ad-hoc payload, fixed envelope). deviceID from JourneyHelper-device-token or a generated persisted UUID (ties to Q2 enrollment).
• Flush strategy (hybrid [DECISION]): periodic batch fetch (config interval) + immediate flush on key events (start/end run, sign-on/off) + navigator.sendBeacon on pagehide/visibilitychange. Delete rows only on 2xx; retry with capped exponential backoff; at-least-once with server-side dedupe on eventId ([DECISION]). Sampling knob for high-frequency UI events (config).
• Event taxonomy (suggested [DECISION] list): auth, run-lifecycle, navigation (incl. off-route enter/exit), stop-dwell, ui, service-performance, error.
• Emission points are one-liners in existing services (ShiftService, RoutingService observers) — not a cross-cutting aspect framework. Backend out of scope (§12).

4.10 Feature flags

• No library. config.flags: Record<string, boolean> in ConfigService (defaults compiled in, overridable via config.json / remote config), read via config.flag('onTimePanel').
• Initial flags: onTimePanel, audioCallouts, offRouteAudio, interactionLock, positionSmoothing, navClamping, telemetry, scheduleApi, mapClickOverride (dev), gpsTest (dev). Each horizon feature ships dark behind its flag; flags removed once bedded in (flags are for rollout, not permanent config — anti-gold-plating rule).

4.11 Error handling

• Custom ErrorHandler (+ the unhandledrejection listener Angular’s handler misses) → ErrorLogService: persisted ring buffer in Dexie (error_log, max 100 from config) — the current in-memory log dies on the crash-reload it exists to explain; persistence fixes that.
• Error-log dialog keeps today’s features: list, clear, export-to-JSON, simulate-error test hooks (dev flag).
• When telemetry lands, errors also enqueue as eventType: 'error' — one pipeline, two sinks.
• GPS permission-denied UX (Swal today) → Material dialog from a PositionService.errors$ subscriber in the shell.

5. Domain port + golden regression tests (sequenced FIRST)

The gate: no navigation UI work starts until these pass. This is the enforcement mechanism for “preserve the special sauce”.

5.1 What the engine is (extraction boundary)

From routing-view-model.js + location-manager.js, the pure functions:

• findProximity(shape, point) — nearest-point distance in metres (off-route input).
• findChainage(shape, point, currentChainage, lookAheadM) — forward-only window scan: lineSliceAlong(current, current+50 m) when navigating, whole-line otherwise; per-segment nearestPointOnLine with local→global chainage conversion. Port bug-for-bug — including the from-zero full-line search when currentChainage === 0 and the behaviour that chainage halts (does not regress or advance) while off-route (update_chainage gates on !isOffRoute).
• isOffRoute(proximity, thresholdM, navigating) — navigating && proximity > 50.
• POI pipeline: buildPoiList(pois) (icon mapping, cumulative→incremental chainage, display strings) and advancePois(pois, chainage) (filter chainage_meters >= chainage; nextDirection = head; nextStop = first Stop; nextTurn = first Turn; upcoming = slice(1,5)).
• formatDistance(m) — the 5 m / 50 m / 0.1 km rounding tiers (drivers see these strings; lock them).
• Position stages: accuracyGate(prev, fix, ratio) and deriveBearing(history) from LocationManager.

5.2 Golden test harness — [O]

1. Fixture format: JSONL traces of RawFix + a shape GeoJSON + POI CSV per scenario; goldens are JSONL of per-fix RoutingState (chainage to 0.1 m, proximity, isOffRoute, nextStop id, nextTurn id, formatted distance string).
2. Record goldens from the legacy engine: run the legacy JS (it’s module.exports-clean; stub ko.observable with a 10-line shim, import the same Turf version) in Node over each trace. Human spot-checks each golden once (the legacy engine is the spec, but eyes on the output catches “faithfully ported a typo that matters”).
3. Scenario set (minimum):
   • Clean end-to-end run on a long real shape (generated via the demo-mode turf.along walker — it already exists as a synthetic driver).
   • Off-route excursion and return — the crown jewels: assert chainage halts during the excursion, isOffRoute transitions exactly where the legacy does, and recovery re-acquires without jumping backwards.
   • Self-overlapping / out-and-back shape (the look-ahead window’s reason to exist — e.g. a loop route or the same road driven both directions): assert no chainage snap-back.
   • GPS noise / jitter trace (exercises the accuracy gate) and a stationary-drift trace.
   • Start-of-route acquisition (chainage 0 full-line search) and end-of-route runoff.
   • U-turn POI and dense-stop sequences (nextStop/nextTurn ordering).
   • At least 2 real recorded drives (export via the current gps-test tool — Phase 0 task; if hardware capture slips, synthetic traces gate the port and real traces are added before cutover).
4. Port domain/chainage/ in TS; run the same traces; diff against goldens with tight tolerances (float noise only). CI-gated forever — these tests also protect the Phase 6 interpolation work and any future OCC-corridor loading (same engine, new shape input).
5. Property adds (cheap, high value): chainage is monotonically non-decreasing while on-route and navigating; 0 ≤ chainage ≤ totalLength; POI list is always a suffix of the original.

5.3 Tasks

6. UI component inventory (Knockout → Angular Material)

Deleted, not ported: ~81% of custom.js (sliders, share, OTP, ads, Swup, …), runtime import_templates(), vendor.js window-globals (→ ES imports), webpack config + cache-busting plugin, Bootstrap/sticky-ui CSS, ObjectViewModel, getShapesByPrefix (R10), the 15 highlight_*.css theme files (pending the custom.js CSS-injection check flagged by the review).

7. Feature roadmap by horizon

Every feature: flag-gated, config-driven thresholds, honours the [DECISION]s verbatim.

7.1 Immediate (next release after parity)

F1. On-time running info — onTimePanel - Tasks: (a) speedKmh observer: < 2 km/h sustained ~2 s (debounced) and at/near a stop → open left panel; auto-collapse on movement; driver-dismissable [O-design, S-build]; (b) schedule model: scheduled arrival per stop from stop_times vs shift start; “should-be” position = interpolate scheduled position at now [O]; (c) OnTimePanelComponent: full stop list, mm:ss ahead/behind, timepoints visually distinct, current-position marker + a should-be horizontal-rule marker in the list (not a map object) [S]; (d) gentle colour tokens only (no red/flash) [S]. - Depends: pipeline speed (Phase 1), shift schedule data. Only for shift-planned services — never in manual/RAIL route mode (gate on ShiftService.isPlannedShift). - Must-not-break: non-distractive rule; offline. Open: Q4 (timepoint field in data).

F2. Audible next-stop / turn callouts — audioCallouts - AudioGuidanceService (speechSynthesis): announce on next-stop/next-turn change + distance-band re-announcements; reuse formatDistance → spokenDistance. Settings toggle (off switchable) per [DECISION]. Serialise utterances; nothing queues up at a stop. [S]

F3. Audible off-route alert — offRouteAudio - Single very subtle cue on isOffRoute rising edge (short soft chime, not speech, quiet, no repeat spam — re-arm only after on-route recovery + hold-down). Pairs with existing visual flag; no behaviour change to routing. [S] Audio asset choice: human sign-off (non-distractive).

F4. Interaction lock while moving — interactionLock - InteractionLockService: speedKmh > 10 (config, not UI-editable) with hysteresis → shell signal; components/CSS disable fiddly targets (route selection, settings, admin, search keyboard); navigation-critical glances stay. Must never trap the driver — dismiss/back and the off-route display always work. [S-build, O-review of what’s locked]

7.2 Medium-term

F5. Animation smoothing — positionSmoothing (pipeline stage 3) - Dead-reckoning along the route line ([DECISION], not map easing): worker tick (~100–250 ms, config) projects forward from last fix using speed/accel along the known shape when navigating & on-route; converge (don’t jump) on each real fix; fall back to raw pass-through off-route or when not navigating. Golden tests must be unaffected (they consume truePosition$); add interpolator-specific tests (convergence, overshoot at stops). [O]

F6. Nav pill / arrow clamping — navClamping (pipeline stage 4) - Snap displayPosition$ to nearest-point-on-line only when navigating and on-route; release to true position when isOffRoute ([DECISION] — never hide reality during an excursion). Reuses the proximity intercept already computed in the worker (zero extra Turf cost). Bearing from line tangent when clamped. [O for stage, S for map hookup] - F5+F6 land together sensibly (both are “presented position” quality; one worker changeset).

F7. Telemetry monitoring (client) — telemetry — build §4.9; instrument: auth/run lifecycle, navigation (incl. off-route enter/exit + duration), stop-dwell (chainage window + <2 km/h dwell timer — shares F1’s stop-proximity logic), UI opens, service-performance. [O service, S emission points] Depends: Q2 (deviceID), Q5 (endpoint).

F8. GTFS serving (shifts → API) — scheduleApi — implement ApiSource (DriverID → activities; HttpClient + JWT interceptor — org standard activates here), base_url from config, cache-then-network with last-known allocation persisted (offline sign-on must-not-break); sign-on flow gains DriverID entry per API contract (Q3). [S once contract known]

7.3 Long-term (directional — design allowances only, no build now)

• F9. Depot Mode: geofence auto-entry on truePosition$ (polygon in config/data) → top-down zoom mode in MapService; spot polygons as a data-driven layer; spot allocation + confirm-spot = first OCC push channel use case. Allowance made: pipeline mode switching + MapService layer API already fit.
• F10. OCC-pushed detour corridor: OCC supplies a sanctioned shape; app loads it into the same chainage engine (SetActivity with a new shape — protocol already supports it). No auto-reroute, ever. Golden harness reused to validate corridor loading.
• F11. OCC service alerts/messages: shared OccChannelService abstraction (transport TBD — Q6); notification UI honouring non-distractive rules.
• Common dependency: the OCC push channel — spike, don’t build, until a backend exists (§12).

8. Risk mitigations (R1–R10 → concrete tasks)

9. Testing & verification strategy

Right-sized: heavy where behaviour is safety-adjacent (engine, data), light where it’s chrome.

1. Golden regression tests (§5) — the centrepiece. CI gate from Phase 1 forever; re-run through the worker path (D7) and after F5/F6.
2. Unit tests (Vitest) — pipeline stages (accuracy gate, bearing, clamp release-on-off-route), GtfsSyncService atomicity (fake-indexeddb: inject failure mid-sync → assert old data intact; R1 upgrade test), ScheduleSource cache-then-network fallback, telemetry outbox (enqueue-offline → flush-online → dedupe-safe retry), ConfigService overlay/fallback, BackActionService, distance/spoken formatting.
3. Component tests — selective: PinpadComponent (validation/async callback), OnTimePanel trigger logic (fake timers), activity list @switch. No snapshot theatre.
4. E2E smoke (Playwright, ~5 flows) — boots the real app with a SyntheticSource seeded via the dev flag: sign-on (valid/invalid) → shift list → select trip → start navigation → drive a canned trace → next-stop updates → off-route flag raises → back-stack unwinds. Plus GTFS sync dialog happy path.
5. Offline/PWA gate — installability audit + scripted SW checks + manual airplane-mode cold-start on the target tablet (in the M4 checklist; this is the R3 payoff and doesn’t get waved through).
6. Performance checkpoints — on real tablet hardware: worker round-trip latency per fix on the biggest shape (budget: < 50 ms p95), map frame rate while navigating, sync duration on the full dataset, memory after an hour of simulated driving (leak check — the R8 regression test in spirit).
7. Parity verification (Phase 3–4) — side-by-side checklist against the legacy app per feature slice (same data, same synthetic drive): a human eyeballs behavioural equivalence; goldens cover the math, this covers the UX.
8. Field pilot before cutover — ≥1 device on real routes for ≥1 week, gps-test trace recording on, error log reviewed. Cheap, and it’s a bus app — reality is the test bench.

9.a Parity checklist (the M3/M4 cutover sign-off)

A feature slice is “at parity” only when, against the same GTFS data and the same synthetic drive, the new app matches the legacy app on:

• Sign-on: valid ShiftID loads the same activities; invalid rejected identically.
• Shift-bat: same activities, order, trip/transfer rendering, timepoints.
• Route/RAIL selection: same shapes found; prefix filter behaves identically.
• Route overview: same stops/POIs/turns drawn; same camera fit.
• Start-navigation gate: enables within 50 m of start, same as legacy.
• Guidance: next-stop, next-turn, upcoming list, and distance strings match the goldens live.
• Off-route: flag raises/clears at the same points; chainage halts; no auto-reroute.
• GTFS sync: version prompt → sync → progress → data refresh (no reload); failure leaves data intact.
• Diagnostics / error log / GPS-test / demo: functionally equivalent.
• Shell: wake-lock, dark mode, settings menu, back-stack, connectivity banner behave as before.
• Offline: installed app cold-starts and drives a synthetic trace in airplane mode (the R3 payoff).

10. Sequenced phased roadmap

Dependencies flow downward; phases 5+ overlap freely once 4 ships. Sizes: S ≤ 1 day, M ≈ 2–4 days, L ≈ 1–2 weeks of focused agent+review time.

Phase 0 — Foundations & guardrails (no app code yet) (S–M total) - Scaffold workspace (next/): Angular latest, standalone, strict, Material, ESLint/Prettier, Vitest, CI (lint+test+build). [S] - Ops: rotate + referrer-restrict MapTiler key (R4); rotate Google key (R5). [human] - Decisions locked: Q1 admin PIN, Q2 enrollment, Q3 API contract sketch, Q4 timepoint data. [human] - D1–D4: golden harness, trace generator, real-trace capture kickoff, goldens recorded. [O] - ✅ M0: CI green on empty app; goldens exist and legacy engine replays them deterministically.

Phase 1 — Domain core & position pipeline (L) - D5–D7: chainage engine port → goldens pass → worker host + RoutingService. [O] - PositionService: sources (geolocation, synthetic), stages 1–2, truePosition$/ displayPosition$ (stages 3–4 identity), teardown-correct (R8). [O] - ConfigService + app-config.ts seeded from §4.6 inventory. [S] - ✅ M1: goldens pass through the full worker path; pipeline unit tests green.

Phase 2 — Data layer (M–L) - DbService (version chain, R1 test), read API port + memoized getEnrichedShapes. [S] - GtfsSyncService atomic sync (R2) + version-check flow + sync dialog. [O sync core, S dialog] - ScheduleSource interface + StaticFileSource. [S] - ✅ M2: full sync of production GTFS data passes atomically; injected mid-sync failure leaves old data intact; sign-on query works offline.

Phase 3 — UI parity build (L; the bulk of [S] work) > Slice into vertical, PR-sized deliverables — one flow per PR (shell → map → sign-on/shift → > navigation wiring → diagnostics), each independently reviewable and parity-checkable. Avoid one > monolithic UI PR. - Shell: AppShell, header, back-action, settings sidenav, theme, connectivity banner, wake lock. [S] - Map: MapService + MapComponent + overlays + padding directive. [O service, S overlays] - Sign-on/shift: Pinpad, shift panel, activity list (@switch union), trip facade, route selection (virtual scroll, R9 fix), RAIL mode. [S] - Navigation loop wired end-to-end: select → overview → start nav → guidance → stop. [O wiring] - Diagnostics, error handler + persisted log + dialog, GPS-test rebuild (+trace export), demo service. [S, gps-test O-assist] - Q1/Q2 outcomes built (admin gate; enrollment or deletion). [S] - ✅ M3 “parity build”: every legacy user flow works in the new app against the same data; side-by-side checklist signed off; perf checkpoints met (worker-deferral decision taken here).

Phase 4 — PWA, hardening, cutover (M) - @angular/pwa + ngsw config + update flow (§4.8); install/offline gates. [S config, O review] - E2E smoke suite; field pilot (≥1 week); bug burn-down. [S + human] - Cutover checklist: staging→prod swap, legacy at fallback URL, SW-release stub in fallback, localStorage/Dexie compatibility verified on an upgraded real device. - ✅ M4 CUTOVER. Rollback = URL repoint (§3.3), available for a full release cycle.

Phase 5 — Immediate horizon (M–L) — F1 on-time panel [O+S], F2 callouts [S], F3 off-route audio [S], F4 interaction lock [S+O review]. Flag-gated; staged to the pilot device first. ✅ M5: Immediate features live; non-distractive review sign-off (human, on a moving vehicle).

Phase 6 — Medium horizon (L) — F5+F6 smoothing & clamping (one worker changeset, goldens untouched) [O]; F7 telemetry client [O+S]; F8 ApiSource when contract lands [S]. ✅ M6: smoothed+clamped nav in field use; outbox proven over real connectivity gaps.

Phase 7 — Long horizon (design-first) — depot geofence spike, OCC channel spike (Q6), corridor-loading proof on the golden harness. Build only with a backend commitment.

11. Open questions / decisions needed

ideas.md currently contains no unresolved [OPEN] tags — all its calls are [DECISION]s (honoured above). The following need answers; Q1–Q4 before Phase 3 ends, and none block Phases 0–2 (except the decisions themselves being Phase 0 tasks):

• Q1 (R6) Admin PIN: what should gate the admin menu? Options: (a) PIN in config.json (out of source; obfuscation-not-security — probably fine, the menu only triggers re-syncs);
  2. server-issued once an API exists; (c) drop the gate. Recommend (a) now, revisit at F8.
• Q2 (R7) Enrollment: is device enrollment (QR → device token) a real requirement or dead scaffolding? Determines: the route guard, the QR-scanner dependency, and telemetry deviceID provenance (enrollment token vs generated UUID). Recommend: decide by intent — if fleet device management is coming, keep + finish it; otherwise delete and use a generated persisted deviceID for telemetry.
• Q3 GTFS/shifts API contract (F8): endpoint shape for DriverID → activities, auth scheme (org-standard JWT — who issues tokens to drivers/devices, and how does a tablet log in?), and how DriverID enters the sign-on UX (replaces or supplements ShiftID pinpad?).
• Q4 Timepoint data (F1): does the stop_times feed carry a timepoint flag (GTFS standard field) or another marker? The on-time panel’s “timepoints distinctively marked” needs it in the data or a rule for deriving it.
• Q5 Telemetry endpoint & policy (F7): endpoint URL/config, retention, sampling rates for UI events, and confirmation that implied-consent posture is signed off by the org (per [DECISION], no in-app consent UI).
• Q6 OCC push transport (F9–F11): WebSocket vs SSE vs polling vs FCM — defer until a backend exists; spike only.
• Q7 Offline map imagery: accept “no tiles offline, nav data still works” (status quo, recommended) or fund an offline tile-pack investigation later? Affects nothing now; flagging so the caveat is a decision, not a surprise.
• Q8 Target tablet baseline: confirm device/OS/WebView floor (affects 100dvh, wake lock, sendBeacon, worker perf budgets) — one-line answer, Phase 0.
• Q9 RAIL mode status: it exists in production behaviour today (prefix-filtered shapes) but isn’t in ideas.md. Assumed in scope for parity (it’s cheap — a filter input on RouteSelection). Confirm it’s still wanted.
• Q10 Routing execution (Opus): reaffirm — start the chainage engine on the main thread; build the Web Worker host only if the Phase 3 perf checkpoint demands it (§4.4). Confirm you’re happy trading the ideas.md §4 “always worker” call for “measure first.”
• Q11 Pull clamping (F6) forward? Nav-pill clamping directly fixes the “wrong side of the road” driver complaint and is nearly free (reuses the engine’s proximity intercept). Option to move it from Medium (Phase 6) into the Immediate horizon (Phase 5); smoothing (F5) stays Medium. Recommend: pull F6 forward, keep F5 in Medium.

12. Explicitly out of scope

• The /telemetry backend (client-side enablement only — per ideas.md §5).
• Custom indoor positioning for depot mode (device high-accuracy mode suffices — [DECISION]).
• OCC backend / push infrastructure (client abstractions + spikes only, Phase 7).
• Auto-rerouting of any kind — permanently out by principle, not by phase.
• Pixel/visual parity with the sticky-ui theme (functional parity only; Material look).
• Knockout/Angular hybrid interop (rejected strategy, §3.1).
• NgRx or other state libraries; Nx/monorepo tooling.
• Offline map tile packs (Q7 — status-quo caveat accepted for now).
• Multi-city/network generalisation beyond the Brisbane network (config service makes the centre/keys movable, but no active work).
• Porting dead code: ~81% of custom.js, getShapesByPrefix, ObjectViewModel, webpack tooling.

Opus tightening applied to Fable 5 draft v1. The draft’s suggested review focus is addressed: (a) Phase 3 sliced into PR-sized vertical deliverables (§10); (b) worker demoted to a measured contingency with an explicit checkpoint (§4.4, Q10); (c) Q1/Q2 recommendations stand (§11); (d) F6 clamping flagged to pull forward into Immediate (§11 Q11). Remaining decisions for Sandy: Q1–Q11 (§11).