@navaramap/three 0.0.0

package/src/layers/effect/index.ts

@@ -0,0 +1,5 @@
+export * from "./FinalCopyEffectDesc";
+export * from "./MRTPassEffectDesc";
+export * from "./SelectiveEffectDesc";
+export * from "./SkyEnvMapEffectDesc";
+export * from "./TransparentPassEffectDesc";

package/src/layers/index.ts

@@ -0,0 +1 @@
+export * from "./effect";

package/src/layersManager.ts

@@ -0,0 +1,63 @@
+import { EffectDesc, BaseHandle, EffectHandle } from "./core";
+import { Layer, type LayerEvent } from "./layer";
+
+export class LayersManager {
+  private layers = new Map<string, Layer | BaseHandle>();
+
+  add(l: Layer | BaseHandle) {
+    this.layers.set(l.id, l);
+    const deleteLayer = () => {
+      this.layers.delete(l.id);
+    };
+    if (l instanceof BaseHandle) {
+      l.on("deleted", deleteLayer);
+    } else {
+      l.on("deleted", deleteLayer);
+    }
+  }
+
+  get(id: string) {
+    return this.layers.get(id);
+  }
+
+  emitById<K extends keyof LayerEvent>(
+    k: K,
+    id: string,
+    ...args: Parameters<LayerEvent[K]>
+  ) {
+    const l = this.layers.get(id);
+    if (!l) return;
+    if (l instanceof Layer) {
+      l.emit(k, ...args);
+    }
+  }
+
+  emitAll<K extends keyof LayerEvent>(
+    k: K,
+    ...args: Parameters<LayerEvent[K]>
+  ) {
+    for (const l of this.layers.values()) {
+      if (l instanceof Layer) {
+        l.emit(k, ...args);
+      }
+    }
+  }
+
+  *getResourceLayers() {
+    for (const l of this.layers.values()) {
+      if (!(l instanceof Layer)) continue;
+      yield l;
+    }
+  }
+
+  *getEffectDescs(): Generator<EffectHandle> {
+    for (const handle of this.layers.values()) {
+      if (!(handle instanceof BaseHandle)) continue;
+
+      const desc = handle.ref;
+      if (!(desc instanceof EffectDesc)) continue;
+
+      yield handle as EffectHandle;
+    }
+  }
+}

package/src/light.ts

@@ -0,0 +1,15 @@
+import type { Vector3 } from "three";
+
+export type Light = {
+  ambient?: {
+    enabled?: boolean;
+    color?: number;
+    intensity?: number;
+  };
+  sun?: {
+    enabled?: boolean;
+    color?: number;
+    position?: Vector3;
+    intensity?: number;
+  };
+};

package/src/loaders/AbortableImageLoader.ts

