@navaramap/three 0.0.0 → 0.0.2

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@navaramap/three",
   "type": "module",
-  "version": "0.0.0",
+  "version": "0.0.2",
   "main": "dist/index.umd.cjs",
   "module": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -12,7 +12,7 @@
   "license": "MIT OR Apache-2.0",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/eukarya-inc/navara.git",
+    "url": "git+https://github.com/reearth/navara.git",
     "directory": "web/navara_three"
   },
   "publishConfig": {
@@ -30,50 +30,51 @@
     "astronomy-engine": "2.1.19",
     "stats.js": "0.17.0",
     "three-stdlib": "2.36.1",
-    "@navaramap/core": "0.0.0",
-    "@navaramap/worker": "0.0.0",
-    "@navaramap/engine": "0.0.0",
-    "@navaramap/font": "0.0.0",
-    "@navaramap/engine-api": "0.0.0",
-    "@navaramap/three_csm": "0.0.0",
-    "@navaramap/three_api": "0.0.0"
+    "@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"
   },
   "devDependencies": {
-    "@playwright/test": "1.59.1",
-    "@radix-ui/react-collapsible": "1.1.12",
-    "@radix-ui/react-label": "2.1.8",
-    "@radix-ui/react-select": "2.2.6",
-    "@radix-ui/react-separator": "1.1.8",
-    "@radix-ui/react-slider": "1.3.6",
-    "@radix-ui/react-slot": "1.2.4",
-    "@radix-ui/react-switch": "1.2.6",
-    "@tailwindcss/postcss": "4.2.2",
+    "@playwright/test": "1.61.1",
+    "@radix-ui/react-collapsible": "1.1.17",
+    "@radix-ui/react-label": "2.1.12",
+    "@radix-ui/react-select": "2.3.4",
+    "@radix-ui/react-separator": "1.1.12",
+    "@radix-ui/react-slider": "1.4.4",
+    "@radix-ui/react-slot": "1.3.0",
+    "@radix-ui/react-switch": "1.3.4",
+    "@tailwindcss/postcss": "4.3.3",
     "@tweakpane/core": "2.0.5",
     "@types/geojson": "7946.0.16",
+    "@types/node": "26.1.1",
     "@types/stats.js": "0.17.4",
-    "@types/three": "0.184.0",
+    "@types/three": "0.185.1",
     "ajv": "8.20.0",
     "class-variance-authority": "0.7.1",
     "clsx": "2.1.1",
-    "dayjs": "1.11.20",
-    "lucide-react": "1.14.0",
-    "playwright": "1.59.1",
-    "postcss": "8.5.9",
-    "postprocessing": "6.38.3",
-    "sharp": "0.34.5",
+    "dayjs": "1.11.21",
+    "lucide-react": "1.25.0",
+    "playwright": "1.61.1",
+    "postcss": "8.5.20",
+    "postprocessing": "6.39.3",
+    "sharp": "0.35.3",
     "shiki": "4.3.1",
-    "tailwind-merge": "3.5.0",
-    "tailwindcss": "4.2.2",
+    "tailwind-merge": "3.6.0",
+    "tailwindcss": "4.3.3",
     "tailwindcss-animate": "1.0.7",
-    "three": "0.184.0",
-    "tsx": "4.21.0",
+    "three": "0.185.1",
+    "tsx": "4.23.1",
     "tweakpane": "4.0.5",
     "vite-plugin-glsl": "1.6.0",
-    "vite-plugin-static-copy": "4.1.0",
-    "@navaramap/three_default_descs": "0.0.0",
-    "@navaramap/three_default_plugin": "0.0.0",
-    "@navaramap/three_plugins": "0.0.0",
-    "@navaramap/three_react": "0.0.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"
   },
   "scripts": {
     "start": "vite",

package/src/core/EffectDesc.ts

@@ -16,8 +16,7 @@ import {
 import type { ViewContext } from "./ViewContext";
 
 type EffectInstance =
-  | PostProcessingPass
-  | Pass<PostProcessingPass, PostProcessingEffect>;
+  PostProcessingPass | Pass<PostProcessingPass, PostProcessingEffect>;
 
 export type EffectConfig = {
   type?: "effect";
@@ -183,8 +182,7 @@ export abstract class EffectDesc<
   Config extends EffectConfig = EffectConfig,
   UpdateConfig extends EffectUpdate = EffectUpdate,
   InstanceObj extends EffectInstance | { raw: EffectInstance } =
-    | EffectInstance
-    | { raw: EffectInstance },
+    EffectInstance | { raw: EffectInstance },
   Instance extends EffectBaseInstance<InstanceObj> =
     EffectBaseInstance<InstanceObj>,
 > extends BaseDesc<Config, UpdateConfig, Instance> {

package/src/core/MeshDesc.ts

@@ -204,8 +204,7 @@ export abstract class MeshDesc<
   Config extends MeshConfig = MeshConfig,
   UpdateConfig extends MeshUpdate = MeshUpdate,
   InstanceObj extends Object3D | { raw: Object3D } =
-    | Object3D
-    | { raw: Object3D },
+    Object3D | { raw: Object3D },
   CustomEvent extends BaseEventMap = BaseEventMap,
   Instance extends MeshBaseInstance<InstanceObj> =
     MeshBaseInstance<InstanceObj>,

package/src/core/MeshDescWithSelectiveEffect.ts

@@ -26,8 +26,7 @@ export abstract class MeshDescWithSelectiveEffect<
   UpdateConfig extends MeshUpdateWithSelectiveEffect =
     MeshUpdateWithSelectiveEffect,
   InstanceObj extends Object3D | { raw: Object3D } =
-    | Object3D
-    | { raw: Object3D },
+    Object3D | { raw: Object3D },
   CustomEvent extends BaseEventMap = BaseEventMap,
   Instance extends MeshBaseInstance<InstanceObj> =
     MeshBaseInstance<InstanceObj>,

package/src/declutter/DeclutterManager.test.ts

@@ -0,0 +1,235 @@
+import { PerspectiveCamera } from "three";
+import { describe, expect, it } from "vitest";
+
+import { DeclutterManager } from "./DeclutterManager";
+import { CANDIDATE_STRIDE, type DeclutterKernel } from "./kernel";
+import type { DeclutterCandidate, DeclutterParticipant } from "./types";
+
+const R = 6378137.0;
+
+/** Camera one earth-radius above (R, 0, 0), looking at the surface. */
+function makeCamera(): PerspectiveCamera {
+  const camera = new PerspectiveCamera(60, 800 / 600, 1, 1e9);
+  camera.position.set(2 * R, 0, 0);
+  camera.up.set(0, 0, 1);
+  camera.lookAt(R, 0, 0);
+  camera.updateMatrixWorld(true);
+  return camera;
+}
+
+/**
+ * Placement kernel stub. The real projection/grid/placement is Rust and is
+ * covered by the crate's tests; here we only need to drive the manager's
+ * orchestration, so the stub records what it was handed and returns a
+ * caller-controlled hidden pattern.
+ */
+class StubKernel implements DeclutterKernel {
+  calls: { candidates: Float64Array; n: number }[] = [];
+  /** Override to control which candidates come back hidden. Default: all shown. */
+  hiddenFor: (n: number) => Uint8Array = (n) => new Uint8Array(n);
+
+  place(candidates: Float64Array): Uint8Array {
+    const n = candidates.length / CANDIDATE_STRIDE;
+    this.calls.push({ candidates: candidates.slice(), n });
+    return this.hiddenFor(n);
+  }
+}
+
+class FakeParticipant implements DeclutterParticipant {
+  hidden = new Map<number, boolean>();
+  /** How many more stepDeclutterFade calls report an active fade. */
+  fadeStepsLeft = 0;
+  fadeDeltas: number[] = [];
+
+  constructor(readonly candidates: Omit<DeclutterCandidate, "owner">[]) {}
+
+  collectDeclutterCandidates(out: DeclutterCandidate[]): void {
+    for (const c of this.candidates) out.push({ ...c, owner: this });
+  }
+
+  applyDeclutter(handle: number, hidden: boolean): void {
+    this.hidden.set(handle, hidden);
+  }
+
+  stepDeclutterFade(deltaMs: number): boolean {
+    this.fadeDeltas.push(deltaMs);
+    if (this.fadeStepsLeft <= 0) return false;
+    this.fadeStepsLeft--;
+    return true;
+  }
+}
+
+function label(
+  partial: Partial<Omit<DeclutterCandidate, "owner">>,
+): Omit<DeclutterCandidate, "owner"> {
+  return {
+    anchorX: R,
+    anchorY: 0,
+    anchorZ: 0,
+    addHeight: 0,
+    minX: -10,
+    maxX: 10,
+    minY: -10,
+    maxY: 10,
+    sizeInMeters: false,
+    priority: 0,
+    isShown: false,
+    handle: 0,
+    ...partial,
+  };
+}
+
+describe("DeclutterManager", () => {
+  it("packs candidates for the kernel and applies the returned hidden flags", () => {
+    const kernel = new StubKernel();
+    // Return the second candidate hidden.
+    kernel.hiddenFor = (n) => {
+      const flags = new Uint8Array(n);
+      flags[1] = 1;
+      return flags;
+    };
+    const manager = new DeclutterManager(kernel);
+    const p = new FakeParticipant([
+      label({
+        handle: 0,
+        priority: 3,
+        isShown: true,
+        minX: -4,
+        sizeInMeters: true,
+      }),
+      label({ handle: 1, priority: 1 }),
+    ]);
+    manager.register(p);
+
+    expect(manager.update(makeCamera(), 800, 600, 0)).toBe("ran");
+
+    // Results applied by handle, in candidate order.
+    expect(p.hidden.get(0)).toBe(false);
+    expect(p.hidden.get(1)).toBe(true);
+
+    // Candidate 0 was packed into the stride layout the Rust kernel expects.
+    const { candidates } = kernel.calls[0];
+    expect(candidates.length).toBe(2 * CANDIDATE_STRIDE);
+    expect(candidates[0]).toBe(R); // anchorX
+    expect(candidates[4]).toBe(-4); // minX
+    expect(candidates[8]).toBe(1); // sizeInMeters -> 1
+    expect(candidates[9]).toBe(3); // priority
+    expect(candidates[10]).toBe(1); // isShown -> 1
+  });
+
+  it("throttles re-runs and reports them so the caller can schedule a frame", () => {
+    const manager = new DeclutterManager(new StubKernel());
+    const p = new FakeParticipant([label({ handle: 0 })]);
+    manager.register(p);
+    const camera = makeCamera();
+
+    expect(manager.update(camera, 800, 600, 0)).toBe("ran");
+    expect(manager.update(camera, 800, 600, 50)).toBe("idle");
+
+    manager.markDirty();
+    expect(manager.update(camera, 800, 600, 50)).toBe("throttled");
+    expect(
+      manager.update(camera, 800, 600, DeclutterManager.MIN_INTERVAL_MS),
+    ).toBe("ran");
+  });
+
+  it("re-runs when the camera moves and stays idle when nothing changed", () => {
+    const manager = new DeclutterManager(new StubKernel());
+    const p = new FakeParticipant([label({ handle: 0 })]);
+    manager.register(p);
+    const camera = makeCamera();
+
+    expect(manager.update(camera, 800, 600, 0)).toBe("ran");
+    expect(manager.update(camera, 800, 600, 1000)).toBe("idle");
+
+    camera.position.z += 1000;
+    camera.updateMatrixWorld(true);
+    expect(manager.update(camera, 800, 600, 2000)).toBe("ran");
+
+    // A viewport resize also invalidates placement.
+    expect(manager.update(camera, 1024, 768, 3000)).toBe("ran");
+  });
+
+  it("reports 'animating' while fades are active, then settles", () => {
+    const manager = new DeclutterManager(new StubKernel());
+    const p = new FakeParticipant([label({ handle: 0 })]);
+    manager.register(p);
+    const camera = makeCamera();
+
+    // The pass that (re)targets labels also starts their fade.
+    p.fadeStepsLeft = 2;
+    expect(manager.update(camera, 800, 600, 0)).toBe("animating");
+    expect(manager.update(camera, 800, 600, 16)).toBe("animating");
+    expect(manager.update(camera, 800, 600, 32)).toBe("idle");
+  });
+
+  it("clamps fade steps after an idle gap", () => {
+    const manager = new DeclutterManager(new StubKernel());
+    const p = new FakeParticipant([label({ handle: 0 })]);
+    manager.register(p);
+    const camera = makeCamera();
+
+    manager.update(camera, 800, 600, 0);
+    // 10s of engine idle must not advance a new fade by 10s worth.
+    manager.update(camera, 800, 600, 10_000);
+    for (const delta of p.fadeDeltas) {
+      expect(delta).toBeLessThanOrEqual(DeclutterManager.MAX_FADE_STEP_MS);
+    }
+  });
+
+  it("prefers 'animating' over 'throttled' so pending passes still settle", () => {
+    const manager = new DeclutterManager(new StubKernel());
+    const p = new FakeParticipant([label({ handle: 0 })]);
+    manager.register(p);
+    const camera = makeCamera();
+
+    expect(manager.update(camera, 800, 600, 0)).toBe("ran");
+    manager.markDirty();
+    p.fadeStepsLeft = 1;
+    // Dirty + inside the throttle window + fading: animating wins because its
+    // prompt follow-ups re-enter update, which runs the pass once due.
+    expect(manager.update(camera, 800, 600, 50)).toBe("animating");
+    expect(
+      manager.update(camera, 800, 600, DeclutterManager.MIN_INTERVAL_MS),
+    ).toBe("ran");
+  });
+
+  it("goes idle when the last participant unregisters", () => {
+    const manager = new DeclutterManager(new StubKernel());
+    const p = new FakeParticipant([label({ handle: 0 })]);
+    manager.register(p);
+    const camera = makeCamera();
+    expect(manager.update(camera, 800, 600, 0)).toBe("ran");
+
+    manager.unregister(p);
+    expect(manager.update(camera, 800, 600, 1000)).toBe("idle");
+  });
+
+  it("reports the remaining throttle window since the last pass, not the full constant", () => {
+    const manager = new DeclutterManager(new StubKernel());
+    const p = new FakeParticipant([label({ handle: 0 })]);
+    manager.register(p);
+    const camera = makeCamera();
+
+    expect(manager.update(camera, 800, 600, 0)).toBe("ran");
+    manager.markDirty();
+    expect(manager.update(camera, 800, 600, 100)).toBe("throttled");
+    // 50ms of the 150ms window has already elapsed since the last pass.
+    expect(manager.remainingThrottleMs(100)).toBe(
+      DeclutterManager.MIN_INTERVAL_MS - 100,
+    );
+    // Never negative once the window has fully elapsed.
+    expect(manager.remainingThrottleMs(10_000)).toBe(0);
+  });
+
+  it("dispose() drops participants so a later update() is idle", () => {
+    const manager = new DeclutterManager(new StubKernel());
+    const p = new FakeParticipant([label({ handle: 0 })]);
+    manager.register(p);
+    const camera = makeCamera();
+    expect(manager.update(camera, 800, 600, 0)).toBe("ran");
+
+    manager.dispose();
+    expect(manager.update(camera, 800, 600, 1000)).toBe("idle");
+  });
+});

package/src/declutter/DeclutterManager.ts

@@ -0,0 +1,256 @@
+import { Matrix4, type PerspectiveCamera } from "three";
+
+import { CANDIDATE_STRIDE, type DeclutterKernel } from "./kernel";
+import type { DeclutterCandidate, DeclutterParticipant } from "./types";
+
+export type DeclutterUpdateResult =
+  /** Nothing to do: no participants, or camera and data unchanged. */
+  | "idle"
+  /** A placement pass ran; results are applied to the participants. */
+  | "ran"
+  /** Labels are mid-fade — the caller should schedule a prompt follow-up
+   *  frame so the animation keeps stepping. */
+  | "animating"
+  /** A pass is due but the throttle window hasn't elapsed — the caller should
+   *  schedule another frame so placement settles after the camera stops. */
+  | "throttled";
+
+/**
+ * Shared screen-space label decluttering.
+ *
+ * Text batches and sprite meshes register as participants; each placement
+ * pass packs every candidate label into a flat buffer and hands it to the
+ * Rust {@link DeclutterKernel}, which projects the anchors, sorts by priority,
+ * and greedily claims screen space — losers are hidden through the meshes'
+ * declutter channels (`uDeclutterHide` uniform / `instanceDeclutterHide`
+ * attribute), which are separate from user-driven `show` state and free to
+ * toggle every pass.
+ *
+ * Placement is hysteretic: currently-shown labels win equal-priority ties
+ * and tolerate {@link DeclutterManager.HYSTERESIS_PX} of marginal overlap
+ * before eviction, so near-ties don't flicker while the camera drifts.
+ *
+ * The pass is view-dependent, so it runs from the render loop — but throttled:
+ * placement only re-runs when the camera or the label set actually changed,
+ * and at most once per {@link DeclutterManager.MIN_INTERVAL_MS}. Callers run
+ * it *before* rendering so results land in the same frame.
+ */
+export class DeclutterManager {
+  /** Minimum time between placement passes (ms). */
+  static readonly MIN_INTERVAL_MS = 150;
+  /** Padding added around every collision box (px); two labels never sit
+   *  closer than twice this. */
+  static readonly PADDING_PX = 2;
+  /** Largest single fade step (ms), so a frame after an idle gap doesn't
+   *  swallow most of a fade in one jump. */
+  static readonly MAX_FADE_STEP_MS = 50;
+  /** Placement hysteresis (px): a currently-shown label's collision test box
+   *  shrinks by this per side, so it survives marginal overlaps that camera
+   *  drift toggles frame to frame instead of flickering. Its full box is
+   *  still claimed against competitors. */
+  static readonly HYSTERESIS_PX = 6;
+
+  private _participants = new Set<DeclutterParticipant>();
+  /** Set when the label set changed (register/update/text change) so the next
+   *  update re-places even with a static camera. */
+  private _dirty = true;
+
+  // Snapshot of the camera/viewport the last pass ran with.
+  private _prevCamera = new Float64Array(34).fill(Number.NaN);
+  private _lastRunAt = Number.NEGATIVE_INFINITY;
+  private _lastStepAt = Number.NaN;
+
+  // Reused per-pass scratch to keep steady-state allocations low.
+  private _candidates: DeclutterCandidate[] = [];
+  /** Packed candidate input for the kernel; grows as the label count does. */
+  private _input = new Float64Array(0);
+  private _viewMatrix = new Matrix4();
+  private _view16 = new Float64Array(16);
+  private _proj16 = new Float64Array(16);
+
+  /** @param _kernel the placement kernel — the Rust-backed
+   *  `wasmDeclutterKernel` in production, a stub in unit tests. */
+  constructor(private readonly _kernel: DeclutterKernel) {}
+
+  /** Milliseconds until the throttle window since the last placement pass
+   *  elapses, clamped to `[0, MIN_INTERVAL_MS]`. Callers use this to schedule
+   *  a follow-up frame after a `"throttled"` result without overshooting the
+   *  window by waiting out the full constant from now. */
+  remainingThrottleMs(nowMs: number): number {
+    return Math.max(
+      0,
+      DeclutterManager.MIN_INTERVAL_MS - (nowMs - this._lastRunAt),
+    );
+  }
+
+  register(participant: DeclutterParticipant): void {
+    this._participants.add(participant);
+    this._dirty = true;
+  }
+
+  unregister(participant: DeclutterParticipant): void {
+    if (this._participants.delete(participant)) {
+      this._dirty = true;
+    }
+  }
+
+  /** Signal that candidates changed (text, positions, visibility, style) so
+   *  the next update re-runs placement even if the camera is still. */
+  markDirty(): void {
+    this._dirty = true;
+  }
+
+  /**
+   * Run a placement pass if one is due, then advance any active show/hide
+   * fades. `widthPx`/`heightPx` are the viewport in CSS pixels (matching the
+   * `uScreenHeightPx` uniform); `nowMs` is the frame timestamp used for
+   * throttling and fade stepping.
+   */
+  update(
+    camera: PerspectiveCamera,
+    widthPx: number,
+    heightPx: number,
+    nowMs: number,
+  ): DeclutterUpdateResult {
+    if (this._participants.size === 0) return "idle";
+
+    let ran = false;
+    let throttled = false;
+    if (this._dirty || this._snapshotChanged(camera, widthPx, heightPx)) {
+      if (nowMs - this._lastRunAt >= DeclutterManager.MIN_INTERVAL_MS) {
+        this._run(camera, widthPx, heightPx);
+        this._takeSnapshot(camera, widthPx, heightPx);
+        this._dirty = false;
+        this._lastRunAt = nowMs;
+        ran = true;
+      } else {
+        throttled = true;
+      }
+    }
+
+    // Step fades even when no pass ran — placement only sets targets; the
+    // animation itself advances here, frame by frame. Clamp the step so the
+    // first frame after an idle gap doesn't jump most of the fade at once.
+    const deltaMs = Number.isFinite(this._lastStepAt)
+      ? Math.min(nowMs - this._lastStepAt, DeclutterManager.MAX_FADE_STEP_MS)
+      : 0;
+    this._lastStepAt = nowMs;
+    let animating = false;
+    for (const p of this._participants) {
+      animating = p.stepDeclutterFade(deltaMs) || animating;
+    }
+
+    // "animating" wins over "throttled": its prompt follow-up frames re-enter
+    // this method, so a pending throttled pass still runs once the window
+    // elapses.
+    if (animating) return "animating";
+    if (throttled) return "throttled";
+    return ran ? "ran" : "idle";
+  }
+
+  private _run(
+    camera: PerspectiveCamera,
+    widthPx: number,
+    heightPx: number,
+  ): void {
+    const candidates = this._candidates;
+    candidates.length = 0;
+    for (const p of this._participants) {
+      p.collectDeclutterCandidates(candidates);
+    }
+    const n = candidates.length;
+    if (n === 0) return;
+
+    // Pack candidates into the flat kernel input. The layout must match
+    // CANDIDATE_STRIDE / the field order the Rust kernel reads.
+    const stride = CANDIDATE_STRIDE;
+    if (this._input.length < n * stride) {
+      this._input = new Float64Array(n * stride);
+    }
+    const input = this._input;
+    for (let i = 0; i < n; i++) {
+      const c = candidates[i];
+      const o = i * stride;
+      input[o] = c.anchorX;
+      input[o + 1] = c.anchorY;
+      input[o + 2] = c.anchorZ;
+      input[o + 3] = c.addHeight;
+      input[o + 4] = c.minX;
+      input[o + 5] = c.maxX;
+      input[o + 6] = c.minY;
+      input[o + 7] = c.maxY;
+      input[o + 8] = c.sizeInMeters ? 1 : 0;
+      input[o + 9] = c.priority;
+      input[o + 10] = c.isShown ? 1 : 0;
+    }
+
+    // The pass may run before the renderer refreshed matrixWorldInverse, so
+    // derive the view matrix from matrixWorld instead of trusting it.
+    const view = this._viewMatrix.copy(camera.matrixWorld).invert();
+    const cam = camera.matrixWorld.elements;
+    // Three.js Matrix4.elements is a plain number[]; copy into f64 scratch so
+    // the typed-array boundary to WASM stays a single cheap copy per matrix.
+    this._view16.set(view.elements);
+    this._proj16.set(camera.projectionMatrix.elements);
+
+    const hidden = this._kernel.place(
+      input.subarray(0, n * stride),
+      this._view16,
+      this._proj16,
+      cam[12],
+      cam[13],
+      cam[14],
+      camera.near,
+      widthPx,
+      heightPx,
+      // Plain math instead of @navara/three_api's degreeToRadian — that one
+      // is a WASM call whose result we'd only marshal straight back in.
+      (camera.fov * Math.PI) / 180.0,
+      DeclutterManager.PADDING_PX,
+      DeclutterManager.HYSTERESIS_PX,
+    );
+
+    // Apply results as fade targets. Order is irrelevant — applyDeclutter is
+    // idempotent per handle — so iterate in candidate order, not sorted order.
+    for (let i = 0; i < n; i++) {
+      const c = candidates[i];
+      c.owner.applyDeclutter(c.handle, hidden[i] !== 0);
+    }
+
+    candidates.length = 0;
+  }
+
+  /** Drop all registered participants. Call when the owning view is disposed
+   *  so this manager doesn't keep strong references to removed meshes (and
+   *  their GPU/font resources) past the view's lifetime. */
+  dispose(): void {
+    this._participants.clear();
+    this._candidates.length = 0;
+  }
+
+  private _snapshotChanged(
+    camera: PerspectiveCamera,
+    widthPx: number,
+    heightPx: number,
+  ): boolean {
+    const s = this._prevCamera;
+    const world = camera.matrixWorld.elements;
+    const proj = camera.projectionMatrix.elements;
+    for (let i = 0; i < 16; i++) {
+      if (s[i] !== world[i] || s[16 + i] !== proj[i]) return true;
+    }
+    return s[32] !== widthPx || s[33] !== heightPx;
+  }
+
+  private _takeSnapshot(
+    camera: PerspectiveCamera,
+    widthPx: number,
+    heightPx: number,
+  ): void {
+    const s = this._prevCamera;
+    s.set(camera.matrixWorld.elements, 0);
+    s.set(camera.projectionMatrix.elements, 16);
+    s[32] = widthPx;
+    s[33] = heightPx;
+  }
+}

package/src/declutter/index.ts

@@ -0,0 +1,7 @@
+export {
+  DeclutterManager,
+  type DeclutterUpdateResult,
+} from "./DeclutterManager";
+export { CANDIDATE_STRIDE, type DeclutterKernel } from "./kernel";
+export { wasmDeclutterKernel } from "./wasmKernel";
+export type { DeclutterCandidate, DeclutterParticipant } from "./types";