@navaramap/three 0.0.6 → 0.0.7

package/src/mesh/sdfText/pendingSettlement.test.ts

@@ -0,0 +1,151 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+import { PendingSettlement } from "./pendingSettlement";
+
+/** Drains several microtask ticks so chained `.then` callbacks have run. */
+const flushMicrotasks = async () => {
+  for (let i = 0; i < 10; i++) await Promise.resolve();
+};
+
+describe("PendingSettlement", () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  it("resolves immediately when nothing is in flight", async () => {
+    const s = new PendingSettlement();
+    let settled = false;
+    void s.whenSettled(1000).then(() => (settled = true));
+    await flushMicrotasks();
+    expect(settled).toBe(true);
+  });
+
+  it("waits for a tracked promise to resolve", async () => {
+    const s = new PendingSettlement();
+    let resolveOp!: () => void;
+    s.track(new Promise<void>((r) => (resolveOp = r)));
+
+    let settled = false;
+    void s.whenSettled(1000).then(() => (settled = true));
+    await flushMicrotasks();
+    expect(settled).toBe(false);
+
+    resolveOp();
+    await flushMicrotasks();
+    expect(settled).toBe(true);
+  });
+
+  it("counts a rejected promise as settled", async () => {
+    const s = new PendingSettlement();
+    let rejectOp!: (e: Error) => void;
+    s.track(new Promise<void>((_, rj) => (rejectOp = rj)));
+
+    let settled = false;
+    void s.whenSettled(1000).then(() => (settled = true));
+
+    rejectOp(new Error("prepare failed"));
+    await flushMicrotasks();
+    expect(settled).toBe(true);
+  });
+
+  it("waits for the last of several tracked promises", async () => {
+    const s = new PendingSettlement();
+    const resolvers: (() => void)[] = [];
+    for (let i = 0; i < 3; i++) {
+      s.track(new Promise<void>((r) => resolvers.push(r)));
+    }
+
+    let settled = false;
+    void s.whenSettled(1000).then(() => (settled = true));
+
+    resolvers[0]();
+    resolvers[1]();
+    await flushMicrotasks();
+    expect(settled).toBe(false);
+
+    resolvers[2]();
+    await flushMicrotasks();
+    expect(settled).toBe(true);
+  });
+
+  it("resolves at the timeout when an operation never settles", async () => {
+    const s = new PendingSettlement();
+    s.track(new Promise<void>(() => {}));
+
+    let settled = false;
+    void s.whenSettled(1000).then(() => (settled = true));
+
+    await vi.advanceTimersByTimeAsync(999);
+    expect(settled).toBe(false);
+
+    await vi.advanceTimersByTimeAsync(1);
+    expect(settled).toBe(true);
+  });
+
+  // A timed-out waiter used to stay queued forever when its operation never
+  // settled, so repeated calls grew the queue without bound and a late settle
+  // still invoked every one of them.
+  it("drops timed-out waiters instead of queueing them forever", async () => {
+    const s = new PendingSettlement();
+    s.track(new Promise<void>(() => {}));
+
+    for (let i = 0; i < 5; i++) {
+      void s.whenSettled(1000);
+      await vi.advanceTimersByTimeAsync(1000);
+    }
+
+    // Private, but the leak is only observable here — the queue is the bug.
+    const waiters = (s as unknown as { _waiters: unknown[] })._waiters;
+    expect(waiters.length).toBe(0);
+  });
+
+  it("completes once when a settle races the timeout", async () => {
+    const s = new PendingSettlement();
+    let resolveOp!: () => void;
+    s.track(new Promise<void>((r) => (resolveOp = r)));
+
+    let count = 0;
+    void s.whenSettled(1000).then(() => count++);
+
+    // Time out first, then let the operation settle afterwards.
+    await vi.advanceTimersByTimeAsync(1000);
+    expect(count).toBe(1);
+
+    resolveOp();
+    await flushMicrotasks();
+    expect(count).toBe(1);
+
+    // The settle still drained the queue, so a fresh call resolves at once.
+    let after = false;
+    void s.whenSettled(1000).then(() => (after = true));
+    await flushMicrotasks();
+    expect(after).toBe(true);
+  });
+
+  it("supports waiters registered across separate settle cycles", async () => {
+    const s = new PendingSettlement();
+
+    let resolveA!: () => void;
+    s.track(new Promise<void>((r) => (resolveA = r)));
+    let firstSettled = false;
+    void s.whenSettled(1000).then(() => (firstSettled = true));
+    resolveA();
+    await flushMicrotasks();
+    expect(firstSettled).toBe(true);
+
+    let resolveB!: () => void;
+    s.track(new Promise<void>((r) => (resolveB = r)));
+    let secondSettled = false;
+    void s.whenSettled(1000).then(() => (secondSettled = true));
+    await flushMicrotasks();
+    expect(secondSettled).toBe(false);
+
+    resolveB();
+    await flushMicrotasks();
+    expect(secondSettled).toBe(true);
+  });
+});

