Skip to content

Latest commit

 

History

History
106 lines (74 loc) · 27.7 KB

roadmap.md

File metadata and controls

106 lines (74 loc) · 27.7 KB

From the first Android device test to an everyday maps app

Audit: 2026-10-12. Released baseline: 0.1.7 / Android code 8, including active-view transit refresh and strict journey-stop links alongside local saved travel and the broader compact place package. Source/browser review and the signed artifact passed. Development version 0.1.8 / Android code 9 adds explicit native navigation for four modes; integrated Android engine/GPS/voice/service runtime acceptance remains open. Reassess the affected rows after implementation changes. Versioned APK and native evidence belong in delivery.md; installation belongs in android.md.

Version 0.1.2 installed and rendered its bundled main interface with Metro stopped on a Google-free software emulator. An Android system-process ANR blocked healthy interaction checks; the map stayed gray/loading. Native map/clipboard/location acceptance and physical-device runtime remain unverified. The main remaining work is accepting transit and navigation flows on Android and broadening discovery and place details. Expo/NativeWind remains the selected foundation.

Capability matrix

“Implemented” means inspected code plus automated/browser/service evidence exists. The matrix describes the reviewed and inspected 0.1.7 release; development navigation scope follows separately. Read the delivery record before claiming native map rendering, positioning, lifecycle behaviour or battery results.

Capability Current implementation Gap affecting everyday use
Map and basic UX Implemented: native MapLibre/OpenFreeMap, Italian search and categories, map/list, place sheets, Android back handling, selected markers. Main UI rendered in the 0.1.2 emulator check. Healthy native map interaction remains unverified after a system-process ANR. Portrait/light mode only; gestures, text scaling and keyboard behaviour require Android device checks.
Places and search Released in 0.1.5: 23,274 compact bundled records from a wider food/shop rectangle plus compatibility supplements, with shared taxonomy membership and full contributor details materialized only for selected result groups. Italian aliases, indexed name/address matching and bounded one-edit name matching retain exact/prefix priority. Category queries use a 5 km radius; names search the whole package. Manifest bounds, a map outline and capped-result labels expose limited coverage. Photon supplements names/addresses when enabled. The extract is not complete or field verified. No natural-language query engine, representative venue/duplicate accuracy benchmark or in-app data refresh. Numeric tokens stay exact; fuzzy matching is deliberately bounded. Different names can still describe duplicate records; preserve distinct branches/tenants. Desktop timing does not establish native startup, typing latency or memory.
Useful business details Partial: name/category/address, available website/telephone, source/date/licences, saved places. Preparation excludes explicit permanent closures. Released 0.1.5 adds an evidence-backed locality exclusion, a separately attributed branch phone correction and contributor provenance through result deduplication. Source-selected spot checks found conflicts/incomplete evidence and established no current-operation claim. No opening-hours model, “open now”, menus, prices, ratings, reviews, photos or accessibility details. A business's operating status is not today's opening hours. Existing favourites retain saved snapshots rather than automatically receiving new package corrections.
Road route planning Implemented: one walking/cycling/driving route, geometry, duration/distance, basic Italian manoeuvres; manual map origin or requested device position. The shared saved-itinerary slot can retain a selected road preview and its original consultation time. No alternative routes, address-search origin, reverse journey, intermediate stops, avoid-tolls preferences or traffic. Roundabout instructions omit exit numbers. This is a planning preview.
Transit journey planning Implemented: retain MATO alternatives; explicit departure/arrive-by controls in Europe/Rome; boarding/alighting stops and times, supplied stop codes/platforms and trip-level direction, walking/wait/transfer summaries, cancellation/unknown/scheduled/prediction labels and manual refresh. Same-query failures retain the selected journey and its age. Version 0.1.6 restores the saved selected alternative without provider/location calls. Automatic explicit-time defaults refresh after leaving Adesso; deliberate edits survive mode toggles. Native transit UI remains unverified. Strict validated GTT board links and active-view refresh are released in 0.1.7. No continuous travel monitoring, intermediate-stop list, walking manoeuvres, fare/ticket information or accessibility filter. Missing provider fields stay unknown.
GTT stop information Implemented: nearby stops and lines, trip-to-stop matching, direct realtime predictions, cancellations/unknown/stale states, stop-related alerts and explicit failure states. Version 0.1.6 adds up to 100 exact-identity stop shortcuts; changed entries remain unavailable and removable or explicitly replaceable. Released 0.1.7 refreshes active boards through bounded visibility-aware deadlines; the UI clock also ages existing predictions. In development (after 0.1.7): scheduled-first boards from the bundled GTT timetable, with live updates re-joined by schedule identity directly from GTT's export; package updates through the published manifest work once the Pages/prerelease mirrors are enabled. Metro is scheduled-only. No live vehicle map. Metro and regional rail coverage are not established end to end.
Following a journey Released 0.1.7 provides planning and a one-shot foreground fix. Development 0.1.8 adds explicit native road guidance, platform GPS/service, offline Italian TTS and a selected-transit session with manual transitions. The integrated native engine/GPS/voice/service has not run on a usable Android runtime. Mode-specific progress, prompt timing, wrong-turn recovery, transfers, screen-off operation and battery checks remain open; see navigation acceptance.
Privacy and resilience Implemented: no app account/key/analytics SDK, direct providers, local favourites, Android backup disabled, foreground permission only, request deadlines/cancellation/rate limits. Persisted Solo ricerca locale blocks Photon before cache access and while preferences load/unreadable; opt-out cancels pending work. One bounded itinerary snapshot restores locally, with separate save/source times and explicit refresh; failed saved-travel writes/removals retain committed data. The preference controls search; maps, routes and arrivals still use network services. Online search sends query/map area when enabled. Providers receive IP addresses; route providers receive endpoints. Native preference/saved-travel persistence remains unverified. No dependable offline basemap/routing; public-service uptime remains best effort.
Accessibility and maintenance Partial: labelled icon buttons, 44–48+ dp controls, status text, list alternatives to map markers, source/licence screen, automated regressions and bounded persisted diagnostics with preview/manual copy/off/clear. Failed/invalid diagnostic preferences suspend recording; saved-travel failures use four fixed codes without saved values or raw errors. TalkBack, large text, touch exploration and motor accessibility have not been tested. Selecting an origin depends on map tapping or GPS. No export/import favourites or in-app dataset updates; native diagnostic clipboard/persistence remains unverified.

