@navaramap/three 0.0.5 → 0.0.6

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@navaramap/three",
   "type": "module",
-  "version": "0.0.5",
+  "version": "0.0.6",
   "main": "dist/index.umd.cjs",
   "module": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -30,13 +30,13 @@
     "astronomy-engine": "2.1.19",
     "stats.js": "0.17.0",
     "three-stdlib": "2.36.1",
-    "@navaramap/core": "0.0.5",
-    "@navaramap/engine": "0.0.5",
-    "@navaramap/engine-api": "0.0.5",
-    "@navaramap/font": "0.0.5",
-    "@navaramap/three-api": "0.0.5",
-    "@navaramap/three-csm": "0.0.5",
-    "@navaramap/worker": "0.0.5"
+    "@navaramap/engine-api": "0.0.6",
+    "@navaramap/engine": "0.0.6",
+    "@navaramap/font": "0.0.6",
+    "@navaramap/three-api": "0.0.6",
+    "@navaramap/three-csm": "0.0.6",
+    "@navaramap/core": "0.0.6",
+    "@navaramap/worker": "0.0.6"
   },
   "devDependencies": {
     "@playwright/test": "1.61.1",
@@ -71,10 +71,10 @@
     "tweakpane": "4.0.5",
     "vite-plugin-glsl": "1.6.0",
     "vite-plugin-static-copy": "4.1.1",
-    "@navaramap/three-default-descs": "0.0.5",
-    "@navaramap/three-plugins": "0.0.5",
-    "@navaramap/three-react": "0.0.5",
-    "@navaramap/three-default-plugin": "0.0.5"
+    "@navaramap/three-default-descs": "0.0.6",
+    "@navaramap/three-default-plugin": "0.0.6",
+    "@navaramap/three-react": "0.0.6",
+    "@navaramap/three-plugins": "0.0.6"
   },
   "scripts": {
     "start": "vite",

package/src/core/DescRegistry.ts

@@ -80,9 +80,10 @@ export abstract class DescRegistry<
   }
 
   /**
-   * Get constructor by name (protected method for subclasses)
+   * Get constructor by name. Public so `ViewContext.findLight`/`findMesh`
+   * can resolve a registered key to its descriptor class.
    */
-  protected getConstructor(name: string): TConstructor | undefined {
+  getConstructor(name: string): TConstructor | undefined {
     return this.registry.get(name);
   }
 }

package/src/core/EffectDesc.ts

@@ -6,6 +6,7 @@ import invariant from "tiny-invariant";
 
 import { Pass } from "../effects";
 import type ThreeView from "../index";
+import type { GBufferName } from "../material/gbufferLayout";
 
 import {
   BaseDesc,
@@ -194,6 +195,15 @@ export abstract class EffectDesc<
   static insertBefore?: string[];
   /** Set to `true` to allow multiple instances of this effect in the pipeline. */
   static allowDuplication?: boolean;
+  /**
+   * Optional G-buffer attachments this effect reads. The view derives its
+   * G-buffer configuration as the union of these across active effects:
+   * adding an effect allocates what it needs, removing the last effect that
+   * needs a buffer releases it. Changing the configuration reallocates
+   * attachments and recompiles shaders, so add effects once and tune them
+   * via `update()` instead of re-adding.
+   */
+  static requiredBuffers?: readonly GBufferName[];
 
   private instanceId: string;
 

package/src/core/EffectDescRegistry.ts

@@ -1,4 +1,5 @@
 import type ThreeView from "../index";
+import type { GBufferName } from "../material/gbufferLayout";
 
 import { DescRegistry } from "./DescRegistry";
 import { EffectDesc, type EffectConfig } from "./EffectDesc";
@@ -28,4 +29,17 @@ export class EffectDescRegistry extends DescRegistry<
   findEffectType(config: Record<string, unknown>): string | null {
     return this.findTypeFromConfig(config);
   }
+
+  /**
+   * Optional G-buffer attachments the effect type declares via the
+   * `requiredBuffers` static (empty when it declares none).
+   */
+  getRequiredBuffers(effectType: string): readonly GBufferName[] {
+    const EffectClass = this.getConstructor(effectType) as
+      | (EffectDescConstructor & {
+          requiredBuffers?: readonly GBufferName[];
+        })
+      | undefined;
+    return EffectClass?.requiredBuffers ?? [];
+  }
 }

package/src/core/MeshDesc.ts

