@navaramap/three 0.0.0

package/src/event/workerTaskSettlement.test.ts

@@ -0,0 +1,243 @@
+import type {
+  DelegatedWorkerTasksResult,
+  ReconstructableEntity,
+} from "@navaramap/engine";
+import { expect, it, vi } from "vitest";
+
+import type { WorkerPoolPromise, WorkerPoolPromises } from "../type";
+
+import {
+  runDelegatedWorkerTask,
+  settleWorkerTask,
+} from "./workerTaskSettlement";
+
+const makeCtx = () => ({ workerPoolPromises: new Map() as WorkerPoolPromises });
+
+const asPoolPromise = <T>(promise: Promise<T>) =>
+  promise as unknown as WorkerPoolPromise<T>;
+
+const cancellationError = () => {
+  const err = new Error("promise cancelled");
+  err.name = "CancellationError";
+  return err;
+};
+
+it("should register the promise, resolve to completed, and unregister", async () => {
+  const ctx = makeCtx();
+  let resolve!: (v: string) => void;
+  const promise = asPoolPromise(new Promise<string>((r) => (resolve = r)));
+
+  const settling = settleWorkerTask(ctx, "id", promise);
+  expect(ctx.workerPoolPromises.get("id")).toBe(promise);
+
+  resolve("value");
+  expect(await settling).toEqual({ status: "completed", value: "value" });
+  expect(ctx.workerPoolPromises.size).toBe(0);
+});
+
+it("should classify a CancellationError as cancelled, not failed", async () => {
+  const ctx = makeCtx();
+  let reject!: (e: unknown) => void;
+  const promise = asPoolPromise(new Promise<void>((_, r) => (reject = r)));
+
+  const settling = settleWorkerTask(ctx, "id", promise);
+  reject(cancellationError());
+
+  expect(await settling).toEqual({ status: "cancelled" });
+  expect(ctx.workerPoolPromises.size).toBe(0);
+});
+
+it("should classify any other rejection as failed with its error", async () => {
+  const ctx = makeCtx();
+  const error = new Error("worker exploded");
+  const settling = settleWorkerTask(
+    ctx,
+    "id",
+    asPoolPromise(Promise.reject(error)),
+  );
+
+  expect(await settling).toEqual({ status: "failed", error });
+  expect(ctx.workerPoolPromises.size).toBe(0);
+});
+
+it("should not delete a map entry that was replaced by a newer task", async () => {
+  const ctx = makeCtx();
+  let reject!: (e: unknown) => void;
+  const promise = asPoolPromise(new Promise<void>((_, r) => (reject = r)));
+  const settling = settleWorkerTask(ctx, "id", promise);
+
+  // A newer task reuses the id while the first one is being cancelled.
+  const replacement = asPoolPromise(new Promise<void>(() => {}));
+  ctx.workerPoolPromises.set("id", replacement);
+  reject(cancellationError());
+
+  expect(await settling).toEqual({ status: "cancelled" });
+  expect(ctx.workerPoolPromises.get("id")).toBe(replacement);
+});
+
+const makeDelegatedCtx = () => ({
+  workerPoolPromises: new Map() as WorkerPoolPromises,
+  workerTaskHandler: {
+    triggerWorkerTaskCompleted: vi.fn(),
+    triggerWorkerTaskFailed: vi.fn(),
+    hasWorkerTask: vi.fn(() => true),
+  },
+});
+
+const makeBoundary = () => ({
+  params: { free: vi.fn() },
+  delegator_id: { free: vi.fn() } as unknown as ReconstructableEntity,
+});
+
+it("should deliver a completed result and not release the delegator again", async () => {
+  const ctx = makeDelegatedCtx();
+  const { params, delegator_id } = makeBoundary();
+  const result = { built: true } as unknown as DelegatedWorkerTasksResult;
+
+  await runDelegatedWorkerTask(
+    ctx,
+    "id",
+    1n,
+    "test task",
+    params,
+    delegator_id,
+    async (task) => {
+      const value = await task.settle(asPoolPromise(Promise.resolve("ok")));
+      expect(value).toBe("ok");
+      task.complete((id) => {
+        expect(id).toBe(delegator_id);
+        return result;
+      });
+    },
+  );
+
+  expect(ctx.workerTaskHandler.triggerWorkerTaskCompleted).toHaveBeenCalledWith(
+    1n,
+    result,
+  );
+  expect(ctx.workerTaskHandler.triggerWorkerTaskFailed).not.toHaveBeenCalled();
+  expect(params.free).toHaveBeenCalledOnce();
+});
+
+it("should release the delegator when the body bails out without completing", async () => {
+  const ctx = makeDelegatedCtx();
+  const { params, delegator_id } = makeBoundary();
+
+  await runDelegatedWorkerTask(
+    ctx,
+    "id",
+    1n,
+    "test task",
+    params,
+    delegator_id,
+    async () => {
+      // Missing input: bail out without completing.
+    },
+  );
+
+  expect(ctx.workerTaskHandler.triggerWorkerTaskFailed).toHaveBeenCalledWith(
+    delegator_id,
+  );
+  expect(
+    ctx.workerTaskHandler.triggerWorkerTaskCompleted,
+  ).not.toHaveBeenCalled();
+  expect(params.free).toHaveBeenCalledOnce();
+});
+
+it("should contain an unexpected body throw and release the delegator", async () => {
+  const ctx = makeDelegatedCtx();
+  const { params, delegator_id } = makeBoundary();
+  const consoleError = vi
+    .spyOn(console, "error")
+    .mockImplementation(() => undefined);
+
+  await runDelegatedWorkerTask(
+    ctx,
+    "id",
+    1n,
+    "test task",
+    params,
+    delegator_id,
+    async () => {
+      throw new Error("boom");
+    },
+  );
+
+  expect(consoleError).toHaveBeenCalledOnce();
+  expect(ctx.workerTaskHandler.triggerWorkerTaskFailed).toHaveBeenCalledWith(
+    delegator_id,
+  );
+  expect(params.free).toHaveBeenCalledOnce();
+  consoleError.mockRestore();
+});
+
+it("should log a failed settlement and run onFailed, which can complete instead", async () => {
+  const ctx = makeDelegatedCtx();
+  const { params, delegator_id } = makeBoundary();
+  const empty = { empty: true } as unknown as DelegatedWorkerTasksResult;
+  const consoleError = vi
+    .spyOn(console, "error")
+    .mockImplementation(() => undefined);
+
+  await runDelegatedWorkerTask(
+    ctx,
+    "id",
+    1n,
+    "test task",
+    params,
+    delegator_id,
+    async (task) => {
+      const value = await task.settle(
+        asPoolPromise(Promise.reject(new Error("worker exploded"))),
+        () => task.complete(() => empty),
+      );
+      expect(value).toBeUndefined();
+    },
+  );
+
+  expect(consoleError).toHaveBeenCalledWith(
+    "Failed to test task in worker:",
+    expect.any(Error),
+  );
+  // `onFailed` completed the task, so the fallback release must not fire.
+  expect(ctx.workerTaskHandler.triggerWorkerTaskCompleted).toHaveBeenCalledWith(
+    1n,
+    empty,
+  );
+  expect(ctx.workerTaskHandler.triggerWorkerTaskFailed).not.toHaveBeenCalled();
+  consoleError.mockRestore();
+});
+
+it("should treat a cancellation as a silent release without invoking onFailed", async () => {
+  const ctx = makeDelegatedCtx();
+  const { params, delegator_id } = makeBoundary();
+  const onFailed = vi.fn();
+  const consoleError = vi
+    .spyOn(console, "error")
+    .mockImplementation(() => undefined);
+
+  await runDelegatedWorkerTask(
+    ctx,
+    "id",
+    1n,
+    "test task",
+    params,
+    delegator_id,
+    async (task) => {
+      const value = await task.settle(
+        asPoolPromise(Promise.reject(cancellationError())),
+        onFailed,
+      );
+      expect(value).toBeUndefined();
+    },
+  );
+
+  expect(onFailed).not.toHaveBeenCalled();
+  expect(consoleError).not.toHaveBeenCalled();
+  // The engine already deleted a cancelled task's delegator, so this release
+  // is a no-op on the Rust side — but it must still consume `delegator_id`.
+  expect(ctx.workerTaskHandler.triggerWorkerTaskFailed).toHaveBeenCalledWith(
+    delegator_id,
+  );
+  consoleError.mockRestore();
+});

