@navaramap/three 0.0.0

package/src/core/MeshDesc.ts

@@ -0,0 +1,457 @@
+import type { BaseEventMap, XYZ } from "@navaramap/core";
+import { Euler, Matrix4, Object3D, Vector3 } from "three";
+import invariant from "tiny-invariant";
+
+import type ThreeView from "../index";
+import type { Scenes } from "../scene";
+
+import {
+  BaseDesc,
+  type BaseInstance,
+  type BaseDescConfig,
+  type BaseDescConfigUpdate,
+} from "./BaseDesc";
+import type { ViewContext } from "./ViewContext";
+
+export type MeshConfig = {
+  type?: "mesh";
+  /**
+   * Local translation. When `matrix` or `matrixWorld` is also set, this is
+   * treated as an offset *inside* that frame (left-multiplied by the frame).
+   * Otherwise it's applied directly as `Object3D.position`.
+   */
+  position?: XYZ;
+  /**
+   * Local scale. See {@link position} for interaction with `matrix` / `matrixWorld`.
+   */
+  scale?: XYZ;
+  /**
+   * Local Euler rotation (XYZ order). See {@link position} for interaction
+   * with `matrix` / `matrixWorld`.
+   */
+  rotation?: XYZ;
+  /**
+   * Local frame. When combined with `position` / `rotation` / `scale`, the
+   * effective local matrix is `matrix · T(position) · R(rotation) · S(scale)`.
+   * Disables Three.js's auto matrix update.
+   */
+  matrix?: Matrix4;
+  /**
+   * World frame (e.g. an NUE-to-ECEF tangent frame on the globe). When
+   * combined with `position` / `rotation` / `scale`, the effective world
+   * matrix is `matrixWorld · T(position) · R(rotation) · S(scale)`, so the
+   * offset fields are interpreted in the frame's local coordinates.
+   * Disables Three.js's auto matrix-world update.
+   */
+  matrixWorld?: Matrix4;
+} & BaseDescConfig;
+
+export type MeshUpdate = Pick<
+  MeshConfig,
+  "position" | "scale" | "rotation" | "matrix" | "matrixWorld"
+> &
+  BaseDescConfigUpdate;
+
+export type PassKey = keyof Pick<
+  Scenes,
+  "opaque" | "transparent" | "mrt" | "skyEnvMap" | "draped"
+>;
+
+export type MeshBaseInstance<Instance extends object = object> =
+  Instance extends Object3D
+    ? Instance
+    : Instance extends {
+          raw: infer Raw extends Object3D;
+        }
+      ? Instance & { raw: Raw } & BaseInstance
+      : Instance & BaseInstance;
+
+/**
+ * Abstract base class for creating custom mesh descriptors.
+ *
+ * Extend this class to add custom Three.js 3D objects (meshes, groups, particles, etc.)
+ * to the Navara scene. The base class handles position/scale/rotation synchronization
+ * and automatic scene management via {@link getPassKey}.
+ *
+ * ## Implementing a Custom Mesh Descriptor
+ *
+ * ### 1. Define configuration types
+ *
+ * Create a description type for your mesh-specific options, then merge it with the
+ * base config and update types:
+ *
+ * ```typescript
+ * type MyMeshDescription = {
+ *   myMesh?: {
+ *     radius?: number;
+ *     color?: Color;
+ *     castShadow?: boolean;
+ *   };
+ * };
+ *
+ * type MyMeshConfig = MeshConfig & MyMeshDescription;
+ * type MyMeshUpdate = MeshUpdate & MyMeshDescription;
+ * ```
+ *
+ * ### 2. Extend `MeshDesc`
+ *
+ * Implement the {@link createMesh} factory method. Optionally override
+ * {@link getPassKey} to control which render scene the mesh belongs to,
+ * {@link onUpdateConfig} for dynamic updates, and {@link update} for animation.
+ *
+ * ```typescript
+ * class MyMeshDesc extends MeshDesc<
+ *   MyMeshConfig,
+ *   MyMeshUpdate,
+ *   Mesh<SphereGeometry, MeshStandardMaterial>
+ * > {
+ *   private config: MyMeshConfig;
+ *
+ *   constructor(view: ThreeView, ctx: ViewContext, config: MyMeshConfig) {
+ *     super(view, ctx, config);
+ *     this.config = config;
+ *   }
+ *
+ *   createMesh() {
+ *     const cfg = this.config.myMesh ?? {};
+ *     const geometry = new SphereGeometry(cfg.radius ?? 1);
+ *     const material = new MeshStandardMaterial({
+ *       color: cfg.color?.raw ?? 0xffffff,
+ *     });
+ *     const mesh = new Mesh(geometry, material);
+ *     mesh.castShadow = cfg.castShadow ?? false;
+ *
+ *     // Enable CSM shadows if needed
+ *     if (mesh.castShadow) {
+ *       this.ctx.applyShadowMaterial(material);
+ *     }
+ *
+ *     return mesh;
+ *   }
+ *
+ *   onUpdateConfig(updates: MyMeshUpdate): void {
+ *     if (updates.myMesh && this._instance) {
+ *       if (updates.myMesh.color !== undefined) {
+ *         this._instance.material.color.set(updates.myMesh.color.raw);
+ *       }
+ *       this.emit("needsUpdate");
+ *     }
+ *     super.onUpdateConfig(updates);
+ *   }
+ * }
+ * ```
+ *
+ * ### 3. Register and use the descriptor
+ *
+ * ```typescript
+ * view.registerMesh("myMesh", MyMeshDesc);
+ *
+ * const handle = view.addMesh<MyMeshDesc>({
+ *   position: { x: 0, y: 100, z: 0 },
+ *   scale: { x: 10, y: 10, z: 10 },
+ *   rotation: { x: 0, y: Math.PI / 4, z: 0 },
+ *   myMesh: { radius: 5, color: new Color("#00ff00") },
+ * });
+ *
+ * // Update dynamically
+ * handle.update({ myMesh: { color: new Color("#ff0000") } });
+ *
+ * // Access the raw Three.js object for direct manipulation
+ * const mesh = handle.ref.raw;
+ *
+ * // Animate on every frame
+ * view.on("preUpdate", (time) => {
+ *   mesh.rotation.y += 0.01;
+ * });
+ *
+ * // Remove the descriptor
+ * handle.delete();
+ * ```
+ *
+ * ## Render Scenes (Pass Keys)
+ *
+ * Override {@link getPassKey} to control which render scene the mesh is added to:
+ * - `"opaque"` (default) - Standard opaque rendering with depth testing.
+ * - `"transparent"` - Transparent rendering pass.
+ * - `"mrt"` - Multiple Render Target scene, used for selective effects (bloom, outline).
+ * - `"skyEnvMap"` - Sky environment map scene.
+ * - `"draped"` - This is only for `DrapedMesh`. The mesh is clamped to the terrain.
+ *
+ * ## Lifecycle
+ *
+ * 1. **Construction** - The descriptor is instantiated with the view context and config.
+ * 2. **{@link createMesh}** - Called during {@link onCreate} to create the Three.js object.
+ *    The base class applies position/scale/rotation and adds it to the scene
+ *    determined by {@link getPassKey}.
+ * 3. **{@link onUpdateConfig}** - Called when `handle.update()` is invoked. The base class
+ *    handles `visible`, `matrix`, `matrixWorld`, `position`, `scale`, and `rotation`; override to handle your
+ *    custom properties. Always call `super.onUpdateConfig(updates)`.
+ * 4. **{@link update}** - Optional per-frame callback for animation.
+ * 5. **{@link onResize}** - Optional callback when the viewport is resized.
+ * 6. **{@link onDestroy}** - Called on `handle.delete()`. The base class removes the mesh
+ *    from its parent scene. Override to dispose geometry/material resources.
+ *
+ * @see The `custom-shader` example page for a complete custom mesh descriptor tutorial using
+ *      MarchingCubes with a custom shader material.
+ *
+ * @typeParam Config - Configuration type (extends {@link MeshConfig})
+ * @typeParam UpdateConfig - Updatable properties (extends {@link MeshUpdate})
+ * @typeParam InstanceObj - The Three.js Object3D type or a wrapper with a `raw` property
+ * @typeParam CustomEvent - Additional custom events the descriptor can emit
+ * @typeParam Instance - Resolved instance type (inferred automatically)
+ */
+export abstract class MeshDesc<
+  Config extends MeshConfig = MeshConfig,
+  UpdateConfig extends MeshUpdate = MeshUpdate,
+  InstanceObj extends Object3D | { raw: Object3D } =
+    | Object3D
+    | { raw: Object3D },
+  CustomEvent extends BaseEventMap = BaseEventMap,
+  Instance extends MeshBaseInstance<InstanceObj> =
+    MeshBaseInstance<InstanceObj>,
+> extends BaseDesc<Config, UpdateConfig, Instance, CustomEvent> {
+  public position?: XYZ;
+  public scale?: XYZ;
+  public rotation?: XYZ;
+  public matrix?: Matrix4;
+  public matrixWorld?: Matrix4;
+  private prevPassKey?: PassKey;
+
+  constructor(view: ThreeView, ctx: ViewContext, config?: Config) {
+    const resolvedConfig = config ?? ({} as Config);
+    super(view, ctx, resolvedConfig);
+    this.position = resolvedConfig.position;
+    this.scale = resolvedConfig.scale;
+    this.rotation = resolvedConfig.rotation;
+    this.matrix = resolvedConfig.matrix;
+    this.matrixWorld = resolvedConfig.matrixWorld;
+  }
+
+  /**
+   * Determines which render scene the mesh is added to.
+   * Override this to change the rendering pass for your mesh.
+   *
+   * @returns The pass key: `"opaque"` (default), `"transparent"`, `"mrt"`, or `"skyEnvMap"`.
+   */
+  protected getPassKey(): PassKey {
+    return "opaque";
+  }
+
+  /**
+   * Factory method to create the Three.js 3D object.
+   *
+   * Override this to return your custom mesh. The returned object can be
+   * either a Three.js `Object3D` directly (e.g. `Mesh`, `Group`, `Points`) or
+   * a wrapper object with a `raw` property containing the `Object3D`.
+   *
+   * The base class calls this during {@link onCreate} and automatically
+   * applies position, scale, rotation, and adds the object to the appropriate
+   * scene. Picking is opt-in: if your layer supports it, construct a
+   * {@link PickableMesh} here and register it yourself via
+   * `this.ctx.registerPickableMesh(this.id, wrapper)` before returning.
+   */
+  abstract createMesh(): Instance;
+
+  get raw() {
+    if (!this._instance) return;
+
+    if (this._instance instanceof Object3D) {
+      return this._instance as Instance extends Object3D ? Instance : never;
+    }
+    if ("raw" in this._instance) {
+      return this._instance.raw as Instance extends {
+        raw: infer Raw extends Object3D;
+      }
+        ? Raw
+        : never;
+    }
+    return;
+  }
+
+  onCreate() {
+    this._instance = this.createMesh();
+    invariant(this.raw);
+
+    this.applyTransform();
+
+    this._instance.visible = this.visible;
+
+    this.onPassKeyChange();
+  }
+
+  /**
+   * Composes position, rotation, and scale into a local `T · R · S` matrix.
+   * Returns identity when none are set.
+   */
+  protected composeLocalTransform(): Matrix4 {
+    const local = new Matrix4();
+    if (this.position) {
+      local.multiply(
+        new Matrix4().makeTranslation(
+          this.position.x,
+          this.position.y,
+          this.position.z,
+        ),
+      );
+    }
+    if (this.rotation) {
+      local.multiply(
+        new Matrix4().makeRotationFromEuler(
+          new Euler(this.rotation.x, this.rotation.y, this.rotation.z),
+        ),
+      );
+    }
+    if (this.scale) {
+      local.scale(new Vector3(this.scale.x, this.scale.y, this.scale.z));
+    }
+    return local;
+  }
+
+  /**
+   * Applies the configured transform to the underlying `Object3D`.
+   *
+   * When `matrixWorld` (or `matrix`) is set together with any of
+   * `position` / `rotation` / `scale`, the base/frame is left-multiplied
+   * by the local `T · R · S`: e.g. `effective = matrixWorld · T · R · S`.
+   * This lets callers pass a frame (such as an NUE-to-ECEF matrix) as
+   * `matrixWorld` and express offsets inside that frame via
+   * `position` / `rotation` / `scale`.
+   */
+  private applyTransform(): void {
+    invariant(this.raw);
+    const hasLocal =
+      this.position != null || this.rotation != null || this.scale != null;
+
+    if (this.matrixWorld) {
+      this.raw.matrixAutoUpdate = false;
+      this.raw.matrixWorldAutoUpdate = false;
+      if (hasLocal) {
+        this.raw.matrixWorld.multiplyMatrices(
+          this.matrixWorld,
+          this.composeLocalTransform(),
+        );
+      } else {
+        this.raw.matrixWorld.copy(this.matrixWorld);
+      }
+      this.raw.updateMatrixWorld();
+      return;
+    }
+
+    if (this.matrix) {
+      this.raw.matrixAutoUpdate = false;
+      if (hasLocal) {
+        this.raw.matrix.multiplyMatrices(
+          this.matrix,
+          this.composeLocalTransform(),
+        );
+      } else {
+        this.raw.matrix.copy(this.matrix);
+      }
+      return;
+    }
+
+    if (this.position) this.raw.position.copy(this.position);
+    if (this.scale) this.raw.scale.copy(this.scale);
+    if (this.rotation)
+      this.raw.rotation.set(this.rotation.x, this.rotation.y, this.rotation.z);
+  }
+
+  removeFromScene(passKey: PassKey) {
+    const scenes = this.ctx.scenes;
+
+    if (scenes[passKey] && this.raw) {
+      scenes[passKey].remove(this.raw);
+    }
+  }
+
+  addToScene(passKey: PassKey) {
+    if (!this.raw) return;
+
+    const scenes = this.ctx.scenes;
+
+    if (scenes[passKey]) {
+      scenes[passKey].add(this.raw);
+    }
+  }
+
+  onUpdateConfig(updates: UpdateConfig): void {
+    super.onUpdateConfig(updates);
+    invariant(this.raw);
+
+    const spatialChanged =
+      updates.matrix !== undefined ||
+      updates.matrixWorld !== undefined ||
+      updates.position !== undefined ||
+      updates.scale !== undefined ||
+      updates.rotation !== undefined;
+
+    if (updates.matrix !== undefined) this.matrix = updates.matrix;
+    if (updates.matrixWorld !== undefined)
+      this.matrixWorld = updates.matrixWorld;
+    if (updates.position !== undefined) this.position = updates.position;
+    if (updates.scale !== undefined) this.scale = updates.scale;
+    if (updates.rotation !== undefined) this.rotation = updates.rotation;
+
+    if (spatialChanged) {
+      // With a frame present, the effective transform depends on the
+      // combination of all stored fields — recompose the whole thing.
+      // Without a frame, apply only the fields that were actually passed,
+      // so subclasses that strip a field from `updates` (e.g. GLTFModelLayer
+      // keeping `raw.position` at 0 for its RTE shader) can still opt out
+      // of having the base class copy it onto `raw`.
+      if (this.matrixWorld || this.matrix) {
+        this.applyTransform();
+      } else {
+        if (updates.position !== undefined) {
+          this.raw.position.copy(updates.position);
+        }
+        if (updates.scale !== undefined) {
+          this.raw.scale.copy(updates.scale);
+        }
+        if (updates.rotation !== undefined) {
+          this.raw.rotation.set(
+            updates.rotation.x,
+            updates.rotation.y,
+            updates.rotation.z,
+          );
+        }
+      }
+    }
+
+    this.onPassKeyChange();
+  }
+
+  onPassKeyChange() {
+    const nextPassKey = this.getPassKey();
+    if (this.prevPassKey === nextPassKey) return;
+    if (this.prevPassKey) {
+      this.removeFromScene(this.prevPassKey);
+    }
+    this.prevPassKey = nextPassKey;
+    this.addToScene(nextPassKey);
+  }
+
+  onDestroy(): void {
+    if (this.raw && this.raw.parent) {
+      this.raw.parent.remove(this.raw);
+    }
+
+    super.onDestroy();
+  }
+
+  /**
+   * Optional per-frame update callback.
+   * Override this to animate the mesh (e.g. rotation, morph targets, shader uniforms).
+   * @param time - High-resolution timestamp from the main render loop (same value passed
+   *   to `requestAnimationFrame`), in milliseconds.
+   */
+  update?(time: number): void;
+
+  /**
+   * Optional callback when the viewport is resized.
+   * Override this to adjust the mesh based on viewport dimensions.
+   * @param width - New viewport width in pixels.
+   * @param height - New viewport height in pixels.
+   */
+  onResize?(width: number, height: number): void;
+}

