@navaramap/three 0.0.7 → 0.1.0

package/src/core/MeshDesc.ts

@@ -1,4 +1,8 @@
 import type { BaseEventMap, XYZ } from "@navaramap/core";
+import {
+  headingPitchRollToFixedFrame,
+  type GeodeticPlacement,
+} from "@navaramap/three-api";
 import { Euler, Matrix4, Object3D, Vector3, type Mesh } from "three";
 import invariant from "tiny-invariant";
 
@@ -12,6 +16,7 @@ import {
   type BaseDescConfig,
   type BaseDescConfigUpdate,
 } from "./BaseDesc";
+import { ConflictingTransformError } from "./errors";
 import type { ViewContext } from "./ViewContext";
 
 export type MeshConfig = {
@@ -35,6 +40,9 @@ export type MeshConfig = {
    * Local frame. When combined with `position` / `rotation` / `scale`, the
    * effective local matrix is `matrix · T(position) · R(rotation) · S(scale)`.
    * Disables Three.js's auto matrix update.
+   *
+   * Mutually exclusive with `matrixWorld` and `geodetic`: all three define the
+   * object's placement.
    */
   matrix?: Matrix4;
   /**
@@ -43,8 +51,25 @@ export type MeshConfig = {
    * matrix is `matrixWorld · T(position) · R(rotation) · S(scale)`, so the
    * offset fields are interpreted in the frame's local coordinates.
    * Disables Three.js's auto matrix-world update.
+   *
+   * Mutually exclusive with `matrix` and `geodetic`: all three define the
+   * object's placement.
    */
   matrixWorld?: Matrix4;
+  /**
+   * High-level geographic placement in degrees and metres. Builds a
+   * West-Up-North tangent frame at `lng`/`lat`/`height` and applies
+   * `heading`/`pitch`/`roll`/`scale`, then occupies the same slot as
+   * `matrixWorld` — so `position` / `rotation` / `scale` remain offsets
+   * *inside* the resulting frame.
+   *
+   * `heading` is the compass bearing the asset's front (glTF `+Z`) faces, the
+   * same convention as `setCamera`. Because the frame is Y-up with `+Z` north,
+   * an unmodified glTF asset needs no up-axis correction.
+   *
+   * Mutually exclusive with `matrix` and `matrixWorld`.
+   */
+  geodetic?: GeodeticPlacement;
   /**
    * Lighting override for every material of the mesh. `false` outputs albedo
    * only, while normals and the shadow G-buffer keep being written.
@@ -57,8 +82,14 @@ export type MeshConfig = {
 export type MeshUpdate = Pick<
   MeshConfig,
   "position" | "scale" | "rotation" | "matrix" | "matrixWorld" | "lit"
-> &
-  BaseDescConfigUpdate;
+> & {
+  /**
+   * Partial geographic placement, merged into the stored placement — so
+   * `update({ geodetic: { heading } })` keeps the existing lng/lat/height.
+   * `lng` and `lat` are required only when the object has no placement yet.
+   */
+  geodetic?: Partial<GeodeticPlacement>;
+} & BaseDescConfigUpdate;
 
 export type PassKey = keyof Pick<
   Scenes,
@@ -74,6 +105,55 @@ export type MeshBaseInstance<Instance extends object = object> =
       ? Instance & { raw: Raw } & BaseInstance
       : Instance & BaseInstance;
 
+/**
+ * `geodetic`, `matrix` and `matrixWorld` all claim the object's placement, so
+ * they share a single slot and at most one may be set. Every consumer resolves
+ * that slot with a priority chain (`applyTransform`, `applyRTETransform`), so
+ * allowing two would silently drop the lower-priority one — notably `matrix`
+ * under `matrixWorld`, which cannot be honoured at all once
+ * `matrixWorldAutoUpdate` is off. Takes the values rather than reading `this`,
+ * so a caller can check a prospective state before committing it. Exported so
+ * subclasses that override `onUpdateConfig` (e.g. RTE Descriptors like
+ * `GLTFModelDesc`) reuse this single check instead of hand-rolling their own.
+ */
+export function assertNoTransformConflict(
+  geodetic: GeodeticPlacement | undefined,
+  matrix: Matrix4 | undefined,
+  matrixWorld: Matrix4 | undefined,
+): void {
+  if (geodetic) {
+    if (matrixWorld) {
+      throw new ConflictingTransformError("geodetic", "matrixWorld");
+    }
+    if (matrix) {
+      throw new ConflictingTransformError("geodetic", "matrix");
+    }
+  }
+  if (matrix && matrixWorld) {
+    throw new ConflictingTransformError("matrixWorld", "matrix");
+  }
+}
+
+/**
+ * Merges a partial placement onto an existing one and checks it is complete.
+ * Pure — returns the merged value instead of assigning it, so the caller can
+ * validate before committing. Exported so subclasses that manage their own
+ * `onUpdateConfig` (e.g. `GLTFModelDesc`'s RTE-split transform) can merge a
+ * `geodetic` update with the same semantics instead of re-deriving them.
+ */
+export function mergeGeodetic(
+  current: GeodeticPlacement | undefined,
+  update: Partial<GeodeticPlacement>,
+): GeodeticPlacement {
+  const merged = { ...current, ...update };
+  if (merged.lng === undefined || merged.lat === undefined) {
+    throw new Error(
+      "`geodetic` update requires `lng` and `lat` when the object has no geodetic placement yet.",
+    );
+  }
+  return merged as GeodeticPlacement;
+}
+
 /**
  * Abstract base class for creating custom mesh descriptors.
  *
@@ -192,7 +272,7 @@ export type MeshBaseInstance<Instance extends object = object> =
  *    The base class applies position/scale/rotation and adds it to the scene
  *    determined by {@link getPassKey}.
  * 3. **{@link onUpdateConfig}** - Called when `handle.update()` is invoked. The base class
- *    handles `visible`, `matrix`, `matrixWorld`, `position`, `scale`, and `rotation`; override to handle your
+ *    handles `visible`, `matrix`, `matrixWorld`, `position`, `scale`, `rotation`, and `geodetic`; override to handle your
  *    custom properties. Always call `super.onUpdateConfig(updates)`.
  * 4. **{@link update}** - Optional per-frame callback for animation.
  * 5. **{@link onResize}** - Optional callback when the viewport is resized.
@@ -222,6 +302,10 @@ export abstract class MeshDesc<
   public rotation?: XYZ;
   public matrix?: Matrix4;
   public matrixWorld?: Matrix4;
+  public geodetic?: GeodeticPlacement;
+  /** Terrain height under `geodetic`, when `heightReference` is `"terrain"`. */
+  protected terrainHeight?: number;
+  private terrainUnsubscribe?: () => void;
   /** Three-state `lit` override (see {@link MeshConfig.lit}). */
   public lit?: boolean;
   private prevPassKey?: PassKey;
@@ -234,9 +318,88 @@ export abstract class MeshDesc<
     this.rotation = resolvedConfig.rotation;
     this.matrix = resolvedConfig.matrix;
     this.matrixWorld = resolvedConfig.matrixWorld;
+    this.geodetic = resolvedConfig.geodetic;
+    assertNoTransformConflict(this.geodetic, this.matrix, this.matrixWorld);
     this.lit = resolvedConfig.lit;
   }
 
