# Frontend performance and resource budgets

Status: approved release guardrail

Baseline date: 2026-07-29

Baseline revision: `b9b2ecdbfaa9688a79a62ccee38d6b406f14deaa`

These limits turn the Phase 0/6 performance requirements into release gates.
They are ceilings, not allocation targets. A change that needs a higher limit
requires a measured before/after result and explicit review; the default
tolerated regression is 10%.

## Browser resources

| Resource | Limit | Enforcement |
| --- | ---: | --- |
| Decoded terrain tiles | 16 entries and 32 MiB | `TerrainTileCache`; closes every evicted bitmap |
| Service-worker tile cache | 6,000 responses and 96 MiB estimated body bytes | persisted metadata and amortized pruning |
| General scoped browser caches | 128 MiB combined estimated bytes | per-cache TTL/LRU/byte limits; debug snapshots |
| Map/terrain soak | less than 10% retained-heap growth after warm-up over 30 minutes | Playwright/DevTools staging soak |
| Map construction | one main map and one owner map per mounted page | browser construction-count regression |

## Requests and jobs

| Work | Limit |
| --- | ---: |
| Common same-origin API concurrency | 8 |
| Terrain image decode concurrency | 4 |
| Feed selected-path concurrency | 1 |
| Link-quality sparkline concurrency | 2, with a 16-item queue |
| Repeater detail concurrency | 4 |
| HopReach metadata/progress polling | 3 seconds while the RF feature is enabled |
| HopReach compatibility page | 500 nodes, 100,000 maximum offset |
| HopReach bulk evidence request | 5,000 keys and 250,000 result rows |
| Ordinary API deadline | 15 seconds |

Requests are scope-fenced by network, observer, privacy generation, and owner
session where applicable. Hidden pages schedule no polling and perform one
refresh when visible again.

## Rendering

| Work | Limit |
| --- | ---: |
| Topology representative fixture | 600 nodes / 1,200 links |
| Topology React snapshots | at most one every 66 ms while visible |
| Representative topology frame time | p95 below 16.7 ms after simulation warm-up |
| Expandable list details | outside fixed-height virtual rows; no overlap at 375, 768, or 1,280 CSS px |
| Coarse-pointer controls | 44 CSS px where layout permits; otherwise WCAG target spacing applies |

## Production frontend assets

All byte limits below use the output of `vite build`. “Raw” means minified
bytes and “gzip” is computed with Node's default gzip settings.

| Asset group | Raw limit | Gzip limit |
| --- | ---: | ---: |
| Main `App-*` chunk | 900 KiB | 260 KiB |
| `maplibre-gl-*` chunk | 820 KiB | 225 KiB |
| Recharts categorical chunk | 400 KiB | 110 KiB |
| All JavaScript | 2,900 KiB | 850 KiB |
| All CSS | 230 KiB | 42 KiB |

Run `npm run budget` after `npm run build`. CSS has a separate structural
gate: no duplicate selector in the same at-rule/cascade context and no
dashboard/page selector in `styles/globals.css`. Responsive declarations in a
distinct media query are intentional and are not counted as duplicates.

## HopReach RF calculator

The indexed CPU path must match the executable upstream v0.1.32 oracle within
`1e-5 dB`. Conservative-superset tests cover exhaustive and randomized
geography, poles, the antimeridian, borders, dense/empty areas, chunk edges,
and maximum-range paths.

| Measure | Release limit | 2026-08-02 local result |
| --- | ---: | ---: |
| UK-4,600 Standard raster-time ratio | no more than 0.70 of upstream | 0.602 |
| UK-4,600 Precision-tile time ratio | no more than 0.70 of upstream | 0.594 |
| Standard peak terrain working-set ratio | no more than 0.70 of upstream | 0.453 |
| Precision peak terrain working-set ratio | no more than 0.70 of upstream | 0.135 |
| Maximum reference parity error | 0.00001 dB | within tolerance |

The measured times are three-run means with identical dimensions and
`GOMAXPROCS=4`. The working-set gate includes unchanged 100 km range padding
around publication tiles and uses the exact float32 Web-Mercator DEM tile
accounting from `demgrid.Load`. `scripts/benchmark-hopreach.sh` captures
allocation output, independent CPU/heap profiles, and a progressive completion
trace. Full evidence and raw-value interpretation are in
`rf-coverage/BENCHMARKS.md` and `docs/rf-coverage-rollout.md`.

## Rollout evidence

Before a browser-cache, map, topology, or chart release:

1. Record the production asset output and `npm run budget` result.
2. Run desktop/mobile Playwright plus axe.
3. Run `SOAK_BASE_URL=https://test.ukmesh.com npm run soak:production` for the
   30-minute terrain/map soak. The harness records post-GC heap, cache/storage
   snapshots, long tasks, request failures, and MapLibre construction count as
   signed deployment evidence.
4. Roll back on privacy drift, cross-scope state, reload loops, cache quota
   overflow, or a limit above. Retain the prior service-worker namespace for
   seven days.