[EPIC PERFORMANCE] Low Performant Maps

[JorenC]

My idea was to pick 'new experience' up as epic, but I think this is more important.
This is the root cause. We might need a different render package - or rewrite some of this. I'll investigate.
(Not making an issue because you asked me not to)

Root cause

The map is one large, monolithic SVG that react-zoom-pan-pinch scales with a CSS transform, while that SVG is force-promoted to its own GPU compositing layer (transform: translateZ(0)). The flicker is the browser repeatedly
re-rasterizing that oversized layer — it is a compositing/paint problem, not a React re-render problem.

The evidence, piece by piece:

1. It's a single composited surface that gets CSS-scaled.

• InteractiveMapZoomWrapper.tsx:250-257 wraps the map in react-zoom-pan-pinch's , which zooms/pans by applying transform: translate() scale() to the wrapper.
• InteractiveMap.tsx:161-167 then sets transform: "translateZ(0)" on the , forcing it onto its own GPU layer.
• SVG is resolution-independent, so when the CSS scale changes, Chrome re-rasterizes the layer to keep it crisp. At maxScale={4} (InteractiveMapZoomWrapper.tsx:234) on a 1500×1500 viewBox, the rasterized surface is 6000×6000 ×
  devicePixelRatio (~2.6 on a Pixel) ≈ 15,000 px on a side — far past the GPU max-texture / tile-memory budget. When tiles can't be held resident, Chrome drops them → content blanks → flicker. Under real memory pressure it drops the
  whole tile set → "all provinces flicker out at once."

2. The differential flicker ("background stays, top layers flicker") is explained exactly by the layer split.

• mapRenderer.ts:684-707 emits layers in order: background, province-fills, then supply-center-markers, province-names, borders, foreground, units, orders.
• InteractiveMap.tsx:46-69 splits that string into two sibling blocks: below = background + province-fills, above = everything from supply-center-markers onward.
• The above group is dominated by 261 province labels rendered with 4 embedded custom woff2 fonts (measured in the Spice Islands file: 261 , 263 , 4 @font-face, 0 raster images). Custom-font text is by far the most
  expensive thing to re-shape and re-rasterize. So during each re-raster window the cheap vector below stays painted while the text-heavy above blanks — precisely the symptom you described.

3. The existing translateZ(0) "fix" is counter-productive for these maps.

• Commit 70d0ee9 added it to stop "white flicker during zoom on large SVGs with embedded raster images". These maps have no embedded raster images ( count = 0) — they're pure vector + text. For a vector/text map, pinning the
  entire oversized surface as one always-resident, repeatedly-re-rasterized GPU layer increases memory pressure and re-raster cost rather than reducing it.

The two symptoms, one architecture

• Flicker (every device, independent of FPS): tile-dropping / re-raster of the oversized forced-GPU layer; worst on the text-heavy above group.
• Low FPS (your old laptop only): the raw cost of re-rasterizing ~840 vector paths + 261 custom-font text nodes every zoom frame. A fast GPU (Pixel 8a) absorbs it; a weak/old GPU stalls. Same root, different bottleneck.

This is also consistent with Cold War + Spice Islands being worst — they're the label/path-densest maps, so they have the most re-raster work per frame.

Recommended fixes (in order)

1. Quick experiment / likely big flicker win: remove transform: translateZ(0) (or gate it to only maps that actually contain ). Lets Chrome tile normally instead of holding one giant resident bitmap.
2. Proper fix for both flicker and FPS: drive zoom/pan by updating the SVG viewBox (or a transform on an inner ) instead of CSS-scaling a rasterized layer. Vectors stay crisp with no oversized GPU texture to re-raster or drop. This
   is the real fix but larger, since react-zoom-pan-pinch is transform-based — we'd compute viewBox from its transform state or replace the panning lib.
3. Complementary: flatten the never-changing layers (background/names/borders/foreground) so only the dynamic fills/units/orders stay live SVG, cutting per-frame raster cost.

[johnpooch]

A proposal to step back and rethink the map, empirically

First — thank you for the diagnosis above. The GPU-layer / re-rasterisation analysis is genuinely good detective work, and the "oversized resident bitmap vs. text re-raster" framing is almost certainly correct as far as it goes. I want to build on it, but also argue that we should widen the frame before we commit to another round of fixes, because I think the solutions we've tried so far are treating symptoms of a deeper cause.

Why I think we're playing whack-a-mole

The last few changes have each been locally reasonable and individually defensible, but the pattern worries me:

• Remove will-change → revert it.
• Add a transform cache of 50 → reduce to 5 → drop it entirely.
• Add translateZ(0) → propose removing it.
• CSS-transform zoom → viewBox-driven zoom (Eliminate map zoom flicker via viewBox-driven rendering (Phase 1) #789).

Every one of these was a plausible fix for one symptom on one device. The problem is we have no baseline and no cross-device measurement, so we can't actually say whether any of them helped. #789 is the clearest example: it was verified as fixing the flicker on a Pixel 8a, and it visibly regressed pan/zoom on my iPhone (side-by-side video on the PR). That's not bad luck — it's the inevitable result of optimising without a measurement that generalises across devices.

The root cause is heavier than the GPU layer

I measured the classical dSVG to get some hard numbers:

• 1,091 KB total, of which 903 KB is raw path geometry (d attributes). No embedded rasters at all.
• 16,871 path drawing commands across 144 paths.
• Two single paths are ~139 KB each (the sea/landmass and the borders).

That geometry is the real cost, and it explains why both approaches we've tried disappoint:

• CSS-transform the whole SVG (current main): the browser rasterises once into a GPU layer, then transforms the bitmap — cheap to move, but the layer goes oversized at zoom → re-raster under memory pressure → the flicker described above.
• Drive viewBox every frame (Eliminate map zoom flicker via viewBox-driven rendering (Phase 1) #789): no oversized layer, so no flicker — but now the browser must re-tessellate and re-paint ~17k path commands on the CPU every gesture frame. A fast Pixel holds 60fps; my iPhone goes CPU-bound and janks.

In other words, #789 didn't remove the cost — it moved it from the GPU to the CPU, and the trade went the wrong way on my device. Flattening static layers (solution 3 above) helps the React/DOM side but doesn't change the fact that we're asking the browser to paint ~17k bezier commands live.

The reframe: we should never be painting that geometry live

Here's the key realisation. Canvas and WebGL are not automatically faster than SVG — if you redraw 17k path commands per frame on a canvas, you've rebuilt #789's jank with a different API. The thing that actually buys performance, in SVG, Canvas, or WebGL alike, is one invariant:

Rasterise the expensive static layer once. Each frame, move only a camera and repaint the light overlay.

The base map (landmasses, borders, province fills, names) is rendered once — never during a gesture. The overlay (units, orders, hover, selection) is tiny. So we should never be re-painting the heavy geometry during pan/zoom.

Proposed architecture — three layers, and buy the viewport

I'd like us to stop hand-rolling the pan/zoom/compositing machinery (we currently own a 270-line zoom wrapper, a 710-line string renderer, and a 560-line SVG-primitive builder) and instead lean on a battle-tested library that has solved interactive pan/zoom-a-big-thing on mobile a million times. My current candidate is Leaflet with CRS.Simple, because it gives us the viewport and vector hit-testing and pinned overlays in one well-trodden API. OpenSeadragon is the alternative if deep-zoom tiling of the base image becomes the dominant concern; a WebGL/Pixi renderer stays as an escape hatch only if measurement proves a library can't hold frame rate.

The model is three clean layers:

Layer	Source	Cost	Changes
Base (visual)	Full-detail SVG → rasterised once to an image/tiles	One-time raster	Per phase only
Hit-test	Simplified / decimated province polygons	Cheap	Built once per variant
Overlay	Units + order arrows from our existing geometry	Light	On interaction/phase

Two things make this much lower-risk than it sounds:

1. A soft base map at our 4× max zoom is acceptable. That single concession lets the base be a bitmap and removes the hardest constraint.
2. The hard, correctness-critical logic is renderer-agnostic and survives the rewrite. orderGeometry.ts (convoy routing, support staggering, b-spline attachment, head-to-head curves) is pure Point-in/Point-out maths. Only the paint layer (svgPrimitives.ts string-building) gets replaced. We are not reimplementing Diplomacy order rendering from scratch.

Build it standalone, with diagnostics and perf as first-party concerns

I feel strongly that if we're rewriting, we should not instrument the existing map — that's throwing measurement at a component we're about to delete. Instead, the new component should treat observability and performance as part of its contract from day one:

• Build it as an isolated workspace package (packages/map) with a frozen public interface mirroring today's InteractiveMap props (variant + phase + orders + selection in, onClickProvince out). Isolation forces a clean boundary and keeps it from being shaped by the code around it; the eventual swap is a one-line dependency change. The one rule: build it against our real dumped fixtures (classicalMap.dsvg + the fixture game states), not toy data, so it still meets real integration constraints.
• A performance harness as a budget that exists before the implementation. A bench route renders a chosen variant; Playwright + CDP drives a scripted pan/zoom under CPU throttling and captures p95 frame time / long-tasks / paint cost. We write the budget as a failing gate (e.g. p95 frame < 16ms at 6× CPU throttle on Spice Islands) and build until it's green. This is the thing whose absence let Eliminate map zoom flicker via viewBox-driven rendering (Phase 1) #789 ship a regression — it makes "feels worse" into a number.
• Telemetry as a built-in seam. The component takes a telemetry sink (we already run Sentry + Honeycomb) and emits gesture frame-timing and interaction latency tagged with variant-id and device-class, by construction. From day one we'd see real-user numbers across the device spread.

On the complex SVGs — optimise after, with one exception

We haven't really decided what to do about the heavy variants. My answer: defer it. The rasterise-once architecture turns the 17k-command paint from a per-frame cost into a once-per-phase cost, which makes the source SVG's visual complexity almost irrelevant to felt pan/zoom performance. Optimising the source paths first would be tuning the input to a subsystem we're about to make insensitive to it.

The one piece of geometry work we need regardless is generating the decimated hit-test polygons — click/hover detection doesn't need coastline detail, and a polygon simplified at ~5px tolerance detects taps identically while being cheap to render. That's a small, testable build step that ships with v1. Cosmetic SVG optimisation (svgo, path simplification for download size / raster cost) becomes a later, independent knob we reach for only if the harness shows initial load or phase-change raster still hitches.

Suggested sequence

1. Build the new map in packages/map (Leaflet CRS.Simple, three-layer model, orderGeometry carried over intact) until it satisfies the budgets — proved on one surface (GameMap) first.
2. Drop-in replace, then migrate Tutorial and ExpandableMapPreview.
3. Optimise source SVGs only where the harness still shows it matters.

I'd rather spend a week building the harness and a clean component than another month merging device-specific tweaks we can't measure.

[JorenC]

done.