Transit correctness before daily reliance

The stop board and journey planner are separate sources. GTT board predictions are aged against both feed and entity timestamps. The 0.1.1 correction describes MATO predictions by retrieval time and marks them “Da aggiornare” after two minutes; MATO source timestamps are unavailable, so retrieval time is not proof of live source freshness. An itinerary is not continuously monitored for disruption or a missed connection. No code currently ties a selected MATO leg to a GTT board and replans it.

Selecting Mezzi is the request action; there is no separate MATO consent toggle. Describe this accurately in user documentation. MATO's unresolved reuse/availability policy should remain visible as an experimental-service limitation.

0.1.6 scope and acceptance

Released 0.1.6 implements the following contract for one locally saved planning itinerary, saved stop shortcuts, bounded storage-failure diagnostics and reproducible native compiler path mapping. Source/browser review and the signed artifact passed; Android interaction acceptance remains open. Existing manual provider actions, local-only search policy, favourites format and foreground location model are preserved.

  • Save and restore the selected itinerary. Explicit save retains the selected alternative, query, labels, geometry, steps/legs and original retrieval timestamp; the save timestamp is separate. Restore after reload/offline opens that snapshot and selected alternative without route, search, arrival or location requests. Reopened source data stays honestly aged. A pending request from the previous planner view cannot replace the restored snapshot.
  • Refresh and remove deliberately. Explicit refresh may request current routing once. Failure retains the displayed snapshot and its source age; success retains the selected alternative when identity permits. Neither outcome changes saved bytes until another explicit save. Removing the saved itinerary removes its key and closes its restored view; a late read/request cannot resurrect it.
  • Save exact stop shortcuts. Save uses the installed stop ID and retains its code, coordinates and dataset version. Opening requires an exact current ID/code/coordinate match; missing or changed records remain unavailable and removable. A valid shortcut opens that current board through its existing arrival/alert actions, without route, search or location requests. Save/remove operations remain ordered and bounded.
  • Keep committed data through failure. Versioned journey and stop keys validate nested fields and size limits independently. Corrupt/unsupported/oversized reads stay unavailable; failed writes/removals retain the previously committed value. Races between hydration and explicit operations cannot publish obsolete values. Expected validation/limit/unavailable-stop states remain actionable in the UI.
  • Report only fixed local failure codes. Read/write/remove failures and invalid persisted input may record the four allowlisted saved-travel codes. Names, coordinates, identifiers, saved payloads and raw errors never enter diagnostics. Expected limits, not-ready actions and stale/missing stop matches generate no diagnostic event. Existing recording preference, preview/manual copy/off/clear and byte/event bounds still apply.
  • Build and inspect the release. The normal build appends environment-derived Clang path mappings while preserving signing, bundled JavaScript and native sources. Verify the expected certificate, public revision/version, permissions/backup, Google-free runtime graph, 16 KB ZIP/ELF alignment and all-entry private-content scan on the final artifact. A dirty-checkout validation artifact is not release evidence.

