@navaramap/three 0.0.0

package/src/tileTexture/SlotPlanner.test.ts

@@ -0,0 +1,105 @@
+import { Color, Vector2, type Texture } from "three";
+import { describe, expect, it } from "vitest";
+
+import { planSlots, quantizeSlotCount } from "./SlotPlanner";
+import type { CompositeLayer } from "./types";
+
+const fakeTex = {} as unknown as Texture;
+
+function rasterLayer(absSlot: number): CompositeLayer {
+  return {
+    kind: "raster",
+    region: absSlot < 24 ? "raster" : "vector",
+    absSlot,
+    texture: fakeTex,
+    uvOffset: new Vector2(0, 0),
+    uvScale: new Vector2(1, 1),
+    color: new Color(),
+    opacity: 1,
+    water: false,
+  };
+}
+
+describe("quantizeSlotCount", () => {
+  it("returns 0 when n is 0 — empty bucket contributes no slots", () => {
+    expect(quantizeSlotCount(0, 32)).toBe(0);
+    expect(quantizeSlotCount(-1, 32)).toBe(0);
+  });
+
+  it("rounds up to the next power of two", () => {
+    expect(quantizeSlotCount(1, 32)).toBe(1);
+    expect(quantizeSlotCount(2, 32)).toBe(2);
+    expect(quantizeSlotCount(3, 32)).toBe(4);
+    expect(quantizeSlotCount(5, 32)).toBe(8);
+    expect(quantizeSlotCount(9, 32)).toBe(16);
+    expect(quantizeSlotCount(17, 32)).toBe(32);
+  });
+
+  it("clamps to max", () => {
+    expect(quantizeSlotCount(33, 32)).toBe(32);
+    expect(quantizeSlotCount(100, 32)).toBe(32);
+    // Non-power-of-two max: result is the bucket's quantised value capped.
+    expect(quantizeSlotCount(7, 6)).toBe(6);
+  });
+
+  it("keeps exact powers of two intact", () => {
+    expect(quantizeSlotCount(4, 32)).toBe(4);
+    expect(quantizeSlotCount(16, 32)).toBe(16);
+  });
+});
+
+describe("planSlots", () => {
+  const BOUNDARY = 24;
+  const MAX = 32;
+
+  it("returns empty layout with no active layers", () => {
+    const plan = planSlots([], BOUNDARY, MAX);
+    expect(plan).toMatchObject({
+      rasterCount: 0,
+      vectorCount: 0,
+      boundary: 24,
+    });
+    expect(plan.slots).toHaveLength(0);
+  });
+
+  it("quantizes each bucket's high-water mark independently", () => {
+    // raster high-water at absSlot 2 → 3 → quantized 4; vector at 24 → 1.
+    const plan = planSlots(
+      [rasterLayer(0), rasterLayer(2), rasterLayer(24)],
+      BOUNDARY,
+      MAX,
+    );
+    expect(plan.rasterCount).toBe(4);
+    expect(plan.vectorCount).toBe(1);
+    expect(plan.slots).toHaveLength(5);
+  });
+
+  it("maps compact slots to absolute slots and skips the raster/vector gap", () => {
+    const plan = planSlots(
+      [rasterLayer(0), rasterLayer(1), rasterLayer(24)],
+      BOUNDARY,
+      MAX,
+    );
+    // Raster compact slots map 1:1; vector compact slot 2 jumps to abs 24.
+    expect(plan.slots.map((s) => s.absSlot)).toEqual([0, 1, 24]);
+    expect(plan.slots.map((s) => s.region)).toEqual([
+      "raster",
+      "raster",
+      "vector",
+    ]);
+  });
+
+  it("leaves inactive prefix slots without a layer", () => {
+    // Only absSlot 2 active in the raster bucket → quantized to 4 slots,
+    // slots 0,1,3 carry no layer.
+    const layer = rasterLayer(2);
+    const plan = planSlots([layer], BOUNDARY, MAX);
+    expect(plan.rasterCount).toBe(4);
+    expect(plan.slots.map((s) => s.layer)).toEqual([
+      undefined,
+      undefined,
+      layer,
+      undefined,
+    ]);
+  });
+});

