@react-x11/components 0.9.0 → 0.11.0

package/src/maps/controller.ts

@@ -240,18 +240,6 @@ const timers = globalThis as {
   performance?: { now(): number };
 };
 
-/**
- * The clock a glide is measured on.
- *
- * `performance.now()` rather than the `Date.now()` the settle window uses:
- * this one is compared across two frames of a 60Hz display, and `Date.now()`
- * counts whole milliseconds, so a sixth of the step would be error. Reached
- * through `globalThis` because `src/` compiles with `types: []`.
- */
-function now(): number {
-  return timers.performance?.now() ?? Date.now();
-}
-
 /**
  * The settle timer, unref'd where the runtime allows it.
  *
@@ -266,6 +254,29 @@ function arm(tick: () => void, ms: number): unknown {
   return handle;
 }
 
+/**
+ * The clock a glide is measured on, and the timer that steps it.
+ *
+ * `performance.now()` rather than the `Date.now()` the settle window uses:
+ * this one is compared across two frames of a 60Hz display, and `Date.now()`
+ * counts whole milliseconds, so a sixth of the step would be error. Reached
+ * through `globalThis` because `src/` compiles with `types: []`.
+ *
+ * One object, exported from this module though not from the package, so a
+ * test can stand in for both and step a glide a frame at a time. The glide
+ * is wall-clock time on purpose, and a runner slow enough to spend the whole
+ * of one inside a single `await` finds it over before it can look.
+ */
+export const glideClock = {
+  now(): number {
+    return timers.performance?.now() ?? Date.now();
+  },
+  arm,
+  disarm(handle: unknown): void {
+    timers.clearTimeout?.(handle);
+  },
+};
+
 function clamp(value: number, low: number, high: number): number {
   return value < low ? low : value > high ? high : value;
 }