Native save/restore/contact/map/location/lifecycle, force-stop persistence, accessibility and physical same-key upgrades remain device checks. Stored routes remain planning snapshots. The later development navigation implementation has its own acceptance contract; the 0.1.6 evidence does not validate it.

Active-view transit refresh: implemented at source/browser level

This scope targets foreground refresh and correct retrieval age. PR8 merged after both independent Standards and Spec production reviews, the final test-delta review and exact-head CI passed. Source integration, simulated browser acceptance and the inspected 0.1.7 artifact are complete. Android interaction acceptance remains open. Journey-to-GTT stop links are described separately below.

  • Preserve retrieval age. GTT cache hits retain the original fetchedAt; departure windows and prediction age are evaluated at the current time. Arrivals and alerts have independent retrieval timestamps, source timestamps, errors and retained snapshots. Failure never renews age or turns unavailable alerts into an empty successful result.
  • Refresh only the active view. Target intervals are 60 seconds for arrivals, 300 seconds for alerts and 120 seconds for transit plans. Roads have no automatic refresh. Saved restoration makes no provider/location call and stays unarmed until explicit refresh of that query; automatic updates never write saved bytes.
  • Suspend synchronously. Hidden views, Privacy, inactive/background AppState and unmount cancel timers and abort in-flight/queued work. Late completion cannot publish after suspension or an identity change. Resume permits at most one overdue request per resource, without catching up missed intervals.
  • Bound requests and retain data. Manual/timer requests coalesce while pending; resource backoff is capped at 15 minutes and manual refresh respects the existing rate-limit cooldown. Same-query failure retains displayed data and its age; arrivals and alerts can succeed or fail independently. Cache hits cannot create a retry loop.
  • Keep the selected preview explicit. If its stable ID disappears from fresh alternatives, retain its old geometry/time with a stale notice. Only explicit selection or reappearance of that ID changes the displayed itinerary. Saving that retained selection is disabled until a fresh alternative is chosen; an existing saved snapshot remains untouched.

The final PR8 source passed bun run verify with typecheck, zero-warning lint and 161 tests. Simulated feeds and virtual request timers at 320 pixels cover unarmed saved restoration, selected-ID disappearance/reappearance and explicit choice, unchanged saved bytes, independent resource cadence/failure retention, Privacy/background cancellation, bounded resume and zero road automatic requests. Basemap requests remained enabled; document width matched the viewport.

Fix-specific browser checks confirm that a still-young manual cache hit preserves its original deadline. A source timestamp aged from 290 to 310 seconds produces the stale-source warning on the real 30-second display tick, with no extra alert fetch or changed retrieval text. Reaching the original deadline makes the next alert request; fresh source data clears the stale warning and updates retrieval text. Exact cadence is established by deterministic controller tests. The signed 0.1.7 release artifact passed inspection and is published. Android foreground/background/screen-lock/return, real-provider cadence and battery behavior remain device checks; browser fixtures do not establish those outcomes.

Strict journey-stop links: released in 0.1.7

Version 0.1.7 / Android code 8 connects validated MATO transit-leg endpoints to the installed GTT stop board. Source integration, simulated browser acceptance, both independent final reviews, exact-head CI and the signed release artifact passed. bun run verify passed typecheck, zero-warning lint and 169 tests; native board-return interaction remains unverified.

  • Match public codes strictly. Require the exact mato:gtt:<digits> identifier, an exactly matching supplied public stop code, one installed stop with that code and valid coordinates within 10 metres. Duplicate codes, missing/invalid coordinates or disagreement produce readable endpoints without arrivals links. Names, nearby stops and internal IDs never substitute for a failed match.
  • Open the installed stop deliberately. Only a validated endpoint exposes an arrivals action. Opening it uses the installed stop's internal ID for the GTT board; rendering a link makes no provider or location request.
  • Return to the selected planning preview. A temporary stop board preserves the query, selected alternative and saved bytes. Journey refresh pauses while that board is visible; Back restores the original journey. An unarmed saved preview remains unarmed on return, unrelated navigation/query changes clear the board, and detail scrolling resets for the changed view.

