@react-x11/components 0.8.0 → 0.10.0

package/dist/maps/node.js

@@ -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
@@ -29,13 +30,15 @@
 // nothing is ever rasterized during a drag.
 import { Node } from 'react-x11/node';
 import { Surface } from 'react-x11/ntk';
-import { GeometryBuffer } from './mvt.js';
+import { MapController, quantizeZoom } from './controller.js';
 import { BATCH_VERTICES, DrawScratch, drawTileRun, isMapCanvas, now, prepareStyle, } from './paint.js';
-import { DEFAULT_TILE_SIZE, cameraForBounds, boundsOf, dataTileFor, subTileOf, projectLngLat, rasterFor, tileCover, transformFor, unprojectPoint, visibleBounds, } from './proj.js';
-import { TileCache, pyramid } from './tiles.js';
+import { DEFAULT_TILE_SIZE, dataSquareOf, dataTileFor, subTileOf, rasterFor, tileCover, tileKey, transformFor, } from './proj.js';
+import { TileCache, drawnFor, pyramid } from './tiles.js';
+import { attributionOf } from './sources.js';
 import { shortbreadStyle } from './styles.js';
+import { isDarkTheme, overlayPalette } from './theme.js';
 import { LabelShaper, collectLabels, drawLabels, placeLabels, } from './labels.js';
-import { drawMarkers, drawOverlays, markerAt, markerRect } from './overlay.js';
+import { ATTRIBUTION_OPACITY, ATTRIBUTION_SIZE, attributionLayout, drawMarkers, drawOverlays, markerRect, } from './overlay.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
  *  `kind` is what paint order, the test queries and the DEV style assertion
@@ -57,20 +60,6 @@ export const SELF_DAMAGED_PROPS = [
     'sources',
     'mapStyle',
 ];
-/** 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. */
@@ -101,26 +90,6 @@ function intersectRects(a, b) {
         return null;
     return { x, y, width: right - x, height: bottom - y };
 }
-const timers = globalThis;
-/**
- * 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) {
-    const handle = timers.setTimeout?.(tick, SETTLE_MS) ?? null;
-    handle?.unref?.();
-    return handle;
-}
-function clamp(value, low, high) {
-    return value < low ? low : value > high ? high : value;
-}
-function quantize(zoom) {
-    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
@@ -136,38 +105,95 @@ function rectsOverlap(a, b) {
         a.y < b.y + b.height &&
         a.y + a.height > b.y);
 }
+/** Whether `outer` covers all of `inner`. */
+function containsRect(outer, inner) {
+    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, b) {
+    return a.length === b.length && a.every((source, i) => source === b[i]);
+}
+/**
+ * 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() {
+        return now();
+    },
+};
 export class MapViewNode extends Node {
     _cache;
     _scratch = new DrawScratch();
-    _geometry = new GeometryBuffer();
     _shaper = 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".
      */
-    _camera = { center: { lon: 0, lat: 20 }, zoom: 2 };
+    _controller;
+    _ownsController;
+    /** This element, as its controller sees it. */
+    _view;
     _prepared = null;
     _preparedFrom = null;
     _defaultStyle = null;
     /** The placement, and what it was computed for. */
     _labels = [];
     _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. */
+    _labelZoom = 0;
+    _labelSources = [];
+    _labelCandidates = new Map();
+    _shapedFamily;
     /** Candidates per tile, so a pan that brings a tile back does not redo
      *  the walk over its symbol layers. */
     _candidates = new Map();
-    _gesture = null;
-    _hover = null;
-    /** Set while a gesture is in flight and for `SETTLE_MS` after it, which
-     *  is when rasterization is suspended. */
-    _settleAt = 0;
-    _settleTimer = null;
-    _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. */
+    _outgoing = 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. */
+    _paintedBackground;
+    /** Whether a frame has been painted: before one, a restyle has no
+     *  previous picture to hold. */
+    _painted = false;
     /** Whether any tile has been rasterized in the frame being painted — the
      *  forward-progress guarantee below. */
     _rastered = false;