package/src/mesh/sdfText/pendingSettlement.ts

@@ -0,0 +1,68 @@
+/**
+ * Counts in-flight async operations and lets callers await the moment the
+ * count returns to zero, bounded by a timeout.
+ *
+ * Used to defer a text batch's render-completion report until its labels'
+ * async font preparations have landed: the report drives the Rust tile-LOD
+ * swap, and reporting while glyph runs are still being shaped swaps a parent
+ * tile out for a child that draws nothing (a tile-shaped blank).
+ */
+export class PendingSettlement {
+  private _pending = 0;
+  private _waiters: (() => void)[] = [];
+
+  get pending(): number {
+    return this._pending;
+  }
+
+  /** Track an in-flight operation. Rejection counts as settled too — a failed
+   *  font prepare must not hold the LOD swap hostage. */
+  track(p: Promise<unknown>): void {
+    this._pending++;
+    const done = () => {
+      this._pending--;
+      if (this._pending === 0) {
+        const waiters = this._waiters;
+        this._waiters = [];
+        for (const w of waiters) w();
+      }
+    };
+    p.then(done, done);
+  }
+
+  /**
+   * Resolves once nothing tracked is in flight, or after `timeoutMs`,
+   * whichever comes first. Only operations already tracked when this is
+   * called are waited on (plus any tracked before the count next reaches
+   * zero); resolves immediately when already settled.
+   *
+   * Settle and timeout are mutually exclusive completion paths, and the
+   * timeout drops its own waiter: an operation that never settles would
+   * otherwise leave every timed-out waiter queued forever, so repeated calls
+   * would grow `_waiters` without bound.
+   */
+  whenSettled(timeoutMs: number): Promise<void> {
+    if (this._pending === 0) return Promise.resolve();
+    return new Promise((resolve) => {
+      let finished = false;
+      const finish = () => {
+        if (finished) return;
+        finished = true;
+        clearTimeout(timer);
+        resolve();
+      };
+      // Declared after `finish` so it can be `const`; `finish` only reads it
+      // when invoked, which is always after this assignment.
+      const timer = setTimeout(() => {
+        this._removeWaiter(finish);
+        finish();
+      }, timeoutMs);
+      this._waiters.push(finish);
+    });
+  }
+
+  private _removeWaiter(waiter: () => void): void {
+    const i = this._waiters.indexOf(waiter);
+    if (i !== -1) this._waiters.splice(i, 1);
+  }
+}

package/src/pick/pickTerrain.ts

@@ -123,12 +123,22 @@ export class TerrainPicker {
       1.0 / PackFactors[3],
     ];
 