package/src/tileTexture/SlotPlanner.ts

@@ -0,0 +1,102 @@
+import type { CompositeLayer, CompositeLayerRegion } from "./types";
+
+/**
+ * Round `n` up to the next power of two, clamped to `[0, max]`. Bounds the
+ * number of generated shader variants to log₂(max)+1 so churn in the active
+ * count doesn't trigger a shader-compile per tile per frame. Compiles are
+ * tens of ms each — variant explosion is the worst-case stutter source here.
+ *
+ * `Math.clz32(n - 1)` gives the leading-zero count of (n-1) interpreted as a
+ * uint32. `1 << (32 - clz32(n - 1))` is then the smallest power of two ≥ n.
+ * For n=1, clz32(0)=32 so the shift is 1<<0=1 — the n=1 edge falls out of the
+ * same formula. Returns 0 when n is 0 so an empty bucket contributes no slots.
+ */
+export function quantizeSlotCount(n: number, max: number): number {
+  if (n <= 0) return 0;
+  return Math.min(1 << (32 - Math.clz32(n - 1)), max);
+}
+
+/** One compact slot, mapped to its absolute slot and (optionally) a layer. */
+export type SlotBinding = {
+  /** Compact index `[0, rasterCount + vectorCount)`. */
+  compactSlot: number;
+  /** Absolute slot index into the TileMesh main-shader per-slot uniforms. */
+  absSlot: number;
+  region: CompositeLayerRegion;
+  /**
+   * The active layer occupying `absSlot`, or undefined for an inactive prefix
+   * slot. The compact space is a prefix per bucket (so `winningSlot = absSlot`
+   * stays addressable), hence a quantized bucket can hold gaps.
+   */
+  layer: CompositeLayer | undefined;
+};
+
+/**
+ * The compact slot layout for one tile's composite pass. `rasterCount` and
+ * `vectorCount` are power-of-two-quantized high-water marks; `slots` is the
+ * concrete compact→absolute mapping the enhancers bind against.
+ */
+export type SlotPlan = {
+  rasterCount: number;
+  vectorCount: number;
+  /** `texturizedSceneIndexFrom` — boundary between raster and vector regions. */
+  boundary: number;
+  slots: SlotBinding[];
+};
+
+/**
+ * Flatten active layers into the compact slot layout. Raster-region layers
+ * occupy compact slots `[0, rasterCount)` (absSlot = compact); vector-region
+ * layers occupy `[rasterCount, total)` mapping to `boundary + offset`. Each
+ * bucket's count is the quantized high-water mark of its active absolute slots.
+ *
+ * Callers pass only active layers (shown AND textured), so each bucket's
+ * high-water mark is simply its highest active absolute slot.
+ *
+ * Stitching seam: a layer maps to exactly one slot today. To stitch multiple
+ * source textures onto one logical layer later, expand a layer into several
+ * consecutive SlotBindings here — the rest of the pipeline already binds per
+ * SlotBinding.
+ */
+export function planSlots(
+  layers: readonly CompositeLayer[],
+  boundary: number,
+  maxTextures: number,
+): SlotPlan {
+  let rasterHigh = 0;
+  let vectorHigh = 0;
+  const byAbsSlot = new Map<number, CompositeLayer>();
+  for (const layer of layers) {
+    byAbsSlot.set(layer.absSlot, layer);
+    if (layer.region === "raster") {
+      rasterHigh = Math.max(rasterHigh, layer.absSlot + 1);
+    } else {
+      vectorHigh = Math.max(vectorHigh, layer.absSlot - boundary + 1);
+    }
+  }
+
+  const rasterCount = quantizeSlotCount(rasterHigh, boundary);
+  const vectorCount = quantizeSlotCount(vectorHigh, maxTextures - boundary);
+
+  const slots: SlotBinding[] = [];
+  for (
+    let compactSlot = 0;
+    compactSlot < rasterCount + vectorCount;
+    compactSlot++
+  ) {
+    const region: CompositeLayerRegion =
+      compactSlot < rasterCount ? "raster" : "vector";
+    const absSlot =
+      compactSlot < rasterCount
+        ? compactSlot
+        : boundary + (compactSlot - rasterCount);
+    slots.push({
+      compactSlot,
+      absSlot,
+      region,
+      layer: byAbsSlot.get(absSlot),
+    });
+  }
+
+  return { rasterCount, vectorCount, boundary, slots };
+}