@@ -0,0 +1,203 @@
+import { Loader } from "three";
+
+function createElementNS(name: string) {
+  return document.createElementNS("http://www.w3.org/1999/xhtml", name);
+}
+
+/** Same shape as a fetch abort rejection: `err.name === "AbortError"`. */
+function abortError() {
+  return new DOMException("The operation was aborted.", "AbortError");
+}
+
+/**
+ * Decoded tile image. `ImageBitmap` on browsers with `createImageBitmap`
+ * (decode happens off the main thread); `HTMLImageElement` on the fallback
+ * path. An `ImageBitmap` is produced with `imageOrientation: "flipY"`, so the
+ * consumer must upload it with `texture.flipY = false` to match the
+ * `<img>`-path orientation (the GL flip flag is ignored for ImageBitmap
+ * uploads anyway).
+ */
+export type LoadedImage = HTMLImageElement | ImageBitmap;
+
+// Ref: https://github.com/mrdoob/three.js/blob/beab9e845f9e5ae11d648f55b24a0e910b56a85a/src/loaders/ImageLoader.js
+export class AbortableImageLoader extends Loader<LoadedImage> {
+  loadAsyncWithAbort(
+    url: string,
+    abort?: AbortController,
+    onProgress?: (event: ProgressEvent) => void,
+  ) {
+    // eslint-disable-next-line @typescript-eslint/no-this-alias
+    const scope = this;
+
+    return new Promise<LoadedImage>(function (resolve, reject) {
+      scope.load(url, resolve, onProgress, reject, abort);
+    });
+  }
+
+  load(
+    url: string,
+    onLoad: (data: LoadedImage) => void,
+    _onProgress?: (event: ProgressEvent) => void,
+    onError?: (err: unknown, isAborted?: boolean) => void,
+    abort?: AbortController,
+    timeout = 5000,
+  ): void {
+    if (this.path !== undefined) url = this.path + url;
+
+    // eslint-disable-next-line @typescript-eslint/no-this-alias
+    const scope = this;
+
+    let settled = false;
+
+    // Report the timeout before aborting: abort() dispatches its event
+    // synchronously, so the reverse order would let the fallback path's
+    // abort listener settle the load as AbortError first and swallow the
+    // TimeoutError.
+    const timeoutId = window.setTimeout(() => {
+      fail(new Error("TimeoutError"));
+      abort?.abort();
+    }, timeout);
+
+    function done(image: LoadedImage) {
+      if (settled) return;
+      settled = true;
+      window.clearTimeout(timeoutId);
+
+      onLoad(image);
+
+      scope.manager.itemEnd(url);
+    }
+
+    function fail(err: unknown, isAborted?: boolean) {
+      if (settled) return;
+      settled = true;
+      window.clearTimeout(timeoutId);
+
+      if (onError) onError(err, isAborted);
+
+      scope.manager.itemError(url);
+      scope.manager.itemEnd(url);
+    }
+
+    // Before any async work, so every done/fail (which call itemEnd) has a
+    // matching itemStart even when the fetch itself rejects or times out.
+    scope.manager.itemStart(url);
+
+    fetch(url, { signal: abort?.signal })
+      .then((r) => {
+        // Unlike the <img> path (which fires "error" on a 4xx/5xx), fetch
+        // resolves on HTTP error statuses — fail here instead of trying to
+        // decode the error body as an image (e.g. a 404 that returns a
+        // placeholder image would otherwise be shown as a real tile).
+        if (!r.ok) throw new Error(`HTTP ${r.status} while loading ${url}`);
+        return r.blob();
+      })
+      .then((blob) => {
+        if (settled) {
+          return;
+        }
+        if (abort?.signal.aborted) {
+          fail(abortError(), true);
+          return;
+        }
+
+        if (typeof createImageBitmap === "function") {
+          // Decodes off the main thread and needs no object URL.
+          // - flipY is baked in (see LoadedImage);
+          // - premultiply disabled and colorSpaceConversion "none" so the
+          //   decoded bytes match the old <img> → texImage2D path, where
+          //   three sets UNPACK_PREMULTIPLY_ALPHA/UNPACK_COLORSPACE_CONVERSION
+          //   to NONE (critical for RGB-encoded elevation fragments, whose
+          //   bytes must not be color-managed before the shader decodes them).
+          createImageBitmap(blob, {
+            imageOrientation: "flipY",
+            premultiplyAlpha: "none",
+            colorSpaceConversion: "none",
+          })
+            .then((bitmap) => {
+              // createImageBitmap cannot be cancelled; if the load already
+              // settled (abort/timeout) while it was decoding, just release
+              // the now-useless bitmap.
+              if (settled || abort?.signal.aborted) {
+                bitmap.close();
+                if (!settled) fail(abortError(), true);
+                return;
+              }
+              done(bitmap);
+            })
+            .catch((e) => fail(e));
+          // Settle promptly on abort instead of blocking itemEnd (and any
+          // loads gated on it) until the un-cancellable decode finishes. The
+          // decode still runs; its .then closes the orphaned bitmap above.
+          abort?.signal.addEventListener(
+            "abort",
+            () => fail(abortError(), true),
+            { once: true },
+          );
+          return;
+        }
+
+        this.loadViaImageElement(url, blob, done, fail, abort);
+      })
+      .catch((e) => {
+        fail(e, !e.name || e.name === "AbortError");
+      });
+  }
+
+  /**
+   * Fallback for browsers without `createImageBitmap`. The object URL keeps
+   * the blob alive until revoked, so it must be revoked on every exit path
+   * (load, error, abort) or each fetched tile leaks its encoded bytes for the
+   * page's lifetime.
+   */
+  private loadViaImageElement(
+    url: string,
+    blob: Blob,
+    done: (image: LoadedImage) => void,
+    fail: (err: unknown, isAborted?: boolean) => void,
+    abort?: AbortController,
+  ) {
+    if (abort?.signal.aborted) {
+      fail(abortError(), true);
+      return;
+    }
+
+    const objectUrl = window.URL.createObjectURL(blob);
+    const image = createElementNS("img") as HTMLImageElement;
+
+    function cleanup() {
+      window.URL.revokeObjectURL(objectUrl);
+      image.removeEventListener("load", onImageLoad, false);
+      image.removeEventListener("error", onImageError, false);
+      abort?.signal.removeEventListener("abort", onAbort, false);
+    }
+
+    function onImageLoad(this: HTMLImageElement) {
+      cleanup();
+      done(this);
+    }
+
+    function onImageError(event: unknown) {
+      cleanup();
+      fail(event);
+    }
+
+    function onAbort() {
+      // Abort the decode by clearing the image element.
+      image.src = "";
+      image.remove();
+      cleanup();
+      fail(abortError(), true);
+    }
+
+    image.addEventListener("load", onImageLoad, false);
+    image.addEventListener("error", onImageError, false);
+    abort?.signal.addEventListener("abort", onAbort, false);
+
+    if (url.slice(0, 5) !== "data:") {
+      if (this.crossOrigin !== undefined) image.crossOrigin = this.crossOrigin;
+    }
+
+    image.src = objectUrl;
+  }
+}