@@ -1,8 +1,9 @@
 import type { BaseEventMap, XYZ } from "@navaramap/core";
-import { Euler, Matrix4, Object3D, Vector3 } from "three";
+import { Euler, Matrix4, Object3D, Vector3, type Mesh } from "three";
 import invariant from "tiny-invariant";
 
 import type ThreeView from "../index";
+import { applyLitOption } from "../material";
 import type { Scenes } from "../scene";
 
 import {
@@ -44,11 +45,18 @@ export type MeshConfig = {
    * Disables Three.js's auto matrix-world update.
    */
   matrixWorld?: Matrix4;
+  /**
+   * Lighting override for every material of the mesh. `false` outputs albedo
+   * only, while normals and the shadow G-buffer keep being written.
+   * `undefined` follows `view.lit` — passing it to `update()` resets a mesh
+   * to inheriting again.
+   */
+  lit?: boolean;
 } & BaseDescConfig;
 
 export type MeshUpdate = Pick<
   MeshConfig,
-  "position" | "scale" | "rotation" | "matrix" | "matrixWorld"
+  "position" | "scale" | "rotation" | "matrix" | "matrixWorld" | "lit"
 > &
   BaseDescConfigUpdate;
 
@@ -214,6 +222,8 @@ export abstract class MeshDesc<
   public rotation?: XYZ;
   public matrix?: Matrix4;
   public matrixWorld?: Matrix4;
+  /** Three-state `lit` override (see {@link MeshConfig.lit}). */
+  public lit?: boolean;
   private prevPassKey?: PassKey;
 
   constructor(view: ThreeView, ctx: ViewContext, config?: Config) {
@@ -224,6 +234,25 @@ export abstract class MeshDesc<
     this.rotation = resolvedConfig.rotation;
     this.matrix = resolvedConfig.matrix;
     this.matrixWorld = resolvedConfig.matrixWorld;
+    this.lit = resolvedConfig.lit;
+  }
+
+  /**
+   * Applies {@link lit} to every material under the mesh. Subclasses that
+   * attach materials asynchronously (glTF) call it again once they exist.
+   */
+  protected applyLit(): void {
+    const root = this.raw;
+    if (!root) return;
+    root.traverse((object) => {
+      const material = (object as Partial<Mesh>).material;
+      if (!material) return;
+      if (Array.isArray(material)) {
+        for (const m of material) applyLitOption(m, this.lit);
+      } else {
+        applyLitOption(material, this.lit);
+      }
+    });
   }
 
   /**
@@ -272,6 +301,7 @@ export abstract class MeshDesc<
     invariant(this.raw);
 
     this.applyTransform();
+    this.applyLit();
 
     this._instance.visible = this.visible;
 
@@ -391,6 +421,12 @@ export abstract class MeshDesc<
     if (updates.scale !== undefined) this.scale = updates.scale;
     if (updates.rotation !== undefined) this.rotation = updates.rotation;
 
+    // Key presence, not value: `!== undefined` could not express a reset.
+    if ("lit" in updates) {
+      this.lit = updates.lit;
+      this.applyLit();
+    }
+
     if (spatialChanged) {
       // With a frame present, the effective transform depends on the
       // combination of all stored fields — recompose the whole thing.
@@ -428,6 +464,7 @@ export abstract class MeshDesc<
     }
     this.prevPassKey = nextPassKey;
     this.addToScene(nextPassKey);
+    this.ctx.emit("meshPassKeyChanged");
   }
 
   onDestroy(): void {

package/src/core/MeshDescWithSelectiveEffect.ts

@@ -39,6 +39,10 @@ export abstract class MeshDescWithSelectiveEffect<
     this.onPassKeyChange();
   };
 
+  private _onGBufferChanged = () => {
+    this.onPassKeyChange();
+  };
+
   constructor(view: ThreeView, ctx: ViewContext, config?: Config) {
     const resolvedConfig = config ?? ({} as Config);
     super(view, ctx, resolvedConfig);
@@ -51,11 +55,16 @@ export abstract class MeshDescWithSelectiveEffect<
     // 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";
     }
+    // Likewise while any optional G-buffer is allocated: outside the MRT pass
+    // the mesh leaves the G-buffer holding what lies behind it, and effects
+    // reading those buffers shade "through" it.
+    if (Object.values(this.view.buffers).some(Boolean)) {
+      return "mrt";
+    }
+    // Otherwise MRT participation is pure overhead.
     return super.getPassKey();
   }
 
@@ -67,6 +76,8 @@ export abstract class MeshDescWithSelectiveEffect<
 
     // Recompute mask when slot assignments change (effect added/removed)
     this.ctx.on("effectSlotsChanged", this._onSlotsChanged);
+    // G-buffer allocation changes also flip getPassKey() (mrt <-> opaque).
+    this.ctx.on("gbufferChanged", this._onGBufferChanged);
   }
 
   override onUpdateConfig(updates: UpdateConfig): void {
@@ -122,6 +133,7 @@ export abstract class MeshDescWithSelectiveEffect<
 
     // Unsubscribe from slot changes
     this.ctx.off("effectSlotsChanged", this._onSlotsChanged);
+    this.ctx.off("gbufferChanged", this._onGBufferChanged);
 
     super.onDestroy();
   }

package/src/core/ViewContext.ts

@@ -2,17 +2,22 @@ import { EventHandler } from "@navaramap/core";
 import type { Core } from "@navaramap/engine";
 import type { ConcurrencyManager } from "@navaramap/worker";
 import type { Pass as PostProcessingPass } from "postprocessing";
-import type { Material, Object3D, WebGLRenderer } from "three";
+import type { Material, Object3D, Texture, WebGLRenderer } from "three";
 import invariant from "tiny-invariant";
 
 import type { LayersManager } from "../layersManager";
+import { type ResolvedGBufferOptions } from "../material/gbufferLayout";
 import type { PickableMesh } from "../mesh/pickableMesh";
 import type { RenderPassOrchestrator } from "../orchestrators";
 import type { CustomRenderPass } from "../passes";
 import type { Scenes } from "../scene";
 import type { MeshCache } from "../type";
 
-import type { EffectHandle } from "./BaseHandle";
+import type { EffectHandle, LightHandle, MeshHandle } from "./BaseHandle";
+import type { EffectDesc } from "./EffectDesc";
+import type { LightDesc } from "./LightDesc";
+import type { MeshDesc } from "./MeshDesc";
+import type { Registries } from "./Registries";
 import { SelectiveEffectRegistry } from "./SelectiveEffectRegistry";
 
 type ViewContextEvents = {
@@ -31,6 +36,18 @@ type ViewContextEvents = {
    * Listeners should recompute effectIdsMask to stay in sync.
    */
   effectSlotsChanged: () => void;
+  /**
+   * Emitted when the derived G-buffer configuration changes. Meshes re-evaluate
+   * their pass placement: outside the MRT pass they would leave the G-buffer
+   * holding whatever lies behind them.
+   */
+  gbufferChanged: () => void;
+  /**
+   * Emitted when a mesh moves between render scenes. The view re-derives the
+   * buffer configuration from it: draped meshes need the globe normal but,
+   * not being effects, cannot declare `requiredBuffers` themselves.
+   */
+  meshPassKeyChanged: () => void;
 };
 
 /**
@@ -49,6 +66,7 @@ type ViewContextEvents = {
 export class ViewContext extends EventHandler<ViewContextEvents> {
   private _selectiveEffectRegistry: SelectiveEffectRegistry;
   private _renderPass?: CustomRenderPass;
+  private _registries?: Registries;
 
   constructor(
     /** Scene containers for different rendering passes. */