-    // Calculate dot product
+    // readRenderTargetPixels returns bytes 0..255; a GLSL texel channel is byte / 255.
     return (
-      (rgba[0] / 256.0) * UnpackFactors4[0] +
-      (rgba[1] / 256.0) * UnpackFactors4[1] +
-      (rgba[2] / 256.0) * UnpackFactors4[2] +
-      (rgba[3] / 256.0) * UnpackFactors4[3]
+      (rgba[0] / 255.0) * UnpackFactors4[0] +
+      (rgba[1] / 255.0) * UnpackFactors4[1] +
+      (rgba[2] / 255.0) * UnpackFactors4[2] +
+      (rgba[3] / 255.0) * UnpackFactors4[3]
+    );
+  }
+
+  // Clamped device-pixel center for a CSS-pixel screen coordinate. Sampling
+  // and ray reconstruction must both use this exact point: the depth copy
+  // target is linearly filtered, and any off-center coordinate would blend
+  // neighboring packed-RGBA texels into meaningless depth values.
+  private _texelCenter(cssCoord: number, size: number, pixelRatio: number) {
+    return (
+      Math.max(0, Math.min(size - 1, Math.floor(cssCoord * pixelRatio))) + 0.5
     );
   }
 
@@ -147,18 +157,11 @@ export class TerrainPicker {
     const height = renderer.getContext().drawingBufferHeight;
     const pixelRatio = renderer.getPixelRatio();
 
-    // Clamp coordinates to screen bounds
-    const clampedX = Math.max(
-      0,
-      Math.min(width - 1, Math.floor(x * pixelRatio)),
-    );
-    const clampedY = Math.max(
-      0,
-      Math.min(height - 1, Math.floor(y * pixelRatio)),
-    );
+    const centerX = this._texelCenter(x, width, pixelRatio);
+    const centerY = this._texelCenter(y, height, pixelRatio);
 
     // Update the depth pick pass with current parameters
-    const samplePos = new Vector2(clampedX / width, 1.0 - clampedY / height); // Flip Y
+    const samplePos = new Vector2(centerX / width, 1.0 - centerY / height); // Flip Y
     this.depthPickPass.update(depthTexture, samplePos);
 
     // Render and get pixels
@@ -186,10 +189,11 @@ export class TerrainPicker {
     const height = renderer.getContext().drawingBufferHeight;
     const pixelRatio = renderer.getPixelRatio();
 
-    // Convert screen coordinates to NDC [-1,1]
+    // Convert the sampled texel's center to NDC [-1,1], so the reconstructed
+    // ray goes through the exact pixel whose depth was read.
     const screenCoords = new Vector2(
-      ((x * pixelRatio) / width) * 2.0 - 1.0,
-      -(((y * pixelRatio) / height) * 2.0 - 1.0),
+      (this._texelCenter(x, width, pixelRatio) / width) * 2.0 - 1.0,
+      -((this._texelCenter(y, height, pixelRatio) / height) * 2.0 - 1.0),
     );
 
     let clipCoords: Vector4;

package/src/terrain/sampleTerrainMostDetailed.test.ts

@@ -0,0 +1,236 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+import type { QuantizedMeshSource } from "../type";
+
+import { sampleTerrainMostDetailed } from "./sampleTerrainMostDetailed";
+
+// The worker pool package probes os.cpus at import time, which jsdom lacks;
+// report "no pool" so the DEM decode falls back to the main thread (the
+// quantized-mesh tests never decode images anyway).
+vi.mock("@navaramap/worker", () => ({
+  workerPoolStats: () => undefined,
+  queueTask: vi.fn(),
+}));
+
+// The WASM math is covered by Rust unit tests; here it is mocked with a
+// transparent JS model (geographic scheme, TMS y-flip, constant height per
+// level) so the tests exercise the orchestration: grouping, the 404 descent,
+// retries, status-code policy and aborts.
+vi.mock("@navaramap/engine-api", () => {
+  const tileFor = (
+    geographic: boolean,
+    level: number,
+    lng: number,
+    lat: number,
+  ) => {
+    const columns = (geographic ? 2 : 1) * 2 ** level;
+    const rows = 2 ** level;
+    const x = Math.min(
+      Math.floor(((lng + Math.PI) / (2 * Math.PI)) * columns),
+      columns - 1,
+    );
+    const y = Math.min(
+      Math.floor(((Math.PI / 2 - lat) / Math.PI) * rows),
+      rows - 1,
+    );
+    return { x, y };
+  };
+  return {
+    default: vi.fn().mockResolvedValue(undefined),
+    terrainPositionsToTiles: vi.fn(
+      (geographic: boolean, level: number, positions: Float64Array) => {
+        const result = new Uint32Array(positions.length);
+        for (let i = 0; i < positions.length; i += 2) {
+          const { x, y } = tileFor(
+            geographic,
+            level,
+            positions[i],
+            positions[i + 1],
+          );
+          result[i] = x;
+          result[i + 1] = y;
+        }
+        return result;
+      },
+    ),
+    terrainTileUrl: vi.fn(
+      (
+        template: string,
+        _geographic: boolean,
+        tms: boolean,
+        x: number,
+        y: number,
+        z: number,
+      ) => {
+        const urlY = tms ? 2 ** z - 1 - y : y;
+        return template
+          .replace("{x}", String(x))
+          .replace("{y}", String(urlY))
+          .replace("{z}", String(z));
+      },
+    ),
+    // Heights encode the sampled level so tests can assert which LOD won.
+    sampleQuantizedMeshHeights: vi.fn(
+      (
+        bytes: Uint8Array,
+        _geographic: boolean,
+        _x: number,
+        _y: number,
+        z: number,
+        positions: Float64Array,
+      ) => {
+        if (bytes.length === 0) return undefined; // undecodable payload
+        return new Float64Array(positions.length / 2).fill(1000 + z);
+      },
+    ),
+    sampleRasterDemHeights: vi.fn(),
+  };
+});
+
+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 };
+
+const SOURCE: QuantizedMeshSource = {
+  type: "quantized-mesh",
+  url: "https://terrain.test/{z}/{x}/{y}.terrain",
+  maxZoom: 14,
+};
+
+/** fetch stub: tiles exist only at or below `coverageLevel`. */
+function stubFetch(
+  coverageLevel: number,
+  overrides?: (url: string) => Response | undefined,
+) {
+  const seen: string[] = [];
+  const mocked = vi.fn(async (input: RequestInfo | URL) => {
+    const url = String(input);
+    seen.push(url);
+    const override = overrides?.(url);
+    if (override) return override;
+    const z = Number(url.match(/\/(\d+)\/\d+\/\d+\.terrain/)?.[1]);
+    if (z <= coverageLevel) {
+      return new Response(new Uint8Array([1, 2, 3]), { status: 200 });
+    }
+    return new Response(null, { status: 404 });
+  });
+  vi.stubGlobal("fetch", mocked);
+  return { seen, mocked };
+}
+
+describe("sampleTerrainMostDetailed", () => {
+  beforeEach(() => {
+    vi.useRealTimers();
+  });
+  afterEach(() => {
+    vi.unstubAllGlobals();
+    vi.clearAllMocks();
+  });
+
+  it("returns an empty array for no positions", async () => {
+    await expect(sampleTerrainMostDetailed(SOURCE, [])).resolves.toEqual([]);
+  });
+
+  it("samples at maxZoom when the tile exists, without mutating the input", async () => {
+    stubFetch(14);
+    const input = [{ ...KARIYA }];
+    const results = await sampleTerrainMostDetailed(SOURCE, input);
+    expect(results).toHaveLength(1);
+    expect(results[0].height).toBe(1014);
+    expect(results[0].level).toBe(14);
+    expect(results[0].lat).toBe(KARIYA.lat);
+    expect(input[0]).toEqual(KARIYA);
+    expect((input[0] as Record<string, unknown>).height).toBeUndefined();
+  });
+
+  it("descends to the deepest available level on 404", async () => {
+    stubFetch(11);
+    const results = await sampleTerrainMostDetailed(SOURCE, [KARIYA]);
+    expect(results[0].height).toBe(1011);
+    expect(results[0].level).toBe(11);
+  });
+
+  it("fetches a shared tile once for positions in the same tile", async () => {
+    const { mocked } = stubFetch(14);
+    const results = await sampleTerrainMostDetailed(SOURCE, [KARIYA, NEARBY]);
+    // Both positions fall in the same z14 geographic tile.
+    expect(mocked).toHaveBeenCalledTimes(1);
+    expect(results.map((r) => r.height)).toEqual([1014, 1014]);
+  });
+
+  it("samples distant positions from their own tiles", async () => {
+    const { mocked } = stubFetch(14);
+    const results = await sampleTerrainMostDetailed(SOURCE, [KARIYA, TOKYO]);
+    expect(mocked).toHaveBeenCalledTimes(2);
+    expect(results.map((r) => r.height)).toEqual([1014, 1014]);
+  });
+
+  it("keeps a fixed options.level from falling back to parents", async () => {
+    const { seen } = stubFetch(10);
+    const results = await sampleTerrainMostDetailed(SOURCE, [KARIYA], {
+      level: 12,
+    });
+    expect(results[0].height).toBeUndefined();
+    expect(results[0].level).toBeUndefined();
+    expect(seen.every((url) => url.includes("/12/"))).toBe(true);
+  });
+
+  it("rejects on 401/403 instead of silently coarsening", async () => {
+    stubFetch(14, () => new Response(null, { status: 403 }));
+    await expect(sampleTerrainMostDetailed(SOURCE, [KARIYA])).rejects.toThrow(
+      /403/,
+    );
+  });
+
+  it("retries 5xx and then reports undefined heights", async () => {
+    let calls = 0;
+    vi.stubGlobal(
+      "fetch",
+      vi.fn(async () => {
+        calls++;
+        return new Response(null, { status: 503 });
+      }),
+    );
+    const results = await sampleTerrainMostDetailed(SOURCE, [KARIYA]);
+    expect(results[0].height).toBeUndefined();
+    // Initial attempt + 2 retries for the deepest level, and no descent to a
+    // parent — a persistent server error is not "tile missing".
+    expect(calls).toBe(3);
+  });
+
+  it("sends the quantized-mesh Accept header and the bearer token", async () => {
+    const { mocked } = stubFetch(14);
+    await sampleTerrainMostDetailed({ ...SOURCE, token: "secret" }, [KARIYA]);
+    const call = mocked.mock.calls[0] as unknown as [string, RequestInit];
+    const headers = call[1].headers as Record<string, string>;
+    expect(headers.Accept).toContain("application/vnd.quantized-mesh");
+    expect(headers.Authorization).toBe("Bearer secret");
+  });
+
+  it("rejects when already aborted", async () => {
+    stubFetch(14);
+    const controller = new AbortController();
+    controller.abort();
+    await expect(
+      sampleTerrainMostDetailed(SOURCE, [KARIYA], {
+        signal: controller.signal,
+      }),
+    ).rejects.toThrow();
+  });
+
+  it("marks heights undefined when the payload does not decode", async () => {
+    // 200 with an empty body: the mocked sampler returns undefined for it.
+    stubFetch(14, () => new Response(new Uint8Array(0), { status: 200 }));
+    const results = await sampleTerrainMostDetailed(SOURCE, [KARIYA]);
+    expect(results[0].height).toBeUndefined();
+  });
+
+  it("requires source.url", async () => {
+    await expect(
+      sampleTerrainMostDetailed({ type: "quantized-mesh", url: "" }, [KARIYA]),
+    ).rejects.toThrow(/url/);
+  });
+});