@navaramap/three 0.0.2 → 0.0.3

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@navaramap/three",
   "type": "module",
-  "version": "0.0.2",
+  "version": "0.0.3",
   "main": "dist/index.umd.cjs",
   "module": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -30,13 +30,13 @@
     "astronomy-engine": "2.1.19",
     "stats.js": "0.17.0",
     "three-stdlib": "2.36.1",
-    "@navaramap/font": "0.0.2",
-    "@navaramap/core": "0.0.2",
-    "@navaramap/engine-api": "0.0.2",
-    "@navaramap/engine": "0.0.2",
-    "@navaramap/three_api": "0.0.2",
-    "@navaramap/three_csm": "0.0.2",
-    "@navaramap/worker": "0.0.2"
+    "@navaramap/core": "0.0.3",
+    "@navaramap/engine": "0.0.3",
+    "@navaramap/font": "0.0.3",
+    "@navaramap/three_api": "0.0.3",
+    "@navaramap/engine-api": "0.0.3",
+    "@navaramap/worker": "0.0.3",
+    "@navaramap/three_csm": "0.0.3"
   },
   "devDependencies": {
     "@playwright/test": "1.61.1",
@@ -71,10 +71,10 @@
     "tweakpane": "4.0.5",
     "vite-plugin-glsl": "1.6.0",
     "vite-plugin-static-copy": "4.1.1",
-    "@navaramap/three_default_descs": "0.0.2",
-    "@navaramap/three_default_plugin": "0.0.2",
-    "@navaramap/three_plugins": "0.0.2",
-    "@navaramap/three_react": "0.0.2"
+    "@navaramap/three_default_descs": "0.0.3",
+    "@navaramap/three_default_plugin": "0.0.3",
+    "@navaramap/three_plugins": "0.0.3",
+    "@navaramap/three_react": "0.0.3"
   },
   "scripts": {
     "start": "vite",

package/src/atmosphere.ts

@@ -14,7 +14,13 @@ import invariant from "tiny-invariant";
 
 import { type ThreeViewCamera } from "./camera";
 import { ATMOSPHERE_ASSETS_URL, STBN_URL } from "./constants";
-import { shiftDateToElevation, shiftDateToHourAngle } from "./solar";
+import {
+  dateForSolarTime,
+  getSolarTime as solarTimeAt,
+  getSunElevation as sunElevationAt,
+  shiftDateToElevation,
+  shiftDateToHourAngle,
+} from "./solar";
 
 /**
  * Events emitted by the {@link Atmosphere} class.
@@ -258,6 +264,42 @@ export class Atmosphere extends EventHandler<AtmosphereEvents> {
     return dotProduct < 0;
   }
 
+  /**
+   * Returns the sun's elevation angle in degrees above the local horizon at
+   * `location` for the current {@link date}. Positive is above the horizon,
+   * negative below (night); includes atmospheric refraction.
+   *
+   * @example
+   * const elevation = view.atmosphere.getSunElevation(view.camera.positionGeographic);
+   * if (elevation < 0) console.log("The sun has set.");
+   */
+  getSunElevation(location: { lat: number; lng: number }): number {
+    return sunElevationAt(this.date, location.lat, location.lng);
+  }
+
+  /**
+   * Returns the local apparent solar time at `lng` for the current
+   * {@link date}, in hours in the range [0, 24) where 12 is solar noon.
+   * Accounts for the equation of time.
+   *
+   * @example
+   * const hours = view.atmosphere.getSolarTime({ lng: 139.69 }); // e.g. 6.3 = 06:18
+   */
+  getSolarTime(location: { lng: number }): number {
+    return solarTimeAt(this.date, location.lng);
+  }
+
+  /**
+   * Sets {@link date} so the local apparent solar time at `lng` equals `hours`
+   * (0–24), keeping the same solar day. Inverse of {@link getSolarTime}.
+   *
+   * @example
+   * view.atmosphere.setSolarTime({ lng: 139.69 }, 6.3); // sunrise over Tokyo
+   */
+  setSolarTime(location: { lng: number }, hours: number): void {
+    this.date = dateForSolarTime(this.date, location.lng, hours);
+  }
+
   /**
    * Gets the current date used for calculating sun/moon positions.
    */

package/src/event/feature.ts

@@ -118,6 +118,20 @@ export async function processRenderableFeatureAdded(
 
   const featureLayerId = ev.layer_id;
 
+  // Captured once: the render-completion report is deferred until the mesh is
+  // in its render/bake scene (see below), by which point `ev` may be gone.
+  const bits = ev.bits;
+  const renderedType =
+    point || billboard || text
+      ? "point"
+      : model
+        ? "model"
+        : polyline
+          ? "polyline"
+          : polygon
+            ? "polygon"
+            : undefined;
+
   const useParallel = checkFeatureParallel(feature);
 
   if (useParallel) {
@@ -127,15 +141,6 @@ export async function processRenderableFeatureAdded(
 
   const obj = await renderFeature(ctx, feature, tileHandle, featureLayerId)
     ?.then((r) => {
-      const type = (() => {
-        if (point || billboard || text) return "point";
-        else if (model) return "model";
-        else if (polyline) return "polyline";
-        else if (polygon) return "polygon";
-      })();
-      if (type) {
-        featureHandler.markFeatureIsRendered(type, ev.bits);
-      }
       // The glTF/Draco decode happened on the JS side, so report the actual
       // decoded GPU size back to the ledger (its compressed-payload estimate
       // undercounts Draco content). Draco decode inflates geometry markedly.
@@ -164,7 +169,12 @@ export async function processRenderableFeatureAdded(
       }
     });
 
-  if (!obj) return;
+  if (!obj) {
+    // renderFeature produced no mesh (e.g. empty geometry); still report
+    // rendered so the tile's LOD/activation can advance, as before.
+    if (renderedType) featureHandler.markFeatureIsRendered(renderedType, bits);
+    return;
+  }
 
   // Sprite should be handled by mesh itself.
   const transform = (polyline ?? polygon ?? model)?.transform;
@@ -185,7 +195,10 @@ export async function processRenderableFeatureAdded(
 
   meshes.set(id, obj);
 
-  if (isDraped && tileHandle) {
+  // `!= null` (not truthiness): the root vector tile's handle is 0, which is
+  // falsy — a truthy check silently dropped root-tile draped meshes from the
+  // texturized scene cache, leaving small datasets that render at z0 blank.
+  if (isDraped && tileHandle != null) {
     // Insert the bakeable draped mesh into the per-tile cache now (it is fully built at
     // this point). Readiness/ancestor-fallback is decided entirely on the Rust side from
     // the ECS lifecycle, so no `scene_ready` is reported. Insert even when invisible —
@@ -213,6 +226,14 @@ export async function processRenderableFeatureAdded(
     });
   }
 
+  // Report render-completion to Rust only now that the mesh is in its render
+  // (MRT) or bake (texturized) scene. For draped features this must follow the
+  // `texturizedSceneByTileCoordinates.add` above: the Rust drape resolve flips a
+  // terrain tile's vector source to this tile once its features report rendered,
+  // so reporting before the offscreen scene existed left the terrain tile's
+  // vector drape blank until a camera-move re-traverse.
+  if (renderedType) featureHandler.markFeatureIsRendered(renderedType, bits);
+
   if (obj instanceof PolygonMesh && polygon && polygon.outline_geometry) {
     const outline = await renderPolygonOutline(ctx, polygon);
     outline.renderOrder = FEATURE_RENDER_ORDER;
@@ -320,7 +341,7 @@ export async function processRenderableFeatureChanged(
   if (
     ((obj instanceof PolygonMesh && obj.clampToGround) ||
       (obj instanceof PolylineMesh && obj.draped)) &&
-    tileHandle
+    tileHandle != null // the root tile's handle is 0 (falsy)
   ) {
     texturizedSceneByTileCoordinates.markDirty(tileHandle, layerId);
   }
@@ -345,7 +366,16 @@ export async function processRenderableFeatureChanged(
 
   obj.updateMatrix();
 
-  if (obj.visible) {
+  // Re-emit `featureUpdated` (which re-runs the layer's registered evaluator
+  // over this whole feature set) only when the set is actually displayed at the
+  // current LOD. `obj.visible` is not that signal for draped meshes: they stay
+  // visible while built so they remain stable bakeable drape sources (see
+  // PolygonMesh._update), so gating on it alone re-evaluated every built draped
+  // tile on every activation flip during zoom. The evaluator's per-feature
+  // values persist in the batch data texture, and user-driven restyles reach
+  // inactive sets through `Layer.forceUpdate`, so skipping inactive sets here
+  // is safe.
+  if (obj.visible && active) {
     handleFeatureUpdatedEventByLayerId(
       viewEvents,
       layersManager,

package/src/event/features/polygon.ts

@@ -19,5 +19,6 @@ export function processPolygonChanged(
   active: boolean,
   tileHandle: TileHandle | undefined,
 ) {
-  obj._update(m.material, active, !!tileHandle);
+  // `!= null`, not truthiness: the root vector tile's handle is 0.
+  obj._update(m.material, active, tileHandle != null);
 }

package/src/input.ts

@@ -15,6 +15,21 @@ export function registerInputEvents(
 
   let lastTerrainDistance: number | undefined;
 
+  // Mousedown and mousemove must share the same coordinate space: the engine
+  // re-anchors its cursor position from the mousedown coordinates so the first
+  // drag delta is never computed against a stale position (e.g. after the
+  // window lost focus while the OS cursor kept moving).
+  const normalizePosition = (event: MouseEvent) => {
+    const rect = element.getBoundingClientRect();
+    const width = element.clientWidth;
+    const height = element.clientHeight;
+    const aspectRatio = width / height;
+    return {
+      x: ((event.clientX - rect.left) / width) * aspectRatio,
+      y: (event.clientY - rect.top) / height,
+    };
+  };
+
   const mousedown = (event: MouseEvent) => {
     mouseEvent = {
       type: "mousedown",
@@ -22,7 +37,11 @@ export function registerInputEvents(
     };
     const terrainDistance = getTerrainDistance?.() ?? undefined;
     lastTerrainDistance = terrainDistance;
-    core.input({ ...mouseEvent, terrain_distance: terrainDistance });
+    core.input({
+      ...mouseEvent,
+      ...normalizePosition(event),
+      terrain_distance: terrainDistance,
+    });
   };
   const mouseup = () => {
     core.input({
@@ -33,13 +52,9 @@ export function registerInputEvents(
   };
 
   const mousemove = (event: MouseEvent) => {
-    const width = element.clientWidth;
-    const height = element.clientHeight;
-    const aspectRatio = width / height;
     core.input({
       type: "mousemove",
-      x: (event.clientX / width) * aspectRatio,
-      y: event.clientY / height,
+      ...normalizePosition(event),
     });
   };
 
@@ -109,36 +124,54 @@ export function registerInputEvents(
       key: event?.key,
     });
   };
-  // This is used to emit a key up event without any params.
-  const keyupEmpty = () => {
-    core.input({
-      type: "keyup",
-    });
+
+  // Releases every pressed button and modifier key. When the window loses
+  // focus or visibility the matching mouseup/keyup fires in another window, so
+  // without this the engine would keep acting on stale pressed state after the
+  // user comes back.
+  const releaseInputs = () => {
+    for (const button of [0, 1, 2]) {
+      core.input({ type: "mouseup", button });
+    }
+    mouseEvent = undefined;
+    core.input({ type: "keyup", key_code: "ControlLeft", key: "Control" });
+    core.input({ type: "keyup", key_code: "ControlRight", key: "Control" });
+  };
+  const visibilitychange = () => {
+    if (document.visibilityState === "hidden") {
+      releaseInputs();
+    }
   };
 
   element.addEventListener("mousedown", mousedown);
   element.addEventListener("mouseup", mouseup);
-  element.addEventListener("mouseleave", mouseup);
-  element.addEventListener("mouseleave", keyupEmpty);
+  element.addEventListener("mouseleave", releaseInputs);
   element.addEventListener("mousemove", mousemove);
   element.addEventListener("touchstart", touchstart);
   element.addEventListener("touchend", touchend);
+  // The browser cancels active touches on app switches and system gestures;
+  // treat them as ended so no stale touch stays in the engine.
+  element.addEventListener("touchcancel", touchend);
   element.addEventListener("touchmove", touchmove);
   element.addEventListener("wheel", wheel);
   document.addEventListener("keydown", keydown);
   document.addEventListener("keyup", keyup);
+  window.addEventListener("blur", releaseInputs);
+  document.addEventListener("visibilitychange", visibilitychange);
 
   return () => {
     element.removeEventListener("mousedown", mousedown);
     element.removeEventListener("mouseup", mouseup);
-    element.removeEventListener("mouseleave", mouseup);
-    element.removeEventListener("mouseleave", keyupEmpty);
+    element.removeEventListener("mouseleave", releaseInputs);
     element.removeEventListener("mousemove", mousemove);
     element.removeEventListener("touchstart", touchstart);
     element.removeEventListener("touchend", touchend);
+    element.removeEventListener("touchcancel", touchend);
     element.removeEventListener("touchmove", touchmove);
     element.removeEventListener("wheel", wheel);
     document.removeEventListener("keydown", keydown);
     document.removeEventListener("keyup", keyup);
+    window.removeEventListener("blur", releaseInputs);
+    document.removeEventListener("visibilitychange", visibilitychange);
   };
 }

package/src/material/enhancer/instancedSprite/instancedSpriteBaseEnhancer/mutates.test.ts

@@ -10,6 +10,7 @@ import type { InstancedSpriteBaseState } from "./types";
 
 vi.mock("@navaramap/three_api", () => ({
   degreeToRadian: (degree: number) => (degree * Math.PI) / 180,
+  RTE_ONE_UNIFORM: { value: 1.0 },
 }));
 
 vi.mock("@navaramap/engine-api", () => ({

package/src/material/enhancer/instancedSprite/instancedSpriteBaseEnhancer/mutates.ts

@@ -1,4 +1,5 @@
 import { encodePosition } from "@navaramap/engine-api";
+import { RTE_ONE_UNIFORM } from "@navaramap/three_api";
 import {
   type Matrix4,
   type Texture,
@@ -82,6 +83,7 @@ export const createBaseMutates = (
       uniforms.uRTCCenterView = refs.uRTCCenterView;
       uniforms.uEyeRTELow = refs.uEyeRTELow;
       uniforms.uEyeRTEHigh = refs.uEyeRTEHigh;
+      uniforms.u_rteOne = RTE_ONE_UNIFORM;
       uniforms.uScale = refs.uScale;
       uniforms.uCenter = refs.uCenter;
       uniforms.uSizeInMeters = refs.uSizeInMeters;

package/src/material/enhancer/instancedSprite/instancedSpriteBaseEnhancer/types.ts

@@ -77,6 +77,8 @@ export type InstancedSpriteBaseRefs = {
   uRTCCenterView: UniformValue<Vector3>;
   uEyeRTELow: UniformValue<Vector3>;
   uEyeRTEHigh: UniformValue<Vector3>;
+  /** Always 1.0 — blocks fast-math reassociation of the RTE recombination. */
+  u_rteOne?: UniformValue<number>;
   uScale: UniformValue<number>;
   uCenter: UniformValue<Vector2>;
   uSizeInMeters: UniformValue<boolean>;

package/src/material/enhancer/polygon/polygonBaseEnhancer/mutates.ts

@@ -1,3 +1,4 @@
+import { RTE_ONE_UNIFORM } from "@navaramap/three_api";
 import type { Matrix4, Texture, Vector3 } from "three";
 import { Matrix4 as ThreeMatrix4, Vector3 as ThreeVector3 } from "three";
 
@@ -78,6 +79,7 @@ export const createBaseMutates = (useRTE: boolean): PolygonBaseMutates => {
         uniforms.u_cameraPositionHigh = refs.u_cameraPositionHigh;
         uniforms.u_cameraPositionLow = refs.u_cameraPositionLow;
         uniforms.modelViewMatrixRTE = refs.modelViewMatrixRTE;
+        uniforms.u_rteOne = RTE_ONE_UNIFORM;
       }
 
       // Height uniforms

package/src/material/enhancer/polygon/polygonBaseEnhancer/shader.ts

@@ -115,7 +115,11 @@ ${ShadowMapDepthVertex}
 #include <envmap_vertex>
 
 vPosition = absTransformed.xyz;
-vViewPosition = -absMvPosition.xyz;
+// mvPosition comes from the RTE projection (modelViewMatrixRTE * camera-relative
+// position), so it is precise at any distance. Deriving vViewPosition from
+// modelViewMatrix * absTransformed instead would suffer f32 cancellation at
+// ECEF magnitude and make view-dependent shading wobble as the camera moves.
+vViewPosition = -mvPosition.xyz;
 `,
       useRTE,
     )

package/src/material/enhancer/polygon/polygonBaseEnhancer/types.ts

@@ -108,6 +108,8 @@ export type PolygonBaseRefs = {
   modelViewMatrixRTE?: UniformValue<Matrix4>;
   u_cameraPositionHigh?: UniformValue<Vector3>;
   u_cameraPositionLow?: UniformValue<Vector3>;
+  /** Always 1.0 — blocks fast-math reassociation of the RTE recombination. */
+  u_rteOne?: UniformValue<number>;
 };
 
 export type PolygonBaseUniforms = Partial<PolygonBaseRefs>;

package/src/material/enhancer/polyline/polylineBaseEnhancer/mutates.ts

@@ -1,3 +1,4 @@
+import { RTE_ONE_UNIFORM } from "@navaramap/three_api";
 import {
   Color as ThreeColor,
   Matrix4 as ThreeMatrix4,
@@ -101,6 +102,7 @@ export const createBaseMutates = (useRTE: boolean): PolylineBaseMutates => {
         uniforms.u_cameraPositionHigh = refs.u_cameraPositionHigh;
         uniforms.u_cameraPositionLow = refs.u_cameraPositionLow;
         uniforms.modelViewMatrixRTE = refs.modelViewMatrixRTE;
+        uniforms.u_rteOne = RTE_ONE_UNIFORM;
       }
 
       // Batch texture

package/src/material/enhancer/polyline/polylineBaseEnhancer/types.ts

@@ -114,6 +114,8 @@ export type PolylineBaseRefs = {
   modelViewMatrixRTE?: UniformValue<Matrix4>;
   u_cameraPositionHigh?: UniformValue<Vector3>;
   u_cameraPositionLow?: UniformValue<Vector3>;
+  /** Always 1.0 — blocks fast-math reassociation of the RTE recombination. */
+  u_rteOne?: UniformValue<number>;
 };
 
 export type PolylineBaseUniforms = Partial<PolylineBaseRefs>;

package/src/material/enhancer/sdfText/sdfTextBaseEnhancer/mutates.ts

@@ -1,4 +1,5 @@
 import { encodePosition } from "@navaramap/engine-api";
+import { RTE_ONE_UNIFORM } from "@navaramap/three_api";
 import { Color, DataTexture, type Matrix4, Vector2, Vector3 } from "three";
 
 import type { UniformValue } from "../../../types";
@@ -119,6 +120,7 @@ export const createBaseMutates = (
       uniforms.uRTCCenterView = refs.uRTCCenterView;
       uniforms.uEyeRTELow = refs.uEyeRTELow;
       uniforms.uEyeRTEHigh = refs.uEyeRTEHigh;
+      uniforms.u_rteOne = RTE_ONE_UNIFORM;
       uniforms.nvr_uBatchId = refs.nvr_uBatchId;
       uniforms.nvr_uPickable = refs.nvr_uPickable;
       uniforms.uAtlas = refs.uAtlas;

package/src/material/enhancer/sdfText/sdfTextBaseEnhancer/types.ts

@@ -111,6 +111,8 @@ export type SdfTextBaseRefs = {
   uRTCCenterView: UniformValue<Vector3>;
   uEyeRTELow: UniformValue<Vector3>;
   uEyeRTEHigh: UniformValue<Vector3>;
+  /** Always 1.0 — blocks fast-math reassociation of the RTE recombination. */
+  u_rteOne?: UniformValue<number>;
   nvr_uBatchId: UniformValue<number>;
   nvr_uPickable: UniformValue<number>;
   uAtlas: UniformValue<DataTexture | null>;

package/src/material/overrideMaterialsForMRT.ts

@@ -431,8 +431,13 @@ export function setupMaterialForMRT(
   material: ShaderMaterial,
   options?: SetupMaterialForMRTOptions,
 ): void {
-  if (material instanceof LineMaterial) {
-    injectGBufferToLineMaterial(material);
+  // Detect LineMaterial by `type`, not only `instanceof`: callers may construct
+  // it from `three/examples/jsm/lines` while this module's `LineMaterial` comes
+  // from `three-stdlib`, so a bare `instanceof` misses those cross-copy
+  // instances and would wrongly route them through the ShaderMaterial path
+  // (whose normal-buffer write references an undeclared `normal`).
+  if (material instanceof LineMaterial || material.type === "LineMaterial") {
+    injectGBufferToLineMaterial(material as LineMaterial);
     return;
   }
   injectGBufferToShaderMaterial(material, options?.normal);