@navaramap/three 0.0.7 → 0.1.0

package/src/pick/pickHelper.test.ts

@@ -0,0 +1,302 @@
+import { PerspectiveCamera, Vector2, type WebGLRenderer } from "three";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+import type { MeshCache } from "../type";
+
+import { isClickGesture, PickHelper } from "./pickHelper";
+
+describe("isClickGesture", () => {
+  it("accepts a mouseup at the exact mousedown position", () => {
+    expect(isClickGesture(new Vector2(100, 100), new Vector2(100, 100))).toBe(
+      true,
+    );
+  });
+
+  it("accepts small jitter during a click (a few pixels)", () => {
+    expect(isClickGesture(new Vector2(100, 100), new Vector2(102, 101))).toBe(
+      true,
+    );
+    expect(isClickGesture(new Vector2(100, 100), new Vector2(97, 103))).toBe(
+      true,
+    );
+  });
+
+  it("accepts travel just under the 5px tolerance", () => {
+    // 3-4-5 triangle scaled slightly down: distance ~4.99
+    expect(isClickGesture(new Vector2(0, 0), new Vector2(2.99, 3.99))).toBe(
+      true,
+    );
+  });
+
+  it("rejects travel at or beyond the 5px tolerance", () => {
+    expect(isClickGesture(new Vector2(0, 0), new Vector2(3, 4))).toBe(false);
+    expect(isClickGesture(new Vector2(0, 0), new Vector2(5, 0))).toBe(false);
+  });
+
+  it("rejects a clear drag", () => {
+    expect(isClickGesture(new Vector2(100, 100), new Vector2(180, 40))).toBe(
+      false,
+    );
+  });
+
+  it("uses euclidean distance, not per-axis deltas", () => {
+    // Each axis moved less than 5px but the combined travel exceeds it.
+    expect(isClickGesture(new Vector2(0, 0), new Vector2(4, 4))).toBe(false);
+  });
+});
+
+/**
+ * Renderer stub: just enough of the WebGLRenderer surface for PickHelper.
+ * `pixel` is what the next readback returns; `scissors`/`renderCount`
+ * record the GPU work a pick performed.
+ */
+const createRendererStub = () => {
+  const state = {
+    pixel: [0, 0, 0] as [number, number, number],
+    renderCount: 0,
+    scissors: [] as { x: number; y: number; w: number; h: number }[],
+  };
+  const renderer = {
+    getContext: () => ({ drawingBufferWidth: 800, drawingBufferHeight: 600 }),
+    getPixelRatio: () => 1,
+    getClearColor: () => undefined,
+    getClearAlpha: () => 1,
+    getRenderTarget: () => null,
+    setClearColor: () => undefined,
+    setRenderTarget: () => undefined,
+    clear: () => undefined,
+    autoClear: true,
+    render: () => {
+      state.renderCount++;
+    },
+    setScissor: (x: number, y: number, w: number, h: number) => {
+      state.scissors.push({ x, y, w, h });
+    },
+    setScissorTest: () => undefined,
+    readRenderTargetPixels: (
+      _target: unknown,
+      _x: number,
+      _y: number,
+      _w: number,
+      _h: number,
+      buffer: Uint8Array,
+    ) => {
+      [buffer[0], buffer[1], buffer[2]] = state.pixel;
+      buffer[3] = 255;
+    },
+  } as unknown as WebGLRenderer;
+  return { renderer, state };
+};
+
+describe("PickHelper", () => {
+  let rafCallbacks: Map<number, FrameRequestCallback>;
+  let nextRafId: number;
+
+  beforeEach(() => {
+    rafCallbacks = new Map();
+    nextRafId = 0;
+    vi.stubGlobal("requestAnimationFrame", (cb: FrameRequestCallback) => {
+      rafCallbacks.set(++nextRafId, cb);
+      return nextRafId;
+    });
+    vi.stubGlobal("cancelAnimationFrame", (id: number) => {
+      rafCallbacks.delete(id);
+    });
+  });
+
+  afterEach(() => {
+    vi.unstubAllGlobals();
+  });
+
+  /** Runs every rAF callback queued so far (one simulated frame). */
+  const runFrame = () => {
+    const callbacks = [...rafCallbacks.values()];
+    rafCallbacks.clear();
+    for (const cb of callbacks) cb(0);
+  };
+
+  const setup = (opts?: { clickable?: boolean; hoverable?: boolean }) => {
+    const element = document.createElement("div");
+    const { renderer, state } = createRendererStub();
+    const picks: number[][] = [];
+    const hovers: number[][] = [];
+    // Mutable so tests can flip a gate mid-flight (listener removal).
+    const gates = {
+      clickable: opts?.clickable ?? true,
+      hoverable: opts?.hoverable ?? true,
+    };
+    const helper = new PickHelper(
+      element,
+      renderer,
+      new PerspectiveCamera(),
+      new Map() as MeshCache,
+      (arr) => picks.push(arr),
+      (arr) => hovers.push(arr),
+      () => gates.clickable,
+      () => gates.hoverable,
+    );
+    helper.enablePick(true);
+
+    const mouse = (type: string, x: number, y: number, buttons = 0) =>
+      element.dispatchEvent(
+        new MouseEvent(type, { clientX: x, clientY: y, buttons }),
+      );
+    return { helper, element, state, picks, hovers, gates, mouse };
+  };
+
+  describe("click picking", () => {
+    it("decodes the batch id from the pick render", () => {
+      const { state, picks, mouse } = setup();
+      state.pixel = [0, 1, 2]; // (0 << 16) + (1 << 8) + 2
+
+      mouse("mousedown", 100, 100);
+      mouse("mouseup", 100, 100);
+
+      expect(picks).toEqual([[258]]);
+      expect(state.renderCount).toBe(1);
+    });
+
+    it("reports an empty pick for a miss (batch id 0)", () => {
+      const { picks, mouse } = setup();
+
+      mouse("mousedown", 100, 100);
+      mouse("mouseup", 100, 100);
+
+      expect(picks).toEqual([[]]);
+    });
+
+    it("limits GPU work to the clicked pixel via scissor", () => {
+      const { state, mouse } = setup();
+
+      mouse("mousedown", 30, 40);
+      mouse("mouseup", 30, 40);
+
+      // y is flipped into WebGL space: 600 - 1 - 40.
+      expect(state.scissors).toEqual([{ x: 30, y: 559, w: 1, h: 1 }]);
+    });
+
+    it("does not pick when the gesture is a drag", () => {
+      const { state, picks, mouse } = setup();
+
+      mouse("mousedown", 100, 100);
+      mouse("mouseup", 150, 150);
+
+      expect(picks).toEqual([]);
+      expect(state.renderCount).toBe(0);
+    });
+
+    it("skips the pick render entirely when nobody listens", () => {
+      const { state, picks, mouse } = setup({ clickable: false });
+
+      mouse("mousedown", 100, 100);
+      mouse("mouseup", 100, 100);
+
+      expect(picks).toEqual([]);
+      expect(state.renderCount).toBe(0);
+    });
+  });
+
+  describe("hover picking", () => {
+    it("picks at most once per animation frame, at the latest position", () => {
+      const { state, hovers, mouse } = setup();
+      state.pixel = [0, 0, 7];
+
+      mouse("mousemove", 10, 10);
+      mouse("mousemove", 20, 20);
+      mouse("mousemove", 30, 30);
+      expect(hovers).toEqual([]); // nothing until the frame fires
+
+      runFrame();
+
+      expect(hovers).toEqual([[7]]);
+      expect(state.renderCount).toBe(1);
+      expect(state.scissors).toEqual([{ x: 30, y: 569, w: 1, h: 1 }]);
+    });
+
+    it("reports an empty hover for a miss", () => {
+      const { hovers, mouse } = setup();
+
+      mouse("mousemove", 10, 10);
+      runFrame();
+
+      expect(hovers).toEqual([[]]);
+    });
+
+    it("is suppressed while a mouse button is pressed", () => {
+      const { state, hovers, mouse } = setup();
+
+      mouse("mousemove", 10, 10, 1);
+      runFrame();
+
+      expect(hovers).toEqual([]);
+      expect(state.renderCount).toBe(0);
+    });
+
+    it("re-checks the listener gate when the frame fires", () => {
+      const { state, hovers, gates, mouse } = setup();
+      state.pixel = [0, 0, 7];
+
+      mouse("mousemove", 10, 10);
+      // Listeners are removed between the mousemove and the frame.
+      gates.hoverable = false;
+      runFrame();
+
+      expect(hovers).toEqual([]);
+      expect(state.renderCount).toBe(0);
+    });
+
+    it("schedules nothing when no hover listener is registered", () => {
+      const { state, hovers, mouse } = setup({ hoverable: false });
+
+      mouse("mousemove", 10, 10);
+
+      expect(rafCallbacks.size).toBe(0);
+      runFrame();
+      expect(hovers).toEqual([]);
+      expect(state.renderCount).toBe(0);
+    });
+
+    it("mouseleave reports nothing hovered and cancels the pending pick", () => {
+      const { state, hovers, element, mouse } = setup();
+      state.pixel = [0, 0, 7];
+
+      mouse("mousemove", 10, 10);
+      element.dispatchEvent(new MouseEvent("mouseleave"));
+
+      expect(hovers).toEqual([[]]);
+
+      runFrame();
+      // The queued pick was cancelled: no render, no second callback.
+      expect(hovers).toEqual([[]]);
+      expect(state.renderCount).toBe(0);
+    });
+
+    it("mouseleave stays silent without hover listeners", () => {
+      const { hovers, element } = setup({ hoverable: false });
+
+      element.dispatchEvent(new MouseEvent("mouseleave"));
+
+      expect(hovers).toEqual([]);
+    });
+  });
+
+  describe("enablePick(false)", () => {
+    it("detaches every handler and cancels pending hover picks", () => {
+      const { helper, state, picks, hovers, mouse } = setup();
+      state.pixel = [0, 0, 7];
+      mouse("mousemove", 10, 10);
+
+      helper.enablePick(false);
+
+      expect(rafCallbacks.size).toBe(0);
+      mouse("mousedown", 100, 100);
+      mouse("mouseup", 100, 100);
+      mouse("mousemove", 20, 20);
+      runFrame();
+
+      expect(picks).toEqual([]);
+      expect(hovers).toEqual([]);
+      expect(state.renderCount).toBe(0);
+    });
+  });
+});

