diff --git a/README.md b/README.md index 323c0bf..9b17f01 100644 --- a/README.md +++ b/README.md @@ -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 ` 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 @@ -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. diff --git a/docs/plans/2026-11-07-issue-10-loading-error-degraded-states.md b/docs/plans/2026-11-07-issue-10-loading-error-degraded-states.md new file mode 100644 index 0000000..6448422 --- /dev/null +++ b/docs/plans/2026-11-07-issue-10-loading-error-degraded-states.md @@ -0,0 +1,113 @@ +# Plan: No loading, error, or degraded states: failed data loads leave an empty map and SYS NOMINAL (issue #10) + +Risk tier: High. Not a forced-High area, but it raises from Low for each of: stateful, interactive UI (retry, live regions, focus) that jsdom only partly exercises; async fetch, WebGPU error scopes and device-loss promises; integration with MapLibre and deck.gl callbacks that only a real browser fires; altering existing behavior (the header, the heatmap row, RENDER); and roughly a dozen files. + +Domain skills: +- superpowers:test-driven-development: invoke. +- vercel-react-best-practices: invoke (state from external callbacks, stable callbacks, no set-state in effects, derived state in render). +- chrome-devtools-mcp:a11y-debugging: invoke (new button, live regions, focus after Retry, header status announcements). +- chrome-devtools-mcp:chrome-devtools: invoke for the live drive. If the MCP cannot launch, use Playwright via Node with the cached Chromium (`~/.cache/ms-playwright`). +- frontend-design: not applicable because the new text and button reuse the existing HUD styling (uppercase mono labels, `--accent` bordered buttons like `.gpu-bench-btn`). +- dataviz, django, fastapi, expo, payments, email: not applicable because none of that is touched. + +## Decisions (orchestrator, pre-approved) + +- Per-layer status in the layer panel: loading text, feature count when loaded, error text with a RETRY button that refetches without a page reload. +- Header status derived from real state: LOADING, NOMINAL, DEGRADED. +- MapLibre `onError` handled for basemap style failures with a visible fallback message. +- A short visible note explains what is unavailable without WebGPU. +- Status changes are announced politely (`aria-live="polite"` / `role="status"`), never as alerts. +- Terse uppercase HUD wording. +- In scope from the issue comments: a render-device failure or a lost render device shows an error state for RENDER and makes the header DEGRADED; a heatmap compute failure, including asynchronous shader or pipeline validation errors, shows the heatmap layer as failed, not loaded. +- WebGPU missing makes the header DEGRADED (the issue lists "SYS NOMINAL even when WebGPU is missing" as a defect). +- Retry must work with whatever fetch `useAirports` does today (issue #9 will change the airports pipeline; do none of its work). + +## Acceptance criteria + +1. Data layer states. `useAirports` and `usePorts` each return `{ , loaded, error, retry }`. In the layer panel each data layer (AIRPORTS, SEA PORTS) shows a status line under its toggle row: + - while the request is in flight (initially and after Retry): `LOADING...`; + - when loaded: the feature count formatted with `toLocaleString('en-US')` followed by ` FEATURES` (for example `84,512 FEATURES`; `0 FEATURES` for an empty file); + - when failed: `LOAD FAILED`, the error message in the text's `title`, and a `RETRY` button whose accessible name is `Retry