package/src/core/MeshDescRegistry.ts

@@ -0,0 +1,32 @@
+import type ThreeView from "../index";
+
+import type { AnyMeshDesc } from "./BaseHandle";
+import { DescRegistry } from "./DescRegistry";
+import type { MeshConfig } from "./MeshDesc";
+import type { ViewContext } from "./ViewContext";
+
+export type AnyMeshConfig = MeshConfig;
+
+export type MeshDescConstructor<TConfig extends AnyMeshConfig = AnyMeshConfig> =
+  new (view: ThreeView, ctx: ViewContext, config: TConfig) => AnyMeshDesc;
+
+export class MeshDescRegistry extends DescRegistry<
+  MeshDescConstructor,
+  AnyMeshDesc,
+  AnyMeshConfig
+> {
+  create(name: string, config: AnyMeshConfig): AnyMeshDesc {
+    const MeshClass = this.getConstructor(name);
+    if (!MeshClass) {
+      throw new Error(`Unknown mesh type: ${name}`);
+    }
+    return new MeshClass(this.view, this.ctx, config);
+  }
+
+  /**
+   * Find mesh type from config (alias for findTypeFromConfig for backward compatibility)
+   */
+  findMeshType(config: Record<string, unknown>): string | null {
+    return this.findTypeFromConfig(config);
+  }
+}