package/src/event/workerTaskSettlement.ts

@@ -0,0 +1,128 @@
+import type {
+  DelegatedWorkerTasksResult,
+  ReconstructableEntity,
+} from "@navaramap/engine";
+
+import type { WorkerPoolPromise } from "../type";
+
+import type { EventContext } from "./context";
+
+/**
+ * How a worker-pool task ended. Cancellation (tile/feature evicted while the
+ * task was queued or running) is a routine outcome under camera movement, not
+ * an error: it must never surface as a rejection to the event pipeline.
+ */
+export type WorkerTaskSettlement<T> =
+  | { status: "completed"; value: T }
+  | { status: "cancelled" }
+  | { status: "failed"; error: unknown };
+
+function isCancellation(err: unknown): boolean {
+  return err instanceof Error && err.name === "CancellationError";
+}
+
+/**
+ * Own the workerPoolPromises lifecycle around one pool task: register the
+ * promise (so a removal event can cancel it), classify the outcome, and
+ * always unregister.
+ */
+export async function settleWorkerTask<T>(
+  ctx: Pick<EventContext, "workerPoolPromises">,
+  id: string,
+  promise: WorkerPoolPromise<T>,
+): Promise<WorkerTaskSettlement<T>> {
+  ctx.workerPoolPromises.set(id, promise);
+  try {
+    return { status: "completed", value: await promise };
+  } catch (error) {
+    return isCancellation(error)
+      ? { status: "cancelled" }
+      : { status: "failed", error };
+  } finally {
+    // Only delete our own entry: a new task could in principle reuse the id
+    // between a cancel and this continuation.
+    if (ctx.workerPoolPromises.get(id) === promise) {
+      ctx.workerPoolPromises.delete(id);
+    }
+  }
+}
+
+/** Helpers handed to a delegated-task body by {@link runDelegatedWorkerTask}. */
+export type DelegatedTaskHandle = {
+  /**
+   * Register + await one pool task via {@link settleWorkerTask} and classify
+   * the outcome: the settled value on completion, `undefined` otherwise. A
+   * failure is logged (as `Failed to <label> in worker:`) and `onFailed` runs
+   * before returning, so a task kind can substitute its own failure
+   * completion (e.g. the MVT parse completes with an empty result).
+   */
+  settle<T>(
+    promise: WorkerPoolPromise<T>,
+    onFailed?: () => void,
+  ): Promise<T | undefined>;
+  /**
+   * Deliver the task result to the engine. `build` receives ownership of
+   * `delegator_id` (the `DelegatedWorkerTasksResult.with*` constructors
+   * consume it).
+   */
+  complete(
+    build: (delegator_id: ReconstructableEntity) => DelegatedWorkerTasksResult,
+  ): void;
+};
+
+/**
+ * Shared scaffolding around one delegated worker task: own the wasm-bindgen
+ * boundary objects (`params` is freed on every path; `delegator_id` is
+ * consumed exactly once) and guarantee the delegator always settles. A body
+ * that returns without calling `complete` — worker failure, missing input,
+ * buffer registration failure, or an unexpected throw — releases the
+ * delegator through `triggerWorkerTaskFailed`; otherwise it would stay
+ * Requested forever and permanently occupy one of the engine's pending
+ * dispatch slots for its task kind. For a task the engine already cancelled
+ * the release is a no-op on the Rust side, so cancellations need no special
+ * casing here.
+ */
+export async function runDelegatedWorkerTask<P extends { free(): void }>(
+  ctx: Pick<EventContext, "workerPoolPromises" | "workerTaskHandler">,
+  id: string,
+  bits: bigint,
+  label: string,
+  params: P,
+  delegator_id: ReconstructableEntity,
+  body: (task: DelegatedTaskHandle) => Promise<void>,
+): Promise<void> {
+  let delegatorSettled = false;
+  const task: DelegatedTaskHandle = {
+    async settle(promise, onFailed) {
+      const settled = await settleWorkerTask(ctx, id, promise);
+      if (settled.status === "completed") {
+        return settled.value;
+      }
+      if (settled.status === "failed") {
+        console.error(`Failed to ${label} in worker:`, settled.error);
+        onFailed?.();
+      }
+      return undefined;
+    },
+    complete(build) {
+      // Flag before building so a throw inside `build` (after `with*` already
+      // consumed `delegator_id`) cannot lead to a double free below.
+      delegatorSettled = true;
+      ctx.workerTaskHandler.triggerWorkerTaskCompleted(
+        bits,
+        build(delegator_id),
+      );
+    },
+  };
+  try {
+    await body(task);
+  } catch (error) {
+    console.error(`Failed to ${label}:`, error);
+  } finally {
+    params.free();
+    if (!delegatorSettled) {
+      // Consumes `delegator_id`.
+      ctx.workerTaskHandler.triggerWorkerTaskFailed(delegator_id);
+    }
+  }
+}