package/src/loaders/AbortableTextureLoader.ts

@@ -0,0 +1,74 @@
+import { Loader, Texture } from "three";
+
+import { AbortableImageLoader } from "./AbortableImageLoader";
+
+/**
+ * Dispose a texture and release its backing image. When the texture is backed
+ * by an `ImageBitmap` (the `createImageBitmap` decode path in
+ * AbortableImageLoader), `texture.dispose()` frees the GL texture but NOT the
+ * bitmap's decoded-pixel memory, which lives off-heap until `.close()` — so a
+ * plain dispose leaks it on every tile removal. Safe for any texture: images
+ * that are not ImageBitmaps (render targets, HTMLImageElement) are left alone.
+ */
+export function disposeTexture(texture: Texture): void {
+  const image = texture.image as unknown;
+  texture.dispose();
+  if (typeof ImageBitmap !== "undefined" && image instanceof ImageBitmap) {
+    image.close();
+  }
+}
+
+// Ref: https://github.com/mrdoob/three.js/blob/beab9e845f9e5ae11d648f55b24a0e910b56a85a/src/loaders/TextureLoader.js
+export class AbortableTextureLoader extends Loader {
+  loadAsyncWithAbort(
+    url: string,
+    abort?: AbortController,
+    onProgress?: (event: ProgressEvent) => void,
+  ) {
+    // eslint-disable-next-line @typescript-eslint/no-this-alias
+    const scope = this;
+
+    return new Promise<Texture>(function (resolve, reject) {
+      scope.load(url, resolve, onProgress, reject, abort);
+    });
+  }
+
+  load(
+    url: string,
+    onLoad: (data: Texture) => void,
+    onProgress?: (event: ProgressEvent) => void,
+    onError?: (err: unknown, isAborted?: boolean) => void,
+    abort?: AbortController,
+  ): Texture {
+    const texture = new Texture();
+
+    const loader = new AbortableImageLoader(this.manager);
+    loader.setCrossOrigin(this.crossOrigin);
+    loader.setPath(this.path);
+
+    loader.load(
+      url,
+      function (image) {
+        texture.image = image;
+        if (
+          typeof ImageBitmap !== "undefined" &&
+          image instanceof ImageBitmap
+        ) {
+          // The bitmap is already flipped at decode time
+          // (imageOrientation: "flipY" — see AbortableImageLoader).
+          texture.flipY = false;
+        }
+        texture.needsUpdate = true;
+
+        if (onLoad !== undefined) {
+          onLoad(texture);
+        }
+      },
+      onProgress,
+      onError,
+      abort,
+    );
+
+    return texture;
+  }
+}

