HI-Fi: driver assist and summary page

[hir-al-14]

Summary

• Adds the high-fidelity driver_assist PWA flow for importing route JSON, completing/reporting stops, finishing a route, and exporting a route summary JSON.

Motivation

• Drivers need a browser-based mobile workflow that matches the existing delivery flow while preserving route progress locally and producing a usable end-of-route summary for dispatch or review.

Changes

• Frontend:

  • Connected /upload-route to the driver assist route import flow so uploaded JSON is transformed into driver route state instead of looping back to upload.
  • Updated /driver_assist with the mobile-first stop workflow: route summary, remaining/delivered/reported sections, expandable stop cards, notes, delivered status, issue reporting, and navigation.
  • Added local progress persistence so driver notes, completed stops, and reported failures survive refreshes.
  • Added /driver_assist/summary with total/complete/remaining counts, per-stop completion badges, b2 footer branding, and sticky route summary export.
  • Connected route summary export to the shared JSON download helper.
  • Split driver assist UI into focused component, style, storage, summary, import, transform, and export helper files.
  • Added practical comments across the driver assist route, summary, storage, import, transform, and export code paths.
  • Ran Prettier across changed app/ui files and kept the actual content diff focused to the driver assist files.

• Backend:

  • No backend changes in this driver assist UI work.

• Mobile:

  • No native app/mobile changes in this driver assist UI work.

Validation

Frontend

• npm --prefix app/ui run lint
• npm --prefix app/ui run format:check
• npm --prefix app/ui run typecheck
• npm --prefix app/ui run test
• npm --prefix app/ui run build
• npm --prefix app/mobile run lint
• npm --prefix app/mobile run typecheck

Backend

• cmake --preset dev
• .github/scripts/check-backend-static.sh build/dev
• cmake --build --preset dev --parallel
• ctest --preset dev --output-on-failure --no-tests=error -LE 'e2e|docker'
• docker compose -f deploy/compose/docker-compose.arm64.yml --env-file deploy/env/http-server.arm64.env config

Risk

• Main risk is browser storage state: stale or invalid saved driver route JSON could send a driver back to upload, but invalid local data is cleared and invalid uploads show user-facing errors.
• Route summary export depends on the browser download path, so download behavior may vary slightly by browser/PWA install mode.

Rollout and Recovery

• Roll out by merging the PWA UI changes and having drivers open /driver_assist or install the PWA from the browser.
• Recovery is to revert this PR; existing route-manager JSON save files and native mobile app behavior remain separate.

High-Signal PR Checklist

• The summary states the user-visible or operational outcome, not just file names.
• The motivation explains why this change is needed now.
• The change list separates frontend, backend, infrastructure, and documentation work where applicable.
• Validation includes exact commands run, relevant output, and any checks intentionally skipped.
• Risks, migrations, feature flags, and rollback steps are called out when relevant.
• Screenshots or request/response examples are included for UI and API behavior changes.

Screenshots for driver assist

[markboenigk]

Great work on the driver assist flow — the library boundary in lib/driver-route/, the Zod validation, and the localStorage resilience are all solid. A few things to fix before merge:

Bugs

• CSV is accepted but not handled. upload-route/page.tsx validates .json and .csv extensions and the dropzone copy says "Drag and drop .json or .csv files here", but driver_assist/page.tsx calls loadSessionFromText() which only understands JSON. A driver uploading a CSV will leave the upload page and then hit "This file is not valid JSON." Either remove CSV from the accepted types, or add a CSV parse path.

• Warning button in summary is a dead stub. driver_assist/summary/page.tsx renders a <button aria-label="View remaining deliveries"> with no onClick. Wire it up or remove it.

• export const dynamic = "force-dynamic" is misplaced and ineffective. In upload-route/page.tsx it appears after "use client" and the imports, which is the wrong order for Next.js to pick it up. It also has no effect in a client component — route segment config only applies to server components. Remove it.

Minor

• The setTimeout(0) in driver_assist/summary/page.tsx is unnecessary. persistRoute is a synchronous localStorage.setItem, so the write is already committed before router.push fires. Replace with a direct call.

• upload-route/page.tsx injects styles via a raw inline <style> string while every other driver_assist/ file uses CSSProperties objects from styles.ts. Ideally this is consistent — or at least call out the intentional split.

[hir-al-14]

Rebased this branch on top of fix-driver-route-export-import branch which is PR #213, so it includes the latest Driver Assist upload fixes first.
Then added the review fixes: CSV route uploads now work, the dead summary warning button was removed, and the unnecessary summary setTimeout(0) was replaced with a cleaner route load.

[markboenigk]

Thanks for addressing all the feedback — CSV handling, the dead warning button, the dynamic export, and the style comment are all good.

Two things to fix before merge:

CSV lat/lng accepts empty columns as 0,0
In routeUploadValidation.ts, Number("") === 0 which passes Number.isFinite, so a CSV row with a missing lat or lng column silently places the stop at coordinates 0,0 instead of rejecting the file. The existing check needs a non-empty guard before converting:

```ts
const latStr = value(["lat", "latitude"]);
const lngStr = value(["lng", "lon", "long", "longitude"]);
if (!latStr || !lngStr || !Number.isFinite(Number(latStr)) || !Number.isFinite(Number(lngStr))) {
throw new Error("CSV route stops must include valid lat and lng columns.");
}
```

queueMicrotask in summary/page.tsx still defers unnecessarily
The setTimeout(0) was there to wait for a localStorage write — but persistRoute is a synchronous setItem, so by the time router.push fires the write is already committed. The queueMicrotask still defers setRoute/setHasCheckedRoute, which means if savedRoute is null, router.replace fires synchronously while the state updates are still pending — so the component can briefly re-render with hasCheckedRoute=true and route=null before navigation finishes. A plain direct call is safe here:

```ts
const savedRoute = readSavedRoute();
setRoute(savedRoute);
setHasCheckedRoute(true);
if (!savedRoute) {
router.replace("/upload-route");
}
```