package/src/inMemoryBufferStore.test.ts

@@ -0,0 +1,60 @@
+import { describe, expect, it } from "vitest";
+
+import { InMemoryBufferStore } from "./inMemoryBufferStore";
+
+describe("InMemoryBufferStore", () => {
+  it("tracks totalBytes and count on set/take/delete", () => {
+    const store = new InMemoryBufferStore();
+    expect(store.totalBytes).toBe(0);
+    expect(store.count).toBe(0);
+
+    const a = new Float32Array(10); // 40 bytes
+    store.set(1, a);
+    expect(store.totalBytes).toBe(40);
+    expect(store.count).toBe(1);
+    expect(store.get(1)).toBe(a);
+
+    const b = new Uint8Array(5); // 5 bytes
+    store.set(2, b);
+    expect(store.totalBytes).toBe(45);
+    expect(store.count).toBe(2);
+
+    // take returns and removes.
+    expect(store.take(1)).toBe(a);
+    expect(store.get(1)).toBeUndefined();
+    expect(store.totalBytes).toBe(5);
+    expect(store.count).toBe(1);
+
+    store.delete(2);
+    expect(store.totalBytes).toBe(0);
+    expect(store.count).toBe(0);
+  });
+
+  it("re-accounts bytes when a handle is replaced", () => {
+    const store = new InMemoryBufferStore();
+    store.set(1, new Uint32Array(10)); // 40 bytes
+    expect(store.totalBytes).toBe(40);
+    store.set(1, new Uint32Array(2)); // 8 bytes
+    expect(store.totalBytes).toBe(8);
+    expect(store.count).toBe(1);
+  });
+
+  it("take/delete on a missing handle is a no-op", () => {
+    const store = new InMemoryBufferStore();
+    store.set(1, new Uint8Array(3));
+    expect(store.take(999)).toBeUndefined();
+    store.delete(999);
+    expect(store.totalBytes).toBe(3);
+    expect(store.count).toBe(1);
+  });
+
+  it("clear drops everything", () => {
+    const store = new InMemoryBufferStore();
+    store.set(1, new Float64Array(4)); // 32 bytes
+    store.set(2, new Uint8Array(8));
+    store.clear();
+    expect(store.totalBytes).toBe(0);
+    expect(store.count).toBe(0);
+    expect(store.get(1)).toBeUndefined();
+  });
+});

