@navaramap/three 0.0.8 → 0.1.1

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@navaramap/three",
   "type": "module",
-  "version": "0.0.8",
+  "version": "0.1.1",
   "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/core": "0.0.8",
-    "@navaramap/engine-api": "0.0.8",
-    "@navaramap/three-api": "0.0.8",
-    "@navaramap/font": "0.0.8",
-    "@navaramap/three-csm": "0.0.8",
-    "@navaramap/worker": "0.0.8",
-    "@navaramap/engine": "0.0.8"
+    "@navaramap/core": "0.1.1",
+    "@navaramap/engine": "0.1.1",
+    "@navaramap/three-api": "0.1.1",
+    "@navaramap/three-csm": "0.1.1",
+    "@navaramap/worker": "0.1.1",
+    "@navaramap/engine-api": "0.1.1",
+    "@navaramap/font": "0.1.1"
   },
   "devDependencies": {
     "@playwright/test": "1.62.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.8",
-    "@navaramap/three-default-plugin": "0.0.8",
-    "@navaramap/three-plugins": "0.0.8",
-    "@navaramap/three-react": "0.0.8"
+    "@navaramap/three-default-descs": "0.1.1",
+    "@navaramap/three-default-plugin": "0.1.1",
+    "@navaramap/three-react": "0.1.1",
+    "@navaramap/three-plugins": "0.1.1"
   },
   "scripts": {
     "start": "vite",

package/src/core/BaseDesc.ts

@@ -76,6 +76,8 @@ export abstract class BaseDesc<
 
   private _visible?: boolean;
 
+  private _destroyed = false;
+
   constructor(
     view: ThreeView,
     ctx: ViewContext,
@@ -92,8 +94,20 @@ export abstract class BaseDesc<
   /**
    * Called when the this class is added to the scene. Override this to create the Three.js objects.
    * This is where you should initialize `this._instance` and add it to the appropriate scene.
+   *
+   * May return a promise: a descriptor whose implementation loads lazily
+   * (e.g. an `await import(...)` of a heavy renderer dependency) can be
+   * `async`, awaiting the module before delegating to `super.onCreate()`
+   * (after checking {@link destroyed}). `addMesh`/`addLight`/`addEffect`
+   * still return their handle synchronously; the instance appears once the
+   * promise settles, and a rejection is reported through the descriptor's
+   * `error` event (when it declares one). Handle calls issued while the
+   * promise is pending are safe: `update()`/`visible` store their fields
+   * without touching the missing instance (the deferred `super.onCreate()`
+   * applies them), and per-frame/resize hooks are wired only after creation
+   * completes.
    */
-  abstract onCreate(): void;
+  abstract onCreate(): void | Promise<void>;
 
   /**
    * Called when the configuration is updated via `BaseHandle.update()`.
@@ -122,9 +136,19 @@ export abstract class BaseDesc<
    * Override this to clean up resources. Remember to call `super.onDestroy()`.
    */
   onDestroy(): void {
+    this._destroyed = true;
     this._instance = undefined;
   }
 
+  /**
+   * True once {@link onDestroy} has run. An async {@link onCreate} (and the
+   * hook wiring that waits on it) checks this after its awaited module
+   * resolves, so a descriptor deleted mid-load creates nothing.
+   */
+  get destroyed(): boolean {
+    return this._destroyed;
+  }
+
   /**
    * Gets whether this is currently visible.
    */

package/src/core/MeshDesc.test.ts

@@ -274,15 +274,15 @@ describe("MeshDesc geodetic placement", () => {
 });
 
 describe("MeshDesc terrain-referenced placement", () => {
-  type LatLngRad = { lat: number; lng: number };
+  type LatLngDeg = { lat: number; lng: number };
 
   const terrainView = (height: number | undefined) => {
     const listeners: ((h: number) => void)[] = [];
     const unsubscribe = vi.fn();
     const spy = {
-      sampleTerrainHeight: vi.fn((_pos: LatLngRad) => height),
+      sampleTerrainHeight: vi.fn((_pos: LatLngDeg) => height),
       observeTerrainHeightAt: vi.fn(
-        (_pos: LatLngRad, cb: (h: number) => void) => {
+        (_pos: LatLngDeg, cb: (h: number) => void) => {
           listeners.push(cb);
           return unsubscribe;
         },
@@ -297,8 +297,6 @@ describe("MeshDesc terrain-referenced placement", () => {
     return desc;
   };
 
-  const rad = (deg: number) => (deg * Math.PI) / 180;
-
   it("seeds from the resident-tile sample and subscribes", () => {
     const { view, spy } = terrainView(300);
     createWith(view, {
@@ -308,10 +306,10 @@ describe("MeshDesc terrain-referenced placement", () => {
     expect(spy.sampleTerrainHeight).toHaveBeenCalled();
     expect(spy.observeTerrainHeightAt).toHaveBeenCalled();
 
-    // Both engine methods take RADIANS, while `geodetic` is degrees.
+    // Both terrain methods take the same degrees `geodetic` carries.
     const pos = spy.sampleTerrainHeight.mock.calls[0][0];
-    expect(pos.lat).toBeCloseTo(rad(TOKYO.lat), 9);
-    expect(pos.lng).toBeCloseTo(rad(TOKYO.lng), 9);
+    expect(pos.lat).toBeCloseTo(TOKYO.lat, 9);
+    expect(pos.lng).toBeCloseTo(TOKYO.lng, 9);
 
     // terrain 300 + requested 10
     expect(lastPlacement()?.height).toBeCloseTo(310, 9);

package/src/core/MeshDesc.ts

@@ -3,7 +3,7 @@ import {
   headingPitchRollToFixedFrame,
   type GeodeticPlacement,
 } from "@navaramap/three-api";
-import { Euler, MathUtils, Matrix4, Object3D, Vector3, type Mesh } from "three";
+import { Euler, Matrix4, Object3D, Vector3, type Mesh } from "three";
 import invariant from "tiny-invariant";
 
 import type ThreeView from "../index";
@@ -369,10 +369,7 @@ export abstract class MeshDesc<
       return;
     }
 
-    const pos = {
-      lat: MathUtils.degToRad(g.lat),
-      lng: MathUtils.degToRad(g.lng),
-    };
+    const pos = { lat: g.lat, lng: g.lng };
     this.terrainHeight = this.view.sampleTerrainHeight(pos) ?? 0;
     this.terrainUnsubscribe = this.view.observeTerrainHeightAt(
       pos,
@@ -601,7 +598,6 @@ export abstract class MeshDesc<
     assertNoTransformConflict(nextGeodetic, nextMatrix, nextMatrixWorld);
 
     super.onUpdateConfig(updates);
-    invariant(this.raw);
 
     const spatialChanged =
       updates.matrix !== undefined ||
@@ -639,6 +635,8 @@ export abstract class MeshDesc<
       this.applyLit();
     }
 
+    if (!this.raw) return;
+
     if (spatialChanged) {
       // With a frame present, the effective transform depends on the
       // combination of all stored fields — recompose the whole thing.

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/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,