Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
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
7 changes: 4 additions & 3 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,14 +11,14 @@ Built with React 19, Vite, MapLibre GL (through `react-map-gl`), deck.gl (`@deck
- **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.
- **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:** adapter name, render tier (`WebGPU`, `WebGL Fallback`, or `Detecting...`), active point count, frame time with a 60-frame sparkline, an on-demand compute benchmark (press `RUN` next to 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 the render tier, active point count, and frame time. On small screens (see below) it is hidden while a feature popup is open.
- **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.

## 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 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: the panel shows `WebGL Fallback`, the heatmap toggle never appears, and on screens wider than 1024px 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, 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 @@ -75,5 +75,6 @@ public/data/ports.geojson bundled ports data
- 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.
- Stress points are generated on the main thread. Large counts (millions of points) briefly block the UI once the slider settles.
- The 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 COMPUTE.
- 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.
- 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.
73 changes: 73 additions & 0 deletions docs/plans/2026-11-07-issue-8-gpu-panel-render-backend.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,73 @@
# Plan: GPU panel shows RENDER WebGPU while deck.gl is actually rendering with WebGL2 (issue #8)

Risk tier: High. Not a forced-High area, but it raises two tiers from Low: the render backend comes from deck.gl's device initialization inside a MapLibre control, which jsdom cannot exercise (integration), and it alters existing behavior (RENDER no longer derives from the WebGPU adapter probe). Five or six files change.

Domain skills:
- superpowers:test-driven-development: invoke.
- vercel-react-best-practices: invoke (state from an external callback, stable callbacks, no work in render).
- chrome-devtools-mcp:chrome-devtools: invoke for the live drive. If the chrome-devtools MCP fails (locked profile), use Playwright via `npx playwright` with the cached Chromium instead.
- chrome-devtools-mcp:a11y-debugging: not applicable because no control, focus order, or accessible name changes; only visible text of two values and one key changes.
- frontend-design: not applicable because the panel keeps its existing HUD styling.
- dataviz, django, fastapi, expo, payments, email: not applicable because none of that is touched.

## Decision (user)

Report the truth. Do not wire WebGPU rendering. RENDER reads the device type deck.gl actually created. WebGPU compute availability (the `useGPUCapabilities` tier) stays separate and only gates the compute readout.

## Acceptance criteria

1. RENDER shows the backend deck.gl actually uses: the luma.gl device type passed to deck's `onDeviceInitialized` callback. `webgl` (luma.gl's WebGL2 device; `webgl2` is accepted as an alias) shows `WebGL2`, `webgpu` shows `WebGPU`. Before deck has initialized its device, RENDER shows `Detecting...`. Any other non-empty type shows `Unknown`, including names of `Object.prototype` members such as `__proto__`, `toString`, and `constructor` (the lookup is a `Map`, not a plain object).
2. The WebGPU adapter tier (`webgpu`, `no-webgpu`, `unknown`) never decides the RENDER text. With tier `webgpu` and a `webgl` device, RENDER shows `WebGL2`. The strings `WebGL Fallback` and the tier-derived `WebGPU` RENDER label are gone.
3. RENDER value class: `ok` when the device type is `webgl`/`webgl2`/`webgpu`, `warn` while detecting or unknown.
4. The compute item's key reads `WEBGPU COMPUTE` (was `COMPUTE`), so WebGPU compute availability reads apart from RENDER. Its behavior from #11 is unchanged: `--` and no RUN button unless the tier is `webgpu` and the benchmark is supported; the RUN button's accessible name stays `Run compute benchmark`; the value stays a polite live region.
5. GPU label, in order: adapter `device`, then adapter `description`; if both are empty, adapter `vendor` and `architecture` joined with a space (either alone if only one is set); if the adapter offers none of those, the render device's `info.renderer` from deck's device (luma.gl `device.info.renderer`, the unmasked WebGL renderer string when exposed); otherwise `Unknown`. The GPU value carries class `gpu-info-name`, which truncates it with an ellipsis at 32ch, and a `title` attribute with the full name, because the renderer string can be about 90 characters. The panel keeps `pointer-events: none`; `.gpu-info-name` sets `pointer-events: auto` so the title tooltip shows on hover.
6. Unit tests cover: RENDER for `webgl`, `webgl2`, and `webgpu` device types; the not-yet-initialized state (`Detecting...`); an unrecognized type; tier `webgpu` with device `webgl` still showing `WebGL2`; each GPU label fallback step. A MapView wiring test (with `react-map-gl/maplibre`, `@deck.gl/mapbox`, and the GPU hooks mocked) shows `Detecting...` first, then `WebGL2` after the overlay's `onDeviceInitialized` is called with `{ type: 'webgl' }`, proving the callback is passed to the `MapboxOverlay` constructor.
7. Prior work preserved: all other existing tests pass; tests that looked up the `COMPUTE` key text are updated only for the new key text. At 1024px wide or less the panel shows only RENDER, PTS, FRAME. At 375x812, 768x1024, and 1440x900 the panel stays inside the viewport and does not overlap the header, the layer panel, or an open popup at 768. At every width over 1024px the panel does not overlap an open feature popup whatever the GPU label length: the panel's top-level `max-width` is `calc(100vw - 340px)` (the 1024px rule already used it; the 640px narrow rule keeps `calc(100vw - 32px)`). Because that cap can wrap the panel above 1024px, the `|` separators are hidden at every width (kept in the DOM) and items are spaced by `column-gap: 14px`, as #5 already did at 1024px and below, so a wrapped row never starts or ends with a separator. No new `color:` rule unless it is added to `src/styles.test.js`'s `TEXT_PAIRS`.
8. README's GPU info panel bullet and Requirements text describe RENDER as the deck.gl backend (`WebGL2`, `WebGPU`, or `Detecting...`) and no longer say the panel shows `WebGL Fallback`; references to the COMPUTE key use `WEBGPU COMPUTE`.

## Files that change

- `src/components/gpuLabels.js` (new): pure helpers `renderBackendLabel(deviceType)` returning `{ text, ok }` (or two functions, implementer's choice), and `gpuDeviceLabel(adapterInfo, renderInfo)`. No React.
- `src/components/gpuLabels.test.js` (new): unit tests for both helpers (AC1, AC5).
- `src/components/gpuLabels.protoKeys.test.js` (new, review fix B1): `renderBackendLabel` returns `Unknown`, not ok, for prototype member names (AC1).
- `src/index.css` (review fix B2): new `.gpu-info-name` rule (nowrap, hidden overflow, ellipsis, `max-width: 32ch`, no `color:`), and the top-level `.gpu-info-panel` `max-width` becomes `calc(100vw - 340px)`.
- `src/index.css` (review fix F2): top-level `.gpu-info-sep` gets `display: none` and `.gpu-info-panel` gets `column-gap: 14px`.
- `src/styles.gpuSeparators.test.js` (new, review fix F2): asserts both top-level declarations.
- `src/styles.gpuPanel.test.js` (new, review fix F1): the panel keeps `pointer-events: none` and `.gpu-info-name` has `pointer-events: auto`.
- `src/styles.test.js` (review fix B2): asserts the `.gpu-info-name` declarations, the top-level panel `max-width`, and that the 1024px and 640px panel widths from #5 are unchanged.
- `src/components/GPUInfoPanel.gpuName.test.jsx` (new, review fix B2): the GPU value has class `gpu-info-name` and the full name in `title`.
- `src/components/GPUInfoPanel.jsx`: read `renderDevice` from `capabilities` (`{ type, renderer }` or null/undefined; must be optional so existing tests that omit it render `Detecting...`). RENDER text and class from `renderBackendLabel(renderDevice?.type)`. GPU text from `gpuDeviceLabel(adapterInfo, renderDevice)`, in a value span with class `gpu-info-name` and `title` set to the full name. Compute key text `WEBGPU COMPUTE`. `isWebGPU` (tier) keeps gating only the RUN button.
- `src/components/GPUInfoPanel.test.jsx` and `src/components/GPUInfoPanel.benchmarkTier.test.jsx`: change `getByText('COMPUTE')` lookups and the `'COMPUTE'` entry in the secondary-key loop to `'WEBGPU COMPUTE'`; add panel tests for AC1 to AC3 (incl. tier `webgpu` + device `webgl`).
- `src/components/MapView.jsx`: `const [renderDevice, setRenderDevice] = useState(null)`. A stable `useCallback` `(device) => setRenderDevice({ type: device.type, renderer: device.info?.renderer })`. `DeckGLOverlay` takes `onDeviceInitialized` and passes it in the `MapboxOverlay` constructor props (the overlay creates its `Deck` in `onAdd` from those props, so it must be there at construction; `setProps({ layers })` keeps it). Add `renderDevice` to the `capabilities` memo and its deps.
- `src/components/MapView.test.jsx` (new): wiring test of AC6. Mock `react-map-gl/maplibre` (`Map` renders children; `useControl(factory)` calls the factory once and returns its result), mock `@deck.gl/mapbox` `MapboxOverlay` as a class that records its constructor props and has `setProps`, mock `maplibre-gl/dist/maplibre-gl.css` and `../config/maplibreWorker.js` if needed, mock `useGPUCapabilities` and `useGPUCompute`. Call the recorded `onDeviceInitialized` inside `act` and assert RENDER.
- `README.md`: AC8, plus the GPU name truncation and hover in the panel bullet and a Known limitations line that RENDER is not updated after deck reports its device (device creation failure stays `Detecting...`, context loss is not reflected).

## Order of work

1. Red: `gpuLabels.test.js`, then the helpers.
2. Red: panel tests (new RENDER cases, renamed key), then `GPUInfoPanel.jsx`.
3. Red: `MapView.test.jsx`, then `MapView.jsx`.
4. README.
5. Gate, then live drive.

## Risks

- `onDeviceInitialized` must be in the constructor props; passing it only through `setProps` after `onAdd` would miss the event. The wiring test asserts constructor props.
- React StrictMode double-invokes effects; `useControl` may create the overlay twice in dev. The callback only sets state, so a repeated call is harmless.
- If deck's device creation fails, RENDER stays `Detecting...`. Loading and error states are issue #10; not handled here (noted in the PR).
- Longer key text `WEBGPU COMPUTE` widens the panel at widths over 1024px; re-measure at 1440.
- luma.gl's WebGL device type string is `webgl`, not `webgl2`; the label maps both.

## Not done

- WebGPU rendering (`deviceProps: { type: 'webgpu' }`): rejected by the user.
- Header "SYS NOMINAL" and loading/error states: issue #10.

## Proof

- AC1, AC3, AC5: `src/components/gpuLabels.test.js`, `src/components/gpuLabels.protoKeys.test.js`, and the new panel tests.
- AC2: panel test with tier `webgpu` and device `webgl`.
- AC4, AC7: existing panel and benchmark tier tests (key text updated), `src/styles.test.js`.
- AC5 truncation, tooltip, and AC7 popup clearance: `src/components/GPUInfoPanel.gpuName.test.jsx`, `src/styles.test.js`, `src/styles.gpuPanel.test.js`, and `src/styles.gpuSeparators.test.js`; live drive at 1440x900, 1280x800, and 1025x800 checks no separator is visible; live drive at 1440x900 and 1025x800 with a feature popup open measures the panel and popup rects.
- AC6: `src/components/MapView.test.jsx`.
- Live drive: `npm run build && npm run preview`; in the browser RENDER shows `WebGL2`, and the console shows the deck canvas holds a `webgl2` context (for example `[...document.querySelectorAll('canvas')].map(c => !!c.getContext('webgl2'))` all true, and no `webgpu` context) matching the label. Note: headless Chromium has no WebGPU adapter and the user's Chrome returns null from `requestAdapter()`, so the tier is `no-webgpu` there; WEBGPU COMPUTE shows `--` with no RUN button. GPU label shows the WebGL renderer string when the adapter offers nothing. Re-measure layout at 375x812, 768x1024, 1440x900.
2 changes: 1 addition & 1 deletion src/components/GPUInfoPanel.benchmarkTier.test.jsx
Original file line number Diff line number Diff line change
Expand Up @@ -18,7 +18,7 @@ describe('GPUInfoPanel RUN control and the detected tier', () => {
it.each(['no-webgpu', 'unknown'])('hides the RUN button when the tier is %s', (tier) => {
render(<GPUInfoPanel capabilities={{ ...base, tier }} benchmark={benchmark} />)
expect(screen.queryByRole('button', { name: 'Run compute benchmark' })).not.toBeInTheDocument()
expect(screen.getByText('COMPUTE').closest('.gpu-info-item')).toHaveTextContent('--')
expect(screen.getByText('WEBGPU COMPUTE').closest('.gpu-info-item')).toHaveTextContent('--')
})

it('shows the RUN button when the tier is webgpu', () => {
Expand Down
34 changes: 34 additions & 0 deletions src/components/GPUInfoPanel.gpuName.test.jsx
Original file line number Diff line number Diff line change
@@ -0,0 +1,34 @@
import { describe, it, expect } from 'vitest'
import { render, screen } from '@testing-library/react'
import { GPUInfoPanel } from './GPUInfoPanel.jsx'

// The GPU name can be a ~90 character WebGL renderer string. It is truncated
// by CSS (gpu-info-name) so the panel clears the feature popup, and the full
// name stays readable in the title attribute.
const RENDERER = 'ANGLE (Google, Vulkan 1.3.0 (SwiftShader Device (Subzero) (0x0000C0DE)), SwiftShader driver)'
const base = {
tier: 'no-webgpu',
adapterInfo: {},
renderDevice: { type: 'webgl', renderer: RENDERER },
activePointCount: 0,
frameTime: 16,
frameHistory: [],
gpuThroughput: '--',
}

describe('GPUInfoPanel GPU name', () => {
const gpuVal = () => screen.getByText('GPU').closest('.gpu-info-item').querySelector('.gpu-info-val')

it('marks the GPU value for truncation and keeps the full name in title', () => {
render(<GPUInfoPanel capabilities={base} />)
expect(gpuVal()).toHaveClass('gpu-info-name')
expect(gpuVal()).toHaveAttribute('title', RENDERER)
expect(gpuVal()).toHaveTextContent(RENDERER)
})

it('titles a short adapter name too', () => {
render(<GPUInfoPanel capabilities={{ ...base, tier: 'webgpu', adapterInfo: { device: 'RTX 4090' } }} />)
expect(gpuVal()).toHaveClass('gpu-info-name')
expect(gpuVal()).toHaveAttribute('title', 'RTX 4090')
})
})
20 changes: 12 additions & 8 deletions src/components/GPUInfoPanel.jsx
Original file line number Diff line number Diff line change
@@ -1,3 +1,5 @@
import { renderBackendLabel, gpuDeviceLabel } from './gpuLabels.js'

function Sparkline({ history }) {
if (!history || history.length === 0) return null

Expand Down Expand Up @@ -47,25 +49,27 @@ function BenchmarkButton({ running, onRun }) {
}

export function GPUInfoPanel({ capabilities, benchmark = NO_BENCHMARK }) {
const { tier, adapterInfo, activePointCount, frameTime, frameHistory, gpuThroughput, heatmapComputeMs } = capabilities
const { tier, adapterInfo, renderDevice, activePointCount, frameTime, frameHistory, gpuThroughput, heatmapComputeMs } =
capabilities

const deviceLabel =
adapterInfo.device || adapterInfo.description || adapterInfo.vendor || adapterInfo.architecture || 'Unknown'
const renderLabel =
tier === 'no-webgpu' ? 'WebGL Fallback' : tier === 'unknown' ? 'Detecting...' : 'WebGPU'
const deviceLabel = gpuDeviceLabel(adapterInfo, renderDevice)
// RENDER is the backend deck.gl created; the WebGPU tier only gates compute.
const render = renderBackendLabel(renderDevice?.type)
const isWebGPU = tier === 'webgpu'
const frameClass = frameTime <= 16 ? 'ok' : frameTime <= 33 ? 'warn' : 'err'

return (
<div className="gpu-info-panel">
<span className="gpu-info-item gpu-info-secondary">
<span className="gpu-info-key">GPU</span>
<span className="gpu-info-val">{deviceLabel}</span>
<span className="gpu-info-val gpu-info-name" title={deviceLabel}>
{deviceLabel}
</span>
</span>
<span className="gpu-info-sep gpu-info-secondary">|</span>
<span className="gpu-info-item">
<span className="gpu-info-key">RENDER</span>
<span className={`gpu-info-val ${isWebGPU ? 'ok' : 'warn'}`}>{renderLabel}</span>
<span className={`gpu-info-val ${render.ok ? 'ok' : 'warn'}`}>{render.text}</span>
</span>
<span className="gpu-info-sep">|</span>
<span className="gpu-info-item">
Expand All @@ -82,7 +86,7 @@ export function GPUInfoPanel({ capabilities, benchmark = NO_BENCHMARK }) {
</span>
<span className="gpu-info-sep gpu-info-secondary">|</span>
<span className="gpu-info-item gpu-info-secondary">
<span className="gpu-info-key">COMPUTE</span>
<span className="gpu-info-key">WEBGPU COMPUTE</span>
<span className="gpu-info-val" aria-live="polite">{gpuThroughput}</span>
{/* navigator.gpu can exist with no adapter, so also require the detected tier. */}
{benchmark.supported && isWebGPU ? (
Expand Down
Loading
Loading