package/src/pick/pickHelper.ts

@@ -18,6 +18,21 @@ export type PickHelperOptions = {
   debug: boolean;
 };
 
+/**
+ * Travel tolerance in CSS pixels between mousedown and mouseup to count as a click.
+ * Follows Cesium's `_clickPixelTolerance` (MapLibre uses 3px).
+ * ref: https://github.com/CesiumGS/cesium/blob/9fda7ab97a762e40c74b1d0e1814c98a2de43337/packages/engine/Source/Core/ScreenSpaceEventHandler.js#L1012
+ * ref: https://github.com/maplibre/maplibre-gl-js/blob/3a0a4f795fef5b2a29034d71833475589c344eaf/src/ui/map.ts#L542
+ */
+const CLICK_PIXEL_TOLERANCE = 5;
+
+export function isClickGesture(
+  downPosition: Vector2,
+  upPosition: Vector2,
+): boolean {
+  return downPosition.distanceTo(upPosition) < CLICK_PIXEL_TOLERANCE;
+}
+
 /**
  * GPU picking using a dedicated single-pixel render pass.
  *
@@ -32,6 +47,12 @@ export type PickHelperOptions = {
  * Re-parenting is safe because pass scenes all have identity world
  * transforms, so world matrices of the re-parented objects are
  * unaffected.
+ *
+ * Two gestures trigger a pick: a click (mousedown/mouseup within
+ * {@link CLICK_PIXEL_TOLERANCE}) and hovering, throttled to at most one
+ * pick per animation frame. Both are lazy: a pick runs only while the
+ * matching `shouldClickPick` / `shouldHoverPick` gate returns true
+ * (i.e. someone is listening for the result).
  */
 export class PickHelper {
   private element: HTMLElement;
@@ -49,10 +70,20 @@ export class PickHelper {
   /** Full-size render target used for click picking with scissor restriction. */
   private pickRenderTarget: WebGLRenderTarget;
 
-  private mouseMoved: boolean;
+  private onHoverCallback: (pickArr: number[]) => void;
+  /** Click picks run only while this returns true (e.g. featureClick listeners exist). */
+  private shouldClickPick: () => boolean;
+  /** Hover picks run only while this returns true (e.g. hover listeners exist). */
+  private shouldHoverPick: () => boolean;
+
+  private mouseDownPosition?: Vector2;
   private mouseDownHandler: (event: MouseEvent) => void;
-  private mouseMoveHandler: (event: MouseEvent) => void;
   private mouseUpHandler: (event: MouseEvent) => void;
+  private hoverMoveHandler: (event: MouseEvent) => void;
+  private hoverLeaveHandler: () => void;
+  /** Latest mousemove position awaiting a hover pick, in client coords. */
+  private hoverPosition?: Vector2;
+  private hoverRafId?: number;
 
   constructor(
     element: HTMLElement,
@@ -60,6 +91,9 @@ export class PickHelper {
     camera: PerspectiveCamera,
     meshes: MeshCache,
     onPickCallback: (pickArr: number[]) => void,
+    onHoverCallback: (pickArr: number[]) => void,
+    shouldClickPick: () => boolean,
+    shouldHoverPick: () => boolean,
     options?: PickHelperOptions,
   ) {
     this.element = element;
@@ -68,11 +102,14 @@ export class PickHelper {
     this._camera = camera;
     this._meshes = meshes;
     this.onPickCallback = onPickCallback;
+    this.onHoverCallback = onHoverCallback;
+    this.shouldClickPick = shouldClickPick;
+    this.shouldHoverPick = shouldHoverPick;
 
-    this.mouseMoved = false;
     this.mouseDownHandler = (event: MouseEvent) => this.onMouseDown(event);
-    this.mouseMoveHandler = (event: MouseEvent) => this.onMouseMove(event);
     this.mouseUpHandler = (event: MouseEvent) => this.onMouseUp(event);
+    this.hoverMoveHandler = (event: MouseEvent) => this.onHoverMouseMove(event);
+    this.hoverLeaveHandler = () => this.onHoverMouseLeave();
 
     const width = this._renderer.getContext().drawingBufferWidth;
     const height = this._renderer.getContext().drawingBufferHeight;
@@ -93,16 +130,21 @@ export class PickHelper {
     }
   }
 
-  private onMouseDown(_event: MouseEvent) {
-    this.mouseMoved = false;
-  }
-
-  private onMouseMove(_event: MouseEvent) {
-    this.mouseMoved = true;
+  private onMouseDown(event: MouseEvent) {
+    this.mouseDownPosition = new Vector2(event.clientX, event.clientY);
   }
 
   private onMouseUp(event: MouseEvent) {
-    if (!this.mouseMoved) {
+    const downPosition = this.mouseDownPosition;
+    this.mouseDownPosition = undefined;
+    if (!downPosition) return;
+
+    // Skip the GPU pick entirely when nobody is listening for the result.
+    if (!this.shouldClickPick()) return;
+
+    if (
+      isClickGesture(downPosition, new Vector2(event.clientX, event.clientY))
+    ) {
       this.onMouseClick(event);
     }
   }
@@ -110,15 +152,64 @@ export class PickHelper {
   enablePick(bPick: boolean) {
     if (bPick) {
       this.element.addEventListener("mousedown", this.mouseDownHandler);
-      this.element.addEventListener("mousemove", this.mouseMoveHandler);
       this.element.addEventListener("mouseup", this.mouseUpHandler);
+      this.element.addEventListener("mousemove", this.hoverMoveHandler);
+      this.element.addEventListener("mouseleave", this.hoverLeaveHandler);
     } else {
       this.element.removeEventListener("mousedown", this.mouseDownHandler);
-      this.element.removeEventListener("mousemove", this.mouseMoveHandler);
       this.element.removeEventListener("mouseup", this.mouseUpHandler);
+      this.element.removeEventListener("mousemove", this.hoverMoveHandler);
+      this.element.removeEventListener("mouseleave", this.hoverLeaveHandler);
+      this.cancelPendingHoverPick();
+    }
+  }
+
+  /**
+   * Hover picking: schedules at most one GPU pick per animation frame from
+   * the latest mousemove position. Suppressed while any mouse button is
+   * pressed (camera drags would otherwise trigger a pick per frame) and
+   * while `shouldHoverPick` returns false, so pages without hover
+   * listeners pay nothing.
+   */
+  private onHoverMouseMove(event: MouseEvent) {
+    if (event.buttons !== 0 || !this.shouldHoverPick()) return;
+
+    if (!this.hoverPosition) this.hoverPosition = new Vector2();
+    this.hoverPosition.set(event.clientX, event.clientY);
+
+    if (this.hoverRafId !== undefined) return;
+    this.hoverRafId = requestAnimationFrame(() => {
+      this.hoverRafId = undefined;
+      const position = this.hoverPosition;
+      if (!position) return;
+      this.hoverPosition = undefined;
+
+      // Listeners may have been removed between the mousemove that
+      // scheduled this frame and now. Re-check so no orphan pick runs.
+      if (!this.shouldHoverPick()) return;
+
+      const batchId = this.pickBatchIdAt(position.x, position.y);
+      this.onHoverCallback(batchId > 0 ? [batchId] : []);
+    });
+  }
+
+  private onHoverMouseLeave() {
+    this.cancelPendingHoverPick();
+    // Report "nothing hovered" so diff-based enter/leave synthesis can
+    // close out the current hover when the cursor exits the canvas.
+    if (this.shouldHoverPick()) {
+      this.onHoverCallback([]);
     }
   }
 
+  private cancelPendingHoverPick() {
+    if (this.hoverRafId !== undefined) {
+      cancelAnimationFrame(this.hoverRafId);
+      this.hoverRafId = undefined;
+    }
+    this.hoverPosition = undefined;
+  }
+
   /**
    * Moves every pickable raw (visible, currently parented) into the
    * dedicated `pickScene` and activates the picking uniforms on its
@@ -213,9 +304,19 @@ export class PickHelper {
   }
 
   private onMouseClick(event: MouseEvent) {
+    const batchId = this.pickBatchIdAt(event.clientX, event.clientY);
+    const pickArr = batchId > 0 ? [batchId] : [];
+    this.onPickCallback(pickArr);
+  }
+
+  /**
+   * Runs the single-pixel pick render at the given client coordinates and
+   * returns the decoded batch ID (0 when nothing pickable is hit).
+   */
+  private pickBatchIdAt(clientX: number, clientY: number): number {
     const rect = this.element.getBoundingClientRect();
-    const x = event.clientX - rect.left;
-    const y = event.clientY - rect.top;
+    const x = clientX - rect.left;
+    const y = clientY - rect.top;
 
     const pixelRatio = this._renderer.getPixelRatio();
     const fullWidth = this._renderer.getContext().drawingBufferWidth;
@@ -255,13 +356,11 @@ export class PickHelper {
 
     this._renderer.setScissorTest(false);
 
-    const batchId =
+    return (
       (this.pixelBuffer[0] << 16) +
       (this.pixelBuffer[1] << 8) +
-      this.pixelBuffer[2];
-
-    const pickArr = batchId > 0 ? [batchId] : [];
-    this.onPickCallback(pickArr);
+      this.pixelBuffer[2]
+    );
   }
 
   public dispose() {

package/src/plugins/AttributionPlugin/index.ts

@@ -189,7 +189,7 @@ export class AttributionPlugin extends Plugin<View, ViewContext> {
 
   async init(view: View, _ctx: ViewContext): Promise<void> {
     this.view = view;
-    // Recompute the zoom level on render. `fovy` is undefined until the first
+    // Recompute the zoom level on render. `fov` is undefined until the first
     // frame, so a camera `moveend` alone would miss the initial value on a
     // static map; `preRender` reliably fires while the scene renders. The
     // level-change gate in `handlePreRender` keeps this from churning the DOM.

package/src/renderOrder.ts

@@ -1,3 +1,13 @@
 export const FEATURE_RENDER_ORDER = 1;
+/**
+ * Polylines (strokes) must draw after polygon fills. In the per-tile bake
+ * scene, sibling fill/stroke meshes are created asynchronously and land in
+ * the scene in arbitrary order, so a fill baked later paints over the stroke.
+ * In the MRT scene, polyline materials skip the depth test but still write
+ * depth, so a coplanar fill drawn after a stroke z-fights against the
+ * stroke's depth per fragment (mottled boundaries). Encoding the stacking in
+ * renderOrder makes both cases deterministic.
+ */
+export const STROKE_RENDER_ORDER = FEATURE_RENDER_ORDER + 1;
 export const SKY_RENDER_ORDER = 100;
 export const STARS_RENDER_ORDER = SKY_RENDER_ORDER + 1;

package/src/terrain/sampleTerrainMostDetailed.test.ts

@@ -37,6 +37,7 @@ vi.mock("@navaramap/engine-api", () => {
   };
   return {
     default: vi.fn().mockResolvedValue(undefined),
+    angleToRadian: (deg: number) => (deg * Math.PI) / 180,
     terrainPositionsToTiles: vi.fn(
       (geographic: boolean, level: number, positions: Float64Array) => {
         const result = new Uint32Array(positions.length);
@@ -87,12 +88,11 @@ vi.mock("@navaramap/engine-api", () => {
   };
 });
 
-const KARIYA = { lat: (35.0 * Math.PI) / 180, lng: (137.0 * Math.PI) / 180 };
-const NEARBY = {
-  lat: (35.001 * Math.PI) / 180,
-  lng: (137.001 * Math.PI) / 180,
-};
-const TOKYO = { lat: (35.68 * Math.PI) / 180, lng: (139.76 * Math.PI) / 180 };
+// Public inputs are degrees; the mocked engine functions still receive the
+// radians the implementation converts to.
+const KARIYA = { lat: 35.0, lng: 137.0 };
+const NEARBY = { lat: 35.001, lng: 137.001 };
+const TOKYO = { lat: 35.68, lng: 139.76 };
 
 const SOURCE: QuantizedMeshSource = {
   type: "quantized-mesh",

package/src/terrain/sampleTerrainMostDetailed.ts

@@ -1,5 +1,6 @@
 import type { LatLng } from "@navaramap/core";
 import {
+  angleToRadian,
   sampleQuantizedMeshHeights,
   sampleRasterDemHeights,
   terrainPositionsToTiles,
@@ -29,9 +30,9 @@ export type SampleTerrainOptions = {
 };
 
 export type SampledTerrainPosition = {
-  /** Latitude in radians, echoed from the input. */
+  /** Latitude in degrees, echoed from the input. */
   lat: number;
-  /** Longitude in radians, echoed from the input. */
+  /** Longitude in degrees, echoed from the input. */
   lng: number;
   /**
    * Terrain height in meters, or `undefined` when no tile covering the
@@ -104,7 +105,7 @@ type SourceConfig = {
  *
  * @param source - A `quantized-mesh` or `raster-dem` source description (the
  *   same shape `addSource` accepts)
- * @param positions - Geodetic positions (lat/lng in radians)
+ * @param positions - Geodetic positions (lat/lng in degrees)
  * @param options - Optional abort signal and fixed-level sampling
  * @returns One result per input position, in the same order (the input
  *   objects are not mutated)
@@ -123,10 +124,11 @@ export async function sampleTerrainMostDetailed(
   // Fixed-level sampling never falls back to parents.
   const floorLevel = options?.level != null ? startLevel : config.minZoom;
 
+  // The engine samplers work in radians; inputs and echoed outputs are degrees.
   const flat = new Float64Array(positions.length * 2);
   positions.forEach((p, i) => {
-    flat[i * 2] = p.lng;
-    flat[i * 2 + 1] = p.lat;
+    flat[i * 2] = angleToRadian(p.lng);
+    flat[i * 2 + 1] = angleToRadian(p.lat);
   });
 
   // Group positions by their containing tile at the starting level; each

package/src/terrain/terrainHeightEvent.test.ts

@@ -0,0 +1,32 @@
+import type { TerrainHeightUpdatedEvent } from "@navaramap/engine";
+import { describe, expect, it } from "vitest";
+
+import { hasObservedTerrainHeight } from "./terrainHeightEvent";
+
+const BITS = 42n;
+
+/** Only `bits` and `height` are read; the rest of the event is irrelevant here. */
+const event = (height: number | undefined, bits = BITS) =>
+  ({ bits, height }) as TerrainHeightUpdatedEvent;
+
+describe("hasObservedTerrainHeight", () => {
+  it("accepts a sea-level height of 0", () => {
+    // Regression: a truthiness guard dropped 0, so a terrain refinement that
+    // resolved to sea level never re-placed a `heightReference: "terrain"` mesh.
+    expect(hasObservedTerrainHeight(event(0), BITS)).toBe(true);
+  });
+
+  it("accepts ordinary and negative heights", () => {
+    expect(hasObservedTerrainHeight(event(910.5), BITS)).toBe(true);
+    expect(hasObservedTerrainHeight(event(-12), BITS)).toBe(true);
+  });
+
+  it("rejects an absent height", () => {
+    expect(hasObservedTerrainHeight(event(undefined), BITS)).toBe(false);
+  });
+
+  it("rejects an event for a different observer entity", () => {
+    expect(hasObservedTerrainHeight(event(0, 7n), BITS)).toBe(false);
+    expect(hasObservedTerrainHeight(event(910.5, 7n), BITS)).toBe(false);
+  });
+});

package/src/terrain/terrainHeightEvent.ts

@@ -0,0 +1,22 @@
+import type { TerrainHeightUpdatedEvent } from "@navaramap/engine";
+
+/**
+ * Whether a terrain-height event carries a usable height for the observer
+ * registered as `entityBits`.
+ *
+ * `height` is the engine's `Option<f64>` (`TerrainHeightObserver.height` in
+ * `navara_tile_component`): `undefined` means no tile covering the position has
+ * resolved a height yet, which is the case this filters out.
+ *
+ * **Deliberately `!= null` and not a truthiness check.** `0` is sea level — a
+ * perfectly valid computed height, and the engine only emits an event when the
+ * height actually changed. Dropping it would leave a mesh placed with
+ * `geodetic.heightReference: "terrain"` stranded at its previous altitude
+ * whenever a refinement resolved to the sea.
+ */
+export function hasObservedTerrainHeight(
+  ev: TerrainHeightUpdatedEvent,
+  entityBits: bigint,
+): ev is TerrainHeightUpdatedEvent & { height: number } {
+  return ev.bits === entityBits && ev.height != null;
+}