package/src/loaders/index.ts

@@ -0,0 +1,5 @@
+export { AbortableImageLoader } from "./AbortableImageLoader";
+export {
+  AbortableTextureLoader,
+  disposeTexture,
+} from "./AbortableTextureLoader";

package/src/material/enhancer/DESIGN.md

@@ -0,0 +1,300 @@
+# Material Enhancer Pattern
+
+A compositional pattern for Three.js materials that separates shader logic into testable, composable units.
+
+## Problem
+
+Three.js materials with multiple shader features become monolithic — all shader modifications interleaved in a single class, making code **hard to test in isolation**. You cannot unit-test one shader feature without the entire material setup, and GPU uniform objects (`{ value: T }`) are mutable shared state that easily breaks when accessed from multiple places.
+
+## Solution: Testable Separation of Concerns
+
+The Material Enhancer pattern splits material logic into three layers, each testable independently:
+
+| Layer       | What it holds                                       | Testability benefit                           |
+| ----------- | --------------------------------------------------- | --------------------------------------------- |
+| **State**   | Immutable config snapshot (replaced on each update) | Assert state transitions with simple equality |
+| **Refs**    | Mutable `{ value: T }` uniform objects for the GPU  | Hidden in closure — cannot leak into tests    |
+| **Mutates** | Functions that sync refs from state                 | Test ref-syncing logic without a real shader  |
+
+The key insight: **state and refs serve different purposes**. State is a clean, serializable snapshot for comparison and assertions. Refs are GPU implementation details that must be mutated in place. By hiding refs behind mutates functions, each layer can be tested without the others.
+
+## API
+
+```typescript
+type MaterialEnhancer<M, Props, States, Mutates, Shaders> = {
+  material: M;
+  availableShaders: Shaders;
+  mount(props: Props): void; // Initialize state + refs
+  update(props: Props): void; // Update state, sync refs (no recompilation)
+  transformShader(shader): void; // Inject custom GLSL + assign uniforms
+  states(): States; // Read current state (for assertions)
+  mutates(): Mutates; // Access controlled mutation functions
+  programCacheKey(): string; // Cache key for shader define changes
+};
+```
+
+### Lifecycle
+
+```
+1. Create material + enhancer
+2. mount(props)                           → initializes state and refs
+3. material.onBeforeCompile = enhancer.transformShader
+4. Three.js calls transformShader()       → injects GLSL, assigns uniforms
+5. update(props)                          → updates state, syncs refs (no recompilation)
+```
+
+**Constraint**: All methods except `mount()` throw if called before `mount()` (enforced with `invariant`). The factory returns an uninitialized enhancer.
+
+**Note**: `states()` returns the current internal state object. After calling `update()`, call `states()` again to get the latest snapshot.
+
+## Factory Pattern
+
+Enhancers use factory functions. State and refs are closure-private:
+
+```typescript
+function createFeatureEnhancer(material: MeshLambertMaterial) {
+  let state: FeatureState | null = null;
+  let mutates: FeatureMutates | null = null;
+
+  return {
+    material,
+    availableShaders: ["lambert"] as const,
+
+    mount: (props) => {
+      state = {
+        featureEnabled: props.featureEnabled ?? false,
+        intensity: props.intensity ?? 1.0,
+      };
+      mutates = createMutates(); // refs created inside, captured in closure
+      mutates.update(state);
+    },
+
+    update: (props) => {
+      const prev = state.featureEnabled;
+      state = { ...state, ...props };
+      mutates.update(state); // sync refs from new state
+      if (state.featureEnabled !== prev) material.needsUpdate = true;
+    },
+
+    transformShader: (shader) => {
+      if (state.featureEnabled) shader.defines.FEATURE_X = 1;
+      mutates.updateUniforms(shader.uniforms, state);
+    },
+
+    states: () => state,
+    mutates: () => mutates,
+    programCacheKey: () =>
+      JSON.stringify({ featureEnabled: state?.featureEnabled }),
+  };
+}
+```
+
+### Refs Management (inside `createMutates`)
+
+```typescript
+const createMutates = (): FeatureMutates => {
+  const refs = { uIntensity: { value: 1.0 } }; // private to closure
+  return {
+    update: (state) => {
+      refs.uIntensity.value = state.intensity;
+    },
+    updateUniforms: (uniforms, state) => {
+      uniforms.uIntensity = refs.uIntensity;
+    },
+  };
+};
+```
+
+This is the core testability mechanism. Each module can be tested in isolation:
+
+```typescript
+// Test state transitions (state.test.ts)
+const state = updateState({ intensity: 0.5 }, DEFAULT_STATE);
+expect(state.intensity).toBe(0.5);
+
+// Test ref syncing (mutates.test.ts)
+const mutates = createMutates();
+const state = { intensity: 0.7 };
+mutates.update(state);
+const uniforms: Record<string, unknown> = {};
+mutates.updateUniforms(uniforms, state);
+expect((uniforms.uIntensity as { value: number }).value).toBe(0.7);
+
+// Test shader injection (shader.test.ts)
+const mockShader = {
+  defines: {},
+  uniforms: {},
+  vertexShader: "...",
+  fragmentShader: "...",
+};
+transformShader(state, mutates, mockShader);
+expect(mockShader.defines.FEATURE_X).toBe(1);
+```
+
+Each file (`state.ts`, `mutates.ts`, `shader.ts`) has a co-located `.test.ts` file.
+
+### Shader Compatibility Testing
+
+Three.js has some built-in shader types, each with different structure. An enhancer declares which shaders it supports via `availableShaders`. The shared test utility `testShaderCompatibility` automatically generates a test matrix across all supported shaders and prop configurations:
+
+```typescript
+// shader.test.ts
+testShaderCompatibility(
+  "featureEnhancer",
+  (material) => createFeatureEnhancer(material as SupportedMaterial),
+  [
+    { name: "Feature enabled", props: { featureEnabled: true } },
+    { name: "Feature disabled", props: { featureEnabled: false } },
+  ],
+  FEATURE_SHADER_MARKERS,
+);
+```
+
+For each (shader type x props) combination, `testShaderCompatibility` verifies:
+
+1. `mount(props)` + `transformShader()` does not throw
+2. `update(props)` + `transformShader()` does not throw
+3. All declared markers are present in the transformed shader output
+
+This ensures enhancers work correctly across all Three.js shader types without writing repetitive per-shader tests.
+
+## Composition
+
+Enhancers compose by wrapping a base enhancer. Each layer delegates to its base:
+
+```typescript
+function createComposedEnhancer(baseEnhancer) {
+  let state = null,
+    mutates = null;
+  return {
+    mount: (props) => {
+      baseEnhancer.mount(props.base ?? {}); // delegate to base
+      state = createInitialState(props.feature);
+      mutates = createComposedMutates();
+      mutates.update(state);
+    },
+    transformShader: (shader) => {
+      baseEnhancer.transformShader(shader); // base injects first
+      if (state.featureEnabled) shader.defines.FEATURE_Y = 1;
+      mutates.updateUniforms(shader.uniforms, state);
+    },
+    update: (props) => {
+      if (props.base) baseEnhancer.update(props.base);
+      if (props.feature) {
+        const prev = state.featureEnabled;
+        state = updateState(props.feature, state);
+        mutates.update(state);
+        if (state.featureEnabled !== prev) material.needsUpdate = true;
+      }
+    },
+    states: () => ({ base: baseEnhancer.states(), feature: state }),
+    mutates: () => ({ base: baseEnhancer.mutates() }),
+    programCacheKey: () =>
+      baseEnhancer.programCacheKey() +
+      JSON.stringify({ featureEnabled: state?.featureEnabled }),
+  };
+}
+```
+
+## Shader Modification: Replacer vs ShaderReplacer
+
+Two utilities handle shader string manipulation. They serve different roles in the composition chain:
+
+| Aspect                | `Replacer`                            | `ShaderReplacer<Markers>`                           |
+| --------------------- | ------------------------------------- | --------------------------------------------------- |
+| **Used by**           | Base enhancer only                    | Composing enhancers only                            |
+| **Search by**         | Arbitrary string / regex              | Declared markers only (type-safe)                   |
+| **Operations**        | `replace()`, `replaceWithCondition()` | `insertBefore()`, `insertAfter()`, `replaceBlock()` |
+| **Preserves markers** | N/A                                   | Yes — markers remain after every operation          |
+
+### Base enhancer: `Replacer`
+
+The base enhancer is the first in the chain, so there are no markers yet. It uses `Replacer` to replace Three.js `#include` directives with custom GLSL and **places markers** at insertion points for composing enhancers:
+
+```typescript
+// Base enhancer's shader.ts — uses Replacer to build initial shader + place markers
+shader.fragmentShader = createReplacer(shader.fragmentShader).replace(
+  "uniform vec3 diffuse;",
+  `${MARKERS.fragment.UNIFORM_START}
+uniform vec3 diffuse;
+uniform bool uClampToGround;
+${MARKERS.fragment.UNIFORM_END}`,
+).source;
+```
+
+### Composing enhancer: `ShaderReplacer`
+
+Composing enhancers operate on the base enhancer's output, which already contains markers. `ShaderReplacer<Markers>` restricts operations to declared markers at the type level, preventing accidental modifications to arbitrary shader code:
+
+```typescript
+// Composing enhancer's shader.ts — uses ShaderReplacer, restricted to base markers
+shader.fragmentShader = createFeatureShaderReplacer(shader.fragmentShader)
+  .insertAfter(MARKERS.fragment.UNIFORM_END, "uniform float uFoo;")
+  .replaceBlock(
+    {
+      start: MARKERS.fragment.UNIFORM_START,
+      end: MARKERS.fragment.UNIFORM_END,
+    },
+    "uniform float uBar;",
+  ).source;
+```
+
+### Markers
+
+Markers are GLSL comments defined in `markers.ts` and organized by shader stage:
+
+```typescript
+const MARKERS = {
+  vertex: {},
+  fragment: {
+    UNIFORM_START: "// NVR_FEATURE_UNIFORM_START",
+    UNIFORM_END: "// NVR_FEATURE_UNIFORM_END",
+  },
+} as const satisfies ShaderMarkers;
+```
+
+Each base enhancer exposes a typed factory (e.g., `createFeatureShaderReplacer`) that returns a `ShaderReplacer` restricted to its markers. All `ShaderReplacer` operations preserve markers and return `this` for chaining.
+
+## External Refs
+
+Some uniforms (e.g., shared textures) are created externally and passed via props. The enhancer must hold the same `{ value: T }` object reference to receive future external mutations:
+
+```typescript
+setTexture: (texture: UniformValue<Texture | null>) => {
+  refs.uTexture = texture; // assign the ref object, not just the value
+},
+```
+
+## Shader Defines and Recompilation
+
+State properties that affect `#define` flags follow two patterns:
+
+- **Immutable after mount**: Cannot change after initialization (e.g., `useRTE`).
+- **Mutable with recompilation**: Can change; triggers `material.needsUpdate = true` and must be included in `programCacheKey()`.
+
+## Type Conventions
+
+Each enhancer defines four types:
+
+```typescript
+type FeatureProps = { ... };                         // Input (public)
+type FeatureState = Readonly<{ ... }>;               // Immutable snapshot (public)
+type FeatureRefs = { ... };                          // Uniform references (internal)
+type FeatureUniforms = Partial<FeatureRefs>;         // Uniform types (internal)
+type FeatureMutates = Mutates<FeatureState, FeatureUniforms, { ... }>; // Mutation interface (public)
+```
+
+## File Organization
+
+```
+/featureEnhancer
+  index.ts    - Factory function + public type re-exports
+  types.ts    - Props, State, Refs, Uniforms, Mutates type definitions
+  mutates.ts  - createMutates, default ref values (use structuredClone for defaults)
+  state.ts    - State transitions and default values
+  shader.ts   - transformShader logic
+  material.ts - Supported material types and shader compatibility
+  markers.ts  - Marker constants and typed ShaderReplacer factory
+```
+
+Each module has a co-located `*.test.ts` file (e.g., `state.test.ts`, `mutates.test.ts`, `shader.test.ts`) if it has a logic.