package/src/inMemoryBufferStore.ts

@@ -0,0 +1,67 @@
+/**
+ * JS-side companion to the WASM `BufferStore`'s `External` entries: holds the
+ * real typed-array bytes for handles that WASM tracks by byte count only,
+ * keeping fetched pbf / worker-built geometry out of WASM linear memory (which
+ * never shrinks). The lifecycle is Rust-driven — handles are issued by
+ * `Core.newExternalBuffer` and evicted via `drainRemovedExternalHandles`, so
+ * there is no LRU here.
+ */
+type StoredArray = Uint8Array | Uint32Array | Float32Array | Float64Array;
+
+export class InMemoryBufferStore {
+  private _map = new Map<number, StoredArray>();
+  private _totalBytes = 0;
+
+  /** Bytes currently held across all entries. */
+  get totalBytes(): number {
+    return this._totalBytes;
+  }
+
+  /** Number of entries currently held. */
+  get count(): number {
+    return this._map.size;
+  }
+
+  /**
+   * Store `array` under `handle`. Replacing an existing handle re-accounts its
+   * bytes so `totalBytes` never drifts.
+   */
+  set(handle: number, array: StoredArray): void {
+    const old = this._map.get(handle);
+    if (old) {
+      this._totalBytes -= old.byteLength;
+    }
+    this._map.set(handle, array);
+    this._totalBytes += array.byteLength;
+  }
+
+  /** Read an entry without removing it, or `undefined` if absent. */
+  get(handle: number): StoredArray | undefined {
+    return this._map.get(handle);
+  }
+
+  /** Remove and return an entry, transferring ownership to the caller. */
+  take(handle: number): StoredArray | undefined {
+    const array = this._map.get(handle);
+    if (array) {
+      this._map.delete(handle);
+      this._totalBytes -= array.byteLength;
+    }
+    return array;
+  }
+
+  /** Drop an entry. A no-op for a handle that is not present. */
+  delete(handle: number): void {
+    const array = this._map.get(handle);
+    if (array) {
+      this._map.delete(handle);
+      this._totalBytes -= array.byteLength;
+    }
+  }
+
+  /** Drop every entry (called on view dispose). */
+  clear(): void {
+    this._map.clear();
+    this._totalBytes = 0;
+  }
+}

package/src/index.iife.ts

@@ -0,0 +1,11 @@
+export * from "./index";
+export { default } from "./index";
+export { DefaultPlugin } from "@navaramap/three_default_plugin";
+export type {
+  DefaultDescriptions,
+  DefaultMeshDescription,
+  DefaultLightDescription,
+  DefaultEffectDescription,
+} from "@navaramap/three_default_plugin";
+export * from "@navaramap/three_default_descs";
+export { AttributionPlugin } from "./plugins";