package/src/tileTexture/TileTextureCache.test.ts

@@ -0,0 +1,227 @@
+import { describe, it, expect, vi } from "vitest";
+
+import { TileTextureCache } from "./TileTextureCache";
+import type { AtlasFactory, CompositeAtlas } from "./types";
+
+function makeFakeAtlas(): CompositeAtlas {
+  // Minimal stand-ins for Texture / WebGLRenderTarget — the cache only checks
+  // identity (acquire returns the same Texture instance) and lifecycle.
+  const tex = (name: string) =>
+    ({ name, needsUpdate: false }) as unknown as CompositeAtlas["color"];
+  return {
+    target: { dispose: vi.fn() } as unknown as CompositeAtlas["target"],
+    color: tex("color"),
+    attr: tex("attr"),
+    normal: tex("normal"),
+    dispose: vi.fn(),
+  };
+}
+
+function makeCache(maxPooled = 0) {
+  const factory = vi.fn<AtlasFactory>(() => makeFakeAtlas());
+  const cache = new TileTextureCache({
+    size: 512,
+    atlasFactory: factory,
+    maxPooled,
+  });
+  return { cache, factory };
+}
+
+describe("TileTextureCache.acquire", () => {
+  it("creates exactly one atlas per handle even across multiple acquires", () => {
+    const { cache, factory } = makeCache();
+    const a = cache.acquire(1n);
+    const b = cache.acquire(1n);
+    expect(factory).toHaveBeenCalledTimes(1);
+    expect(a.color).toBe(b.color);
+    expect(cache.size).toBe(1);
+  });
+
+  it("newly-acquired handles start dirty in every reason category", () => {
+    const { cache } = makeCache();
+    cache.acquire(1n);
+    const reasons = cache.consumeDirty(1n);
+    expect(reasons).not.toBeNull();
+    // First composite must run, so all reason categories present.
+    expect(reasons?.has("material")).toBe(true);
+    expect(reasons?.has("texture-binding")).toBe(true);
+    expect(reasons?.has("vector-revision")).toBe(true);
+    expect(reasons?.has("hillshade")).toBe(true);
+  });
+});
+
+describe("TileTextureCache.release", () => {
+  it("disposes atlas only when refCount reaches zero (pooling disabled)", () => {
+    const { cache, factory } = makeCache();
+    cache.acquire(1n);
+    cache.acquire(1n);
+    const entry = cache.getEntry(1n);
+    if (!entry) throw new Error("expected entry to exist");
+    const atlas = entry.atlas;
+
+    cache.release(1n);
+    expect(atlas.dispose).not.toHaveBeenCalled();
+    expect(cache.size).toBe(1);
+
+    cache.release(1n);
+    expect(atlas.dispose).toHaveBeenCalledTimes(1);
+    expect(cache.size).toBe(0);
+
+    // A subsequent acquire reuses the slot but spins up a fresh atlas.
+    cache.acquire(1n);
+    expect(factory).toHaveBeenCalledTimes(2);
+  });
+
+  it("is a no-op for unknown handles", () => {
+    const { cache } = makeCache();
+    expect(() => cache.release(999n)).not.toThrow();
+  });
+});
+
+describe("TileTextureCache atlas pooling", () => {
+  it("pools a fully-released atlas and reuses it for the next acquire", () => {
+    const { cache, factory } = makeCache(2);
+    cache.acquire(1n);
+    const entry = cache.getEntry(1n);
+    if (!entry) throw new Error("expected entry to exist");
+    const atlas = entry.atlas;
+
+    cache.release(1n);
+    expect(atlas.dispose).not.toHaveBeenCalled();
+    expect(cache.pooledCount).toBe(1);
+
+    // Reused for a different handle, without a factory call.
+    const out = cache.acquire(2n);
+    expect(factory).toHaveBeenCalledTimes(1);
+    expect(out.color).toBe(atlas.color);
+    expect(cache.pooledCount).toBe(0);
+  });
+
+  it("marks an entry backed by a pooled atlas fully dirty so it gets repainted", () => {
+    const { cache } = makeCache(2);
+    cache.acquire(1n);
+    cache.consumeDirty(1n);
+    cache.release(1n);
+
+    cache.acquire(2n);
+    const reasons = cache.consumeDirty(2n);
+    expect(reasons?.has("material")).toBe(true);
+    expect(reasons?.has("texture-binding")).toBe(true);
+    expect(reasons?.has("vector-revision")).toBe(true);
+    expect(reasons?.has("hillshade")).toBe(true);
+  });
+
+  it("disposes released atlases once the pool is full", () => {
+    const { cache } = makeCache(1);
+    cache.acquire(1n);
+    cache.acquire(2n);
+    const e1 = cache.getEntry(1n);
+    const e2 = cache.getEntry(2n);
+    if (!e1 || !e2) throw new Error("expected both entries");
+
+    cache.release(1n);
+    expect(e1.atlas.dispose).not.toHaveBeenCalled();
+    expect(cache.pooledCount).toBe(1);
+
+    cache.release(2n);
+    expect(e2.atlas.dispose).toHaveBeenCalledTimes(1);
+    expect(cache.pooledCount).toBe(1);
+  });
+
+  it("disposeAll drains the pool", () => {
+    const { cache } = makeCache(2);
+    cache.acquire(1n);
+    const entry = cache.getEntry(1n);
+    if (!entry) throw new Error("expected entry to exist");
+    const atlas = entry.atlas;
+    cache.release(1n);
+    expect(cache.pooledCount).toBe(1);
+
+    cache.disposeAll();
+    expect(atlas.dispose).toHaveBeenCalledTimes(1);
+    expect(cache.pooledCount).toBe(0);
+  });
+});
+
+describe("TileTextureCache.markDirty + consumeDirty", () => {
+  it("coalesces multiple markDirty calls into a single consume result", () => {
+    const { cache } = makeCache();
+    cache.acquire(1n);
+    // Drain the initial-acquire dirty set so we test markDirty in isolation.
+    cache.consumeDirty(1n);
+
+    cache.markDirty(1n, "hillshade");
+    cache.markDirty(1n, "vector-revision");
+    cache.markDirty(1n, "hillshade"); // duplicate
+
+    const reasons = cache.consumeDirty(1n);
+    expect(reasons?.size).toBe(2);
+    expect(reasons?.has("hillshade")).toBe(true);
+    expect(reasons?.has("vector-revision")).toBe(true);
+  });
+
+  it("consumeDirty leaves the entry clean", () => {
+    const { cache } = makeCache();
+    cache.acquire(1n);
+    cache.consumeDirty(1n);
+    expect(cache.isDirty(1n)).toBe(false);
+    expect(cache.consumeDirty(1n)).toBeNull();
+  });
+
+  it("markDirty on unknown handle is a no-op (no entry created)", () => {
+    const { cache } = makeCache();
+    cache.markDirty(42n, "hillshade");
+    expect(cache.size).toBe(0);
+    expect(cache.consumeDirty(42n)).toBeNull();
+  });
+});
+
+describe("TileTextureCache dev refcount diagnostics", () => {
+  it("logs an error on release without acquire", () => {
+    const spy = vi.spyOn(console, "error").mockImplementation(() => {});
+    const { cache } = makeCache();
+    cache.release(999n);
+    expect(spy).toHaveBeenCalledWith(
+      expect.stringContaining("double release or release without acquire"),
+    );
+    spy.mockRestore();
+  });
+
+  it("logs an error on double release", () => {
+    const spy = vi.spyOn(console, "error").mockImplementation(() => {});
+    const { cache } = makeCache();
+    cache.acquire(1n);
+    cache.release(1n);
+    // Entry is gone after the first release, so this is release-without-entry.
+    cache.release(1n);
+    expect(spy).toHaveBeenCalledTimes(1);
+    spy.mockRestore();
+  });
+
+  it("logs an error when disposeAll finds live refcounts", () => {
+    const spy = vi.spyOn(console, "error").mockImplementation(() => {});
+    const { cache } = makeCache();
+    cache.acquire(1n);
+    cache.disposeAll();
+    expect(spy).toHaveBeenCalledWith(expect.stringContaining("leaked acquire"));
+    spy.mockRestore();
+  });
+});
+
+describe("TileTextureCache.disposeAll", () => {
+  it("disposes every atlas and clears the cache", () => {
+    const { cache } = makeCache();
+    cache.acquire(1n);
+    cache.acquire(2n);
+    const e1 = cache.getEntry(1n);
+    const e2 = cache.getEntry(2n);
+    if (!e1 || !e2) throw new Error("expected both entries");
+    const a1 = e1.atlas;
+    const a2 = e2.atlas;
+
+    cache.disposeAll();
+    expect(a1.dispose).toHaveBeenCalledTimes(1);
+    expect(a2.dispose).toHaveBeenCalledTimes(1);
+    expect(cache.size).toBe(0);
+  });
+});