Simulated feeds and virtual request timers at 320 pixels verified that public codes 2603 and 488 open and save installed internal stops 1765 and 3035. Rendering valid links makes no GTT request; mismatched coordinates and a rail namespace leave readable endpoints without links or GTT calls. A normal journey pauses route refresh during the board and resumes one overdue request on return, retaining selection. A reloaded saved second alternative restores without route/search/GTT/location requests, remains unarmed after the board closes and retains identical saved bytes. Privacy/background suspend the board; return resumes at most one overdue request per resource. Unrelated category navigation clears the board, aborts pending arrivals and prevents queued alerts from reaching transport. Both board/journey transitions reset detail scrolling; document width matches the viewport at 320 and 390 pixels, with the 390-pixel board screenshot visually inspected. Basemap requests remained enabled. Native foreground/background behavior, TalkBack and physical-device interaction remain separate checks; fixtures do not establish provider reliability or battery use. This released scope adds planning actions; development navigation is separate and carries the native acceptance gates.

First Android device session: acceptance evidence

Run these after the installation steps in android.md. Record app version, Android version, permission/network state and the exact query or public stop code for each failure. Private home/work coordinates are unnecessary for reports.

  1. Launch and browsing. With Metro stopped and no Play services in the app's profile, launch, pan/zoom, then search explicitly, select a result marker and open/close its sheet using Android back. Pass: the initial map is unselected; results follow the search action, controls remain reachable, and no exit/crash occurs during these transitions. Follow the map interaction acceptance checks for launch defaults and location feedback.
  2. Discovery and local-only search. Center within the packaged data bounds; try food/shop categories, plural aliases, a known public venue with a one-letter typo and a street address. Open a food place and a shop. Enable Solo ricerca locale, restart and confirm no Photon request during startup or searches; move outside coverage and inspect the outline, radius and capped/empty-result wording. Pass: relevant places retain sources/contact details, saved policy is honored, deliberate missing-data states remain visible and neither uncertain hours nor completeness is invented. A missing name is evidence to investigate, not proof that the business closed.
  3. Permission and origin. Deny location, plan a walking journey using a chosen map point, then test approximate and precise permission outdoors. During a pending GPS request, choose a manual origin. Pass: the manual choice wins; GPS failure leaves browsing usable; the indicated origin matches the chosen point. The blue point is a captured location, not active tracking.
  4. Road planning. Use a public destination a few kilometres away and compare walking, bicycle and car. Pass: modes produce plausible paths, distance/duration/steps agree with the map, and the interface never claims navigation has started. Check the arrival entrance and crossings on a familiar walking route.
  5. A real transit journey. In the rebuilt transit release, plan between two public destinations within the supported network and choose a vehicle result plus a transfer result. Compare alternatives, departure/arrive-by selection, boarding stop, direction, alighting stop and arrival against the operator. Pass: the selected map path and leg details agree, supplied codes/platforms are shown, a cancelled/unknown leg stays explicit and a failed same-query refresh retains the old journey with its age. An all-walking result does not validate vehicles or transfers.
  6. At a stop. Open the actual public stop code shown on the sign, including the correct side/direction. Compare the next reported departure with the operator. Refresh once, then disconnect for more than two minutes. Pass: no new “live” prediction is fabricated, existing data ages to stale, and unavailable alerts remain distinct from an empty alert list. Empty predictions are allowed; they must not mean “no service”.
  7. Persistence, upgrades and lifecycle. Save a business, selected itinerary and stop shortcut, then force-stop/relaunch and change connectivity. Restore the itinerary without routing/search/arrivals/location requests; verify its original source age, explicit refresh and failed-write/removal behavior. Background during a position request. Install a later same-key release through the public download or Obtainium path without uninstalling. Pass: saved items/preferences persist after restart and upgrade, the expected version is installed, and interrupted requests recover through a useful action. Unpersisted itineraries still disappear; checking for updates without a newer build does not prove upgrade preservation.
  8. Comfort and accessibility. Repeat search/place/route/stop flows with large system text and TalkBack if used. Pass: labels and primary actions remain readable and reachable. Record a 20–30 minute normal-use battery observation as a baseline, not a navigation battery benchmark.

The first session is complete when every step has an observed result, including “unavailable from provider” or a recorded known gap. A successful APK install alone does not close the native runtime gate.

Remaining milestones

Finish each scoped PR with fixture checks and an observed manual result; record provider-unavailable and device-unverified outcomes explicitly. Transit alternatives/time selection, discovery/search privacy, the broader compact package and saved travel are released. Their native completion criteria are acceptance steps 5, 2 and 7 on the inspected APK, alongside map/location/diagnostic gates. The data workflow owns source pins, preservation rules, reproduction and the limits of desktop/spot-check evidence.