package/src/core/MeshDescWithSelectiveEffect.ts

@@ -0,0 +1,129 @@
+import type { BaseEventMap } from "@navaramap/core";
+import { Mesh, type Object3D } from "three";
+
+import type ThreeView from "../index";
+import { arraysEqual } from "../utils";
+
+import {
+  MeshDesc,
+  type MeshConfig,
+  type MeshUpdate,
+  type MeshBaseInstance,
+  type PassKey,
+} from "./MeshDesc";
+import type { ViewContext } from "./ViewContext";
+
+export type MeshConfigWithSelectiveEffect = MeshConfig & {
+  effectIds?: string[];
+};
+
+export type MeshUpdateWithSelectiveEffect = MeshUpdate & {
+  effectIds?: string[];
+};
+
+export abstract class MeshDescWithSelectiveEffect<
+  Config extends MeshConfigWithSelectiveEffect = MeshConfigWithSelectiveEffect,
+  UpdateConfig extends MeshUpdateWithSelectiveEffect =
+    MeshUpdateWithSelectiveEffect,
+  InstanceObj extends Object3D | { raw: Object3D } =
+    | Object3D
+    | { raw: Object3D },
+  CustomEvent extends BaseEventMap = BaseEventMap,
+  Instance extends MeshBaseInstance<InstanceObj> =
+    MeshBaseInstance<InstanceObj>,
+> extends MeshDesc<Config, UpdateConfig, InstanceObj, CustomEvent, Instance> {
+  protected _effectIds: string[] = [];
+  private _onSlotsChanged = () => {
+    this.updateEffectIdsMask();
+    // Slot count changes can flip the pass returned by getPassKey()
+    // (mrt <-> opaque), so re-evaluate scene placement.
+    this.onPassKeyChange();
+  };
+
+  constructor(view: ThreeView, ctx: ViewContext, config?: Config) {
+    const resolvedConfig = config ?? ({} as Config);
+    super(view, ctx, resolvedConfig);
+    this._effectIds = resolvedConfig.effectIds ?? [];
+  }
+
+  protected override getPassKey(): PassKey {
+    // When at least one selective effect is registered on this view, all
+    // SE-capable meshes must share the MRT depth/color path so the depth
+    // ordering between SE participants stays consistent — an empty
+    // effectIds list still has to coexist with non-empty siblings, and is
+    // expressed by effectIdsMask=0 rather than by falling back to opaque.
+    // When no effect is registered, MRT participation is pure overhead, so
+    // defer to the parent's default (opaque) pass.
+    if (this.ctx.selectiveEffectRegistry.slotCount > 0) {
+      return "mrt";
+    }
+    return super.getPassKey();
+  }
+
+  override onCreate() {
+    super.onCreate();
+
+    // Compute and set effectIdsMask on material uniforms
+    this.updateEffectIdsMask();
+
+    // Recompute mask when slot assignments change (effect added/removed)
+    this.ctx.on("effectSlotsChanged", this._onSlotsChanged);
+  }
+
+  override onUpdateConfig(updates: UpdateConfig): void {
+    // ----------------------------------------------------------------------------
+    // SelectiveEffect: effectIds update
+    // Sync _effectIds before delegating to super so any downstream handler
+    // observing the descriptor sees the new value.
+    // ----------------------------------------------------------------------------
+    let effectIdsChanged = false;
+
+    if (updates.effectIds !== undefined) {
+      const nextEffectIds = updates.effectIds ?? [];
+
+      if (!arraysEqual(this._effectIds, nextEffectIds)) {
+        this._effectIds = [...nextEffectIds];
+        effectIdsChanged = true;
+      }
+    }
+
+    super.onUpdateConfig(updates);
+
+    if (effectIdsChanged) {
+      // Recompute effectIdsMask for material uniforms.
+      this.updateEffectIdsMask();
+    }
+  }
+
+  /**
+   * Compute effectIdsMask and set on the mesh's material.
+   * Override this for non-standard mesh structures (e.g., Object3D with child meshes).
+   */
+  protected updateEffectIdsMask(): void {
+    const registry = this.ctx.selectiveEffectRegistry;
+    if (!registry) return;
+
+    const mask =
+      this._effectIds.length > 0 ? registry.computeMask(this._effectIds) : 0;
+    const raw = this.raw;
+    if (
+      raw instanceof Mesh &&
+      !Array.isArray(raw.material) &&
+      raw.material?.userData?.uEffectIdsMask
+    ) {
+      raw.material.userData.uEffectIdsMask.value = mask;
+    }
+  }
+
+  override onDestroy(): void {
+    // ----------------------------------------------------------------------------
+    // SelectiveEffect: cleanup
+    // ----------------------------------------------------------------------------
+    this._effectIds = [];
+
+    // Unsubscribe from slot changes
+    this.ctx.off("effectSlotsChanged", this._onSlotsChanged);
+
+    super.onDestroy();
+  }
+}