@@ -133,6 +151,26 @@ export class ViewContext extends EventHandler<ViewContextEvents> {
     this._renderPass = renderPass;
   }
 
+  /** @internal */
+  _setRegistries(registries: Registries) {
+    this._registries = registries;
+  }
+
+  /**
+   * @internal
+   * No-op until the pass exists — it reads the view's configuration at
+   * creation time.
+   */
+  _setGBufferOptions(buffers: ResolvedGBufferOptions): void {
+    this._renderPass?.setBuffers(buffers);
+    this.emit("gbufferChanged");
+  }
+
+  /** @internal No-op until the pass exists (see {@link _setGBufferOptions}). */
+  _setLit(lit: boolean): void {
+    this._renderPass?.setLit(lit);
+  }
+
   /**
    * Gets the globe depth texture for post-processing effects.
    */
@@ -162,23 +200,47 @@ export class ViewContext extends EventHandler<ViewContextEvents> {
    */
   getNormalTexture() {
     invariant(this._renderPass, "CustomRenderPass isn't initialized yet.");
-    return this._renderPass.gbufferRenderTarget.textures[1];
+    const index = this._renderPass.textureIndex.normal;
+    return index === undefined
+      ? undefined
+      : this._renderPass.gbufferRenderTarget.textures[index];
   }
 
   /**
    * Gets the effect IDs texture from the G-buffer.
+   * `undefined` when the view disabled `buffers.selectiveEffect`.
    */
-  getEffectIdsTexture() {
+  getEffectIdsTexture(): Texture | undefined {
     invariant(this._renderPass, "CustomRenderPass isn't initialized yet.");
-    return this._renderPass.gbufferRenderTarget.textures[2];
+    const index = this._renderPass.textureIndex.effectIds;
+    return index === undefined
+      ? undefined
+      : this._renderPass.gbufferRenderTarget.textures[index];
   }
 
   /**
    * Gets the emissive texture from the G-buffer.
+   * `undefined` when the view disabled `buffers.emissive`.
+   */
+  getEmissiveTexture(): Texture | undefined {
+    invariant(this._renderPass, "CustomRenderPass isn't initialized yet.");
+    const index = this._renderPass.textureIndex.emissive;
+    return index === undefined
+      ? undefined
+      : this._renderPass.gbufferRenderTarget.textures[index];
+  }
+
+  /**
+   * Gets the shadow texture (R=shadow amount, 0=lit..1=fully shadowed) from
+   * the G-buffer. `undefined` unless an active effect requires the `shadow`
+   * buffer.
    */
-  getEmissiveTexture() {
+  getShadowTexture(): Texture | undefined {
     invariant(this._renderPass, "CustomRenderPass isn't initialized yet.");
-    return this._renderPass.gbufferRenderTarget.textures[3];
+    const index = this._renderPass.textureIndex.shadow;
+    return index === undefined
+      ? undefined
+      : this._renderPass.gbufferRenderTarget.textures[index];
   }
 
   // --- Descriptor query ---
@@ -188,6 +250,53 @@ export class ViewContext extends EventHandler<ViewContextEvents> {
     return this.layersManager.getEffectDescs();
   }
 
+  /** @internal Iterate over all registered light descriptors. */
+  _getLights(): Generator<LightHandle> {
+    return this.layersManager.getLightDescs();
+  }
+
+  /** @internal Iterate over all registered mesh descriptors. */
+  _getMeshes(): Generator<MeshHandle> {
+    return this.layersManager.getMeshDescs();
+  }
+
+  /**
+   * Finds an active effect descriptor by its `key` (e.g. `"mrt"`,
+   * `"selectiveBloom"`). Returns the first match, or `undefined`.
+   */
+  findEffect<T extends EffectDesc = EffectDesc>(key: string): T | undefined {
+    for (const handle of this._getEffects()) {
+      if (handle.ref.getKey() === key) return handle.ref as T;
+    }
+    return undefined;
+  }
+
+  /**
+   * Finds the first active light descriptor registered under `key` (e.g.
+   * `"sun"`), for inheriting the scene's lighting in a custom effect.
+   */
+  findLight<T extends LightDesc = LightDesc>(key: string): T | undefined {
+    const LightClass = this._registries?.light.getConstructor(key);
+    if (!LightClass) return undefined;
+    for (const handle of this._getLights()) {
+      if (handle.ref instanceof LightClass) return handle.ref as T;
+    }
+    return undefined;
+  }
+
+  /**
+   * Finds an active mesh descriptor by its registered key (e.g. `"box"`,
+   * `"gltfModel"`). Returns the first match, or `undefined`.
+   */
+  findMesh<T extends MeshDesc = MeshDesc>(key: string): T | undefined {
+    const MeshClass = this._registries?.mesh.getConstructor(key);
+    if (!MeshClass) return undefined;
+    for (const handle of this._getMeshes()) {
+      if (handle.ref instanceof MeshClass) return handle.ref as T;
+    }
+    return undefined;
+  }
+
   /**
    * Register a material for CSM shadow rendering.
    * @experimental This API may change or be removed in future versions.

package/src/device.ts

@@ -53,8 +53,10 @@ const MOBILE_MAX_PIXEL_RATIO = 1.0;
 /**
  * Default pixel-ratio cap applied on every mobile device (without opting into
  * `mobileOptimization`). The fixed screen-sized render-target stack (composer
- * buffers, gbuffer MRT, depth textures — ~100 B/px, counted by the ledger as
- * `fixed_gpu_bytes`) grows quadratically with the drawing-buffer size: at
+ * buffers, gbuffer MRT and depth textures, counted by the ledger as
+ * `fixed_gpu_bytes`) grows quadratically with the drawing-buffer size — and
+ * with the derived `buffers` configuration, which starts at two attachments
+ * (color + normal) and grows as effects declare `requiredBuffers`: at
  * DPR 3 it alone can exceed a mobile tile-cache budget and permanently close
  * the load gate. Above DPR 2 the sharpness gain is marginal on phone screens.
  */

package/src/index.ts

@@ -108,7 +108,14 @@ import {
 import { FinalCopyEffectDesc } from "./layers/effect/FinalCopyEffectDesc";
 import { LayersManager } from "./layersManager";
 import { disposeTexture } from "./loaders";
-import { overrideMaterialsForMRT } from "./material";
+import {
+  overrideMaterialsForMRT,
+  GBUFFER_ATTACHMENT_NAMES,
+  resolveGBufferOptions,
+  unionGBufferRequirements,
+  type GBufferName,
+  type ResolvedGBufferOptions,
+} from "./material";
 import type { TileMesh } from "./mesh/tile";
 import { RenderPassOrchestrator } from "./orchestrators/RenderPassOrchestrator";
 import { PickHelper } from "./pick/pickHelper";
@@ -245,11 +252,6 @@ export type WorkerMemoryStats = {
   fontWorker: FontWorkerMemoryStats | undefined;
 };
 
-// NOTE:
-// This overrides all materials to output a normal buffer, meaning Navara operates using MRT (Multiple Render Targets).
-// Currently, Navara requires two buffers, so your shader must output them.
-overrideMaterialsForMRT();
-
 /**
  * Configuration options for initializing ThreeView.
  */
@@ -792,6 +794,15 @@ export default class ThreeView<
   /** Built-in attribution UI; unset when disabled or in a worker (no DOM). */
   private _attribution?: AttributionPlugin;
 
+  /**
+   * Derived G-buffer attachment configuration — the union of the
+   * `requiredBuffers` declared by the active effects.
+   */
+  private _buffers: ResolvedGBufferOptions;
+
+  /** Scene-level default of the `lit` material option (see {@link lit}). */
+  private _lit = true;
+
   private pixelRatioMatchedMedia?: MediaQueryList;
 
   private fixedGpuBytesReportScheduled = false;
@@ -808,9 +819,43 @@ export default class ThreeView<
     return this._attribution;
   }
 
+  /**
+   * Buffers currently allocated. Not configurable — derived as the union of
+   * the active effects' `requiredBuffers`. All but `globeNormal` are G-buffer
+   * attachments.
+   */
+  get buffers(): ResolvedGBufferOptions {
+    return this._buffers;
+  }
+
+  /**
+   * Scene-level default of the `lit` material option. `false` makes every
+   * material without an explicit `lit` output plain albedo, while normals and
+   * the shadow G-buffer keep being written – the input for deferred lighting.
+   * Toggling recompiles the affected shaders once.
+   * @defaultValue true
+   */
+  get lit(): boolean {
+    return this._lit;
+  }
+
+  set lit(value: boolean) {
+    if (this._lit === value) return;
+    this._lit = value;
+    this.viewContext._setLit(value);
+    this.forceUpdate();
+  }
+
   constructor(options: Options = {}) {
     super();
 
+    // Patches the global ShaderLib, but the injected source is
+    // view-independent (defines carry the layout). Here rather than at module
+    // import so importing the library has no side effects.
+    overrideMaterialsForMRT();
+
+    this._buffers = resolveGBufferOptions();
+
     if (!options.canvas) {
       const div = document.createElement("div");
       div.id = "navara-root";
@@ -1412,6 +1457,8 @@ export default class ThreeView<
       this._meshes,
     );
     this.registries = new Registries(this, this.viewContext);
+    this.viewContext.on("meshPassKeyChanged", this._syncGBuffers);
+    this.viewContext._setRegistries(this.registries);
     this.eventContext = new EventContext({
       eventManager: this._eventManager,
       scenes: this._scenes,
@@ -2039,9 +2086,26 @@ export default class ThreeView<
       throw new UnknownTypeError("effect", config);
     }
 
+    // Reject the effect while nothing is created yet if its required
+    // G-buffers would exceed the device's MRT attachment limit
+    // (gl.MAX_DRAW_BUFFERS – spec minimum 4, nearly all devices expose 8).
+    this._assertGBufferCapacity(effectType);
+
     // Create effect descriptor instance
     const effectDesc = this.registries.effect.create(effectType, config);
 
+    const l = new EffectHandle(effectDesc);
+
+    // Store the effect descriptor
+    this.layersManager.add(l);
+
+    // Allocate before `onCreate()`: `createPass()` reads the buffers this
+    // effect declared, so they have to exist by then. Reallocates attachments
+    // and recompiles shaders when the derived configuration actually changes,
+    // so tune effects via `update()` rather than re-adding them.
+    this._syncGBuffers();
+    l.on("deleted", this._syncGBuffers);
+
     // Initialize the effect
     effectDesc.onCreate();
 
@@ -2053,15 +2117,63 @@ export default class ThreeView<
     // Trigger re-render
     effectDesc.on("needsUpdate", this.forceUpdate);
 
-    const l = new EffectHandle(effectDesc);
-
-    // Store the effect descriptor
-    this.layersManager.add(l);
-
     // Return handle for imperative access
     return l as EffectHandle<L>;
   }
 
+  /**
+   * Re-derives the G-buffer configuration from the union of the active
+   * effects' `requiredBuffers` and applies it to the MRT pass when changed.
+   */
+  private _syncGBuffers = (): void => {
+    const requirements: (readonly GBufferName[])[] = [];
+    for (const handle of this.layersManager.getEffectDescs()) {
+      const EffectClass = handle.ref.constructor as {
+        requiredBuffers?: readonly GBufferName[];
+      };
+      if (EffectClass.requiredBuffers) {
+        requirements.push(EffectClass.requiredBuffers);
+      }
+    }
+    // Draped meshes are not effects, so they cannot declare this themselves:
+    // they read the terrain normal through the globe-normal copy.
+    if (this._scenes.draped.children.length > 0) {
+      requirements.push(["globeNormal"]);
+    }
+    this._buffers = unionGBufferRequirements(requirements);
+    this.viewContext._setGBufferOptions(this._buffers);
+  };
+
+  /**
+   * Throws when enabling `effectType`'s required G-buffers would push the
+   * attachment count (color + normal + optional buffers) past the device's
+   * `MAX_DRAW_BUFFERS` limit.
+   */
+  private _assertGBufferCapacity(effectType: string): void {
+    const required = this.registries.effect.getRequiredBuffers(effectType);
+    if (required.length === 0) return;
+    const prospective = unionGBufferRequirements([
+      (Object.keys(this._buffers) as GBufferName[]).filter(
+        (name) => this._buffers[name],
+      ),
+      required,
+    ]);
+    const attachmentCount =
+      2 + GBUFFER_ATTACHMENT_NAMES.filter((name) => prospective[name]).length;
+    // Navara requires WebGL2 (MRT), so the context is always WebGL2.
+    const gl = this.viewContext
+      .getRenderer()
+      .getContext() as WebGL2RenderingContext;
+    const maxDrawBuffers = gl.getParameter(gl.MAX_DRAW_BUFFERS) as number;
+    if (attachmentCount > maxDrawBuffers) {
+      throw new Error(
+        `The "${effectType}" effect requires G-buffers [${required.join(", ")}], ` +
+          `but the resulting ${attachmentCount} MRT attachments exceed this ` +
+          `device's MAX_DRAW_BUFFERS (${maxDrawBuffers}).`,
+      );
+    }
+  }
+
   /**
    * Finds a resource layer by its ID.
    * Only returns resource layers added via `addLayer()` (not mesh, light, or

package/src/layer.ts

@@ -51,12 +51,14 @@ export type LayerEvent = {
  *
  * @example
  * ```typescript
- * // Add a GeoJSON layer
- * const geoJsonLayer = view.addLayer({
+ * // Register a GeoJSON source, then render it with a vector layer
+ * const geoJsonSource = view.addSource({
  *   type: "geojson",
- *   data: {
- *     url: "https://example.com/data.geojson",
- *   },
+ *   url: "https://example.com/data.geojson",
+ * });
+ * const geoJsonLayer = view.addLayer({
+ *   type: "vector",
+ *   source: geoJsonSource,
  *   point: { color: 0xff0000 }
  * });
  *