Next scope Checkable completion criterion
Active-view refresh Released in 0.1.7 after source/browser/artifact checks. Complete Android activity-transition acceptance, verifying selected previews, source age and saved bytes through suspension/failure.
Journey-stop links Released in 0.1.7 after source/browser/artifact checks. Complete native acceptance of the strict matching and board-return contract above.
Discovery acceptance and updates On the inspected compact-package Android release, measure startup, typing/category latency and memory; observe step 2 offline and with persisted local-only policy. Compare a fixed set of independently verified venues/categories against the same source release, recording found/missing/duplicate and branch/contact errors separately from current operation. Preserve tenants, source dates and every licence. Consider SQLite only if native scale/update evidence justifies it; validate package replacement and saved-snapshot reconciliation with the resilience milestone below.
Useful place details Verify public contact/link actions and licensed opening-hours examples, including closed, overnight and unknown hours. Display each field's source/date; derive “open now” only from usable hours. Menus, accessibility, photos, prices and reviews require an actual permitted source and keep missing values explicit.
Journey and stop tools Complete native acceptance of released stop shortcuts; add origin address search/reverse journey, intermediate stops and provider-supported road alternatives/preferences. Preserve cancellation and source/entity freshness. Native acceptance of scheduled-first boards across holidays, midnight and DST (fixtures cover them; device checks pending); regional rail/metro coverage needs sampled operator comparisons.
Resilience and delivery Favourite export/import survives a round trip. Dataset refresh verifies schema, licence, revision and validity before activation, keeps the previous package on failure and explicitly handles saved place snapshots whose source fields changed. A newer same-key APK installs through the public release/Obtainium path without uninstalling and preserves favourites/diagnostic preferences. Offline basemap/routing and live traffic require separate permitted data/engine evidence.
Native navigation acceptance Development 0.1.8 implements explicit navigation in four modes; native compilation and JVM policy/transition tests pass. Complete the mode/boundary acceptance matrix on the inspected APK without Play services, including Ferrostar/JNA loading, GPS/voice, rerouting, manual transit transitions, screen-off/lifecycle and battery. Native builds and browser simulations do not establish these runtime outcomes.

Use actual public journeys plus deterministic cancellation/staleness fixtures; operator disruptions need not occur during the test. Ratings, traffic and other unavailable commercial data remain source/terms decisions. Explain measured benefit before adding an account, paid provider or hosted engine.

Data and provider constraints

  • Overture complements OSM; it does not provide Google's business corpus. Broader downloads can improve coverage without phone accounts or a paid backend, but increase data-preparation/update work. Rich hours/reviews/traffic are separate source problems. See place discovery.
  • Photon is a name/address geocoder, not a complete restaurant-nearby API. The current category chips deliberately stay local. Better citywide discovery should come from a prepared POI index or a separately evaluated permitted service, not repeated broad public-geocoder calls.
  • FOSSGIS remains modest-use, rate-limited, best-effort routing. Automatic rerouting must respect its usage policy; a navigation loop cannot simply call it on every location update. See online services.
  • Provider queues recheck monotonic deadlines after early timer wakes. Released 0.1.5 preserves start-to-start intervals and the 429 cooldown with deterministic early-wake and cancellation regressions. Timer punctuality and wall-clock corrections cannot shorten those queued deadlines; automatic refresh must still respect each provider's usage policy.
  • GTT static and realtime data must stay compatible. GTT rotates trip IDs; the installed timetable package joins only while it matches the live feed. A zero-match feed triggers a manifest check, and boards keep scheduled rows with an explicit notice until a newer package is installed. The CI pipeline and the configured publication host must keep running for this to hold.
  • MATO's technical accessibility is not a service guarantee or settled reuse contract. Resolve that dependency before treating transit planning as dependable. An alternative provider should be evaluated against coverage, terms and privacy; accounts or a hosted engine are not automatic prerequisites for the next UI iteration.

Evidence inspected: App.tsx, src/domain/types.ts, src/services/{search,routing,transit,transit-time,favorites,network,diagnostics}.ts, src/components/{MapCanvas.native,departure-status,JourneyPlanner,route-state,useRoutePlans}.ts*, src/platform/location.ts, app.config.ts, src/data/manifest.json, scripts/data-prepare.py, and the linked research/delivery documents. Two bounded MATO adapter probes returned two genuine alternatives each; this establishes technical access and parser compatibility, not provider uptime or on-ground journey accuracy.