From ef231b351c4e4c3caaf43d61183d5434a04c2a89 Mon Sep 17 00:00:00 2001 From: Brad Stricherz Date: Sat, 7 Nov 2026 21:49:38 -0600 Subject: [PATCH 01/25] docs: plan for issue 10 Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01AELE7jB1i3uqqrHu3SjJjf --- ...-issue-10-loading-error-degraded-states.md | 106 ++++++++++++++++++ 1 file changed, 106 insertions(+) create mode 100644 docs/plans/2026-11-07-issue-10-loading-error-degraded-states.md 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..a482de6 --- /dev/null +++ b/docs/plans/2026-11-07-issue-10-loading-error-degraded-states.md @@ -0,0 +1,106 @@ +# 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