package/src/tileTexture/TileTextureCache.ts

@@ -0,0 +1,192 @@
+import type { TileHandle } from "@navaramap/core";
+
+import type {
+  AtlasFactory,
+  CacheEntry,
+  CompositeAtlas,
+  CompositeOutputs,
+  DirtyReason,
+} from "./types";
+
+/** Dev-build-only refcount diagnostics (never throws in production). */
+const DEV =
+  typeof import.meta !== "undefined" && !!(import.meta as ImportMeta).env?.DEV;
+
+// Every atlas is the same size and format, but tile churn during pan/zoom
+// used to allocate and dispose a ~3MB MRT render target per terrain tile
+// swap. Keeping a few released atlases around lets the next acquire reuse
+// them. Kept small on purpose: pooled atlases are GPU memory the per-tile
+// ledger accounting does not see (each live tile is charged for its own
+// atlas at mesh-attach time, a pooled spare belongs to no tile).
+const DEFAULT_MAX_POOLED_ATLASES = 4;
+
+export type TileTextureCacheOptions = {
+  /** Side length (in pixels) of the composite render targets. */
+  size: number;
+  /** Builds the MRT trio. Injected so unit tests pass fakes. */
+  atlasFactory: AtlasFactory;
+  /** Max spare atlases kept for reuse instead of disposed. 0 disables pooling. */
+  maxPooled?: number;
+};
+
+/**
+ * Pure cache layer for per-tile composite atlases.
+ *
+ * Why: TileMesh previously owned its own WebGLRenderTargets and had no way to
+ * coalesce updates from independent sources (vector revision, hillshade
+ * backfill, material change). Lifting these responsibilities here lets the
+ * compositor render N source textures into one atlas only when something
+ * actually changes, and makes the bookkeeping testable without three.js.
+ */
+export class TileTextureCache {
+  private readonly entries = new Map<TileHandle, CacheEntry>();
+  private readonly opts: TileTextureCacheOptions;
+  private readonly pool: CompositeAtlas[] = [];
+  private readonly maxPooled: number;
+
+  constructor(opts: TileTextureCacheOptions) {
+    this.opts = opts;
+    this.maxPooled = opts.maxPooled ?? DEFAULT_MAX_POOLED_ATLASES;
+  }
+
+  /**
+   * Acquire (or create) the atlas for a handle. Refcounted: a TileMesh
+   * acquires once on construction and releases once on dispose.
+   * Newly-created entries start dirty in every category so the first composite
+   * pass paints them — which also repaints any stale content in a pooled
+   * atlas, so reuse needs no explicit clear.
+   */
+  acquire(handle: TileHandle): CompositeOutputs {
+    let entry = this.entries.get(handle);
+    if (!entry) {
+      const atlas = this.pool.pop() ?? this.opts.atlasFactory(this.opts.size);
+      entry = {
+        handle,
+        atlas,
+        refCount: 0,
+        dirty: new Set<DirtyReason>([
+          "material",
+          "texture-binding",
+          "vector-revision",
+          "hillshade",
+        ]),
+      };
+      this.entries.set(handle, entry);
+    }
+    entry.refCount++;
+    return {
+      color: entry.atlas.color,
+      attr: entry.atlas.attr,
+      normal: entry.atlas.normal,
+    };
+  }
+
+  /**
+   * Decrement refcount. When the last holder releases, the entry is forgotten
+   * and its atlas is pooled for reuse (or disposed once the pool is full).
+   */
+  release(handle: TileHandle): void {
+    const entry = this.entries.get(handle);
+    if (!entry) {
+      if (DEV) {
+        console.error(
+          `TileTextureCache.release: no entry for handle ${handle} (double release or release without acquire)`,
+        );
+      }
+      return;
+    }
+    entry.refCount--;
+    if (DEV && entry.refCount < 0) {
+      console.error(
+        `TileTextureCache.release: refcount went negative for handle ${handle}`,
+      );
+    }
+    if (entry.refCount <= 0) {
+      if (this.pool.length < this.maxPooled) {
+        this.pool.push(entry.atlas);
+      } else {
+        entry.atlas.dispose();
+      }
+      this.entries.delete(handle);
+    }
+  }
+
+  /** Mark an entry dirty for a given reason. No-op if handle isn't tracked. */
+  markDirty(handle: TileHandle, reason: DirtyReason): void {
+    const entry = this.entries.get(handle);
+    if (!entry) return;
+    entry.dirty.add(reason);
+  }
+
+  /**
+   * Return the set of dirty reasons (and clear them) for a handle. Returns
+   * null when the handle isn't tracked or has nothing dirty — compositor uses
+   * that to skip the offscreen pass.
+   */
+  consumeDirty(handle: TileHandle): Set<DirtyReason> | null {
+    const entry = this.entries.get(handle);
+    if (!entry || entry.dirty.size === 0) return null;
+    const reasons = entry.dirty;
+    entry.dirty = new Set<DirtyReason>();
+    return reasons;
+  }
+
+  /** Peek without clearing — used by the compositor's scheduling pass. */
+  isDirty(handle: TileHandle): boolean {
+    const entry = this.entries.get(handle);
+    return !!entry && entry.dirty.size > 0;
+  }
+
+  /** Atlas accessor for the compositor's internal render path. */
+  getEntry(handle: TileHandle): CacheEntry | undefined {
+    return this.entries.get(handle);
+  }
+
+  /**
+   * Return the outputs for a handle that was already acquired. Unlike
+   * acquire(), does NOT touch the refcount — use this from places that just
+   * need to bind the atlas textures (e.g. TileMesh.initMaterial after the
+   * constructor already acquired the entry).
+   */
+  getOutputs(handle: TileHandle): CompositeOutputs | undefined {
+    const entry = this.entries.get(handle);
+    if (!entry) return undefined;
+    return {
+      color: entry.atlas.color,
+      attr: entry.atlas.attr,
+      normal: entry.atlas.normal,
+    };
+  }
+
+  /** Iterate all live entries. Used by compositor.update(). */
+  entriesIter(): IterableIterator<CacheEntry> {
+    return this.entries.values();
+  }
+
+  /** Number of tracked entries (testing/debug). */
+  get size(): number {
+    return this.entries.size;
+  }
+
+  /** Number of pooled (unowned) spare atlases — for stats/debugging. */
+  get pooledCount(): number {
+    return this.pool.length;
+  }
+
+  /** Dispose all atlases (live and pooled) and clear. Called on view shutdown. */
+  disposeAll(): void {
+    for (const entry of this.entries.values()) {
+      if (DEV && entry.refCount > 0) {
+        console.error(
+          `TileTextureCache.disposeAll: handle ${entry.handle} still has refcount ${entry.refCount} (leaked acquire)`,
+        );
+      }
+      entry.atlas.dispose();
+    }
+    this.entries.clear();
+    for (const atlas of this.pool) {
+      atlas.dispose();
+    }
+    this.pool.length = 0;
+  }
+}