+  /**
+   * Builds the world frame for a {@link GeodeticPlacement}, adding
+   * {@link terrainHeight} when one has been observed. This method does not
+   * gate on `heightReference` itself — `terrainHeight` is only ever populated
+   * for a terrain-referenced placement, and is cleared otherwise.
+   *
+   * Fields are passed explicitly rather than spread: `headingPitchRollToFixedFrame`
+   * rejects `heightReference`, which this class resolves itself.
+   */
+  protected resolveGeodeticFrame(g: GeodeticPlacement): Matrix4 {
+    return headingPitchRollToFixedFrame({
+      lng: g.lng,
+      lat: g.lat,
+      height: (g.height ?? 0) + (this.terrainHeight ?? 0),
+      heading: g.heading,
+      pitch: g.pitch,
+      roll: g.roll,
+      scale: g.scale,
+    });
+  }
+
+  /**
+   * Subscribes to terrain height under a terrain-referenced `geodetic`
+   * placement.
+   *
+   * `sampleTerrainHeight` seeds synchronously from tiles already resident, so
+   * the object does not sit at the wrong altitude while tiles stream in; the
+   * observer then re-places it on every terrain update. With no terrain layer
+   * added, the sample is `undefined` and the observer does not fire until a
+   * terrain layer is added, so the placement degrades to ellipsoid-relative
+   * rather than failing — terrain layers may be added after the object.
+   *
+   * Protected (not private) so a subclass that manages its own world-matrix
+   * representation for `geodetic` (e.g. `GLTFModelDesc`'s RTE position split)
+   * can call it directly from its own `onCreate`/`onUpdateConfig` instead of
+   * routing through this class's `onCreate`.
+   */
+  protected subscribeTerrainHeight(): void {
+    this.unsubscribeTerrainHeight();
+
+    const g = this.geodetic;
+    if (!g || g.heightReference !== "terrain") {
+      this.terrainHeight = undefined;
+      return;
+    }
+
+    const pos = { lat: g.lat, lng: g.lng };
+    this.terrainHeight = this.view.sampleTerrainHeight(pos) ?? 0;
+    this.terrainUnsubscribe = this.view.observeTerrainHeightAt(
+      pos,
+      (height) => {
+        if (this.terrainHeight === height) return;
+        this.terrainHeight = height;
+        if (!this.raw) return;
+        this.reapplyGeodeticFrame();
+        this.requestUpdate();
+      },
+    );
+  }
+
+  /**
+   * Re-applies the effective transform after `geodetic`'s resolved frame
+   * changes outside of `onUpdateConfig` — currently only a terrain-height
+   * observation firing asynchronously. Subclasses that override
+   * `applyTransform`'s effect with their own representation (e.g.
+   * `GLTFModelDesc`'s RTE position/rotation split, which needs the *encoded*
+   * position refreshed too) override this instead of relying on the default.
+   */
+  protected reapplyGeodeticFrame(): void {
+    this.applyTransform();
+  }
+
+  private unsubscribeTerrainHeight(): void {
+    this.terrainUnsubscribe?.();
+    this.terrainUnsubscribe = undefined;
+  }
+
   /**
    * Applies {@link lit} to every material under the mesh. Subclasses that
    * attach materials asynchronously (glTF) call it again once they exist.
@@ -300,6 +463,7 @@ export abstract class MeshDesc<
     this._instance = this.createMesh();
     invariant(this.raw);
 
+    this.subscribeTerrainHeight();
     this.applyTransform();
     this.applyLit();
 
@@ -339,28 +503,39 @@ export abstract class MeshDesc<
   /**
    * Applies the configured transform to the underlying `Object3D`.
    *
-   * When `matrixWorld` (or `matrix`) is set together with any of
+   * When `matrixWorld` / `geodetic` (or `matrix`) is set together with any of
    * `position` / `rotation` / `scale`, the base/frame is left-multiplied
    * by the local `T · R · S`: e.g. `effective = matrixWorld · T · R · S`.
    * This lets callers pass a frame (such as an NUE-to-ECEF matrix) as
    * `matrixWorld` and express offsets inside that frame via
    * `position` / `rotation` / `scale`.
+   *
+   * The branches below are a priority chain, which is only safe because
+   * `assertNoTransformConflict` has already rejected any state with more than
+   * one of `geodetic` / `matrixWorld` / `matrix` set — so an earlier branch
+   * can never shadow a configured field.
    */
   private applyTransform(): void {
     invariant(this.raw);
     const hasLocal =
       this.position != null || this.rotation != null || this.scale != null;
 
-    if (this.matrixWorld) {
+    // `geodetic` takes the `matrixWorld` slot; the composition rule
+    // `world · T · R · S` is identical either way.
+    const worldMatrix = this.geodetic
+      ? this.resolveGeodeticFrame(this.geodetic)
+      : this.matrixWorld;
+
+    if (worldMatrix) {
       this.raw.matrixAutoUpdate = false;
       this.raw.matrixWorldAutoUpdate = false;
       if (hasLocal) {
         this.raw.matrixWorld.multiplyMatrices(
-          this.matrixWorld,
+          worldMatrix,
           this.composeLocalTransform(),
         );
       } else {
-        this.raw.matrixWorld.copy(this.matrixWorld);
+        this.raw.matrixWorld.copy(worldMatrix);
       }
       this.raw.updateMatrixWorld();
       return;
@@ -404,16 +579,50 @@ export abstract class MeshDesc<
   }
 
   onUpdateConfig(updates: UpdateConfig): void {
+    // Validate the PROSPECTIVE transform state before mutating anything: a
+    // throw has to leave the Descriptor exactly as it was. Assigning first
+    // and checking after would brick the instance — the guard would then fire
+    // on every later call, including unrelated ones like `{ visible }`, and
+    // the `!== undefined` update convention can never reset a field back to
+    // `undefined`, so there would be no way to recover.
+    const nextGeodetic =
+      updates.geodetic !== undefined
+        ? mergeGeodetic(this.geodetic, updates.geodetic)
+        : this.geodetic;
+    const nextMatrix =
+      updates.matrix !== undefined ? updates.matrix : this.matrix;
+    const nextMatrixWorld =
+      updates.matrixWorld !== undefined
+        ? updates.matrixWorld
+        : this.matrixWorld;
+    assertNoTransformConflict(nextGeodetic, nextMatrix, nextMatrixWorld);
+
     super.onUpdateConfig(updates);
     invariant(this.raw);
 
     const spatialChanged =
       updates.matrix !== undefined ||
       updates.matrixWorld !== undefined ||
+      updates.geodetic !== undefined ||
       updates.position !== undefined ||
       updates.scale !== undefined ||
       updates.rotation !== undefined;
 
+    if (updates.geodetic !== undefined) {
+      const prevGeodetic = this.geodetic;
+      this.geodetic = nextGeodetic;
+
+      // Only these three change what we sample; heading/pitch/roll/scale
+      // leave the sampled position and the reference untouched.
+      const resubscribe =
+        nextGeodetic?.lng !== prevGeodetic?.lng ||
+        nextGeodetic?.lat !== prevGeodetic?.lat ||
+        nextGeodetic?.heightReference !== prevGeodetic?.heightReference;
+      if (resubscribe) {
+        this.subscribeTerrainHeight();
+      }
+    }
+
     if (updates.matrix !== undefined) this.matrix = updates.matrix;
     if (updates.matrixWorld !== undefined)
       this.matrixWorld = updates.matrixWorld;
@@ -434,7 +643,7 @@ export abstract class MeshDesc<
       // so subclasses that strip a field from `updates` (e.g. GLTFModelLayer
       // keeping `raw.position` at 0 for its RTE shader) can still opt out
       // of having the base class copy it onto `raw`.
-      if (this.matrixWorld || this.matrix) {
+      if (this.geodetic || this.matrixWorld || this.matrix) {
         this.applyTransform();
       } else {
         if (updates.position !== undefined) {
@@ -468,6 +677,8 @@ export abstract class MeshDesc<
   }
 
   onDestroy(): void {
+    this.unsubscribeTerrainHeight();
+
     if (this.raw && this.raw.parent) {
       this.raw.parent.remove(this.raw);
     }

package/src/core/errors.ts

@@ -14,3 +14,17 @@ export class UnknownTypeError extends Error {
     );
   }
 }
+
+/**
+ * Raised when a config or update names more than one of `geodetic` / `matrix` /
+ * `matrixWorld`. They share a single placement slot, so the message is
+ * deliberately symmetric — neither argument order implies a winner.
+ */
+export class ConflictingTransformError extends Error {
+  constructor(field: string, conflictsWith: string) {
+    super(
+      `\`${field}\` cannot be combined with \`${conflictsWith}\`: both define the object's placement. ` +
+        `Set only one of them — use \`geodetic\` for geographic placement, or \`matrix\` / \`matrixWorld\` to supply a frame yourself.`,
+    );
+  }
+}

package/src/core/index.ts

@@ -8,6 +8,8 @@ export {
 } from "./BaseDesc";
 export {
   MeshDesc,
+  assertNoTransformConflict,
+  mergeGeodetic,
   type MeshUpdate,
   type MeshConfig,
   type PassKey,

package/src/evaluations/FeatureEvaluator.ts

@@ -99,6 +99,11 @@ export type { GeometryType };
  * Information about a feature batch, passed to evaluation callbacks.
  */
 export type FeatureInfo = {
+  /**
+   * The feature's canonical global batch id (its first instance's id when a
+   * feature spans several instances, e.g. MultiPoint). Pick events report the
+   * same canonical id, so picks and evaluations correlate through this field.
+   */
   batchId: number;
   properties: Record<string, unknown> | undefined;
   layerId: LayerId | undefined;
@@ -431,7 +436,7 @@ export class FeatureEvaluator {
   ) {
     const evaluate = (info: FeatureInfo, batchIndex: number) => {
       const evaluated = f(info);
-      this.applyEvaluatedValues(batchIndex, info.batchId, evaluated);
+      this.applyEvaluatedValues(batchIndex, evaluated);
     };
 
     if (options?.filters) {
@@ -443,30 +448,32 @@ export class FeatureEvaluator {
 
   private applyEvaluatedValues(
     batchIndex: number,
-    batchId: number,
     evaluated: Partial<EvaluatedValue>,
   ) {
     const obj = this.obj;
 
+    // Sprites apply by batch index: a feature can own several instances
+    // (MultiPoint, points derived from line/polygon vertices), so a
+    // batch-id keyed lookup would style only one of them.
     if (obj instanceof InstancedSpriteMesh) {
       if (evaluated.color != null) {
-        obj.setFeatureColorByBatchId(batchId, evaluated.color.raw);
+        obj.setFeatureColorByBatchIndex(batchIndex, evaluated.color.raw);
       }
       if (evaluated.show != null) {
-        obj.setFeatureShowByBatchId(batchId, evaluated.show);
+        obj.setFeatureShowByBatchIndex(batchIndex, evaluated.show);
       }
       if (evaluated.height != null) {
-        obj.setFeatureHeightByBatchId(batchId, evaluated.height);
+        obj.setFeatureHeightByBatchIndex(batchIndex, evaluated.height);
       }
       if (evaluated.size != null) {
-        obj.setFeatureSizeByBatchId(batchId, evaluated.size);
+        obj.setFeatureSizeByBatchIndex(batchIndex, evaluated.size);
       }
       if (evaluated.opacity != null) {
-        obj.setFeatureOpacityByBatchId(batchId, evaluated.opacity);
+        obj.setFeatureOpacityByBatchIndex(batchIndex, evaluated.opacity);
       }
       if (evaluated.declutterPriority != null) {
-        obj.setFeatureDeclutterPriorityByBatchId(
-          batchId,
+        obj.setFeatureDeclutterPriorityByBatchIndex(
+          batchIndex,
           evaluated.declutterPriority,
         );
       }
@@ -474,7 +481,7 @@ export class FeatureEvaluator {
         // Async by nature (the image may need fetching); the atlas dedupes
         // loads by URL so evaluating many features costs one fetch per image.
         // A nullish url clears the override back to the material default.
-        void obj.setFeatureImageByBatchId(batchId, evaluated.image);
+        void obj.setFeatureImageByBatchIndex(batchIndex, evaluated.image);
       }
       return;
     }

package/src/event/context.ts

@@ -189,6 +189,9 @@ export type MeshHandler = {
   setTileMeshPrepared: (handle: bigint) => void;
 };
 
+/** Settles the pending `flyTo` promise registered under `id`. */
+export type FlightHandler = (id: number, completed: boolean) => void;
+
 export type LayerHandler = {
   getLayerIndex: (layerId: string) => number | undefined;
 };
@@ -216,6 +219,7 @@ type EventContextArgs = {
   viewEvents: EventHandler<ViewEvents>;
   layersManager: LayersManager;
   viewContext: ViewContext;
+  flightHandler: FlightHandler;
   layerHandler?: LayerHandler;
   fontManager?: FontManager;
   textureFragmentIndex?: Map<string, Set<TextureSlot>>;
@@ -251,6 +255,7 @@ export class EventContext {
   readonly viewEvents: EventHandler<ViewEvents>;
   readonly layersManager: LayersManager;
   readonly viewContext: ViewContext;
+  readonly flightHandler: FlightHandler;
   readonly layerHandler?: LayerHandler;
   readonly fontManager?: FontManager;
   readonly textureFragmentIndex?: Map<string, Set<TextureSlot>>;
@@ -286,6 +291,7 @@ export class EventContext {
     this.viewEvents = args.viewEvents;
     this.layersManager = args.layersManager;
     this.viewContext = args.viewContext;
+    this.flightHandler = args.flightHandler;
     this.layerHandler = args.layerHandler;
     this.fontManager = args.fontManager;
     this.textureFragmentIndex = args.textureFragmentIndex;

package/src/event/feature.ts

@@ -14,7 +14,7 @@ import {
   PolygonMesh,
   PolylineMesh,
 } from "../mesh";
-import { FEATURE_RENDER_ORDER } from "../renderOrder";
+import { FEATURE_RENDER_ORDER, STROKE_RENDER_ORDER } from "../renderOrder";
 import type { Scenes } from "../scene";
 
 import type { EventContext } from "./context";
@@ -190,7 +190,20 @@ export async function processRenderableFeatureAdded(
     setTransform(obj, transform);
   }
 
-  obj.renderOrder = FEATURE_RENDER_ORDER;
+  // Strokes draw after fills: sibling meshes are created asynchronously in
+  // arbitrary order, and a fill drawn after a coplanar stroke either paints
+  // over it (bake scene) or z-fights against its depth (MRT scene), so the
+  // stacking must come from renderOrder, not insertion order. Only polylines
+  // stroking polygon rings sit on a sibling fill; standalone line strokes
+  // keep the base order — elevated, they would deterministically composite
+  // over every marker and outline they merely cross (PolylineMesh skips the
+  // depth test in the MRT scene).
+  const strokesSiblingFills =
+    polyline?.material.geometryTypes?.includes("polygon") ?? false;
+  obj.renderOrder =
+    obj instanceof PolylineMesh && strokesSiblingFills
+      ? STROKE_RENDER_ORDER
+      : FEATURE_RENDER_ORDER;
 
   // Add to MRT scene if not draped (draped features render to texturized scene)
   const isDraped =

package/src/event/features/billboard.test.ts

@@ -0,0 +1,62 @@
+import type { BillboardMesh as NavaraBillboardMesh } from "@navaramap/engine";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+import type { EventContext } from "../context";
+
+import { renderBillboard } from "./billboard";
+
+const init = vi.fn().mockResolvedValue(undefined);
+const setActive = vi.fn();
+
+vi.mock("../../mesh", () => ({
+  InstancedSpriteMesh: class {
+    _init = init;
+    setActive = setActive;
+  },
+}));
+
+describe("renderBillboard", () => {
+  const ctx = {} as EventContext;
+
+  // `url` is omitted from the material entirely when not passed, mirroring the
+  // engine's `string | undefined` accessor. The engine itself currently always
+  // sends a string (`BillboardMaterial::url` is a `String` defaulting to `""`,
+  // converted as `Some(url)`), so `""` is the shape a real url-less layer
+  // produces — both are covered below.
+  const createMesh = (url?: string) =>
+    ({
+      material: url === undefined ? {} : { url },
+      active: true,
+    }) as unknown as NavaraBillboardMesh;
+
+  beforeEach(() => {
+    init.mockClear();
+    setActive.mockClear();
+  });
+
+  it("creates a mesh when the material carries a default image", async () => {
+    const obj = await renderBillboard(ctx, createMesh("marker.png"));
+
+    expect(obj).toBeDefined();
+    expect(init).toHaveBeenCalledOnce();
+  });
+
+  // Regression: the mesh used to be skipped when the material had no `url`,
+  // so a layer that styles every feature through a FeatureEvaluator
+  // (`{ image }`) never got a mesh — and never a `featureCreated` event to
+  // attach the evaluator to. Empty atlas rects keep such instances invisible
+  // until an image is packed, so the mesh is safe to create eagerly.
+  it("creates a mesh when the material's default image is empty", async () => {
+    const obj = await renderBillboard(ctx, createMesh(""));
+
+    expect(obj).toBeDefined();
+    expect(init).toHaveBeenCalledOnce();
+  });
+
+  it("creates a mesh when the material has no `url` at all", async () => {
+    const obj = await renderBillboard(ctx, createMesh());
+
+    expect(obj).toBeDefined();
+    expect(init).toHaveBeenCalledOnce();
+  });
+});

package/src/event/features/billboard.ts

@@ -8,8 +8,10 @@ export async function renderBillboard(
   ctx: EventContext,
   m: NavaraBillboardMesh,
 ) {
-  if (!m.material.url) return;
-
+  // No `url` check: a billboard layer may carry no material-level image and
+  // get every image per-feature from a FeatureEvaluator (`{ image }`). The
+  // mesh starts with empty atlas rects, which the shader culls, so instances
+  // stay invisible until an image is packed for them.
   const mesh = new InstancedSpriteMesh({
     renderOrder: FEATURE_RENDER_ORDER,
     ctx,

package/src/event/index.ts

@@ -49,6 +49,7 @@ export type {
   FeatureHandler,
   MeshHandler,
   LayerHandler,
+  FlightHandler,
 } from "./context";
 export { EventContext } from "./context";
 export { HillshadeContext } from "./HillshadeContext";
@@ -73,6 +74,10 @@ export function processEvent(ctx: EventContext, event: Events | undefined) {
     processCameraFrustumUpdated(ctx, ev),
   );
 
+  eventManager.forEachStack("camera_flight_ended", (ev) =>
+    ctx.flightHandler(ev.id, ev.completed),
+  );
+
   eventManager.forEachStack("object_transform_updated", (ev) =>
     processObjectTransformUpdated(ctx, ev),
   );
@@ -318,6 +323,8 @@ function processCameraFrustumUpdated(
 
   ctx.camera.raw.near = frustum.near;
   ctx.camera.raw.far = frustum.far;
+  // The engine's `fov` is the vertical fov, matching what
+  // `PerspectiveCamera.fov` expects.
   ctx.camera.raw.fov = radianToDegree(frustum.fov);
   ctx.camera.raw.updateProjectionMatrix();
   ctx.camera.emit("frustumChanged");