@react-x11/components 0.8.0 → 0.10.0

package/src/maps/node.ts

@@ -11,7 +11,8 @@
 // Three caches, and the map's whole performance argument is the way they
 // are layered:
 //
-//  1. **Tile data**, keyed on `source/z/x/y` and valid forever.
+//  1. **Tile data**, keyed on the source object and `z/x/y`, and valid
+//     forever. The object, not its `id` — see `./tiles.ts`.
 //  2. **A rendered `Surface` per tile**, valid for a zoom *level* and a
 //     style — not for a camera position. So a **pan** composites the same
 //     surfaces at new offsets (and blits, so most of them are not even
@@ -32,7 +33,12 @@ import type { A11ySceneItem, Context2D } from 'react-x11/node';
 import type { KeyboardEvent, MouseEvent, WheelEvent } from 'react-x11';
 import { Surface } from 'react-x11/ntk';
 
-import { GeometryBuffer } from './mvt.js';
+import { MapController, quantizeZoom } from './controller.js';
+import type {
+  MapControllerProps,
+  MapPointerInput,
+  MapView,
+} from './controller.js';
 import {
   BATCH_VERTICES,
   DrawScratch,
@@ -44,16 +50,13 @@ import {
 import type { MapCanvas, PreparedStyle } from './paint.js';
 import {
   DEFAULT_TILE_SIZE,
-  cameraForBounds,
-  boundsOf,
+  dataSquareOf,
   dataTileFor,
   subTileOf,
-  projectLngLat,
   rasterFor,
   tileCover,
+  tileKey,
   transformFor,
-  unprojectPoint,
-  visibleBounds,
 } from './proj.js';
 import type {
   LngLat,
@@ -64,11 +67,13 @@ import type {
   TileId,
   Transform,
 } from './proj.js';
-import { TileCache, pyramid } from './tiles.js';
+import { TileCache, drawnFor, pyramid } from './tiles.js';
 import type { CachedTile, SurfaceLike, TileRender } from './tiles.js';
+import { attributionOf } from './sources.js';
 import type { MapSource } from './sources.js';
 import { shortbreadStyle } from './styles.js';
 import type { MapStyle } from './style.js';
+import { isDarkTheme, overlayPalette } from './theme.js';
 import {
   LabelShaper,
   collectLabels,
@@ -76,9 +81,16 @@ import {
   placeLabels,
 } from './labels.js';
 import type { FontsLike, LabelCandidate, PlacedLabel } from './labels.js';
-import { drawMarkers, drawOverlays, markerAt, markerRect } from './overlay.js';
+import {
+  ATTRIBUTION_OPACITY,
+  ATTRIBUTION_SIZE,
+  attributionLayout,
+  drawMarkers,
+  drawOverlays,
+  markerRect,
+} from './overlay.js';
 import type { MapMarker, MapOverlay, OverlayPalette } from './overlay.js';
-import type { MapFrameStats, MapPointerEvent } from './types.js';
+import type { FitBoundsOptions, MapFrameStats } from './types.js';
 
 /** Registration key, `kind` and JSX tag, one string — react-x11 rejects a
  *  node whose `kind` is not the name it was registered under, because
@@ -103,24 +115,6 @@ export const SELF_DAMAGED_PROPS = [
   'mapStyle',
 ] as const;
 
-/** Screen pixels the pointer may travel before a press becomes a drag. */
-const DRAG_THRESHOLD = 3;
-
-/** How long after the last gesture step the map goes back to rasterizing.
- *  Long enough that a wheel-zoom's many steps count as one gesture, short
- *  enough that the map sharpens before the user has finished looking. */
-const SETTLE_MS = 140;
-
-/** Zoom is quantized to this, for the reason react-x11's docs/scale.md
- *  gives about a gesture-driven `scale`: every distinct value is a distinct
- *  set of font sizes to shape, and a wheel feeding a raw accumulator makes
- *  a new set per frame. A sixteenth of a level is finer than the eye reads
- *  as stepping. */
-const ZOOM_STEP = 1 / 16;
-
-/** A wheel notch is this much zoom. */
-const WHEEL_ZOOM = 1 / 2.5;
-
 /** The largest tile surface, per edge, in device pixels. An argb32 surface
  *  is `4 × size²` bytes, so 2048 is 16 MB and is already more than any
  *  pyramid justifies. */
@@ -154,33 +148,6 @@ function intersectRects(a: ScreenRect, b: ScreenRect): ScreenRect | null {
   return { x, y, width: right - x, height: bottom - y };
 }
 
-const timers = globalThis as {
-  setTimeout?(fn: () => void, ms: number): unknown;
-  clearTimeout?(id: unknown): void;
-};
-
-/**
- * The settle timer, unref'd where the runtime allows it.
- *
- * A map that has just been panned holds a 140 ms timer, and an unref'd one
- * does not keep a process alive on its own — which matters for a script or
- * a test that renders a map and expects to exit, and is the call core's
- * caret blink makes for the same reason.
- */
-function arm(tick: () => void): unknown {
-  const handle = timers.setTimeout?.(tick, SETTLE_MS) ?? null;
-  (handle as { unref?(): void } | null)?.unref?.();
-  return handle;
-}
-
-function clamp(value: number, low: number, high: number): number {
-  return value < low ? low : value > high ? high : value;
-}
-
-function quantize(zoom: number): number {
-  return Math.round(zoom / ZOOM_STEP) * ZOOM_STEP;
-}
-
 /** A logical value put on the device grid — the same helper `src/flow/`
  *  keeps, and for the same reason: ntk's fast paths for a blit and a
  *  rounded box are gated on integral geometry, and `x * 1.5` is not always
@@ -200,34 +167,127 @@ function rectsOverlap(a: ScreenRect, b: ScreenRect): boolean {
   );
 }
 
-type Gesture =
-  | {
-      kind: 'pan';
-      startX: number;
-      startY: number;
-      lastX: number;
-      lastY: number;
-      moved: boolean;
-    }
-  | { kind: 'marker'; id: string; startX: number; startY: number };
+/** Whether `outer` covers all of `inner`. */
+function containsRect(outer: ScreenRect, inner: ScreenRect): boolean {
+  return (
+    outer.x <= inner.x &&
+    outer.y <= inner.y &&
+    outer.x + outer.width >= inner.x + inner.width &&
+    outer.y + outer.height >= inner.y + inner.height
+  );
+}
+
+function sameSources(
+  a: readonly MapSource[],
+  b: readonly MapSource[],
+): boolean {
+  return a.length === b.length && a.every((source, i) => source === b[i]);
+}
+
+/** A tile of the cover that is in view, as a frame's work found it. */
+interface VisibleTile {
+  entry: TileCoverEntry;
+  /** Where it lands, in pane-local logical pixels. */
+  box: ScreenRect;
+  cached: CachedTile;
+}
+
+/**
+ * How long a restyle may keep the previous style up once the view moves,
+ * in milliseconds the map was free to draw in.
+ *
+ * A still view is never cut short: its redraw is a fixed amount of work,
+ * and the swap waits for all of it. A moving one can bring tiles into view
+ * as fast as the old ones are finished — a pan with pauses in it, a camera
+ * an application animates — and would never swap. So once the camera has
+ * moved the wait is bounded, and a tile not yet redrawn when it runs out
+ * shows the background until it is. Frames a gesture holds rasterization
+ * off in do not count, since nothing is drawn in them.
+ */
+const RESTYLE_WAIT_MS = 1500;
+
+/**
+ * The clock {@link RESTYLE_WAIT_MS} is measured on: the raster budget's,
+ * read at the same moment, as a frame begins.
+ *
+ * One object, exported from this module though not from the package, so a
+ * test can stand in for it and move the bound's time on a step at a time,
+ * as `glideClock` in `./controller.ts` does for a glide. On the real clock a
+ * test finds the swap only once the step that made it is over, and on a
+ * loaded runner one step took long enough to put that two and a half
+ * seconds past the bound. It is not the budget's own `now`, because a test
+ * that held that one would hold the raster deadline with it: a frame would
+ * draw every tile to the end, and there would be no redraw left for the
+ * bound to cut short.
+ */
+export const restyleClock = {
+  now(): number {
+    return now();
+  },
+};
+
+/**
+ * The previous style, held on screen while a restyle draws the new one.
+ *
+ * A `mapStyle` change or `refresh()` retires every tile surface at once,
+ * and the redraw is budgeted — a dense tile is 50-140 ms against 8 ms a
+ * frame — so it takes a second or more. A tile's own double buffer keeps
+ * its old picture until its new one is done, which is right for a zoom and
+ * wrong here: the map was a patchwork of both styles for that second, under
+ * a background and labels that had already switched. So the whole previous
+ * picture — the tiles of its generation, its background, its labels —
+ * stays up until the view is redrawn, and is replaced in one frame.
+ */
+interface Outgoing {
+  /** The cache generation on screen. Only its pictures are composited. */
+  generation: number;
+  /** The style background the last frame before the switch painted. */
+  background: string | undefined;
+  /**
+   * The labels on screen, and what they were placed for and from — the
+   * quantized zoom, the sources, their candidates and the face — kept
+   * because the style that produced them is gone, or, after `refresh()`,
+   * was edited in place. A zoom re-places them from the candidates; a
+   * source taken off the map takes its names with it.
+   */
+  labels: PlacedLabel[];
+  labelZoom: number;
+  labelSources: readonly MapSource[];
+  candidates: Map<MapSource, LabelCandidate[]>;
+  family: string | undefined;
+  /** The camera and the pane at the switch, and whether either has moved
+   *  since — which is what makes {@link RESTYLE_WAIT_MS} apply. */
+  view: string;
+  moved: boolean;
+  /** Milliseconds the map has been free to draw since the switch, and when
+   *  the last frame that was began on {@link restyleClock} — `null` when
+   *  the last frame was not. */
+  waited: number;
+  lastDrawn: number | null;
+}
 
 export class MapViewNode extends Node {
   private readonly _cache: TileCache;
   private readonly _scratch = new DrawScratch();
-  private readonly _geometry = new GeometryBuffer();
   private _shaper: LabelShaper | null = null;
 
   /**
-   * The camera this element owns, used whenever `props.camera` is absent.
+   * The camera and the gestures: the controller `<Map>` hands down, or this
+   * element's own when it is used bare. Both of `<Map>`'s renderers answer
+   * to one (`./controller.ts`), which is how a fallback from one to the
+   * other keeps the camera and the handle.
    *
-   * The element keeping it — rather than the component above holding it in
-   * `useState` — is what makes a pan cost nothing but a blit: a drag step
-   * moves this number and claims a strip, and React is not involved at all.
-   * Routed through state instead, every pointer step would be a render, a
-   * commit and a full-pane claim, which is the shape `<Flow>` documents as
-   * "the content lags and catches up".
+   * The camera being an object's rather than React state's is what makes a
+   * pan cost nothing but a blit: a drag step moves two numbers and claims a
+   * strip, and React is not involved at all. Routed through state instead,
+   * every pointer step would be a render, a commit and a full-pane claim,
+   * which is the shape `<Flow>` documents as "the content lags and catches
+   * up".
    */
-  private _camera: MapCamera = { center: { lon: 0, lat: 20 }, zoom: 2 };
+  private readonly _controller: MapController;
+  private readonly _ownsController: boolean;
+  /** This element, as its controller sees it. */
+  private readonly _view: MapView;
 
   private _prepared: PreparedStyle | null = null;
   private _preparedFrom: MapStyle | null = null;
@@ -236,17 +296,28 @@ export class MapViewNode extends Node {
   /** The placement, and what it was computed for. */
   private _labels: PlacedLabel[] = [];
   private _labelKey = '';
+  /** …and what it was placed from, all of which a restyle holds on to (see
+   *  {@link Outgoing}): the quantized zoom, the sources on the map, their
+   *  candidates per source, and the face they were shaped in. */
+  private _labelZoom = 0;
+  private _labelSources: readonly MapSource[] = [];
+  private _labelCandidates = new Map<MapSource, LabelCandidate[]>();
+  private _shapedFamily: string | undefined;
   /** Candidates per tile, so a pan that brings a tile back does not redo
    *  the walk over its symbol layers. */
   private readonly _candidates = new Map<string, LabelCandidate[]>();
 
-  private _gesture: Gesture | null = null;
-  private _hover: string | null = null;
-  /** Set while a gesture is in flight and for `SETTLE_MS` after it, which
-   *  is when rasterization is suspended. */
-  private _settleAt = 0;
-  private _settleTimer: unknown = null;
-  private _painting = false;
+  /** The previous style while a restyle draws the new one behind it, or
+   *  null when what is on screen is the current generation. */
+  private _outgoing: Outgoing | null = null;
+  /** The style background the last frame painted — what a restyle keeps
+   *  painting. Remembered rather than recomputed, because `refresh()`
+   *  follows an edit made to the very style object it would be read from. */
+  private _paintedBackground: string | undefined;
+  /** Whether a frame has been painted: before one, a restyle has no
+   *  previous picture to hold. */
+  private _painted = false;
+
   /** Whether any tile has been rasterized in the frame being painted — the
    *  forward-progress guarantee below. */
   private _rastered = false;
@@ -256,10 +327,36 @@ export class MapViewNode extends Node {
 
   constructor(props: Record<string, unknown>, app: unknown) {
     super(ELEMENT, props, app as ConstructorParameters<typeof Node>[2]);
-    // Seeded once. `defaultCamera` is read here and never again, which is
-    // what makes it a *default* rather than a second controlled prop.
+    const given = props.mapController as MapController | undefined;
+    // A bare element's own controller is seeded once: `defaultCamera` is
+    // read here and never again, which is what makes it a *default* rather
+    // than a second controlled prop. `<Map>` seeds the one it hands down.
     const seed = (props.camera ?? props.defaultCamera) as MapCamera | undefined;
-    if (seed) this._camera = { center: { ...seed.center }, zoom: seed.zoom };
+    this._controller = given ?? new MapController(seed);
+    this._ownsController = given === undefined;
+    if (this._ownsController) {
+      this._controller.setProps(props as MapControllerProps);
+    }
+    this._view = {
+      pane: () => this._pane(),
+      scale: () => this._scale,
+      moved: (previous, next, blit) => {
+        // A new pyramid level: different tiles, different labels.
+        if (Math.floor(next.zoom) !== Math.floor(previous.zoom)) {
+          this._labelKey = '';
+        }
+        if (!blit || !this._blitPan(previous, next)) this._repaint('scroll');
+      },
+      // The gesture is over: sharpen. A wake-up, not a repaint — nothing has
+      // moved since the last frame, so what is on screen is still right;
+      // what is needed is a frame to start rasterizing in, and each tile
+      // claims its own box as it lands.
+      settled: () => this._wake('content'),
+      refresh: () => this._restyle(),
+      stats: () => this._stats,
+      focus: () => this.focus(),
+    };
+    this._controller.attach(this._view);
     // A map is a thing you drive with the keyboard as well as the mouse:
     // arrows pan, +/- zoom. Without this it is never focused and no key
     // arrives.
@@ -272,9 +369,7 @@ export class MapViewNode extends Node {
           (error: unknown, tile: TileId & { sourceId: string }) => void
         >('onTileError')?.(entry.error, {
           ...entry.tile,
-          // The data entry is keyed per source, so the id is recoverable
-          // from the key it was built with.
-          sourceId: entry.key.slice(0, entry.key.lastIndexOf(':')),
+          sourceId: entry.sourceId,
         });
       },
       onChange: () => {
@@ -324,26 +419,11 @@ export class MapViewNode extends Node {
   }
 
   private _isDark(): boolean {
-    const theme = this.theme as Record<string, unknown> | undefined;
-    const background = theme?.background;
-    if (typeof background !== 'string') return false;
-    // The same reading `src/code-editor/`'s token themes make: luminance of
-    // the surface the widget sits on, not a flag nobody sets.
-    const hex = background.trim();
-    if (!hex.startsWith('#') || hex.length < 7) return false;
-    const r = parseInt(hex.slice(1, 3), 16);
-    const g = parseInt(hex.slice(3, 5), 16);
-    const b = parseInt(hex.slice(5, 7), 16);
-    return 0.2126 * r + 0.7152 * g + 0.0722 * b < 128;
+    return isDarkTheme(this.theme);
   }
 
   private _palette(): OverlayPalette {
-    const theme = this.theme as Record<string, unknown> | undefined;
-    return {
-      accent: (theme?.accent as string) ?? '#2d6cdf',
-      background: (theme?.background as string) ?? '#ffffff',
-      text: (theme?.text as string) ?? '#111111',
-    };
+    return overlayPalette(this.theme);
   }
 
   private _sources(): MapSource[] {
@@ -351,22 +431,12 @@ export class MapViewNode extends Node {
     return given ? [...given] : [];
   }
 
+  /** What a source is called in its requests and its errors. Not what its
+   *  tiles are cached under — the cache files them under the object. */
   private _sourceId(source: MapSource, index: number): string {
     return source.id ?? `source-${index}`;
   }
 
-  private _minZoom(): number {
-    return this._prop<number>('minZoom') ?? 0;
-  }
-
-  private _maxZoom(): number {
-    return this._prop<number>('maxZoom') ?? 22;
-  }
-
-  private _interactive(): boolean {
-    return this._prop<boolean>('interactive') !== false;
-  }
-
   private _markers(): readonly MapMarker[] {
     return this._prop<readonly MapMarker[]>('markers') ?? [];
   }
@@ -396,8 +466,7 @@ export class MapViewNode extends Node {
   }
 
   camera(): MapCamera {
-    const given = this._prop<MapCamera>('camera');
-    return given ?? this._camera;
+    return this._controller.camera();
   }
 
   /** The camera resolved against the pane. */
@@ -453,46 +522,6 @@ export class MapViewNode extends Node {
 
   // --- camera --------------------------------------------------------------
 
-  /**
-   * Move the camera.
-   *
-   * The one place the camera changes, so the controlled/uncontrolled fork,
-   * the clamping, the notification and — the interesting part — the
-   * decision between a blit and a repaint all live together.
-   */
-  private _applyCamera(next: MapCamera, blit = true): void {
-    const previous = this.camera();
-    const zoom = clamp(next.zoom, this._minZoom(), this._maxZoom());
-    // Latitude is clamped to what Web Mercator can represent; longitude is
-    // not, because the map wraps and a camera just past the antimeridian is
-    // a camera in the next copy of the world.
-    const camera: MapCamera = {
-      center: { lon: next.center.lon, lat: clamp(next.center.lat, -85, 85) },
-      zoom,
-    };
-    if (
-      camera.zoom === previous.zoom &&
-      camera.center.lon === previous.center.lon &&
-      camera.center.lat === previous.center.lat
-    ) {
-      return;
-    }
-    if (this.props.camera === undefined) this._camera = camera;
-    this._prop<(camera: MapCamera) => void>('onCameraChange')?.(camera);
-    if (this._painting) return;
-    // Every camera move defers rasterization, not just a pointer gesture.
-    // An application animating a camera with `panBy` in a loop wants
-    // exactly what a drag wants — composites while it moves, a sharpen when
-    // it stops — and a single programmatic move only pays the settle delay,
-    // which is a seventh of a second.
-    this._touchGesture();
-    if (Math.floor(camera.zoom) !== Math.floor(previous.zoom)) {
-      // A new pyramid level: different tiles, different labels.
-      this._labelKey = '';
-    }
-    if (!blit || !this._blitPan(previous, camera)) this._repaint('scroll');
-  }
-
   /**
    * A pan is a scroll in every way but the bookkeeping, and react-x11#303
    * made the bookkeeping public: `scrollContents` claims the pane, arms the
@@ -548,183 +577,128 @@ export class MapViewNode extends Node {
     return true;
   }
 
-  /** Zoom about a point that must not move — the pointer under a wheel,
-   *  the pane's centre for a key. */
-  private _zoomAbout(delta: number, screenX: number, screenY: number): void {
-    const camera = this.camera();
-    const zoom = clamp(
-      quantize(camera.zoom + delta),
-      this._minZoom(),
-      this._maxZoom(),
-    );
-    if (zoom === camera.zoom) return;
-    const before = this._transform(camera);
-    const anchor = unprojectPoint(before, screenX, screenY);
-    const after = this._transform({ center: camera.center, zoom });
-    // Where the anchor would land at the new zoom, and how far the centre
-    // has to move so it lands where it already is.
-    const moved = projectLngLat(after, anchor);
-    const dx = (moved.x - screenX) / after.world;
-    const dy = (moved.y - screenY) / after.world;
-    this._applyCamera(
-      {
-        zoom,
-        center: unprojectPoint(
-          {
-            ...after,
-            centerX: after.centerX + dx,
-            centerY: after.centerY + dy,
-          },
-          after.paneX,
-          after.paneY,
-        ),
-      },
-      false,
-    );
-  }
-
-  /** Suspend rasterization for the length of a gesture, and arrange for it
-   *  to resume. */
-  private _touchGesture(): void {
-    // Wall-clock here, not the budget clock: this is a 140 ms window, and
-    // it is compared inside a timer callback.
-    this._settleAt = Date.now() + SETTLE_MS;
-    if (this._settleTimer !== null) return;
-    const tick = (): void => {
-      this._settleTimer = null;
-      if (Date.now() < this._settleAt) {
-        this._settleTimer = arm(tick);
-        return;
-      }
-      // The gesture is over: sharpen. A wake-up, not a repaint — nothing
-      // has moved since the last frame, so what is on screen is still
-      // right; what is needed is a frame to start rasterizing in, and each
-      // tile claims its own box as it lands.
-      this._prop<(camera: MapCamera) => void>('onMoveEnd')?.(this.camera());
-      this._wake('content');
-    };
-    this._settleTimer = arm(tick);
-  }
-
+  /** A gesture in flight, or the settle window after a camera move: while
+   *  it lasts nothing is rasterized, so a drag or a wheel is composites
+   *  only. The window is the controller's, and one for both renderers. */
   private get _gesturing(): boolean {
-    return this._gesture !== null || Date.now() < this._settleAt;
+    return this._controller.gesturing;
   }
 
   // --- the imperative surface ----------------------------------------------
+  //
+  // The controller's, for an application holding the element itself rather
+  // than `<Map>`'s handle.
 
   getCamera(): MapCamera {
-    const camera = this.camera();
-    return { center: { ...camera.center }, zoom: camera.zoom };
+    return this._controller.getCamera();
   }
 
   setCamera(camera: Partial<MapCamera>): void {
-    const current = this.camera();
-    this._applyCamera(
-      {
-        center: camera.center ?? current.center,
-        zoom: camera.zoom ?? current.zoom,
-      },
-      false,
-    );
+    this._controller.setCamera(camera);
   }
 
   /** Move by a distance in pane-local logical pixels. */
   panBy(dx: number, dy: number): void {
-    const transform = this._transform();
-    this._applyCamera({
-      zoom: transform.zoom,
-      center: unprojectPoint(
-        transform,
-        transform.paneX + dx,
-        transform.paneY + dy,
-      ),
-    });
+    this._controller.panBy(dx, dy);
   }
 
   zoomIn(step = 1): void {
-    const pane = this._pane();
-    this._zoomAbout(step, pane.width / 2, pane.height / 2);
+    this._controller.zoomIn(step);
   }
 
   zoomOut(step = 1): void {
-    this.zoomIn(-step);
+    this._controller.zoomOut(step);
   }
 
   zoomTo(zoom: number): void {
-    this.setCamera({ zoom });
+    this._controller.zoomTo(zoom);
   }
 
-  fitBounds(
-    bounds: LngLatBounds,
-    options?: { padding?: number; maxZoom?: number },
-  ): void {
-    const pane = this._pane();
-    if (pane.width <= 0 || pane.height <= 0) {
-      // Asked before layout has run — which `fitBounds` in an effect always
-      // is. Remembered and applied at the first paint that has a size.
-      this._pendingFit = { bounds, options };
-      return;
-    }
-    this._applyCamera(
-      cameraForBounds(
-        bounds,
-        { width: pane.width, height: pane.height },
-        {
-          padding: options?.padding ?? 24,
-          tileSize: DEFAULT_TILE_SIZE,
-          minZoom: this._minZoom(),
-          maxZoom: options?.maxZoom ?? this._maxZoom(),
-        },
-      ),
-      false,
-    );
+  fitBounds(bounds: LngLatBounds, options?: FitBoundsOptions): void {
+    this._controller.fitBounds(bounds, options);
   }
 
-  fitMarkers(
-    ids?: readonly string[],
-    options?: { padding?: number; maxZoom?: number },
-  ): void {
-    const wanted = ids ? new Set(ids) : null;
-    const positions: LngLat[] = [];
-    for (const marker of this._markers()) {
-      if (wanted && !wanted.has(marker.id)) continue;
-      positions.push(marker.position);
-    }
-    const bounds = boundsOf(positions);
-    if (bounds) this.fitBounds(bounds, options);
+  fitMarkers(ids?: readonly string[], options?: FitBoundsOptions): void {
+    this._controller.fitMarkers(ids, options);
   }
 
   getBounds(): LngLatBounds {
-    return visibleBounds(this._transform());
+    return this._controller.getBounds();
   }
 
   project(position: LngLat): { x: number; y: number } {
-    return projectLngLat(this._transform(), position);
+    return this._controller.project(position);
   }
 
   unproject(x: number, y: number): LngLat {
-    return unprojectPoint(this._transform(), x, y);
+    return this._controller.unproject(x, y);
   }
 
   markerAt(x: number, y: number): MapMarker | null {
-    return markerAt(this._markers(), this._transform(), x, y);
+    return this._controller.markerAt(x, y);
   }
 
   refresh(): void {
+    this._restyle();
+  }
+
+  /**
+   * Retire every rendered tile — for a new `mapStyle`, or `refresh()` after
+   * an edit made to the style in place. One path for both, and for anything
+   * else that ever needs the map redrawn in a new look.
+   *
+   * The compiled style and the label candidates go with the tiles: both are
+   * readings of the style, and `refresh()` exists because the object was
+   * edited under them. What does not go is the picture on screen. Unless
+   * there is none yet, or `progressive` asked to watch the repaint, it is
+   * held as {@link Outgoing} until the new one is ready to replace it.
+   *
+   * True when it is held. Then nothing on screen changes yet, so the only
+   * claim is the pixel that asks for a frame to start drawing in — and
+   * anything else a commit changed has to claim its own damage.
+   */
+  private _restyle(): boolean {
+    this._prepared = null;
+    this._preparedFrom = null;
+    this._candidates.clear();
+    if (
+      this._outgoing === null &&
+      this._painted &&
+      this._prop<boolean>('progressive') !== true
+    ) {
+      this._outgoing = {
+        generation: this._cache.generation,
+        background: this._paintedBackground,
+        labels: this._labels,
+        labelZoom: this._labelZoom,
+        labelSources: this._labelSources,
+        candidates: this._labelCandidates,
+        family: this._shapedFamily,
+        view: this._viewKey(this._transform(), this._pane()),
+        moved: false,
+        waited: 0,
+        lastDrawn: null,
+      };
+    }
     this._cache.invalidateStyle();
     this._labelKey = '';
-    this._repaint('content');
+    if (this._outgoing === null) {
+      this._repaint('props');
+      return false;
+    }
+    this._wake('props');
+    return true;
+  }
+
+  /** The camera and the pane, as a string that changes when either does. */
+  private _viewKey(transform: Transform, pane: ScreenRect): string {
+    return `${transform.centerX},${transform.centerY},${transform.zoom},${pane.width}x${pane.height}`;
   }
 
   stats(): MapFrameStats | null {
     return this._stats;
   }
 
-  private _pendingFit: {
-    bounds: LngLatBounds;
-    options?: { padding?: number; maxZoom?: number };
-  } | null = null;
-
   // --- painting ------------------------------------------------------------
 
   /** How tall the attribution strip is, in logical pixels — 0 when there is
@@ -735,15 +709,7 @@ export class MapViewNode extends Node {
   }
 
   private _attributionText(): string {
-    const given = this._prop<string>('attribution');
-    if (given !== undefined) return given;
-    const parts: string[] = [];
-    for (const source of this._sources()) {
-      if (source.attribution && !parts.includes(source.attribution)) {
-        parts.push(source.attribution);
-      }
-    }
-    return parts.join(' · ');
+    return attributionOf(this._prop<string>('attribution'), this._sources());
   }
 
   /** How large a tile is rasterized, and how many surface pixels one
@@ -789,7 +755,7 @@ export class MapViewNode extends Node {
     if (!this._visible() || !isMapCanvas(ctx)) return;
 
     const started = now();
-    this._painting = true;
+    const restyleAt = restyleClock.now();
     const scale = this._scale;
     this._frameClip = damage
       ? {
@@ -800,13 +766,10 @@ export class MapViewNode extends Node {
         }
       : null;
 
-    if (this._pendingFit) {
-      const { bounds, options } = this._pendingFit;
-      this._pendingFit = null;
-      this._painting = false;
-      this.fitBounds(bounds, options);
-      this._painting = true;
-    }
+    // A fit asked for before layout had a size — `fitBounds` in an effect —
+    // lands in the first frame that has one, and this frame draws it.
+    this._controller.beginFrame();
+    this._controller.painting = true;
 
     const pane = this._pane();
     const camera = this.camera();
@@ -814,6 +777,7 @@ export class MapViewNode extends Node {
     const style = this._style();
     const frame = this._cache.beginFrame();
     const stats: MapFrameStats = {
+      renderer: 'retained',
       rasterMs: 0,
       drawMs: 0,
       tiles: 0,
@@ -821,6 +785,7 @@ export class MapViewNode extends Node {
       fromAncestor: 0,
       fromDescendant: 0,
       pending: 0,
+      restyling: false,
       labels: 0,
       errors: 0,
       surfaceBytes: 0,
@@ -850,19 +815,68 @@ export class MapViewNode extends Node {
       ? intersectRects(box, this._deviceRect(this._frameClip))
       : box;
     if (!clip) {
-      this._painting = false;
+      this._controller.painting = false;
+      this._controller.paintEnded();
       this._frameClip = null;
       return;
     }
     ctx.rect(clip.x, clip.y, clip.width, clip.height);
     ctx.clip();
 
+    // Rasterization is suspended for the length of a gesture, so a drag or
+    // a wheel is composites only. `rasterBudgetMs` bounds the rest.
+    const budget = this._gesturing
+      ? 0
+      : (this._prop<number>('rasterBudgetMs') ?? 8);
+    const deadline = started + budget;
+    this._rastered = false;
+    const progressive = this._prop<boolean>('progressive') === true;
+
+    // **The work first, then the picture.** Every tile the cover wants is
+    // asked for, and the ones in view are drawn as far as the budget goes —
+    // into their own surfaces, so none of it is on screen yet. Which style
+    // this frame shows is decided only after that, because it depends on
+    // what the work just finished: a restyle swaps in the frame that finds
+    // the view redrawn, and has to know before the first pixel goes down.
+    const sources = this._sources();
+    const holding = this._outgoing !== null && !progressive;
+    const views: VisibleTile[][] = [];
+    for (let i = 0; i < sources.length; i++) {
+      views.push(
+        this._workSource(
+          sources[i],
+          this._sourceId(sources[i], i),
+          transform,
+          pane,
+          style,
+          stats,
+          budget > 0,
+          deadline,
+          holding,
+        ),
+      );
+    }
+    this._settleRestyle(
+      transform,
+      pane,
+      stats,
+      budget,
+      restyleAt,
+      !damage || containsRect(damage, box),
+      progressive,
+    );
+    const outgoing = this._outgoing;
+    stats.restyling = outgoing !== null;
+
     // The style's background under everything: it is what the parts of the
     // world with no tile yet look like, so it is most of what a map looks
-    // like while it loads.
+    // like while it loads. The previous style's while a restyle holds it.
+    const styleBackground = outgoing
+      ? outgoing.background
+      : this._preparedBackground();
+    if (!outgoing) this._paintedBackground = styleBackground;
     const background =
-      (this.style.backgroundColor as string | undefined) ??
-      this._preparedBackground();
+      (this.style.backgroundColor as string | undefined) ?? styleBackground;
     if (background) {
       ctx.fillStyle = background;
       const region = this._frameClip
@@ -871,26 +885,22 @@ export class MapViewNode extends Node {
       ctx.fillRect(region.x, region.y, region.width, region.height);
     }
 
-    // Rasterization is suspended for the length of a gesture, so a drag or
-    // a wheel is composites only. `rasterBudgetMs` bounds the rest.
-    const budget = this._gesturing
-      ? 0
-      : (this._prop<number>('rasterBudgetMs') ?? 8);
-    const deadline = started + budget;
-    this._rastered = false;
-
-    const sources = this._sources();
+    // Only pictures of the generation on screen are composited: the
+    // previous style's while a restyle holds it up, the current one's
+    // otherwise — so a tile last drawn before a switch is never shown in
+    // the style the map was switched away from. `progressive` shows
+    // whatever there is, which is its point.
+    const generation = progressive
+      ? undefined
+      : (outgoing?.generation ?? this._cache.generation);
     for (let i = 0; i < sources.length; i++) {
-      this._paintSource(
+      this._drawSource(
         ctx,
         sources[i],
-        this._sourceId(sources[i], i),
-        transform,
-        pane,
-        style,
+        views[i],
         stats,
-        budget > 0,
-        deadline,
+        progressive,
+        generation,
       );
     }
 
@@ -906,7 +916,9 @@ export class MapViewNode extends Node {
     stats.surfaceBytes = this._cache.surfaceBytes;
     stats.drawMs = now() - started - stats.rasterMs;
     this._stats = stats;
-    this._painting = false;
+    this._painted = true;
+    this._controller.painting = false;
+    this._controller.paintEnded();
     this._frameClip = null;
     void frame;
     this._prop<(stats: MapFrameStats) => void>('onFrame')?.(stats);
@@ -955,8 +967,82 @@ export class MapViewNode extends Node {
     };
   }
 
-  private _paintSource(
-    ctx: MapCanvas,
+  /**
+   * Whether this frame keeps showing the previous style or swaps in the new
+   * one — see {@link Outgoing}.
+   *
+   * The swap waits for every tile in view that has data to have a finished
+   * rendering in the new style, which is `pending` reaching zero: a tile
+   * still loading has nothing to draw and does not hold it, and a tile that
+   * is done waits for the rest rather than going up alone. It is made only
+   * in a frame that repaints the whole pane, because a swap inside a partial
+   * frame would leave the rest of the pane in the old style — so a frame
+   * that finds the view redrawn but was clipped to its one pixel claims the
+   * pane, and the next frame swaps. That is the one full-pane claim a
+   * restyle makes.
+   *
+   * Or, once the view has moved, when {@link RESTYLE_WAIT_MS} of drawing
+   * time has gone by, with whatever is left undrawn.
+   */
+  private _settleRestyle(
+    transform: Transform,
+    pane: ScreenRect,
+    stats: MapFrameStats,
+    budget: number,
+    /** When this frame began, on {@link restyleClock}. */
+    began: number,
+    whole: boolean,
+    progressive: boolean,
+  ): void {
+    const outgoing = this._outgoing;
+    if (!outgoing) return;
+    if (progressive) {
+      // Turned on while a restyle was held: the opt-in holds nothing.
+      this._swapStyle();
+      if (!whole) this._repaint('content');
+      return;
+    }
+    if (!outgoing.moved && this._viewKey(transform, pane) !== outgoing.view) {
+      outgoing.moved = true;
+    }
+    // The clock runs across frames that could draw, two in a row, so the
+    // gap a gesture made — which drew nothing — is not counted when the
+    // next frame after it begins.
+    if (budget > 0) {
+      if (outgoing.lastDrawn !== null) {
+        outgoing.waited += began - outgoing.lastDrawn;
+      }
+      outgoing.lastDrawn = began;
+    } else {
+      outgoing.lastDrawn = null;
+    }
+    const redrawn = stats.pending === 0;
+    // Never by the clock in the middle of a gesture: nothing is drawn
+    // during one, so the view would swap to holes it cannot fill until the
+    // gesture ends.
+    const overdue =
+      budget > 0 && outgoing.moved && outgoing.waited >= RESTYLE_WAIT_MS;
+    if (!redrawn && !overdue) return;
+    if (whole) this._swapStyle();
+    else this._repaint('content');
+  }
+
+  /** The new style goes on screen: every finished tile, its background and
+   *  a label placement of its own, all in the frame being painted. */
+  private _swapStyle(): void {
+    this._outgoing = null;
+    this._cache.swap();
+    this._labelKey = '';
+  }
+
+  /**
+   * A frame's work, for one source: want every tile of its cover, so that
+   * each loads and stays cached, and draw the ones in view into their own
+   * surfaces as far as the budget goes. Returns the ones in view, for
+   * {@link _drawSource} to composite once the frame knows which style it is
+   * showing.
+   */
+  private _workSource(
     source: MapSource,
     sourceId: string,
     transform: Transform,
@@ -966,8 +1052,10 @@ export class MapViewNode extends Node {
     /** False for the length of a gesture, when nothing is rasterized. */
     mayRaster: boolean,
     deadline: number,
-  ): void {
-    const scale = this._scale;
+    /** A restyle is holding the previous style up, so a tile that finishes
+     *  waits for the swap rather than going on screen alone. */
+    holding: boolean,
+  ): VisibleTile[] {
     const p = pyramid(source);
     // The cover goes **deeper than the source cuts**, up to
     // `MAX_OVERZOOM` levels past it, and the data for those tiles comes
@@ -975,16 +1063,27 @@ export class MapViewNode extends Node {
     // overzoomed map sharp: instead of one tile rasterized onto a surface
     // and stretched sixty-four times, there are two hundred and fifty-six
     // tiles sharing one fetch, each drawn at its own natural size, with
-    // detail limited by the data rather than by a bitmap.
-    const cover = tileCover(
-      { ...transform, zoom: transform.zoom },
-      { ...p, maxZoom: p.maxZoom + MAX_OVERZOOM },
-      COVER_PADDING,
+    // detail limited by the data rather than by a bitmap. That is vector
+    // data. An image has no more detail than its pixels, so a raster tile
+    // past the cut is drawn as the whole of its data tile instead — see
+    // `_rasterSquares`.
+    const cover = this._rasterSquares(
+      source,
+      sourceId,
+      tileCover(
+        { ...transform, zoom: transform.zoom },
+        { ...p, maxZoom: p.maxZoom + MAX_OVERZOOM },
+        COVER_PADDING,
+      ),
+      p.maxZoom,
     );
     const zoom = transform.zoom;
     const styleZoom = Math.floor(zoom);
-    const progressive = this._prop<boolean>('progressive') === true;
+    const visible: VisibleTile[] = [];
     for (const entry of cover) {
+      // In the window's logical pixels, the space `pane` is in: what the
+      // overlap tests below, the claim when the tile lands and `_composite`
+      // all take. The pane's origin goes in here and nowhere after.
       const box = {
         x: pane.x + entry.x,
         y: pane.y + entry.y,
@@ -994,13 +1093,14 @@ export class MapViewNode extends Node {
       // Two different questions, and conflating them was a bug worth
       // spelling out. **Whether to work on a tile** is about the pane: the
       // cover is padded, so some of it is off screen and those tiles are
-      // wanted (so they load) but never drawn. **Whether to composite it**
+      // wanted (so they load) but never drawn. They are wanted on *every*
+      // frame, however small its damage rect, because the cache's `sweep`
+      // cancels any load a frame did not want. **Whether to composite it**
       // is about this pass's damage rect, which may be far smaller —
       // including the deliberately tiny claim a rasterization continuation
-      // makes, which must still let the rasterizer run.
+      // makes, which must still let the rasterizer run. The first is asked
+      // here, and the second in `_drawSource`.
       const onScreen = rectsOverlap(box, pane);
-      const inPass =
-        this._frameClip === null || rectsOverlap(box, this._frameClip);
       const cached = this._cache.want(
         source,
         sourceId,
@@ -1009,6 +1109,7 @@ export class MapViewNode extends Node {
         subTileOf(entry.tile, p.maxZoom),
       );
       if (!onScreen) continue;
+      visible.push({ entry, box, cached });
       stats.tiles++;
       if (cached.status === 'error') stats.errors++;
 
@@ -1020,6 +1121,8 @@ export class MapViewNode extends Node {
           size,
           cached.raster ? 0 : styleZoom,
           (edge: number) => this._makeSurface(edge),
+          // A raster tile is the provider's image, the same in every style.
+          !cached.raster,
         );
         if (drawing && drawing.progress !== -1) {
           if (cached.raster) {
@@ -1048,17 +1151,105 @@ export class MapViewNode extends Node {
           // goes blank between them. Claim the box it occupies, because
           // *that* is the pixel change this whole sequence of frames was
           // for; the frames before it claimed almost nothing.
-          if (this._cache.promote(cached)) this._claim(box, 'content');
+          //
+          // Not while a restyle holds the previous style up, though: one
+          // tile in the new style among the rest in the old is the
+          // patchwork the hold is there to prevent. It waits, finished, for
+          // `_swapStyle` to put the whole view up at once. A raster tile
+          // does not wait — it is in no style, so it cannot make one.
+          if ((!holding || !drawing.styled) && this._cache.promote(cached)) {
+            this._claim(box, 'content');
+          }
         }
         // "Pending" means *there is work left that this map could still
         // do*, and nothing weaker — because `paint` asks for another frame
-        // while it is non-zero. A tile whose surface could not be made (a
-        // backend that has none) never becomes drawable, and counting it
-        // would spin the frame clock at the refresh rate forever,
-        // repainting a map that cannot change.
-        if (cached.drawing) stats.pending++;
+        // while it is non-zero, and a restyle swaps when it reaches zero. A
+        // tile whose surface could not be made (a backend that has none)
+        // never becomes drawable, and counting it would spin the frame
+        // clock at the refresh rate forever, repainting a map that cannot
+        // change. A finished tile waiting for a restyle's swap has nothing
+        // left to do either.
+        if (cached.drawing && cached.drawing.progress !== -1) stats.pending++;
       }
+    }
+    return visible;
+  }
+
+  /**
+   * The cover, with every **raster** tile past the source's depth drawn as
+   * the whole of its data tile — once, however many of its cells there are.
+   *
+   * The cover goes deeper than the source cuts because that is what makes
+   * vector data sharp there: each cell is rasterized from its data tile's
+   * features, through the cell (`sub`, in `_rasterize`). An image has no
+   * detail finer than its pixels and no drawing it through a cell: a raster
+   * cell was drawn by uploading the image, all of it, so each cell showed
+   * its data tile whole, shrunk into its own square. Past a raster source's
+   * depth the map was a grid of miniatures of each tile — 2×2 one level
+   * past, 4×4 two — and a 256px source is read a level deeper than the
+   * view, so for `osmRasterSource`, which cuts at 19, that was every zoom
+   * from 19 up.
+   *
+   * A raster map past its provider's depth draws the deepest images larger,
+   * and so does this. The square is where the cover at the source's own
+   * depth puts the data tile, and it is drawn from that tile's own surface —
+   * the one the view at that depth draws, so crossing into overzoom uploads
+   * nothing.
+   *
+   * Which kind a tile is, is known once its data is in. Until then a cell
+   * stays a cell, and is covered from its neighbours in the pyramid like
+   * any other hole. Asking is a `want`, which the frame's own pass repeats
+   * for a cell kept here, and which is idempotent.
+   */
+  private _rasterSquares(
+    source: MapSource,
+    sourceId: string,
+    cover: TileCoverEntry[],
+    maxZoom: number,
+  ): TileCoverEntry[] {
+    // A cover is one level, so every entry in it is past the cut or none is.
+    if (cover.length === 0 || cover[0].tile.z <= maxZoom) return cover;
+    const out: TileCoverEntry[] = [];
+    const squares = new Set<string>();
+    for (const cell of cover) {
+      const cached = this._cache.want(
+        source,
+        sourceId,
+        cell.tile,
+        dataTileFor(cell.tile, maxZoom),
+        subTileOf(cell.tile, maxZoom),
+      );
+      if (!cached.raster) {
+        out.push(cell);
+        continue;
+      }
+      const square = dataSquareOf(cell, maxZoom);
+      const key = `${square.worldCopy}:${tileKey(square.tile)}`;
+      if (squares.has(key)) continue;
+      squares.add(key);
+      out.push(square);
+    }
+    return out;
+  }
 
+  /**
+   * A frame's picture, for one source: composite each tile in view from its
+   * own finished rendering or, for a tile with none, from a finished
+   * ancestor or descendants. Only renderings of `generation` count, and
+   * `undefined` counts any — which is `progressive`.
+   */
+  private _drawSource(
+    ctx: MapCanvas,
+    source: MapSource,
+    visible: readonly VisibleTile[],
+    stats: MapFrameStats,
+    progressive: boolean,
+    generation: number | undefined,
+  ): void {
+    const scale = this._scale;
+    for (const { entry, box, cached } of visible) {
+      const inPass =
+        this._frameClip === null || rectsOverlap(box, this._frameClip);
       // What is composited is `shown`, which is **finished by
       // construction** — a rendering only becomes `shown` when its last
       // style run is done. So a tile appears whole rather than as water,
@@ -1070,14 +1261,13 @@ export class MapViewNode extends Node {
       // behaviour and is honest about what the renderer is doing.
       const showing =
         progressive && cached.drawing ? cached.drawing : cached.shown;
-      if (showing) {
+      if (showing && drawnFor(showing, generation)) {
         if (!inPass) continue;
         this._composite(
           ctx,
           showing.surface,
           showing.size,
           box,
-          pane,
           scale,
           0,
           0,
@@ -1086,15 +1276,10 @@ export class MapViewNode extends Node {
         stats.ready++;
         continue;
       }
-      // Nothing of this tile yet — a first load, which no buffering can
-      // help. Borrow the ancestor that is already drawn, scaled up: that is
-      // the difference between a map that fills in and one that flashes
-      // empty on every zoom.
-      if (!inPass) continue;
 
-      // Nothing of this tile yet — a first load, which no buffering can
-      // help. Two ways to cover it, and which is available says which way
-      // the camera moved.
+      // Nothing of this tile to show — a first load, which no buffering can
+      // help, or a picture in a style the map is not showing. Two ways to
+      // cover it, and which is available says which way the camera moved.
       //
       // **Zooming in**, the tile already in hand is this one's *ancestor*:
       // one composite, scaled up, blurry but complete. **Zooming out**, the
@@ -1104,55 +1289,79 @@ export class MapViewNode extends Node {
       // background — with the labels and the markers still drawn over it —
       // until the coarser tile had been fetched, rasterized and composited.
       //
-      // Descendants win when they cover the whole square, because they are
-      // sharper and they are the level the user is coming *from*; the
-      // ancestor wins when they do not, because a complete blurry picture
-      // beats a sharp one with holes in it.
-      const kids = this._cache.descendantsWithSurface(sourceId, entry.tile);
-      const covered =
-        kids.length > 0 && kids.length === kids[0].span * kids[0].span;
-      const ancestor = covered
-        ? null
-        : this._cache.ancestorWithSurface(sourceId, entry.tile);
-      if (ancestor?.shown) {
-        const up = entry.tile.z - ancestor.tile.z;
+      // Both, in one square: the descendants wherever there are any, because
+      // they are sharper and they are the level the user is coming *from*,
+      // and the ancestor in the gaps between them. The first cut chose one
+      // for the whole square — descendants only when they tiled it, and
+      // only when no ancestor was in hand — and a zoom out lands at the
+      // edges of the level it left, where they never tile it: that was the
+      // background there, sharp tiles in hand or not.
+      //
+      // Looked up whether or not this pass draws the tile, because the
+      // lookup is what stamps a piece as in use: a piece covering a hole is
+      // on screen, and an unstamped entry is the first thing eviction takes
+      // — which, in the one-pixel frames a redraw runs in, was every piece
+      // but the one under that pixel. A restyle keeps such pieces on screen
+      // for as long as its redraw takes.
+      const below = this._cache.descendantsWithSurface(
+        source,
+        entry.tile,
+        generation,
+      );
+      const ancestor =
+        below.gaps.length > 0
+          ? this._cache.ancestorWithSurface(
+              source,
+              entry.tile,
+              undefined,
+              generation,
+            )
+          : null;
+      if (!inPass) continue;
+      for (const piece of below.pieces) {
+        const edge = entry.size / piece.span;
+        this._composite(
+          ctx,
+          piece.value.shown!.surface,
+          piece.value.shown!.size,
+          {
+            x: box.x + piece.x * edge,
+            y: box.y + piece.y * edge,
+            width: edge,
+            height: edge,
+          },
+          scale,
+          0,
+          0,
+          1,
+        );
+      }
+      if (below.pieces.length > 0) stats.fromDescendant++;
+      if (!ancestor?.shown) continue;
+      for (const gap of below.gaps) {
+        // The gap is a tile `log2(span)` levels under this one, and the
+        // ancestor is `up` levels over that: the same sub-square arithmetic
+        // as a whole tile, one level set deeper.
+        const edge = entry.size / gap.span;
+        const up = entry.tile.z + Math.log2(gap.span) - ancestor.tile.z;
         const span = 1 << up;
-        const fx = entry.tile.x - (ancestor.tile.x << up);
-        const fy = entry.tile.y - (ancestor.tile.y << up);
         this._composite(
           ctx,
           ancestor.shown.surface,
           ancestor.shown.size,
-          box,
-          pane,
+          {
+            x: box.x + gap.x * edge,
+            y: box.y + gap.y * edge,
+            width: edge,
+            height: edge,
+          },
           scale,
-          fx,
-          fy,
+          entry.tile.x * gap.span + gap.x - (ancestor.tile.x << up),
+          entry.tile.y * gap.span + gap.y - (ancestor.tile.y << up),
           span,
         );
-        stats.fromAncestor++;
-      } else if (kids.length > 0) {
-        for (const kid of kids) {
-          const piece = entry.size / kid.span;
-          this._composite(
-            ctx,
-            kid.entry.shown!.surface,
-            kid.entry.shown!.size,
-            {
-              x: box.x + kid.x * piece,
-              y: box.y + kid.y * piece,
-              width: piece,
-              height: piece,
-            },
-            pane,
-            scale,
-            0,
-            0,
-            1,
-          );
-        }
-        stats.fromDescendant++;
       }
+      stats.fromAncestor++;
     }
   }
 
@@ -1303,14 +1512,23 @@ export class MapViewNode extends Node {
    * point. Clipping the destination and moving the source rectangle to
    * match keeps the scale factor `sw/dw` exactly what it was, so nothing
    * about the picture changes.
+   *
+   * **`dest` is already in the window's space**, the one `pane` is in — a
+   * tile's `box` is `pane.x + entry.x` — so nothing is added to it here.
+   * The pane's origin used to be added a second time, which drew every
+   * tile that far right of and below where the markers, labels and
+   * overlays put the same place. A constant offset on screen is a
+   * different distance on the ground at every zoom, so it looked like a
+   * marker sliding across the map as it zoomed, and like nothing at all as
+   * it panned, where the blit moves both together. Every test mounted the
+   * map at the window's origin, where the offset is zero.
    */
   private _composite(
     ctx: MapCanvas,
     surface: SurfaceLike,
     size: number,
-    /** Where it lands, in pane-local logical pixels. */
+    /** Where it lands, in the window's logical pixels. */
     dest: ScreenRect,
-    pane: ScreenRect,
     scale: number,
     /** Which sub-square of the surface to take, in `subSpan`ths. */
     subX: number,
@@ -1318,10 +1536,10 @@ export class MapViewNode extends Node {
     subSpan: number,
   ): void {
     if (!ctx.drawImage || size <= 0) return;
-    const x0 = Math.round((pane.x + dest.x) * scale);
-    const y0 = Math.round((pane.y + dest.y) * scale);
-    const x1 = Math.round((pane.x + dest.x + dest.width) * scale);
-    const y1 = Math.round((pane.y + dest.y + dest.height) * scale);
+    const x0 = Math.round(dest.x * scale);
+    const y0 = Math.round(dest.y * scale);
+    const x1 = Math.round((dest.x + dest.width) * scale);
+    const y1 = Math.round((dest.y + dest.height) * scale);
     if (x1 <= x0 || y1 <= y0) return;
 
     // The clip is the content box — device pixels, like everything core
@@ -1368,7 +1586,11 @@ export class MapViewNode extends Node {
     const fonts = (this.app as { fonts?: FontsLike } | undefined)?.fonts;
     if (!fonts) return; // headless: nothing to shape with
     const text = this.resolvedTextStyle();
+    const outgoing = this._outgoing;
+    // While a restyle holds the previous style up, its labels are set in
+    // its face.
     const family =
+      outgoing?.family ??
       this._prop<MapStyle>('mapStyle')?.fontFamily ??
       this._defaultStyle?.fontFamily ??
       text.family;
@@ -1377,41 +1599,92 @@ export class MapViewNode extends Node {
     } else {
       this._shaper.reconfigure(fonts, family, this._scale);
     }
-    const key = `${quantize(transform.zoom)}|${this._cache.generation}`;
+    const clip = this._frameClip ? { ...this._frameClip } : null;
+    if (outgoing) {
+      // The labels that were on screen when the restyle began, and not the
+      // new style's, which would go up over a map still drawn in the old
+      // one. Re-placed only when they have to be — a placement is for one
+      // zoom, and a source taken off the map takes its names with it — and
+      // from what they were placed from, since the style that produced
+      // that is being replaced, or was edited in place.
+      const zoom = quantizeZoom(transform.zoom);
+      const sources = this._sources();
+      if (
+        zoom !== outgoing.labelZoom ||
+        !sameSources(sources, outgoing.labelSources)
+      ) {
+        const candidates: LabelCandidate[] = [];
+        for (const source of sources) {
+          for (const candidate of outgoing.candidates.get(source) ?? []) {
+            candidates.push(candidate);
+          }
+        }
+        outgoing.labels = placeLabels(
+          candidates,
+          transform.world,
+          this._shaper,
+        );
+        outgoing.labelZoom = zoom;
+        outgoing.labelSources = sources;
+      }
+      stats.labels = drawLabels(
+        ctx,
+        outgoing.labels,
+        transform,
+        pane,
+        this._scale,
+        clip,
+        this._shaper,
+      );
+      return;
+    }
+    this._shapedFamily = family;
+    const key = `${quantizeZoom(transform.zoom)}|${this._cache.generation}`;
     if (key !== this._labelKey) {
       this._labelKey = key;
       const styleZoom = Math.floor(transform.zoom);
       // Labels come from the tile the **data** came from, at the depth that
       // source actually cuts — past which many renderings share one tile
       // and collecting per rendering would place every label `span²` times.
-      const wanted = new Set(
-        this._sources().map((source) =>
-          Math.min(styleZoom, pyramid(source).maxZoom),
-        ),
-      );
+      //
+      // And only from the sources on the map now. The cache keeps a
+      // provider's tiles after it is switched away, so that switching back
+      // is free; collecting from all of them drew the old provider's place
+      // names over the new one's map until eviction reached them.
+      const sources = this._sources();
+      const wanted = new Map<MapSource, number>();
+      for (const source of sources) {
+        wanted.set(source, Math.min(styleZoom, pyramid(source).maxZoom));
+      }
       const candidates: LabelCandidate[] = [];
+      const bySource = new Map<MapSource, LabelCandidate[]>();
       for (const cached of this._cache.dataEntries()) {
         if (cached.status !== 'ready' || !cached.vector) continue;
-        if (!wanted.has(cached.tile.z)) continue;
+        if (wanted.get(cached.source) !== cached.tile.z) continue;
         const at = `${cached.key}|${styleZoom}`;
         let found = this._candidates.get(at);
         if (!found) {
-          found = collectLabels(
-            cached.vector,
-            cached.tile,
-            style,
-            styleZoom,
-            this._geometry,
-          );
+          found = collectLabels(cached.vector, cached.tile, style, styleZoom);
           // Bounded the way the shaper's cache is: a map panned across a
           // continent must not turn this into a leak, and rebuilding a
           // tile's candidates is one walk over its symbol layers.
           if (this._candidates.size > 512) this._candidates.clear();
           this._candidates.set(at, found);
         }
-        for (const candidate of found) candidates.push(candidate);
+        let own = bySource.get(cached.source);
+        if (!own) {
+          own = [];
+          bySource.set(cached.source, own);
+        }
+        for (const candidate of found) {
+          candidates.push(candidate);
+          own.push(candidate);
+        }
       }
       this._labels = placeLabels(candidates, transform.world, this._shaper);
+      this._labelZoom = quantizeZoom(transform.zoom);
+      this._labelSources = sources;
+      this._labelCandidates = bySource;
     }
     stats.labels = drawLabels(
       ctx,
@@ -1419,7 +1692,7 @@ export class MapViewNode extends Node {
       transform,
       pane,
       this._scale,
-      this._frameClip ? { ...this._frameClip } : null,
+      clip,
       this._shaper,
     );
   }
@@ -1440,185 +1713,63 @@ export class MapViewNode extends Node {
   ): void {
     const text = this._attributionText();
     if (!text || !this._shaper) return;
-    const shaped = this._shaper.shape(text, 9, palette.text);
+    const shaped = this._shaper.shape(text, ATTRIBUTION_SIZE, palette.text);
     if (!shaped) return;
-    const scale = this._scale;
-    const padding = 4;
-    const width = shaped.width + padding * 2;
-    const height = shaped.height + padding;
-    const x = pane.x + pane.width - width;
-    const y = pane.y + pane.height - height;
+    const at = attributionLayout(shaped, pane, this._scale);
     ctx.save();
-    if (ctx.globalAlpha !== undefined) ctx.globalAlpha = 0.72;
+    if (ctx.globalAlpha !== undefined) ctx.globalAlpha = ATTRIBUTION_OPACITY;
     ctx.fillStyle = palette.background;
-    ctx.fillRect(
-      Math.round(x * scale),
-      Math.round(y * scale),
-      Math.ceil(width * scale),
-      Math.ceil(height * scale),
-    );
+    ctx.fillRect(at.box.x, at.box.y, at.box.width, at.box.height);
     if (ctx.globalAlpha !== undefined) ctx.globalAlpha = 1;
-    shaped.layout.draw(
-      ctx,
-      Math.round((x + padding) * scale),
-      Math.round((y + padding / 2) * scale),
-    );
+    shaped.layout.draw(ctx, at.x, at.y);
     ctx.restore();
   }
 
   // --- behaviour -----------------------------------------------------------
 
-  /** An event's position in the pane's own logical pixels. A synthetic
-   *  event's `x`/`y` are logical and relative to the window, so only the
-   *  pane's own origin has to come off. */
-  private _point(ev: MouseEvent): { x: number; y: number } {
+  /**
+   * An event as the controller reads it. A synthetic event's `x`/`y` are
+   * logical and relative to the window, so only the pane's own origin has
+   * to come off.
+   */
+  private _input(ev: MouseEvent): MapPointerInput {
     const pane = this._pane();
-    return { x: ev.x - pane.x, y: ev.y - pane.y };
-  }
-
-  private _pointerEvent(
-    ev: MouseEvent,
-    marker: MapMarker | null,
-  ): MapPointerEvent {
-    const point = this._point(ev);
     return {
-      lngLat: unprojectPoint(this._transform(), point.x, point.y),
-      x: point.x,
-      y: point.y,
-      marker,
-      shiftKey: ev.shiftKey ?? false,
-      ctrlKey: ev.ctrlKey ?? false,
-      altKey: ev.altKey ?? false,
-      metaKey: ev.metaKey ?? false,
-      button: ev.button ?? 1,
+      x: ev.x - pane.x,
+      y: ev.y - pane.y,
+      button: ev.button,
+      // The click count core puts on a press and on its release, which the
+      // declarations do not name.
+      detail: (ev as { detail?: number }).detail,
+      shiftKey: ev.shiftKey,
+      ctrlKey: ev.ctrlKey,
+      altKey: ev.altKey,
+      metaKey: ev.metaKey,
     };
   }
 
   override defaultMouseDown(ev: MouseEvent): void {
-    const point = this._point(ev);
-    const marker = markerAt(
-      this._markers(),
-      this._transform(),
-      point.x,
-      point.y,
-    );
-    if (marker) {
-      this._gesture = {
-        kind: 'marker',
-        id: marker.id,
-        startX: point.x,
-        startY: point.y,
-      };
-      ev.capturePointer?.();
-      return;
-    }
-    if (!this._interactive()) {
-      // Not a pan, but still a press: the release is what makes a click,
-      // and an application listening for one on a frozen map should get it.
-      this._gesture = {
-        kind: 'pan',
-        startX: point.x,
-        startY: point.y,
-        lastX: point.x,
-        lastY: point.y,
-        moved: false,
-      };
-      ev.capturePointer?.();
-      return;
-    }
-    this._gesture = {
-      kind: 'pan',
-      startX: point.x,
-      startY: point.y,
-      lastX: point.x,
-      lastY: point.y,
-      moved: false,
-    };
-    this.focus();
+    // A pan takes the focus, so the arrows work next. A press on a marker,
+    // or on a map that does not move, is captured all the same: its release
+    // is a click, and an application listening for one should get it.
+    if (this._controller.pointerDown(this._input(ev)) === 'pan') this.focus();
     ev.capturePointer?.();
   }
 
   override defaultMouseDrag(ev: MouseEvent): void {
-    const gesture = this._gesture;
-    if (!gesture || gesture.kind !== 'pan') return;
-    if (!this._interactive()) return;
-    const point = this._point(ev);
-    if (
-      !gesture.moved &&
-      Math.abs(point.x - gesture.startX) < DRAG_THRESHOLD &&
-      Math.abs(point.y - gesture.startY) < DRAG_THRESHOLD
-    ) {
-      return;
-    }
-    gesture.moved = true;
-    // Whole device pixels, because that is what the blit can shift — a
-    // fractional pan would decline it every frame and repaint the pane.
-    const scale = this._scale;
-    const dx = Math.round((point.x - gesture.lastX) * scale) / scale;
-    const dy = Math.round((point.y - gesture.lastY) * scale) / scale;
-    if (dx === 0 && dy === 0) return;
-    gesture.lastX += dx;
-    gesture.lastY += dy;
-    this._touchGesture();
-    this.panBy(-dx, -dy);
+    this._controller.pointerDrag(this._input(ev));
   }
 
   override defaultMouseUp(ev: MouseEvent): void {
-    const gesture = this._gesture;
-    this._gesture = null;
-    if (!gesture) return;
-    const point = this._point(ev);
-    if (gesture.kind === 'marker') {
-      const marker = this._markers().find((m) => m.id === gesture.id);
-      if (
-        marker &&
-        Math.abs(point.x - gesture.startX) < DRAG_THRESHOLD &&
-        Math.abs(point.y - gesture.startY) < DRAG_THRESHOLD
-      ) {
-        const event = this._pointerEvent(ev, marker);
-        this._prop<(m: MapMarker, e: MapPointerEvent) => void>(
-          'onMarkerClick',
-        )?.(marker, event);
-        this._prop<(e: MapPointerEvent) => void>('onMapClick')?.(event);
-      }
-      return;
-    }
-    if (gesture.moved) {
-      this._touchGesture();
-      return;
-    }
-    this._prop<(e: MapPointerEvent) => void>('onMapClick')?.(
-      this._pointerEvent(ev, null),
-    );
+    this._controller.pointerUp(this._input(ev));
   }
 
   override defaultMouseMove(ev: MouseEvent): void {
-    const notify =
-      this._prop<(m: MapMarker | null, e: MapPointerEvent | null) => void>(
-        'onMarkerHover',
-      );
-    if (!notify) return;
-    const point = this._point(ev);
-    const marker = markerAt(
-      this._markers(),
-      this._transform(),
-      point.x,
-      point.y,
-    );
-    const id = marker?.id ?? null;
-    if (id === this._hover) return;
-    this._hover = id;
-    notify(marker, this._pointerEvent(ev, marker));
+    this._controller.pointerMove(this._input(ev));
   }
 
   override defaultMouseLeave(): void {
-    if (this._hover === null) return;
-    this._hover = null;
-    // No event: the pointer has left the map, so there is no position on it
-    // to report and inventing one would be worse than saying so.
-    this._prop<(m: MapMarker | null, e: MapPointerEvent | null) => void>(
-      'onMarkerHover',
-    )?.(null, null);
+    this._controller.pointerLeave();
   }
 
   /**
@@ -1628,103 +1779,106 @@ export class MapViewNode extends Node {
    * scroll chain never hands over.
    */
   override defaultWheel(ev: WheelEvent): void {
-    if (!this._interactive()) return;
     const pane = this._pane();
-    this._touchGesture();
-    this._zoomAbout(
-      -(ev.deltaY ?? 0) * WHEEL_ZOOM * 0.02,
-      ev.x - pane.x,
-      ev.y - pane.y,
-    );
-    // Consumed whether or not the zoom moved: a wheel over a map is never
-    // meant for whatever is behind it.
-    ev.preventDefault();
+    const point = { x: ev.x - pane.x, y: ev.y - pane.y };
+    // Consumed whether or not the zoom moved: a wheel over a map that moves
+    // is never meant for whatever is behind it.
+    // `ev.smooth` is the device: a wheel that clicks whole notches, or a
+    // touchpad whose valuators measured the scroll. The controller eases
+    // the one and applies the other (`MapController.wheel`).
+    if (this._controller.wheel(point, ev.deltaY ?? 0, ev.smooth === true)) {
+      ev.preventDefault();
+    }
   }
 
   override defaultKeyDown(ev: KeyboardEvent): void {
-    // `Node` declares the default actions optional — an element that has
-    // no behaviour of its own simply has none — so calling up is an
-    // optional call rather than a plain one.
-    if (!this._interactive()) {
-      super.defaultKeyDown?.(ev);
+    if (this._controller.keyDown(ev.keysym ?? 0, ev.shiftKey ?? false)) {
+      ev.preventDefault();
       return;
     }
-    const pane = this._pane();
-    const step = ev.shiftKey ? 200 : 60;
-    switch (ev.keysym) {
-      case 0xff51: // XK_Left
-        this.panBy(-step, 0);
-        break;
-      case 0xff53: // XK_Right
-        this.panBy(step, 0);
-        break;
-      case 0xff52: // XK_Up
-        this.panBy(0, -step);
-        break;
-      case 0xff54: // XK_Down
-        this.panBy(0, step);
-        break;
-      case 0x002b: // XK_plus
-      case 0x003d: // XK_equal
-      case 0xffab: // XK_KP_Add
-        this._zoomAbout(1, pane.width / 2, pane.height / 2);
-        break;
-      case 0x002d: // XK_minus
-      case 0xffad: // XK_KP_Subtract
-        this._zoomAbout(-1, pane.width / 2, pane.height / 2);
-        break;
-      default:
-        // Everything else goes to the base class, which is what keeps the
-        // selection keys and Space/Enter-as-a-click working.
-        super.defaultKeyDown?.(ev);
-        return;
-    }
-    ev.preventDefault();
+    // Everything else goes to the base class, which is what keeps the
+    // selection keys and Space/Enter-as-a-click working. `Node` declares the
+    // default actions optional — an element that has no behaviour of its
+    // own simply has none — so calling up is an optional call.
+    super.defaultKeyDown?.(ev);
   }
 
+  /** What a screen reader meets: the markers in view, as buttons — the
+   *  controller's answer, which both renderers give. */
+  override a11yScene(): A11ySceneItem[] {
+    if (!this._visible()) return [];
+    return this._controller.markerScene();
+  }
+
+  /** Every source this element has been handed, and how many `sources`
+   *  changes in a row have made a slot anew — see `_noticeRemade`. */
+  private readonly _seenSources = new WeakSet<MapSource>();
+  private _remade = 0;
+  private _warnedRemade = false;
+
   /**
-   * What a screen reader meets.
+   * Say so, once, when the application makes a source anew on every
+   * render.
    *
-   * A map is one painted rectangle to an assistive technology, and its
-   * markers are the only things in it that are *objects* rather than
-   * cartography — so those are the scene, and the map itself carries the
-   * camera in its description. Announcing every road would be worse than
-   * announcing none.
+   * Tiles are cached per source object (see `./tiles.ts`), so a source
+   * rebuilt on each render starts from an empty cache on each render: every
+   * tile in view is fetched again, and the map is its background until they
+   * land. Under a controlled camera that is a render per pan step — a drag
+   * across a blank map that fetches the whole view on every step.
+   *
+   * What gives it away is a slot handed a source this element has never
+   * had, looking like the one it replaces — the same id, pyramid and
+   * attribution — on three `sources` changes in a row. A provider switch
+   * does that once, and a switch back to a source already shown does not
+   * count at all. Looking alike is only ever the basis of a warning, never
+   * of a cache key: two providers can look exactly alike.
+   *
+   * `process` and `console` come off `globalThis` because `src/` compiles
+   * with `types: []`, as for the terminal's warning.
    */
-  override a11yScene(): A11ySceneItem[] {
-    if (!this._visible()) return [];
-    const transform = this._transform();
-    const pane = this._pane();
-    const scale = this._scale;
-    const items: A11ySceneItem[] = [];
-    for (const marker of this._markers()) {
-      const rect = markerRect(marker, transform);
-      if (
-        rect.x + rect.width < 0 ||
-        rect.y + rect.height < 0 ||
-        rect.x > pane.width ||
-        rect.y > pane.height
-      ) {
-        continue;
+  private _noticeRemade(
+    before: readonly MapSource[] | undefined,
+    next: readonly MapSource[] | undefined,
+  ): void {
+    if (this._warnedRemade) return;
+    let slot = -1;
+    if (before && next) {
+      const length = Math.min(before.length, next.length);
+      for (let i = 0; i < length && slot < 0; i++) {
+        const was = before[i];
+        const now = next[i];
+        if (
+          was &&
+          now &&
+          now !== was &&
+          !this._seenSources.has(now) &&
+          now.id === was.id &&
+          now.tileSize === was.tileSize &&
+          now.minZoom === was.minZoom &&
+          now.maxZoom === was.maxZoom &&
+          now.attribution === was.attribution
+        ) {
+          slot = i;
+        }
       }
-      items.push({
-        id: `marker:${marker.id}`,
-        // Device pixels in the owning window's coordinates, which is what
-        // an a11y scene rect is — the same space as `abs`.
-        rect: {
-          x: (pane.x + rect.x) * scale,
-          y: (pane.y + rect.y) * scale,
-          width: rect.width * scale,
-          height: rect.height * scale,
-        },
-        role: 'button',
-        name:
-          marker.title ??
-          `${marker.position.lat.toFixed(4)}, ${marker.position.lon.toFixed(4)}`,
-        states: { selected: marker.selected ?? false },
-      });
     }
-    return items;
+    for (const source of before ?? []) this._seenSources.add(source);
+    for (const source of next ?? []) this._seenSources.add(source);
+    this._remade = slot < 0 ? 0 : this._remade + 1;
+    if (this._remade < 3) return;
+    this._warnedRemade = true;
+    const g = globalThis as {
+      process?: { env?: Record<string, string | undefined> };
+      console?: { warn(message: string): void };
+    };
+    if (g.process?.env?.NODE_ENV === 'production') return;
+    g.console?.warn(
+      `@react-x11/components: <Map> was handed a new sources[${slot}] on ` +
+        'three renders in a row. Tiles are cached per source object, so ' +
+        'each one started from an empty cache and fetched every tile in ' +
+        'view again. If it is the same provider each time, make it once — ' +
+        'at module scope, or with useMemo.',
+    );
   }
 
   override applyProps(
@@ -1733,25 +1887,38 @@ export class MapViewNode extends Node {
   ): void {
     const before = prev ?? this.props;
     super.applyProps(next, prev);
+    if (this._ownsController) {
+      this._controller.setProps(this.props as MapControllerProps);
+    }
+    if (next.sources !== before.sources) {
+      this._noticeRemade(
+        before.sources as readonly MapSource[] | undefined,
+        next.sources as readonly MapSource[] | undefined,
+      );
+    }
     // Every one of these is in `selfDamagedProps`, so the commit claimed
     // nothing for them and this is the only claim there will be.
-    if (next.mapStyle !== before.mapStyle) {
-      this._prepared = null;
-      this._preparedFrom = null;
-      this._candidates.clear();
-      this._cache.invalidateStyle();
-      this._labelKey = '';
-      this._repaint('props');
-      return;
-    }
+    //
+    // A restyle that repainted the pane covers everything else the commit
+    // changed. One that is held claims a single pixel — nothing on screen
+    // changes until the swap — so a camera or the markers moved in the same
+    // commit still have to claim their own damage below.
+    if (next.mapStyle !== before.mapStyle && !this._restyle()) return;
     if (next.sources !== before.sources) {
+      // Nothing to throw away here: tiles are filed under the source
+      // object, so a new provider starts empty, and one switched away from
+      // keeps the tiles it has for when it comes back — its loads still in
+      // flight are cancelled by the next frame's `sweep`, since nothing asks
+      // for them. Only the label placement is stale.
       this._labelKey = '';
       this._repaint('props');
       return;
     }
     if (next.camera !== before.camera && next.camera !== undefined) {
       const camera = next.camera as MapCamera;
-      const previous = (before.camera as MapCamera | undefined) ?? this._camera;
+      const previous =
+        (before.camera as MapCamera | undefined) ??
+        this._controller.ownCamera();
       if (
         camera.zoom !== previous.zoom ||
         camera.center.lon !== previous.center.lon ||
@@ -1807,13 +1974,13 @@ export class MapViewNode extends Node {
   }
 
   override destroySubtree(): void {
-    if (this._settleTimer !== null) {
-      timers.clearTimeout?.(this._settleTimer);
-      this._settleTimer = null;
-    }
+    this._controller.detach(this._view);
+    if (this._ownsController) this._controller.dispose();
     this._cache.destroy();
     this._candidates.clear();
     this._labels = [];
+    this._labelCandidates = new Map();
+    this._outgoing = null;
     super.destroySubtree();
   }
 }