@@ -176,11 +202,37 @@ export class MapViewNode extends Node {
     _sceneAnnounced = false;
     constructor(props, app) {
         super(ELEMENT, props, app);
-        // 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;
+        // 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);
-        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);
+        }
+        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.
@@ -191,9 +243,7 @@ export class MapViewNode extends Node {
             onError: (entry) => {
                 this._prop('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: () => {
@@ -239,44 +289,20 @@ export class MapViewNode extends Node {
         return this._prepared;
     }
     _isDark() {
-        const theme = this.theme;
-        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);
     }
     _palette() {
-        const theme = this.theme;
-        return {
-            accent: theme?.accent ?? '#2d6cdf',
-            background: theme?.background ?? '#ffffff',
-            text: theme?.text ?? '#111111',
-        };
+        return overlayPalette(this.theme);
     }
     _sources() {
         const given = this._prop('sources');
         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. */
     _sourceId(source, index) {
         return source.id ?? `source-${index}`;
     }
-    _minZoom() {
-        return this._prop('minZoom') ?? 0;
-    }
-    _maxZoom() {
-        return this._prop('maxZoom') ?? 22;
-    }
-    _interactive() {
-        return this._prop('interactive') !== false;
-    }
     _markers() {
         return this._prop('markers') ?? [];
     }
@@ -301,8 +327,7 @@ export class MapViewNode extends Node {
         return pane.width > 0 && pane.height > 0;
     }
     camera() {
-        const given = this._prop('camera');
-        return given ?? this._camera;
+        return this._controller.camera();
     }
     /** The camera resolved against the pane. */
     _transform(camera = this.camera()) {
@@ -344,46 +369,6 @@ export class MapViewNode extends Node {
         this.invalidate(false, { x: box.x, y: box.y, width: 1, height: 1 }, reason);
     }
     // --- 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.
-     */
-    _applyCamera(next, blit = true) {
-        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 = {
-            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('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
@@ -440,134 +425,108 @@ 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. */
-    _zoomAbout(delta, screenX, screenY) {
-        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. */
-    _touchGesture() {
-        // 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 = () => {
-            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('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. */
     get _gesturing() {
-        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() {
-        const camera = this.camera();
-        return { center: { ...camera.center }, zoom: camera.zoom };
+        return this._controller.getCamera();
     }
     setCamera(camera) {
-        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, dy) {
-        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) {
-        const pane = this._pane();
-        this._zoomAbout(step, pane.width / 2, pane.height / 2);
+        this._controller.zoomIn(step);
     }
     zoomOut(step = 1) {
-        this.zoomIn(-step);
+        this._controller.zoomOut(step);
     }
     zoomTo(zoom) {
-        this.setCamera({ zoom });
+        this._controller.zoomTo(zoom);
     }
     fitBounds(bounds, options) {
-        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);
+        this._controller.fitBounds(bounds, options);
     }
     fitMarkers(ids, options) {
-        const wanted = ids ? new Set(ids) : null;
-        const positions = [];
-        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);
+        this._controller.fitMarkers(ids, options);
     }
     getBounds() {
-        return visibleBounds(this._transform());
+        return this._controller.getBounds();
     }
     project(position) {
-        return projectLngLat(this._transform(), position);
+        return this._controller.project(position);
     }
     unproject(x, y) {
-        return unprojectPoint(this._transform(), x, y);
+        return this._controller.unproject(x, y);
     }
     markerAt(x, y) {
-        return markerAt(this._markers(), this._transform(), x, y);
+        return this._controller.markerAt(x, y);
     }
     refresh() {
+        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.
+     */
+    _restyle() {
+        this._prepared = null;
+        this._preparedFrom = null;
+        this._candidates.clear();
+        if (this._outgoing === null &&
+            this._painted &&
+            this._prop('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. */
+    _viewKey(transform, pane) {
+        return `${transform.centerX},${transform.centerY},${transform.zoom},${pane.width}x${pane.height}`;
     }
     stats() {
         return this._stats;
     }
-    _pendingFit = null;
     // --- painting ------------------------------------------------------------
     /** How tall the attribution strip is, in logical pixels — 0 when there is
      *  nothing to say. Read by the blit as well as the paint, so the band it
@@ -576,16 +535,7 @@ export class MapViewNode extends Node {
         return this._attributionText() ? 16 : 0;
     }
     _attributionText() {
-        const given = this._prop('attribution');
-        if (given !== undefined)
-            return given;
-        const parts = [];
-        for (const source of this._sources()) {
-            if (source.attribution && !parts.includes(source.attribution)) {
-                parts.push(source.attribution);
-            }
-        }
-        return parts.join(' · ');
+        return attributionOf(this._prop('attribution'), this._sources());
     }
     /** How large a tile is rasterized, and how many surface pixels one
      *  logical pixel is — the pair the rasterizer needs, and the pair that
@@ -619,7 +569,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
             ? {
@@ -629,19 +579,17 @@ export class MapViewNode extends Node {
                 height: damage.height / scale,
             }
             : 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();
         const transform = this._transform(camera);
         const style = this._style();
         const frame = this._cache.beginFrame();
         const stats = {
+            renderer: 'retained',
             rasterMs: 0,
             drawMs: 0,
             tiles: 0,
@@ -649,6 +597,7 @@ export class MapViewNode extends Node {
             fromAncestor: 0,
             fromDescendant: 0,
             pending: 0,
+            restyling: false,
             labels: 0,
             errors: 0,
             surfaceBytes: 0,
@@ -677,17 +626,45 @@ 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('rasterBudgetMs') ?? 8);
+        const deadline = started + budget;
+        this._rastered = false;
+        const progressive = this._prop('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 = [];
+        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.
-        const background = this.style.backgroundColor ??
-            this._preparedBackground();
+        // 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 ?? styleBackground;
         if (background) {
             ctx.fillStyle = background;
             const region = this._frameClip
@@ -695,16 +672,16 @@ export class MapViewNode extends Node {
                 : { x: box.x, y: box.y, width: box.width, height: box.height };
             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('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(ctx, sources[i], this._sourceId(sources[i], i), transform, pane, style, stats, budget > 0, deadline);
+            this._drawSource(ctx, sources[i], views[i], stats, progressive, generation);
         }
         this._paintLabels(ctx, transform, pane, style, stats);
         const palette = this._palette();
@@ -716,7 +693,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('onFrame')?.(stats);
@@ -762,10 +741,83 @@ export class MapViewNode extends Node {
             height: Math.ceil((rect.y + rect.height) * s) - y,
         };
     }
-    _paintSource(ctx, source, sourceId, transform, pane, style, stats, 
+    /**
+     * 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.
+     */
+    _settleRestyle(transform, pane, stats, budget, 
+    /** When this frame began, on {@link restyleClock}. */
+    began, whole, progressive) {
+        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. */
+    _swapStyle() {
+        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.
+     */
+    _workSource(source, sourceId, transform, pane, style, stats, 
     /** False for the length of a gesture, when nothing is rasterized. */
-    mayRaster, deadline) {
-        const scale = this._scale;
+    mayRaster, deadline, 
+    /** A restyle is holding the previous style up, so a tile that finishes
+     *  waits for the swap rather than going on screen alone. */
+    holding) {
         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
@@ -773,12 +825,18 @@ 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('progressive') === true;
+        const visible = [];
         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,
@@ -788,22 +846,27 @@ 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, entry.tile, dataTileFor(entry.tile, p.maxZoom), subTileOf(entry.tile, p.maxZoom));
             if (!onScreen)
                 continue;
+            visible.push({ entry, box, cached });
             stats.tiles++;
             if (cached.status === 'error')
                 stats.errors++;
             if (cached.status === 'ready') {
                 const plan = this._rasterPlan(entry, p, zoom);
                 const size = cached.raster ? cached.raster.width : plan.size;
-                const drawing = this._cache.beginRender(cached, size, cached.raster ? 0 : styleZoom, (edge) => this._makeSurface(edge));
+                const drawing = this._cache.beginRender(cached, size, cached.raster ? 0 : styleZoom, (edge) => 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) {
                         this._uploadRaster(cached, drawing);
@@ -823,18 +886,87 @@ 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))
+                    //
+                    // 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)
+                // 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.
+     */
+    _rasterSquares(source, sourceId, cover, maxZoom) {
+        // 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 = [];
+        const squares = new Set();
+        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`.
+     */
+    _drawSource(ctx, source, visible, stats, progressive, generation) {
+        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,
@@ -845,22 +977,16 @@ export class MapViewNode extends Node {
             // `progressive` composites the draft instead, which is the old
             // 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, 1);
+                this._composite(ctx, showing.surface, showing.size, box, scale, 0, 0, 1);
                 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
@@ -870,35 +996,54 @@ 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;
-                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, scale, fx, fy, span);
-                stats.fromAncestor++;
+            // 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);
             }
-            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);
-                }
+            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;
+                this._composite(ctx, ancestor.shown.surface, ancestor.shown.size, {
+                    x: box.x + gap.x * edge,
+                    y: box.y + gap.y * edge,
+                    width: edge,
+                    height: edge,
+                }, scale, 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++;
         }
     }
     /**
@@ -1030,18 +1175,28 @@ 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.
      */
     _composite(ctx, surface, size, 
-    /** Where it lands, in pane-local logical pixels. */
-    dest, pane, scale, 
+    /** Where it lands, in the window's logical pixels. */
+    dest, scale, 
     /** Which sub-square of the surface to take, in `subSpan`ths. */
     subX, subY, subSpan) {
         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
@@ -1083,7 +1238,11 @@ export class MapViewNode extends Node {
         if (!fonts)
             return; // headless: nothing to shape with
         const text = this.resolvedTextStyle();
-        const family = this._prop('mapStyle')?.fontFamily ??
+        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')?.fontFamily ??
             this._defaultStyle?.fontFamily ??
             text.family;
         if (!this._shaper) {
@@ -1092,24 +1251,60 @@ 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 = [];
+                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();
+            for (const source of sources) {
+                wanted.set(source, Math.min(styleZoom, pyramid(source).maxZoom));
+            }
             const candidates = [];
+            const bySource = new Map();
             for (const cached of this._cache.dataEntries()) {
                 if (cached.status !== 'ready' || !cached.vector)
                     continue;
-                if (!wanted.has(cached.tile.z))
+                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.
@@ -1117,12 +1312,22 @@ export class MapViewNode extends Node {
                         this._candidates.clear();
                     this._candidates.set(at, found);
                 }
-                for (const candidate of found)
+                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, this._labels, transform, pane, this._scale, this._frameClip ? { ...this._frameClip } : null, this._shaper);
+        stats.labels = drawLabels(ctx, this._labels, transform, pane, this._scale, clip, this._shaper);
     }
     /**
      * The attribution.
@@ -1137,152 +1342,60 @@ export class MapViewNode extends Node {
         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;
+            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. */
-    _point(ev) {
+    /**
+     * 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.
+     */
+    _input(ev) {
         const pane = this._pane();
-        return { x: ev.x - pane.x, y: ev.y - pane.y };
-    }
-    _pointerEvent(ev, marker) {
-        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.detail,
+            shiftKey: ev.shiftKey,
+            ctrlKey: ev.ctrlKey,
+            altKey: ev.altKey,
+            metaKey: ev.metaKey,
         };
     }
     defaultMouseDown(ev) {
-        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?.();
     }
     defaultMouseDrag(ev) {
-        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));
     }
     defaultMouseUp(ev) {
-        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('onMarkerClick')?.(marker, event);
-                this._prop('onMapClick')?.(event);
-            }
-            return;
-        }
-        if (gesture.moved) {
-            this._touchGesture();
-            return;
-        }
-        this._prop('onMapClick')?.(this._pointerEvent(ev, null));
+        this._controller.pointerUp(this._input(ev));
     }
     defaultMouseMove(ev) {
-        const notify = this._prop('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));
     }
     defaultMouseLeave() {
-        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('onMarkerHover')?.(null, null);
+        this._controller.pointerLeave();
     }
     /**
      * The wheel is a zoom, not a scroll, so it is answered here rather than
@@ -1291,119 +1404,131 @@ export class MapViewNode extends Node {
      * scroll chain never hands over.
      */
     defaultWheel(ev) {
-        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();
+        }
     }
     defaultKeyDown(ev) {
-        // `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. */
+    a11yScene() {
+        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`. */
+    _seenSources = new WeakSet();
+    _remade = 0;
+    _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.
      */
-    a11yScene() {
-        if (!this._visible())
-            return [];
-        const transform = this._transform();
-        const pane = this._pane();
-        const scale = this._scale;
-        const items = [];
-        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;
+    _noticeRemade(before, next) {
+        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;
+        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.');
     }
     applyProps(next, prev) {
         const before = prev ?? this.props;
         super.applyProps(next, prev);
+        if (this._ownsController) {
+            this._controller.setProps(this.props);
+        }
+        if (next.sources !== before.sources) {
+            this._noticeRemade(before.sources, next.sources);
+        }
         // 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');
+        //
+        // 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;
-            const previous = before.camera ?? this._camera;
+            const previous = before.camera ??
+                this._controller.ownCamera();
             if (camera.zoom !== previous.zoom ||
                 camera.center.lon !== previous.center.lon ||
                 camera.center.lat !== previous.center.lat) {
@@ -1446,13 +1571,14 @@ export class MapViewNode extends Node {
         claim(after);
     }
     destroySubtree() {
-        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();
     }
 }