@@ -287,6 +298,10 @@ export class MapController {
    * claims nothing and starts no gesture.
    */
   painting = false;
+  /** A camera move made while `painting`, waiting for the frame to end —
+   *  `previous` is the camera the *first* such move started from, so the
+   *  view is told the whole delta however many were fused. */
+  private _paintMove: { previous: MapCamera } | null = null;
 
   private _props: MapControllerProps = {};
   /** The camera, when the application does not control it. */
@@ -361,7 +376,7 @@ export class MapController {
   dispose(): void {
     if (this._settleTimer !== null) timers.clearTimeout?.(this._settleTimer);
     this._settleTimer = null;
-    if (this._glideTimer !== null) timers.clearTimeout?.(this._glideTimer);
+    if (this._glideTimer !== null) glideClock.disarm(this._glideTimer);
     this._glideTimer = null;
     this._glide = null;
   }
@@ -443,11 +458,49 @@ export class MapController {
     const controlled = this._props.camera !== undefined;
     if (!controlled) this._camera = camera;
     this._props.onCameraChange?.(camera);
-    if (this.painting) return;
+    if (this.painting) {
+      // A camera set from **inside** a frame, which is how every camera
+      // animation is written: the map's own `onFrame` is the clock, and the
+      // GL view calls it while it is still painting. Re-entering the paint
+      // is not on, but returning here used to drop the move's *scheduling*
+      // as well as its redraw — so the animation had nothing to ask for the
+      // next frame with, and stopped until something unrelated re-rendered.
+      //
+      // In the maps-gl example that something was the status bar's
+      // half-second interval, and it showed as exactly that: frames every
+      // 11ms, then a 511ms hole with the next request arriving at +508 —
+      // nobody asking, rather than anyone being slow. Manual panning never
+      // hit it because an input event is not inside a paint.
+      //
+      // So the move is remembered, with the camera it started from, and
+      // finished when the frame ends.
+      this._paintMove ??= { previous };
+      return;
+    }
     this.touch();
     if (!controlled) this._view?.moved(previous, camera, blit);
   }
 
+  /**
+   * A frame finished: do whatever `apply` deferred because it was painting.
+   * Called from both painters (`gl/view.ts`, `node.ts`) wherever `painting`
+   * goes back to false.
+   *
+   * Never a blit. A blit needs the exact transform it is shifting from, and
+   * what is flushed here may be several moves fused into one; a full redraw
+   * of a frame that was going to be drawn anyway costs nothing next to
+   * getting that wrong.
+   */
+  paintEnded(): void {
+    const move = this._paintMove;
+    if (!move) return;
+    this._paintMove = null;
+    this.touch();
+    if (this._props.camera === undefined) {
+      this._view?.moved(move.previous, this.camera(), false);
+    }
+  }
+
   getCamera(): MapCamera {
     const camera = this.camera();
     return { center: { ...camera.center }, zoom: camera.zoom };
@@ -501,6 +554,17 @@ export class MapController {
       this._maxZoom(),
     );
     if (zoom === camera.zoom) return;
+    this.apply(this._zoomedAbout(camera, zoom, x, y), false);
+  }
+
+  /** `camera` at `zoom`, with the point at pane-local `x`, `y` where it
+   *  was: what {@link zoomAbout} moves to, and what a glide arrives at. */
+  private _zoomedAbout(
+    camera: MapCamera,
+    zoom: number,
+    x: number,
+    y: number,
+  ): MapCamera {
     const before = this.transform(camera);
     const anchor = unprojectPoint(before, x, y);
     const after = this.transform({ center: camera.center, zoom });
@@ -509,21 +573,42 @@ export class MapController {
     const moved = projectLngLat(after, anchor);
     const dx = (moved.x - x) / after.world;
     const dy = (moved.y - y) / after.world;
-    this.apply(
-      {
-        zoom,
-        center: unprojectPoint(
-          {
-            ...after,
-            centerX: after.centerX + dx,
-            centerY: after.centerY + dy,
-          },
-          after.paneX,
-          after.paneY,
-        ),
-      },
-      false,
+    return {
+      zoom,
+      center: unprojectPoint(
+        {
+          ...after,
+          centerX: after.centerX + dx,
+          centerY: after.centerY + dy,
+        },
+        after.paneX,
+        after.paneY,
+      ),
+    };
+  }
+
+  /**
+   * Where the camera is going, when that is known before it gets there: the
+   * end of a wheel's glide. Null while nothing is gliding — a touchpad's
+   * stream, a drag or an application's own animation go wherever the next
+   * event says, and the view has only the camera to go on.
+   *
+   * What a renderer does with it is get there first: the tiles and label
+   * rasters of the view the glide stops at are asked for while the frames
+   * of the glide are still being drawn, so the settle has them in hand.
+   */
+  destination(): MapCamera | null {
+    const glide = this._glide;
+    if (!glide || !glide.easing) return null;
+    const camera = this.camera();
+    if (glide.applied !== camera.zoom) return null;
+    const zoom = clamp(
+      quantizeZoom(glide.target),
+      this._minZoom(),
+      this._maxZoom(),
     );
+    if (zoom === camera.zoom) return null;
+    return this._zoomedAbout(camera, zoom, glide.x, glide.y);
   }
 
   /**
@@ -550,7 +635,7 @@ export class MapController {
     y: number,
     smooth: boolean,
   ): void {
-    const at = now();
+    const at = glideClock.now();
     const camera = this.camera();
     const glide = this._glide;
     // Where this delta counts from: the target the wheel has already asked
@@ -590,13 +675,13 @@ export class MapController {
       this._glideTimer = null;
       const glide = this._glide;
       if (glide?.easing !== true) return;
-      const at = now();
+      const at = glideClock.now();
       // `stepZoom` clears the record when the target is reached or the
       // camera refuses a step, and this re-arms only while one is left.
       this.stepZoom(at, at - glide.at);
       this._armGlide();
     };
-    this._glideTimer = arm(tick, GLIDE_TICK_MS);
+    this._glideTimer = glideClock.arm(tick, GLIDE_TICK_MS);
   }
 
   /**

package/src/maps/gl/buckets.ts

@@ -38,6 +38,7 @@ import { GeomType, GeometryBuffer } from '../mvt.js';
 import type { FeatureCursor, VectorTile } from '../mvt.js';
 import type { PreparedLayer, PreparedStyle } from '../paint.js';
 import type { MapStyleLayer } from '../style.js';
+import type { TileId } from '../proj.js';
 import { buildTileLabels } from '../anchors.js';
 import type { GlLabelData } from '../anchors.js';
 
@@ -324,6 +325,9 @@ interface Group {
 export function buildTileBuckets(
   tile: VectorTile,
   prepared: PreparedStyle,
+  /** Which tile — what a label layer's `snapInto` distance is measured
+   *  against (`../anchors.ts`). */
+  id?: TileId,
 ): GlTileData {
   const started = now();
   const line = new Stream(1024);
@@ -445,7 +449,7 @@ export function buildTileBuckets(
     fill: fill.take(),
     fillRecords: fill.count,
     draws,
-    labels: buildTileLabels(tile, prepared, TILE_EXTENT),
+    labels: buildTileLabels(tile, prepared, TILE_EXTENT, id),
     stats: {
       features,
       lineRecords: line.count,

package/src/maps/gl/build-worker.ts

@@ -12,6 +12,7 @@
 // specifier would make every build depend on Node's type declarations.
 import { prepareStyle } from '../paint.js';
 import type { PreparedStyle } from '../paint.js';
+import type { TileId } from '../proj.js';
 import { parseVectorTile } from '../sources.js';
 import type { MapStyleLayer } from '../style.js';
 import { buildTileBuckets } from './buckets.js';
@@ -19,7 +20,13 @@ import { buildTileBuckets } from './buckets.js';
 /** What the store sends. */
 export type BuildRequest =
   | { type: 'style'; id: number; layers: MapStyleLayer[] }
-  | { type: 'build'; job: number; style: number; bytes: Uint8Array };
+  | {
+      type: 'build';
+      job: number;
+      style: number;
+      bytes: Uint8Array;
+      tile: TileId;
+    };
 
 interface Port {
   on(event: 'message', listener: (message: unknown) => void): void;
@@ -45,7 +52,11 @@ parentPort?.on('message', (message) => {
   try {
     const prepared = styles.get(request.style);
     if (!prepared) throw new Error(`style ${request.style} was never sent`);
-    const data = buildTileBuckets(parseVectorTile(request.bytes), prepared);
+    const data = buildTileBuckets(
+      parseVectorTile(request.bytes),
+      prepared,
+      request.tile,
+    );
     const transfer = [data.line, data.fill];
     if (data.labels) transfer.push(data.labels.anchors.buffer as ArrayBuffer);
     parentPort.postMessage({ job: request.job, data }, transfer);

package/src/maps/gl/cover.ts

@@ -18,7 +18,14 @@
 // projection — markers, overlays, labels, `project()`. `tileCover` reads a
 // smaller tile one level deeper instead, which puts every image at its own
 // natural size on the one world everything shares.
-import { DEFAULT_TILE_SIZE, tileCover, transformFor } from '../proj.js';
+import {
+  BELOW,
+  DEFAULT_TILE_SIZE,
+  FILL_DEPTH,
+  fillFromBelow,
+  tileCover,
+  transformFor,
+} from '../proj.js';
 import type { MapCamera, TileId, TilePyramid } from '../proj.js';
 import type { GlTileData } from './buckets.js';
 import type { RenderTile } from './renderer.js';
@@ -27,6 +34,17 @@ import type { RenderTile } from './renderer.js';
  *  source has no data there, `undefined` while it is still to come. */
 export interface TileLookup {
   get(tile: TileId): GlTileData | null | undefined;
+  /**
+   * What the store has answered for at or under a tile: `'here'` for the
+   * tile itself, `'below'` for only tiles under it — within `FILL_DEPTH`
+   * levels — and `undefined` for neither.
+   *
+   * What lets a hole's search for pieces skip the parts of the pyramid that
+   * hold nothing. Without it the search asks `get` for every tile down to
+   * that depth — which costs lookups, and stamps a tile still loading as
+   * used, so a load the view has left is not cancelled.
+   */
+  holds?(tile: TileId): 'here' | 'below' | undefined;
 }
 
 export interface CoverResult {
@@ -53,10 +71,18 @@ const MAX_ANCESTOR = 8;
  * The frame's tiles, centre-out, each with its screen square and its clip.
  *
  * A hole — a tile still loading, or one the source has no data for — is
- * covered from whichever side has geometry: the nearest ancestor, drawn at
- * its own larger size and clipped to the hole; or, zooming out, the four
- * children, when all of them are in hand. `AGENTS.md`'s rule for the
- * retained cache holds here too: a pyramid has two neighbours.
+ * covered from whichever side has geometry. Zooming out, that is the tiles
+ * under it: each quarter from the nearest level that has it, down to
+ * `FILL_DEPTH`. Whatever they leave, and the whole of a hole with nothing
+ * under it, is the nearest ancestor's, drawn at its own larger size and
+ * clipped to each gap. `AGENTS.md`'s rule for the retained cache holds here
+ * too: a pyramid has two neighbours.
+ *
+ * The first cut tried the ancestor first, and the children only when all
+ * four of them were in hand. A zoom out leaves the level it came from in
+ * the middle of the view, covering only part of the tiles at the edges, and
+ * a quick one leaves it two or three levels down: both were the background,
+ * with the sharper tiles in hand.
  */
 export function renderCover(
   camera: MapCamera,
@@ -118,53 +144,62 @@ export function renderCover(
       own++;
       continue;
     }
-    // An ancestor: the same ground, `2^k` times the size, from `sub` cells
-    // above and to the left of this entry's square.
-    let found = false;
+    // Under it: a tile with no data has nothing under it either, and past
+    // the pyramid's depth there is nothing to find.
     const { z, x, y } = entry.tile;
+    const below = fillFromBelow(
+      entry.tile,
+      data === null ? 0 : Math.min(FILL_DEPTH, pyramid.maxZoom - z),
+      (under) => {
+        const held = lookup.holds ? lookup.holds(under) : 'here';
+        if (held === undefined) return undefined;
+        if (held === 'below') return BELOW;
+        const got = lookup.get(under);
+        return got === undefined ? BELOW : got;
+      },
+    );
+    for (const piece of below.pieces) {
+      const size = clip.width / piece.span;
+      const px = clip.x + piece.x * size;
+      const py = clip.y + piece.y * size;
+      tiles.push({
+        data: piece.value,
+        x: px,
+        y: py,
+        size,
+        clip: { x: px, y: py, width: size, height: size },
+      });
+    }
+    if (below.covered) descendants++;
+    if (below.gaps.length === 0) continue;
+    // Over it: an ancestor, the same ground `2^k` times the size, from
+    // `sub` cells above and to the left of this entry's square — drawn once
+    // for each gap, clipped to it.
     for (let k = 1; k <= MAX_ANCESTOR && z - k >= pyramid.minZoom; k++) {
       const ancestor = { z: z - k, x: x >> k, y: y >> k };
       const stand = lookup.get(ancestor);
       if (!stand) continue;
-      const span = 1 << k;
-      const size = clip.width * span;
-      tiles.push({
-        data: stand,
-        x: clip.x - (x - (ancestor.x << k)) * clip.width,
-        y: clip.y - (y - (ancestor.y << k)) * clip.width,
-        size,
-        clip,
-      });
+      const size = clip.width * (1 << k);
+      const sx = clip.x - (x - (ancestor.x << k)) * clip.width;
+      const sy = clip.y - (y - (ancestor.y << k)) * clip.width;
+      for (const gap of below.gaps) {
+        const edge = clip.width / gap.span;
+        tiles.push({
+          data: stand,
+          x: sx,
+          y: sy,
+          size,
+          clip: {
+            x: clip.x + gap.x * edge,
+            y: clip.y + gap.y * edge,
+            width: edge,
+            height: edge,
+          },
+        });
+      }
       ancestors++;
-      found = true;
       break;
     }
-    if (found || data === null || z + 1 > pyramid.maxZoom) continue;
-    // Zooming out: the finer level is what is in hand. Only when all four
-    // children have answered, or the hole would be patched with holes.
-    const children: (GlTileData | null)[] = [];
-    for (let dy = 0; dy < 2; dy++) {
-      for (let dx = 0; dx < 2; dx++) {
-        const child = lookup.get({ z: z + 1, x: x * 2 + dx, y: y * 2 + dy });
-        if (child === undefined) break;
-        children.push(child);
-      }
-    }
-    if (children.length !== 4) continue;
-    const half = clip.width / 2;
-    children.forEach((child, i) => {
-      if (!child) return;
-      const cx = clip.x + (i % 2) * half;
-      const cy = clip.y + Math.floor(i / 2) * half;
-      tiles.push({
-        data: child,
-        x: cx,
-        y: cy,
-        size: half,
-        clip: { x: cx, y: cy, width: half, height: half },
-      });
-    });
-    descendants++;
   }
   return { tiles, missing, level, own, ancestors, descendants, inView };
 }