package/src/core/Registries.ts

@@ -0,0 +1,59 @@
+import type ThreeView from "../index";
+
+import { EffectDescRegistry } from "./EffectDescRegistry";
+import { LightDescRegistry } from "./LightDescRegistry";
+import { MeshDescRegistry } from "./MeshDescRegistry";
+import type { ViewContext } from "./ViewContext";
+// import { ResourceRegistry } from "./ResourceRegistry"; // TODO: Implement when needed
+
+/**
+ * Centralized registry manager that bundles all registry types.
+ * This provides direct property access to different types of registries
+ * in the Navara system.
+ */
+export class Registries {
+  mesh: MeshDescRegistry;
+  light: LightDescRegistry;
+  effect: EffectDescRegistry;
+  // resource: ResourceRegistry; // TODO: Implement when needed
+  // pass: PassRegistry; // TODO: Implement when needed
+  // material: MaterialRegistry; // TODO: Implement when needed
+  // shader: ShaderRegistry; // TODO: Implement when needed
+
+  constructor(view: ThreeView, ctx: ViewContext) {
+    this.mesh = new MeshDescRegistry(view, ctx);
+    this.light = new LightDescRegistry(view, ctx);
+    this.effect = new EffectDescRegistry(view, ctx);
+  }
+
+  /**
+   * Get registry statistics for debugging and monitoring
+   */
+  getStats() {
+    return {
+      mesh: {
+        registeredCount: this.mesh.size(),
+        types: this.mesh.getRegisteredTypes(),
+      },
+      light: {
+        registeredCount: this.light.size(),
+        types: this.light.getRegisteredTypes(),
+      },
+      effect: {
+        registeredCount: this.effect.size(),
+        types: this.effect.getRegisteredTypes(),
+      },
+      // TODO: Add other registries when implemented
+    };
+  }
+
+  /**
+   * Clear all registries
+   */
+  clearAll(): void {
+    this.mesh.clear();
+    this.light.clear();
+    this.effect.clear();
+    // TODO: Clear other registries when implemented
+  }
+}