@react-x11/components 0.8.0 → 0.10.0

package/dist/maps/gl/view.js

@@ -0,0 +1,1209 @@
+// The GL renderer as `<Map>` mounts it: a pane (`./pane.ts`) with a
+// `<glarea>` in it, and every frame drawn into the surface from vector tiles
+// — the style, and over it the labels.
+//
+// **The camera is not this renderer's.** It is the map's controller's
+// (`../controller.ts`), which the retained renderer answers to as well, so a
+// fallback in the middle of a pan keeps the camera and the handle. What this
+// file adds is what a camera move costs here: a frame. A pan step is two
+// numbers on the controller and `requestFrame()`, with no render and no
+// commit in the loop — which matters more here than for the retained
+// renderer, because every frame here is a full redraw and the budget for one
+// is the whole frame, not a strip.
+//
+// **Input reaches the map through the pane's handlers**, which a press, a
+// drag and a wheel over the surface bubble up to on both backends — the
+// pointer over a `<glarea>` is the tree's (react-x11#545) — and which end at
+// the controller methods the retained renderer's element calls.
+//
+// **A failure is `<Map>`'s to handle.** A surface that will not come up, a
+// connection with no direct GL, a context or a shader that will not build, a
+// throw from a frame: each is reported once through `onFailure`, and `<Map>`
+// moves an `'auto'` map to the retained renderer or tells a `'gl'` one
+// through `onError`. Nothing here falls back on its own.
+import React, { useEffect, useMemo } from 'react';
+import { useTheme } from 'react-x11';
+import { scaleOf } from '../../internal/units.js';
+import { ATTRIBUTION_OPACITY, ATTRIBUTION_SIZE, attributionLayout, } from '../overlay.js';
+import { prepareStyle } from '../paint.js';
+import { DEFAULT_TILE_SIZE, project, transformFor, worldSize, } from '../proj.js';
+import { attributionOf, pyramidOf } from '../sources.js';
+import { defaultStyleFor, isDarkTheme, overlayPalette } from '../theme.js';
+import { parseColor, premultiplied } from './color.js';
+import { renderCover } from './cover.js';
+import { MarkerBatcher } from './markers.js';
+import { buildOverlayBucket, overlayRegion, regionHolds, regionPlacement, } from './overlays.js';
+import { GL_PANE } from './pane.js';
+import { LABEL_INSTANCE, LabelPlacer } from './placement.js';
+import { GlMapRenderer, gatesAt } from './renderer.js';
+import { GlTileStore } from './store.js';
+import { LabelAtlas, SurfaceTextEngine, fieldBase } from './text.js';
+const h = React.createElement;
+/**
+ * Adaptive quality's rungs, cheapest last. Each leaves out more than the
+ * one before it, in the order that costs the picture least:
+ *
+ *  1. **The fill edge pass** — the half-pixel line that antialiases every
+ *     polygon. A fifth of a dense frame, measured, and a staircase edge is
+ *     invisible on a map in motion.
+ *  2. **The style's newest detail layers** — those whose `minZoom` is within
+ *     `detail` levels of the zoom: buildings and service roads first, then
+ *     sites, minor roads. The style already says which layers are details,
+ *     by bringing them in last.
+ *  3. **A coarser tile level** — the parent level's tiles, drawn at this
+ *     zoom: generalized geometry and fewer features, which is what a low-zoom
+ *     frame (all land and water polygons) is made cheaper by.
+ */
+export const QUALITY_LADDER = [
+    { edges: true, detail: 0, coarser: 0 },
+    { edges: false, detail: 0, coarser: 0 },
+    { edges: false, detail: 1, coarser: 0 },
+    { edges: false, detail: 2, coarser: 0 },
+    { edges: false, detail: 2, coarser: 1 },
+    { edges: false, detail: 3, coarser: 2 },
+];
+/**
+ * The rung a moving frame is drawn at: the lowest predicted to fit the
+ * budget, and a rung up only once that one is predicted well inside it —
+ * so a frame that sits at the budget does not flicker between two rungs.
+ */
+export function chooseQuality(current, predict, budgetMs) {
+    const top = QUALITY_LADDER.length - 1;
+    let rung = Math.max(0, Math.min(current, top));
+    while (rung < top && predict(rung) > budgetMs)
+        rung++;
+    while (rung > 0 && predict(rung - 1) <= budgetMs * 0.75)
+        rung--;
+    return rung;
+}
+/**
+ * Milliseconds per segment instance, learned from frames it measured. It
+ * starts at what this renderer measured on an M1 Pro (3.7 M instances in
+ * 8.5 ms) and moves toward each measured frame, so a slower GPU is priced
+ * right within a few frames of the first gesture.
+ */
+class CostModel {
+    msPerInstance = 2.4e-6;
+    overheadMs = 0.4;
+    predict(instances) {
+        return this.overheadMs + instances * this.msPerInstance;
+    }
+    learn(instances, ms) {
+        // A near-empty frame is all overhead and says nothing about the slope.
+        if (instances < 50_000)
+            return;
+        const slope = Math.max(0, ms - this.overheadMs) / instances;
+        this.msPerInstance += 0.25 * (slope - this.msPerInstance);
+    }
+}
+/** How far outside the pane tiles are kept warm, in logical pixels — the
+ *  retained renderer's ring, so an ordinary flick has its tiles. */
+const COVER_PADDING = 256;
+/** How long a fade waits for the new level's tiles before starting anyway. */
+const FADE_WAIT_MS = 400;
+const DEFAULT_BUDGET_MS = 12;
+/** Milliseconds a frame may spend building tiles' buckets on this thread;
+ *  a frame always builds at least one waiting tile. */
+const BUILD_BUDGET_MS = 6;
+/** Milliseconds a frame may spend measuring strings it has not set before
+ *  — the one label cost that can be large (the first strings on X11 load
+ *  fonts and rasterize glyphs in JS). Placement's remainder waits a frame. */
+const TEXT_BUDGET_MOVING_MS = 1;
+/** Milliseconds a frame may spend making label fields (`text.ts`), about
+ *  0.2 ms each, when there are any to make. */
+const FIELD_BUDGET_MS = 4;
+/** With `labelsWhileMoving`: milliseconds a frame may spend setting the
+ *  text of names it has just placed, so they draw in it. */
+const LIVE_TEXT_BUDGET_MS = 8;
+const TEXT_BUDGET_SETTLED_MS = 4;
+/**
+ * How often a moving view is placed again, in milliseconds — every other
+ * frame or so. The labels shown follow the map every frame regardless; what
+ * waits a frame is a name coming into view, and what that buys is the frame
+ * that would have placed *and* measured *and* uploaded at once, which is
+ * what the late frames of a labelled pan were made of.
+ */
+const PLACE_INTERVAL_MS = 25;
+/** How long the zoom must hold still before labels not already shown are
+ *  placed (see `PlacementFrame.admit`). Under the controller's settle
+ *  window, so the frame that marks the camera settled is one that admits
+ *  them. */
+const ZOOM_QUIET_MS = 120;
+/** Sources taken off the map whose tiles are kept for a switch back. */
+const INACTIVE_STORES = 2;
+const NO_RASTER = {
+    features: 0,
+    vertices: 0,
+    decimated: 0,
+    culled: 0,
+    batches: 0,
+};
+/** A theme colour that does not parse falls back to these. */
+const BLACK = [0, 0, 0, 1];
+const WHITE = [1, 1, 1, 1];
+const INDIRECT = '@react-x11/components maps: this <glarea> draws through indirect GLX, ' +
+    'which has no shaders — the GL renderer needs the direct backend, which ' +
+    "on X11 is createRoot({ glPolicy: 'auto' }) and a DRI3 or Apple-DRI server";
+const globals = globalThis;
+const now = () => globals.performance?.now() ?? Date.now();
+const EMPTY_PANE = { x: 0, y: 0, width: 0, height: 0 };
+const EMPTY_COVER = {
+    tiles: [],
+    missing: [],
+    level: 0,
+    own: 0,
+    ancestors: 0,
+    descendants: 0,
+    inView: [],
+};
+/**
+ * The level fade: which level the frame is drawn from, and the one fading
+ * in over it.
+ *
+ * A new level is waited for — briefly, until every tile of it in view has
+ * answered — so the fade shows it arriving rather than a stand-in for it;
+ * then it fades in over the level it replaces, with an ease at both ends.
+ * A level more than one step away is not faded (the view it would fade
+ * from is sixteen times the tiles), and a change of target halfway
+ * through a fade takes the half-shown level as the one it fades from.
+ *
+ * What it cannot carry is a layer the style starts or stops drawing, which
+ * is {@link GateFader}'s: see there for why that is a separate thing and
+ * not a scene of its own.
+ */
+export class LevelFader {
+    /** The level the frame is drawn from, once one has been drawn. */
+    shown = null;
+    _fade = null;
+    /** Whether a fade is running or waiting to start. */
+    get fading() {
+        return this._fade !== null;
+    }
+    plan(target, cover, options) {
+        const { at, fadeMs } = options;
+        const to = target.level;
+        const plain = { base: target, next: null, alpha: 0 };
+        if (fadeMs <= 0 || this.shown === null || Math.abs(to - this.shown) > 1) {
+            this.shown = to;
+            this._fade = null;
+            return plain;
+        }
+        if (to === this.shown) {
+            this._fade = null;
+            return plain;
+        }
+        let fade = this._fade;
+        if (!fade || fade.to !== to) {
+            if (fade && fade.start !== null && (at - fade.start) / fadeMs >= 0.5) {
+                this.shown = fade.to;
+            }
+            if (this.shown === to) {
+                this._fade = null;
+                return plain;
+            }
+            fade = this._fade = { to, start: null, waitSince: at };
+        }
+        const base = cover(this.shown);
+        if (fade.start === null) {
+            if (target.missing.length > 0 && at - fade.waitSince < FADE_WAIT_MS) {
+                return { base, next: null, alpha: 0 };
+            }
+            fade.start = at;
+        }
+        const p = (at - fade.start) / fadeMs;
+        if (p >= 1) {
+            this.shown = to;
+            this._fade = null;
+            return plain;
+        }
+        return { base, next: target, alpha: p * p * (3 - 2 * p) };
+    }
+}
+/**
+ * The zoom gate's fade: how much of each style layer to draw, as the camera
+ * zooms past the `minZoom` and `maxZoom` the style gives them.
+ *
+ * **Why this is not a scene.** A level fade cross-fades two whole pictures,
+ * and a picture is the natural unit for a change of level. A layer ending
+ * is not: `minZoom` is a zoom, the pyramid changes level at a different
+ * zoom, and the two flips land on different frames — so carrying the gate
+ * as a second scene means a fade retargeted in the middle of another one,
+ * which can only either snap to the arriving scene or restart from the
+ * outgoing one. Both are a step in the picture, and stepping is what the
+ * fade is for. That is what made buildings vanish for one wheel notch and
+ * come back for the next. An opacity per layer has no such conflict: each
+ * layer's number moves on its own, through any number of level fades, and
+ * both scenes of a level fade draw with the same numbers — so the one
+ * thing an opacity ramp is bad at, a map dissolving layer by layer, cannot
+ * happen here, because only the layers actually crossing a gate move.
+ */
+export class GateFader {
+    /** Per style layer, in the prepared style's order. */
+    _alpha = [];
+    _at = null;
+    _fading = false;
+    /** Whether any layer is between the gate's ends — a frame to ask for. */
+    get fading() {
+        return this._fading;
+    }
+    /**
+     * The frame's `layerAlpha`, or null for "what the gate says" — which is
+     * every frame where nothing is crossing one, and every frame at all with
+     * the fade turned off.
+     */
+    step(style, options) {
+        const { at, fadeMs, zoom, detail } = options;
+        const targets = gatesAt(style, zoom, detail);
+        // The first frame, a restyle that changes the layer count, and the fade
+        // turned off: the gate, with nothing to advance.
+        const first = this._at === null || this._alpha.length !== targets.length;
+        if (fadeMs <= 0 || first) {
+            this._alpha = targets;
+            this._at = at;
+            this._fading = false;
+            return null;
+        }
+        const step = (at - (this._at ?? at)) / fadeMs;
+        this._at = at;
+        let fading = false;
+        let moved = false;
+        for (let i = 0; i < targets.length; i++) {
+            const to = targets[i];
+            const from = this._alpha[i];
+            if (from !== to) {
+                const next = to > from ? Math.min(to, from + step) : Math.max(to, from - step);
+                this._alpha[i] = next;
+                if (next !== to)
+                    fading = true;
+            }
+            if (this._alpha[i] !== to)
+                moved = true;
+        }
+        this._fading = fading;
+        return moved ? this._alpha : null;
+    }
+}
+/**
+ * The driver: everything a frame is, between the controller's camera and
+ * the renderer. Exported for the tests that drive it against a recording
+ * GL table — there is no other way to see a whole frame's decisions, and
+ * this host cannot render one (indirect GLX has no shaders).
+ */
+export class GlMapDriver {
+    props;
+    theme = null;
+    _controller;
+    _pane = null;
+    _area = null;
+    _renderer = null;
+    _gl = null;
+    _failed = false;
+    /** A store per source object — the retained cache's rule: a source is its
+     *  own cache, whatever its id. */
+    _stores = new Map();
+    /** Sources taken off the map, oldest first, whose tiles are kept. */
+    _inactive = [];
+    _style = null;
+    _prepared = null;
+    _committed = null;
+    _lastEnd = null;
+    _drawnZoom = null;
+    /** When the zoom last changed — which holds new labels back. */
+    _zoomedAt = -Infinity;
+    _rung = 0;
+    _cost = new CostModel();
+    _fader = new LevelFader();
+    _gates = new GateFader();
+    _placer = new LabelPlacer();
+    /** Places the labels of the view a glide stops at, and shows nothing:
+     *  what it asks the atlas for is measured and set while the glide is
+     *  still being drawn. */
+    _scout = new LabelPlacer();
+    /** The destination the scout last placed, and whether that placement
+     *  measured everything it offered — a frame's text budget can run out
+     *  first, and then the next frame places it again. */
+    _scoutedFor = '';
+    _scoutDone = false;
+    _markers = new MarkerBatcher();
+    /** The overlays' bucket, and what it was built from. */
+    _overlay = null;
+    _atlas = null;
+    _atlasKey = '';
+    /** No labels — the app has no fonts, or placing them failed — and no
+     *  asking again every frame. */
+    _noText = false;
+    /** The attribution's one instance. */
+    _attributionText = new Float32Array(LABEL_INSTANCE);
+    /** An attribution a frame could not draw yet — its string not measured,
+     *  or its field not in the texture — and the size it is drawn at. */
+    _attributionWanted = null;
+    /** When labels were last placed. */
+    _placedAt = -Infinity;
+    _pumpTimer = null;
+    _stats = null;
+    _announced = false;
+    _paneStyle = null;
+    constructor(controller, props) {
+        this._controller = controller;
+        this.props = props;
+    }
+    // --- the controller's view ----------------------------------------------------
+    /** The pane in the window's logical pixels: its box's, which is current
+     *  before the first frame and on a surface that never draws at all. */
+    pane() {
+        const box = this._pane?.contentBox?.();
+        if (!box)
+            return EMPTY_PANE;
+        const s = scaleOf(this._pane);
+        return {
+            x: box.x / s,
+            y: box.y / s,
+            width: box.width / s,
+            height: box.height / s,
+        };
+    }
+    scale() {
+        return scaleOf(this._pane);
+    }
+    /** Any camera move is one frame — there is no blit to prefer. */
+    moved() {
+        this.request();
+    }
+    /** Still: the next frame draws everything adaptive quality left out. */
+    settled() {
+        this.request();
+    }
+    /** `refresh()`: the style read again, and every tile's buckets and label
+     *  anchors built again from its bytes. */
+    refresh() {
+        this._style = null;
+        this._prepared = null;
+        for (const store of this._stores.values())
+            store.rebuild();
+        this._placer.reset();
+        this.request();
+    }
+    stats() {
+        return this._stats;
+    }
+    focus() {
+        this._pane?.focus?.();
+    }
+    request = () => {
+        this._area?.requestFrame?.();
+    };
+    attach() {
+        this._controller.attach(this);
+    }
+    paneRef = (node) => {
+        this._pane = node;
+        if (node)
+            this._controller.attach(this);
+    };
+    areaRef = (node) => {
+        this._area = node;
+    };
+    /** A commit landed: what it changed that a frame shows asks for one. */
+    committed() {
+        const map = this.props.map;
+        const before = this._committed;
+        this._committed = map;
+        if (!before)
+            return;
+        if (map.markers !== before.markers) {
+            this._pane?.notifyA11ySceneChanged?.();
+        }
+        if (map.camera !== before.camera ||
+            map.markers !== before.markers ||
+            map.overlays !== before.overlays ||
+            map.sources !== before.sources ||
+            map.mapStyle !== before.mapStyle ||
+            map.attribution !== before.attribution ||
+            map.antialias !== before.antialias ||
+            map.fillRule !== before.fillRule ||
+            map.levelFade !== before.levelFade ||
+            map.adaptive !== before.adaptive) {
+            this.request();
+        }
+    }
+    /** The style's background: what the pane shows under the surface, and
+     *  what the surface is cleared to. */
+    background() {
+        const style = this.props.map.mapStyle ?? defaultStyleFor(isDarkTheme(this.theme));
+        return style.background ?? '#ffffff';
+    }
+    /** The pane's style, the same object for as long as nothing in it changes
+     *  — a new one every render would be a damage claim every render. */
+    paneStyle(base, background) {
+        const cached = this._paneStyle;
+        if (cached && cached.base === base && cached.background === background) {
+            return cached.value;
+        }
+        const value = [base, { backgroundColor: background }];
+        this._paneStyle = { base, background, value };
+        return value;
+    }
+    // --- input --------------------------------------------------------------------
+    _local(ev) {
+        const pane = this.pane();
+        return { x: ev.x - pane.x, y: ev.y - pane.y };
+    }
+    _input(ev) {
+        const p = this._local(ev);
+        return {
+            x: p.x,
+            y: p.y,
+            button: ev.button,
+            detail: ev.detail,
+            shiftKey: ev.shiftKey,
+            ctrlKey: ev.ctrlKey,
+            altKey: ev.altKey,
+            metaKey: ev.metaKey,
+        };
+    }
+    /** The pane's handlers — the whole of the map's input, on both backends. */
+    handlers = {
+        onMouseDown: (ev) => {
+            if (this._controller.pointerDown(this._input(ev)) === 'pan') {
+                this._pane?.focus?.();
+            }
+            ev.capturePointer?.();
+        },
+        onMouseMove: (ev) => {
+            const input = this._input(ev);
+            if (this._controller.dragging)
+                this._controller.pointerDrag(input);
+            else
+                this._controller.pointerMove(input);
+        },
+        onMouseUp: (ev) => {
+            this._controller.pointerUp(this._input(ev));
+        },
+        onMouseLeave: () => this._controller.pointerLeave(),
+        onWheel: (ev) => {
+            if (this._controller.wheel(this._local(ev), ev.deltaY ?? 0, ev.smooth === true)) {
+                ev.preventDefault?.();
+            }
+        },
+        onKeyDown: (ev) => {
+            if (this._controller.keyDown(ev.keysym ?? 0, ev.shiftKey ?? false)) {
+                ev.preventDefault?.();
+            }
+        },
+    };
+    // --- failure ------------------------------------------------------------------
+    surfaceError = (error) => {
+        this._fail(error);
+    };
+    _fail(error) {
+        if (this._failed)
+            return;
+        this._failed = true;
+        try {
+            this._renderer?.dispose();
+        }
+        catch {
+            // A context that failed may not delete what it made either.
+        }
+        this._renderer = null;
+        this.props.onFailure(error instanceof Error ? error : new Error(String(error)));
+    }
+    // --- the frame ------------------------------------------------------------------
+    draw = (gl, info) => {
+        if (this._failed)
+            return;
+        try {
+            if (gl.backend !== 'direct') {
+                throw new Error(INDIRECT);
+            }
+            const controller = this._controller;
+            // A fit asked for before layout had a size lands in the first frame
+            // that has one, and this frame draws it.
+            controller.beginFrame();
+            controller.painting = true;
+            try {
+                this._frame(gl, info);
+            }
+            finally {
+                controller.painting = false;
+                // `onFrame` ran inside that, and a camera animation drives itself
+                // from it — so whatever it asked for is scheduled here.
+                controller.paintEnded();
+            }
+        }
+        catch (error) {
+            // Core hands an `onDraw` throw to `<glarea onError>` and nothing else;
+            // caught here, it is the map's failure, reported the one way.
+            this._fail(error);
+        }
+    };
+    _styleNow() {
+        const style = this.props.map.mapStyle ?? defaultStyleFor(isDarkTheme(this.theme));
+        if (style !== this._style || !this._prepared) {
+            this._style = style;
+            this._prepared = prepareStyle(style);
+            for (const store of this._stores.values()) {
+                store.setStyle(this._prepared);
+            }
+        }
+        return { style, prepared: this._prepared };
+    }
+    /** A store for every source on the map, in order; the stores of sources
+     *  taken off it stop loading and keep their tiles, a couple of them. */
+    _sourcesNow(prepared) {
+        const map = this.props.map;
+        const sources = map.sources ?? [];
+        const out = [];
+        sources.forEach((source, index) => {
+            let store = this._stores.get(source);
+            if (!store) {
+                store = new GlTileStore({
+                    source,
+                    sourceId: source.id ?? `source-${index}`,
+                    prepared,
+                    onChange: this.request,
+                    onError: (error, tile) => this.props.map.onTileError?.(error, tile),
+                    workers: map.buildWorkers ?? 0,
+                });
+                this._stores.set(source, store);
+            }
+            out.push({ source, store });
+        });
+        this._inactive = this._inactive.filter((s) => !sources.includes(s));
+        for (const [source, store] of this._stores) {
+            if (sources.includes(source) || this._inactive.includes(source)) {
+                continue;
+            }
+            store.abortLoads();
+            this._inactive.push(source);
+        }
+        while (this._inactive.length > INACTIVE_STORES) {
+            const old = this._inactive.shift();
+            this._stores.get(old)?.dispose((data) => this._renderer?.release(data));
+            this._stores.delete(old);
+        }
+        return out;
+    }
+    /**
+     * How long a moving frame may take, or null for "as long as it likes".
+     *
+     * **On unless turned off.** A renderer with no budget spends whatever a
+     * frame costs and asks for the next one on the following compositor tick
+     * regardless, so at the expensive end of a zoom sweep it takes the whole
+     * thread — and the app around it stops getting its timers. Measured on a
+     * fly across ten levels: without a budget the loop went a second at a time
+     * without running a `setTimeout`, and nothing inside it was slow, because
+     * the cost was spread over a hundred frames rather than spent in one call.
+     * With the budget, none. An embedding app should not have to know that to
+     * keep its own clock.
+     *
+     * What it costs is detail while the camera moves, and only while it moves:
+     * the frame after it settles draws everything again.
+     */
+    _budget() {
+        const adaptive = this.props.map.adaptive;
+        if (adaptive === false)
+            return null;
+        return typeof adaptive === 'object'
+            ? (adaptive.budgetMs ?? DEFAULT_BUDGET_MS)
+            : DEFAULT_BUDGET_MS;
+    }
+    _frame(gl, info) {
+        const map = this.props.map;
+        const controller = this._controller;
+        const scale = scaleOf(info.node);
+        if (gl !== this._gl) {
+            // A new context — the surface was recreated — owns none of the old
+            // one's buffers, so everything is uploaded again from the buckets the
+            // stores still hold.
+            this._renderer = null;
+            this._gl = gl;
+        }
+        this._renderer ??= new GlMapRenderer(gl, {
+            antialias: map.antialias,
+            fillRule: map.fillRule,
+        });
+        const renderer = this._renderer;
+        renderer.antialias = map.antialias ?? true;
+        renderer.fillRule = map.fillRule ?? 'nonzero';
+        const { style, prepared } = this._styleNow();
+        const camera = controller.camera();
+        if (this._drawnZoom !== null && this._drawnZoom !== camera.zoom) {
+            this._zoomedAt = now();
+        }
+        this._drawnZoom = camera.zoom;
+        const pane = { width: info.width / scale, height: info.height / scale };
+        const at = now();
+        const moving = controller.moving;
+        const budget = this._budget();
+        // Every source's tiles: built as far as the budget goes, then asked
+        // for — the view, and the ring around it that keeps a pan's tiles warm.
+        const sources = this._sourcesNow(prepared);
+        const buildStart = now();
+        const deadline = buildStart + BUILD_BUDGET_MS;
+        let more = false;
+        for (const { store } of sources) {
+            store.tick();
+            if (store.pump(deadline))
+                more = true;
+        }
+        const buildMs = now() - buildStart;
+        const covers = sources.map(({ source, store }) => {
+            const pyramid = pyramidOf(source);
+            const target = renderCover(camera, pane, scale, pyramid, store, {
+                padding: COVER_PADDING,
+            });
+            store.want(target.missing);
+            return { source, store, pyramid, target };
+        });
+        // Where a wheel's glide stops, while one is running: its tiles are
+        // asked for after the view's own, so the view the glide lands on is
+        // loaded — and its labels set, below — by the time it gets there.
+        const destination = moving ? controller.destination() : null;
+        const ahead = destination
+            ? covers.map((c) => {
+                const cover = renderCover(destination, pane, scale, c.pyramid, c.store);
+                c.store.want(cover.missing);
+                return cover;
+            })
+            : null;
+        // The level fade and adaptive quality are the first source's — the
+        // basemap's; a pyramid over it is drawn at its own level throughout.
+        const primary = covers[0] ?? null;
+        const coverAt = (level) => primary
+            ? renderCover(camera, pane, scale, primary.pyramid, primary.store, {
+                level,
+            })
+            : EMPTY_COVER;
+        const fadeMs = map.levelFade ?? 0;
+        const plan = primary
+            ? this._fader.plan(primary.target, coverAt, { at, fadeMs })
+            : { base: EMPTY_COVER, next: null, alpha: 0 };
+        if (primary && plan.base !== primary.target) {
+            primary.store.want(plan.base.missing);
+        }
+        const frameOf = (tiles, rung) => ({
+            width: info.width,
+            height: info.height,
+            zoom: camera.zoom,
+            scale,
+            style: prepared,
+            background: style.background,
+            sources: tiles,
+            detail: rung.detail,
+            edges: rung.edges ? undefined : false,
+        });
+        // The frame at a rung: the plan's levels with that rung's detail left
+        // out — and, when no fade is running, a coarser level for the base.
+        const build = (r) => {
+            const q = QUALITY_LADDER[r];
+            const base = [];
+            const arriving = [];
+            covers.forEach((c, i) => {
+                let own = i === 0 ? plan.base : c.target;
+                if (i === 0 && q.coarser > 0 && !plan.next) {
+                    const coarser = Math.max(c.pyramid.minZoom, own.level - q.coarser);
+                    if (coarser < own.level)
+                        own = coverAt(coarser);
+                }
+                base.push(own.tiles);
+                arriving.push(i === 0 && plan.next ? plan.next.tiles : c.target.tiles);
+            });
+            return {
+                frame: frameOf(base, q),
+                fade: plan.next
+                    ? { frame: frameOf(arriving, q), alpha: plan.alpha }
+                    : null,
+            };
+        };
+        let rung = 0;
+        let predictedMs = 0;
+        // An overview of the view: its ancestors every other level up to the
+        // pyramid's root, asked for after the view's own tiles and looked up
+        // every frame, so they stay loaded. A view is a speck at those levels,
+        // so this is a tile or two a level. It is what a fast zoom out lands
+        // on: a trackpad's momentum can cross fifteen levels in a quarter of a
+        // second, and every level it passes that has no tile draws the style's
+        // background alone — a frame of one flat colour, labels gone with the
+        // tiles, where a coarser tile would have drawn the place, blurred. With
+        // one level of it in reach two levels up, a hole is always filled from
+        // above (`renderCover`'s ancestors reach eight). The level just above
+        // the view comes first: it is also what the ladder's last rungs draw.
+        if (primary) {
+            const top = primary.pyramid.minZoom;
+            for (let level = primary.target.level - 1; level >= top; level = level - 2 < top && level > top ? top : level - 2) {
+                primary.store.want(coverAt(level).missing);
+            }
+        }
+        if (budget !== null && moving && primary) {
+            const predict = (r) => {
+                const built = build(r);
+                const work = renderer.estimate(built.frame) +
+                    (built.fade ? renderer.estimate(built.fade.frame) : 0);
+                return this._cost.predict(work);
+            };
+            rung = chooseQuality(this._rung, predict, budget);
+            predictedMs = predict(rung);
+        }
+        this._rung = rung;
+        const { frame, fade } = build(rung);
+        // A layer crossing a gate — the style's `minZoom`, or this rung's
+        // `detail` — is ramped rather than cut, and both of a level fade's
+        // scenes draw it at the same ramp. Decided after the rung, because the
+        // rung is one of the gates: a moving frame that drops the style's
+        // newest layers to make its budget would otherwise take them out in
+        // one frame and hand them back in one more when the camera settled,
+        // which is a flicker on exactly the layers a zoom is looking at.
+        const layerAlpha = this._gates.step(prepared, {
+            at,
+            fadeMs,
+            zoom: camera.zoom,
+            detail: QUALITY_LADDER[rung].detail,
+        });
+        if (layerAlpha) {
+            frame.layerAlpha = layerAlpha;
+            if (fade)
+                fade.frame.layerAlpha = layerAlpha;
+        }
+        // The text: the labels, and the attribution, set in the same atlas.
+        let labels = null;
+        let attribution = null;
+        let labelMs = 0;
+        if (!this._noText) {
+            const started = now();
+            try {
+                const atlas = this._atlasFor(info.node, style, scale);
+                if (atlas) {
+                    // Live labels measure at the settled budget while moving too:
+                    // what they admit mid-zoom has to be measured mid-zoom.
+                    const live = map.labelsWhileMoving === true;
+                    const textDeadline = now() +
+                        (moving && !live ? TEXT_BUDGET_MOVING_MS : TEXT_BUDGET_SETTLED_MS);
+                    atlas.beginFrame(textDeadline);
+                    // The attribution before the names: it is one string, measured
+                    // once, and a frame whose budget went on names would leave it
+                    // for a later one — for as long as names keep arriving.
+                    attribution = this._attributionFor(atlas, frame);
+                    labels = this._labelsFor(atlas, frame, fade, at, moving);
+                    if (destination && ahead) {
+                        this._scoutFor(atlas, frame, destination, ahead, at);
+                    }
+                    else if (this._scoutedFor !== '') {
+                        this._scout.reset();
+                        this._scoutedFor = '';
+                    }
+                    // The fields of strings already read back, on a budget of their
+                    // own: the text budget moving is 1 ms, five fields, and a jump
+                    // somewhere new reads back sixty names at once — they came in
+                    // over two hundred milliseconds that way, against none for the
+                    // coverage rasters fields replaced. This frame's draw uploads
+                    // what it makes.
+                    atlas.makeFields(Math.max(textDeadline, now() + FIELD_BUDGET_MS));
+                    this._pumpSoon();
+                }
+            }
+            catch (error) {
+                // Labels are the map's to lose, not the frame's: a failure placing
+                // them turns them off, once and said, and the map draws on.
+                this._noText = true;
+                this._atlas?.dispose();
+                this._atlas = null;
+                if (globals.process?.env?.NODE_ENV !== 'production') {
+                    globals.console?.warn(`@react-x11/components: <Map> stopped drawing labels: ${String(error)}`);
+                }
+            }
+            labelMs = now() - started;
+        }
+        // The overlays and the markers, laid out on the same world as the
+        // tiles under them.
+        const palette = overlayPalette(this.theme);
+        const overlays = this._overlaysFor(renderer, camera, pane, scale, palette, info);
+        const markers = map.markers?.length
+            ? this._markers.batch(map.markers, transformFor(camera, pane, DEFAULT_TILE_SIZE), pane, scale, palette)
+            : null;
+        // Adaptive quality prices moving frames with a rate it learns from
+        // frames it times — and it times only settled ones. Timing a frame means
+        // `glFinish`, which holds this thread until the GPU is done and, on the
+        // Cocoa backend, until the surface is: a moving frame cannot afford
+        // that, and what it reads is not the frame's cost either. Timed on every
+        // moving frame, the cheapest rungs read 16–52 ms of what is a few
+        // milliseconds of drawing, and the model learned from that put nearly
+        // every frame on the coarsest rung. A settled frame is drawn once and
+        // animates nothing, so it can afford two finishes: one to drain what
+        // came before it, and one to time it alone. It still errs slow — a lone
+        // frame after a pause meets a GPU that has clocked down — which errs on
+        // the side of frame rate.
+        const calibrate = budget !== null && !moving;
+        const finish = () => gl.finish?.();
+        if (calibrate)
+            finish();
+        const drawStart = now();
+        const stats = renderer.render(frame, {
+            fade,
+            labels,
+            overlays,
+            markers,
+            attribution,
+        });
+        let measuredMs = 0;
+        if (calibrate) {
+            finish();
+            measuredMs = now() - drawStart;
+            // An upload is not drawing, and would teach the model it was.
+            if (stats.uploads === 0)
+                this._cost.learn(stats.instances, measuredMs);
+        }
+        map.onAfterDraw?.(gl, { width: info.width, height: info.height });
+        for (const { store } of sources) {
+            store.evict((data) => renderer.release(data));
+        }
+        const end = now();
+        const interval = this._lastEnd === null ? 0 : end - this._lastEnd;
+        this._lastEnd = end;
+        let tiles = 0;
+        let ready = 0;
+        let fromAncestor = 0;
+        let fromDescendant = 0;
+        let errors = 0;
+        let building = 0;
+        let loading = 0;
+        for (const c of covers) {
+            tiles += c.target.inView.length;
+            ready += c.target.own;
+            fromAncestor += c.target.ancestors;
+            fromDescendant += c.target.descendants;
+            errors += c.store.failedAmong(c.target.inView);
+            building += c.store.building;
+            loading += c.store.loading;
+        }
+        const level = primary?.target.level ?? 0;
+        this._stats = {
+            renderer: 'gl',
+            // Nothing rasterized, no surfaces held, and every frame whole.
+            rasterMs: 0,
+            surfaceBytes: 0,
+            damage: null,
+            draw: NO_RASTER,
+            drawMs: stats.cpuMs + labelMs,
+            tiles,
+            ready,
+            fromAncestor,
+            fromDescendant,
+            pending: building,
+            restyling: false,
+            labels: stats.labels,
+            errors,
+            gl: {
+                interval,
+                cpuMs: stats.cpuMs,
+                buildMs,
+                building,
+                loading,
+                gpuBytes: renderer.gpuBytes,
+                instances: stats.instances,
+                drawCalls: stats.drawCalls,
+                uploads: stats.uploads,
+                uploadBytes: stats.uploadBytes,
+                offscreen: stats.offscreen,
+                level,
+                shownLevel: this._fader.shown ?? level,
+                fade: stats.fade,
+                quality: rung,
+                predictedMs,
+                measuredMs,
+                moving,
+                labelCandidates: labels ? this._placer.stats.candidates : 0,
+                labelsPlaced: labels ? this._placer.stats.placed : 0,
+                labelMs,
+                textPending: this._atlas?.pending ?? false,
+            },
+        };
+        // A label still fading, strings this frame had no budget to measure,
+        // fields still to be made, or fields still to go into the texture want
+        // the next frame; a batch in flight asks for one itself when it lands.
+        const labelling = labels !== null &&
+            (this._placer.animating ||
+                this._atlas?.starved === true ||
+                this._atlas?.fielding === true ||
+                this._atlas?.uploading === true);
+        // An attribution this frame could not draw may have gone into the
+        // texture during it — the upload happens as the labels draw, after the
+        // frame chose what to draw — and then it is the next frame's.
+        const wanted = this._attributionWanted;
+        const attributing = wanted !== null && this._atlas?.entry(wanted.text) != null;
+        if (more ||
+            this._fader.fading ||
+            this._gates.fading ||
+            labelling ||
+            attributing)
+            this.request();
+        if (!this._announced) {
+            this._announced = true;
+            this._pane?.notifyA11ySceneChanged?.();
+        }
+        map.onFrame?.(this._stats);
+    }
+    /**
+     * The overlays' bucket, placed for this frame: the one there is while the
+     * overlays are the same array, the theme's accent the same colour and
+     * the view inside the bucket's region, and a new one around the view
+     * otherwise.
+     */
+    _overlaysFor(renderer, camera, pane, scale, palette, info) {
+        const overlays = this.props.map.overlays;
+        let current = this._overlay;
+        if (!overlays || overlays.length === 0) {
+            if (current)
+                renderer.release(current.bucket.data);
+            this._overlay = null;
+            return null;
+        }
+        if (!current ||
+            current.overlays !== overlays ||
+            current.accent !== palette.accent ||
+            !regionHolds(current.bucket.region, camera, pane, scale)) {
+            if (current)
+                renderer.release(current.bucket.data);
+            current = this._overlay = {
+                bucket: buildOverlayBucket(overlays, overlayRegion(camera, pane, scale), palette),
+                overlays,
+                accent: palette.accent,
+            };
+        }
+        const { bucket } = current;
+        return {
+            data: bucket.data,
+            passes: bucket.passes,
+            ...regionPlacement(bucket.region, camera, info.width, info.height, scale),
+        };
+    }
+    /**
+     * The atlas every string on the map is set in — the labels, and the
+     * attribution. Made on the first frame, from the app the surface belongs
+     * to, and again when the face or the scale changes; null, and not asked
+     * for again, when the app has no fonts.
+     */
+    _atlasFor(node, style, scale) {
+        const family = style.fontFamily ??
+            this._pane?.resolvedTextStyle?.().family ??
+            'sans-serif';
+        const key = `${family}|${scale}`;
+        if (this._atlas && this._atlasKey === key)
+            return this._atlas;
+        this._atlas?.dispose();
+        this._atlas = null;
+        const engine = SurfaceTextEngine.forApp(node.app, family);
+        if (!engine) {
+            this._noText = true;
+            return null;
+        }
+        // Fields set at a base size that follows the display's scale, so a
+        // label on a 2x panel is sampled from a field twice as fine.
+        this._atlas = new LabelAtlas(engine, { base: fieldBase(scale) });
+        this._atlas.onChange = this.request;
+        this._atlasKey = key;
+        this._placer.reset();
+        return this._atlas;
+    }
+    /**
+     * The frame's labels: placed over the tiles of the level being shown —
+     * the arriving one, once a fade is past halfway — and batched for the
+     * renderer.
+     */
+    _labelsFor(atlas, frame, fade, at, moving) {
+        const live = this.props.map.labelsWhileMoving === true;
+        const from = fade && fade.alpha >= 0.5 ? fade.frame : frame;
+        const centre = project(this._controller.camera().center);
+        const placement = {
+            width: frame.width,
+            height: frame.height,
+            scale: frame.scale,
+            zoom: frame.zoom,
+            style: frame.style,
+            tiles: from.sources.flat(),
+            centerX: centre.x,
+            centerY: centre.y,
+            // The projection's world, which the cover lays every source out on.
+            world: worldSize(frame.zoom, DEFAULT_TILE_SIZE) * frame.scale,
+            now: at,
+            // Live: every name the view offers, at every step of a zoom.
+            admit: live || at - this._zoomedAt >= ZOOM_QUIET_MS,
+        };
+        if (live || !moving || at - this._placedAt >= PLACE_INTERVAL_MS) {
+            this._placer.place(placement, atlas);
+            this._placedAt = at;
+        }
+        // Live: what placement asked for is set now, before the batch, so a
+        // name placed in this frame is drawn in it — its field goes into the
+        // texture ahead of the cap, before this frame's labels draw.
+        if (live)
+            atlas.setNow(now() + LIVE_TEXT_BUDGET_MS);
+        return this._placer.batch(placement, atlas);
+    }
+    /**
+     * Render ahead: place the labels of the view a glide stops at, so that
+     * every string it will show is measured and asked of the atlas while the
+     * glide's own frames are drawn. Nothing it places is drawn — the frame's
+     * placer places the destination again when it gets there, and finds every
+     * box measured and every field in the texture, so the labels fade in
+     * when the view settles rather than a readback and an upload after.
+     *
+     * A fresh placement each time (the scout keeps no labels between runs;
+     * holding a place is for what is on screen), and not every frame: when
+     * the destination moves — another notch — or more of its tiles land, or
+     * the last placement ran out of the frame's text budget before it had
+     * measured everything. It measures out of that budget, after the frame's
+     * own labels.
+     */
+    _scoutFor(atlas, frame, destination, covers, at) {
+        // The destination is recomputed from each frame's camera, so its last
+        // digits wander; to a millionth of a degree it is the same place. And
+        // it is a different question once more of its tiles are in hand.
+        let held = 0;
+        for (const c of covers)
+            held += c.own;
+        const key = `${destination.zoom}|${destination.center.lon.toFixed(6)}|${destination.center.lat.toFixed(6)}|${held}`;
+        if (key === this._scoutedFor && this._scoutDone)
+            return;
+        this._scoutedFor = key;
+        const centre = project(destination.center);
+        this._scout.reset();
+        this._scout.place({
+            width: frame.width,
+            height: frame.height,
+            scale: frame.scale,
+            zoom: destination.zoom,
+            style: frame.style,
+            tiles: covers.flatMap((c) => c.tiles),
+            centerX: centre.x,
+            centerY: centre.y,
+            world: worldSize(destination.zoom, DEFAULT_TILE_SIZE) * frame.scale,
+            now: at,
+            admit: true,
+        }, atlas);
+        this._scoutDone = !atlas.starved;
+    }
+    /**
+     * The attribution, as the retained renderer draws it: the same box on the
+     * same pixels (`attributionLayout`), the text in the labels' face, from
+     * the labels' atlas. Null while there is none to draw — `attribution=""`,
+     * or no source that names one — and until its field is in the texture,
+     * so the box and its text arrive together.
+     */
+    _attributionFor(atlas, frame) {
+        this._attributionWanted = null;
+        const map = this.props.map;
+        const text = attributionOf(map.attribution, map.sources ?? []);
+        if (!text)
+            return null;
+        const s = frame.scale;
+        const size = ATTRIBUTION_SIZE * s;
+        const box = atlas.measure(text, size);
+        const entry = box ? atlas.entry(text) : null;
+        if (!box || !entry) {
+            this._attributionWanted = { text, size };
+            return null;
+        }
+        const at = attributionLayout({ width: box.width / s, height: box.height / s }, { x: 0, y: 0, width: frame.width / s, height: frame.height / s }, s);
+        const palette = overlayPalette(this.theme);
+        // The string sits `pad` texels inside its field, the field is drawn
+        // `k` device pixels a texel, and a level label's quad is centred on its
+        // anchor: this anchor puts the string's corner on the layout's.
+        const k = size / atlas.base;
+        const d = this._attributionText;
+        d[0] = at.x + (entry.width / 2 - atlas.pad) * k;
+        d[1] = at.y + (entry.height / 2 - atlas.pad) * k;
+        d[2] = 1;
+        d[3] = 0;
+        d[4] = entry.x;
+        d[5] = entry.y;
+        d[6] = entry.width;
+        d[7] = entry.height;
+        d.set(premultiplied(parseColor(palette.text) ?? BLACK), 8);
+        d.fill(0, 12, 17); // no halo: the box is what it reads against
+        d[17] = 1;
+        d[18] = k;
+        return {
+            box: at.box,
+            boxColor: premultiplied(parseColor(palette.background) ?? WHITE, ATTRIBUTION_OPACITY),
+            text: { atlas, instances: d, count: 1 },
+        };
+    }
+    /**
+     * Rasterize what placement asked for — after this frame rather than in
+     * it. Setting a batch of strings is milliseconds of this thread, and the
+     * gap between two frames is where that costs no frame anything.
+     */
+    _pumpSoon() {
+        if (this._pumpTimer !== null || !this._atlas?.pending)
+            return;
+        this._pumpTimer = globals.setTimeout(() => {
+            this._pumpTimer = null;
+            this._atlas?.pump();
+        }, 0);
+    }
+    /**
+     * Let go of everything GL: the stores, the atlas, the renderer — all of
+     * it made again, lazily, by the next frame if there is one. React's
+     * strict-mode double effect is the case where there is.
+     */
+    dispose() {
+        this._controller.detach(this);
+        if (this._pumpTimer !== null)
+            globals.clearTimeout(this._pumpTimer);
+        this._pumpTimer = null;
+        this._atlas?.dispose();
+        this._atlas = null;
+        this._atlasKey = '';
+        for (const store of this._stores.values()) {
+            store.dispose((data) => this._renderer?.release(data));
+        }
+        this._stores.clear();
+        this._inactive = [];
+        // Its buffers go with the renderer's.
+        this._overlay = null;
+        try {
+            this._renderer?.dispose();
+        }
+        catch {
+            // The surface may be gone already, and its context with it.
+        }
+        this._renderer = null;
+        this._gl = null;
+    }
+}
+/**
+ * The GL half of `<Map>`: a pane with a `<glarea>` in it, drawn every frame
+ * from vector tiles. Mounted by `<Map>` when it chooses GL; not exported
+ * from the package on its own.
+ */
+export function GlMapPane(props) {
+    const theme = useTheme();
+    const driver = useMemo(() => new GlMapDriver(props.controller, props), [props.controller]);
+    driver.props = props;
+    driver.theme = theme;
+    useEffect(() => {
+        driver.attach();
+        return () => driver.dispose();
+    }, [driver]);
+    useEffect(() => driver.committed());
+    const background = driver.background();
+    return h(GL_PANE, {
+        ref: driver.paneRef,
+        mapController: props.controller,
+        style: driver.paneStyle(props.style, background),
+        role: props.role,
+        'aria-label': props['aria-label'],
+        'data-testname': props['data-testname'],
+        ...driver.handlers,
+    }, h('glarea', {
+        ref: driver.areaRef,
+        style: FILL,
+        clearColor: background,
+        frameLoop: 'demand',
+        onDraw: driver.draw,
+        onError: driver.surfaceError,
+    }, props.children));
+}
+const FILL = { flexGrow: 1 };
+//# sourceMappingURL=view.js.map