Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
25 commits
Select commit Hold shift + click to select a range
ef231b3
docs: plan for issue 10
GeoBradDev Nov 8, 2026
18fd4d6
feat: add render and basemap health to the store and derive the syste…
GeoBradDev Nov 8, 2026
c324fb1
feat: add a stable retry to the airports and ports hooks (#10)
GeoBradDev Nov 8, 2026
2b7c24e
feat: show Failed and Lost on RENDER for an unhealthy render device (…
GeoBradDev Nov 8, 2026
a1316d5
feat: track render device and basemap health in MapView (#10)
GeoBradDev Nov 8, 2026
c35a007
test: add failing test for a heatmap async validation error reported …
GeoBradDev Nov 8, 2026
1f19387
fix: report heatmap error scopes, device loss, and a null adapter as …
GeoBradDev Nov 8, 2026
dd8788f
feat: show per-layer loading, count, and failed states with Retry in …
GeoBradDev Nov 8, 2026
a9d58b1
test: add failing test for a failed airports or ports load showing no…
GeoBradDev Nov 8, 2026
89cf6fd
fix: show data load failures with Retry and derive the header status …
GeoBradDev Nov 8, 2026
cf788a4
feat: announce the header status politely and list the issues when de…
GeoBradDev Nov 8, 2026
6d07e5f
style: add status, retry, note, alert, and basemap fallback styles an…
GeoBradDev Nov 8, 2026
dde4314
test: add failing test for the heatmap awaiting airports forever afte…
GeoBradDev Nov 8, 2026
72bc887
fix: show NO AIRPORT DATA for the heatmap when airports load with 0 r…
GeoBradDev Nov 8, 2026
29a8827
test: add failing test for a null WebGPU adapter leaving the heatmap …
GeoBradDev Nov 8, 2026
447bba6
test: count heatmap compute runs by requestDevice, not requestAdapter…
GeoBradDev Nov 8, 2026
365adae
fix: probe the WebGPU adapter at mount so a null adapter is unsupport…
GeoBradDev Nov 8, 2026
66878f8
test: give MapLibre error events in the MapView health tests the map …
GeoBradDev Nov 8, 2026
47ecae3
test: add failing test for a map creation failure claiming the data l…
GeoBradDev Nov 8, 2026
4e2bfa0
fix: report a map that cannot be created as MAP UNAVAILABLE with REND…
GeoBradDev Nov 8, 2026
6cc56ab
test: add failing test for a late deck error after unmount marking re…
GeoBradDev Nov 8, 2026
1a0bb7e
fix: ignore deck errors after MapView unmounts when judging the rende…
GeoBradDev Nov 8, 2026
5617a26
docs: list the status module and the store health fields in the READM…
GeoBradDev Nov 8, 2026
75043b3
docs: list the review test files in the plan and fix the NO AIRPORT D…
GeoBradDev Nov 8, 2026
570c5f0
docs: correct the unsupported adapter wording and say 0 airports, not…
GeoBradDev Nov 8, 2026
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
21 changes: 12 additions & 9 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,16 +9,17 @@ Built with React 19, Vite, MapLibre GL (through `react-map-gl`), deck.gl (`@deck
- **Basemap:** CARTO dark-matter vector style rendered by MapLibre GL.
- **Airports layer:** every non-closed airport from the OurAirports CSV, drawn as amber points. Click a point to see its properties.
- **Sea ports layer:** the bundled ports GeoJSON, drawn as green points. Click a point to see its properties.
- **Heatmap layer (WebGPU only):** a two-pass compute shader bins airport positions into a 1024 x 512 grid and colorizes it into a bitmap overlay. It runs once, after the airports load. The layer toggle appears only after that compute succeeds, so it is hidden while airports load, when WebGPU is unavailable, and when the airports fetch or the compute fails.
- **Heatmap layer (WebGPU only):** a two-pass compute shader bins airport positions into a 1024 x 512 grid and colorizes it into a bitmap overlay. It runs once, after the airports load. The layer toggle appears whenever WebGPU is present, with a status line: `AWAITING AIRPORTS`, `NO AIRPORT DATA` (the airports fetch failed, or the airports file loaded with 0 airports), `COMPUTING...`, `READY`, or `COMPUTE FAILED` with a `RETRY` button (thrown errors, asynchronous validation or out-of-memory errors, and device loss all count as failures). Without WebGPU the toggle is hidden and the panel says `WEBGPU UNAVAILABLE: HEATMAP AND COMPUTE BENCHMARK OFF`.
- **Load states:** each data layer shows `LOADING...`, its feature count, or `LOAD FAILED` with a `RETRY` button that refetches without reloading the page. The header shows `SYS LOADING`, `SYS NOMINAL`, or `SYS DEGRADED` (any failed layer, heatmap failure, missing WebGPU, failed or lost render device, or failed basemap; the list is in its tooltip and announced to screen readers). If the basemap style fails to load, the map area says `BASEMAP UNAVAILABLE` and the data layers still draw. If the map cannot be created at all (no usable WebGL2), it says `MAP UNAVAILABLE` / `WEBGL2 REQUIRED` and RENDER shows `Failed`.
- **Stress test:** a slider from 0 to 5,000,000 points in steps of 100,000. Points are generated on the main thread 150 ms after the slider stops moving, then drawn as a deck.gl binary attribute layer.
- **GPU info panel:** GPU name (the WebGPU adapter, or the WebGL renderer string when the adapter offers none; a long name is cut off with an ellipsis and shown in full on hover), RENDER: the backend deck.gl actually draws with (`WebGL2`, `WebGPU`, or `Detecting...` until deck has created its device), active point count, frame time with a 60-frame sparkline, an on-demand WebGPU compute benchmark (press `RUN` next to WEBGPU COMPUTE: 5 sequential dispatches over a 64 MB storage buffer, reported as the median in GB/s, labelled `est.` because it is CPU timed, or `Too fast` when the timer is too coarse to measure it; out-of-memory, validation errors, and device loss show `Failed`; the buffer and device are freed when the run ends, and the run stops if the tab is hidden), and heatmap compute time. At 1024px wide or less it shows only RENDER, active point count, and frame time. On small screens (see below) it is hidden while a feature popup is open.
- **Small screens** (640px wide or less, or up to 1024px wide and 500px tall or less): the layer panel starts collapsed behind a "Sensor layers" button, the header drops the coordinates and status, and the feature popup opens as a bottom sheet.
- **GPU info panel:** GPU name (the WebGPU adapter, or the WebGL renderer string when the adapter offers none; a long name is cut off with an ellipsis and shown in full on hover), RENDER: the backend deck.gl actually draws with (`WebGL2`, `WebGPU`, `Detecting...` until deck has created its device, `Failed` if deck could not create one, or `Lost` if the device was lost), active point count, frame time with a 60-frame sparkline, an on-demand WebGPU compute benchmark (press `RUN` next to WEBGPU COMPUTE: 5 sequential dispatches over a 64 MB storage buffer, reported as the median in GB/s, labelled `est.` because it is CPU timed, or `Too fast` when the timer is too coarse to measure it; out-of-memory, validation errors, and device loss show `Failed`; the buffer and device are freed when the run ends, and the run stops if the tab is hidden), and heatmap compute time. At 1024px wide or less it shows only RENDER, active point count, and frame time. On small screens (see below) it is hidden while a feature popup is open.
- **Small screens** (640px wide or less, or up to 1024px wide and 500px tall or less): the layer panel starts collapsed behind a "Sensor layers" button (it shows `<n> FAILED` when a layer has failed), the header drops the coordinates and hides the status visually (screen readers still hear it), and the feature popup opens as a bottom sheet.

## Requirements

- **Node.js:** current LTS (CI uses `lts/*`). Vite 8 needs Node 20.19+ or 22.12+.
- **Browser:** any browser with WebGL 2 for the map and point layers. deck.gl draws through WebGL; WebGPU is used only for compute.
- **WebGPU (optional):** needed for the heatmap and the WEBGPU COMPUTE readout. Use a browser and GPU where `navigator.gpu.requestAdapter()` returns an adapter, for example current Chrome or Edge on desktop. Without it the app still runs: RENDER still shows `WebGL2` (deck.gl renders with WebGL either way), the heatmap toggle never appears, and on screens wider than 1024px WEBGPU COMPUTE shows `--`.
- **WebGPU (optional):** needed for the heatmap and the WEBGPU COMPUTE readout. Use a browser and GPU where `navigator.gpu.requestAdapter()` returns an adapter, for example current Chrome or Edge on desktop. Without it the app still runs: RENDER still shows `WebGL2` (deck.gl renders with WebGL either way), the heatmap toggle never appears (a note in the layer panel says so), the header shows `SYS DEGRADED`, and on screens wider than 1024px WEBGPU COMPUTE shows `--`.
- **Network access:** the basemap style and tiles come from CARTO and the airports CSV comes from GitHub at runtime. The ports data is bundled.

## Setup from a clean clone
Expand Down Expand Up @@ -65,16 +66,18 @@ src/
hooks/ data loading (useAirports, usePorts), WebGPU (useGPUCapabilities,
useGPUCompute, useGPUHeatmap), useStressPoints, useMediaQuery
layers/index.js buildLayers(): visibility and data to deck.gl layers
store/mapStore.js zustand store: viewport, layer visibility, stress count, selection
status/systemStatus.js deriveSystemStatus(): the header's NOMINAL, LOADING, or DEGRADED and its issues
store/mapStore.js zustand store: viewport, layer visibility, stress count, selection,
render device and basemap health
public/data/ports.geojson bundled ports data
```

## Known limitations

- The airports layer depends on GitHub raw being reachable. Fetch errors are kept in hook state but not shown in the UI, so the layer just stays empty.
- The basemap needs CARTO to be reachable; offline, only the overlays draw.
- The heatmap runs once per page load from the first non-empty airports list and does not update afterwards.
- The airports layer depends on GitHub raw being reachable. A failed fetch shows `LOAD FAILED` and can be retried.
- The basemap needs CARTO to be reachable; offline, only the overlays draw. There is no basemap retry; reload the page. Tile errors after the style loads are not reported.
- The heatmap runs once per page load from the first non-empty airports list (again only after a failed run is retried) and does not update afterwards.
- Stress points are generated on the main thread. Large counts (millions of points) briefly block the UI once the slider settles.
- The WEBGPU COMPUTE benchmark is CPU timed (submit to `onSubmittedWorkDone`), so it includes driver and callback latency and reads lower than the real memory bandwidth. The `RUN` control is hidden at 1024px wide or less along with the rest of WEBGPU COMPUTE.
- RENDER is set when deck.gl reports the device it created and is not updated afterwards. If deck fails to create a device, RENDER stays `Detecting...`, and a lost WebGL context is not reflected.
- RENDER is set when deck.gl reports the device it created, and changes afterwards only to `Lost` when that device is lost. A deck that never reports a device or an error leaves RENDER at `Detecting...` and the header at `SYS LOADING`.
- Unit tests run in jsdom, which has no WebGL or WebGPU. GPU code paths are covered by mocks and pure helpers only; check rendering in a real browser.
Loading
Loading