@navaramap/three 0.0.5 → 0.0.6

package/src/layers/effect/MRTPassEffectDesc.ts

@@ -49,6 +49,8 @@ export class MRTPassEffectDesc extends EffectDesc<
       this.view.globe,
       {
         debugNormal: !!this.config.mrt?.debugNormal,
+        buffers: this.view.buffers,
+        lit: this.view.lit,
       },
     );
 
@@ -56,15 +58,44 @@ export class MRTPassEffectDesc extends EffectDesc<
   }
 
   get normalBuffer(): Texture | undefined {
-    return this.raw?.gbufferRenderTarget.textures[1];
+    const pass = this.raw;
+    const index = pass?.textureIndex.normal;
+    return index === undefined
+      ? undefined
+      : pass?.gbufferRenderTarget.textures[index];
   }
 
+  /**
+   * Selective-effect bitmask buffer (R=bitmask).
+   * `undefined` when the view disabled `buffers.selectiveEffect`.
+   */
   get effectIdsBuffer(): Texture | undefined {
-    return this.raw?.gbufferRenderTarget.textures[2];
+    const index = this.raw?.textureIndex.effectIds;
+    return index === undefined
+      ? undefined
+      : this.raw?.gbufferRenderTarget.textures[index];
   }
 
+  /**
+   * Emissive RGB buffer (HDR).
+   * `undefined` when the view disabled `buffers.emissive`.
+   */
   get emissiveBuffer(): Texture | undefined {
-    return this.raw?.gbufferRenderTarget.textures[3];
+    const index = this.raw?.textureIndex.emissive;
+    return index === undefined
+      ? undefined
+      : this.raw?.gbufferRenderTarget.textures[index];
+  }
+
+  /**
+   * Shadow buffer (R=shadow amount, 0=lit..1=fully shadowed).
+   * `undefined` unless an active effect requires the `shadow` buffer.
+   */
+  get shadowBuffer(): Texture | undefined {
+    const index = this.raw?.textureIndex.shadow;
+    return index === undefined
+      ? undefined
+      : this.raw?.gbufferRenderTarget.textures[index];
   }
 
   get depthBuffer(): Texture | undefined {

package/src/layers/effect/SelectiveEffectDesc.ts

@@ -7,6 +7,7 @@ import {
 } from "../../core/EffectDesc";
 import type { ViewContext } from "../../core/ViewContext";
 import type ThreeView from "../../index";
+import type { GBufferName } from "../../material/gbufferLayout";
 
 import type { MRTPassEffectDesc } from "./MRTPassEffectDesc";
 
@@ -42,6 +43,13 @@ export abstract class SelectiveEffectDesc<
   Config extends SelectiveEffectConfig = SelectiveEffectConfig,
   UpdateConfig extends SelectiveEffectUpdate = SelectiveEffectUpdate,
 > extends EffectDesc<Config, UpdateConfig> {
+  /**
+   * Buffer-based selective effects read the effectIds bitmask buffer.
+   * Subclasses that also read the emissive buffer (e.g. bloom) override this
+   * with `["selectiveEffect", "emissive"]`.
+   */
+  static requiredBuffers: readonly GBufferName[] = ["selectiveEffect"];
+
   protected config: Config;
 
   constructor(view: ThreeView, ctx: ViewContext, config: Config) {
@@ -94,13 +102,13 @@ export abstract class SelectiveEffectDesc<
   // Buffer accessors — used by subclass passes to read MRT data
   // ---------------------------------------------------------------------------
 
-  /** Emissive RGB buffer (MRT attachment[3]). */
+  /** Emissive RGB buffer. */
   public getEmissiveBuffer(): Texture | null {
     const mrtDesc = this.find<MRTPassEffectDesc>("mrt");
     return mrtDesc?.emissiveBuffer ?? null;
   }
 
-  /** EffectIds bitmask buffer (MRT attachment[2]). NearestFilter, discrete data. */
+  /** EffectIds bitmask buffer (R=bitmask). NearestFilter, discrete data. */
   public getEffectIdsBuffer(): Texture | null {
     const mrtDesc = this.find<MRTPassEffectDesc>("mrt");
     return mrtDesc?.effectIdsBuffer ?? null;

package/src/layers/effect/TransparentPassEffectDesc.ts

@@ -52,11 +52,12 @@ export class TransparentPassEffectDesc extends EffectDesc<
   }
 
   update(_time: number): void {
-    // Sync lights
-    let i = 0;
+    // Sync each clone from its source by id — the children order of
+    // scenes.light is not stable (e.g. the CSM lights are kept first for
+    // shadow-index ordering), so an index-based pairing would copy across
+    // mismatched light types.
     for (const child of this.ctx.scenes.light.children) {
-      this.light.children[i].copy(child, true);
-      i++;
+      this.lightsSyncMap.get(child.id)?.copy(child, true);
     }
   }
 }

package/src/layersManager.ts

@@ -1,4 +1,12 @@
-import { EffectDesc, BaseHandle, EffectHandle } from "./core";
+import {
+  EffectDesc,
+  BaseHandle,
+  EffectHandle,
+  LightDesc,
+  LightHandle,
+  MeshDesc,
+  MeshHandle,
+} from "./core";
 import { Layer, type LayerEvent } from "./layer";
 
 export class LayersManager {
@@ -60,4 +68,27 @@ export class LayersManager {
       yield handle as EffectHandle;
     }
   }
+
+  *getLightDescs(): Generator<LightHandle> {
+    for (const handle of this.layers.values()) {
+      if (!(handle instanceof BaseHandle)) continue;
+
+      const desc = handle.ref;
+      if (!(desc instanceof LightDesc)) continue;
+
+      yield handle as LightHandle;
+    }
+  }
+
+  *getMeshDescs(): Generator<MeshHandle> {
+    for (const handle of this.layers.values()) {
+      if (!(handle instanceof BaseHandle)) continue;
+
+      const desc = handle.ref;
+      // Covers instanced meshes too — InstancedMeshDesc extends MeshDesc.
+      if (!(desc instanceof MeshDesc)) continue;
+
+      yield handle as MeshHandle;
+    }
+  }
 }

package/src/material/enhancer/model/modelBaseEnhancer/shader.ts

@@ -12,6 +12,7 @@ import SpecularParsFragment from "@shaders/glsl/chunks/spucular_pars_fragment.gl
 import type { WebGLProgramParametersWithUniforms } from "three";
 
 import { createReplacer } from "../../../../utils";
+import { GBUFFER_NORMAL_WRITE_PHYSICAL } from "../../../gbufferLayout";
 
 import { MODEL_BASE_SHADER_MARKERS } from "./markers";
 import type { SupportedMaterial } from "./material";
@@ -151,12 +152,12 @@ if (nvr_uPickable > 0.0 && diffuseColor.a > 0.0) {
 `,
     )
     .replace(
-      "normalBuffer = vec4(packNormalToVec2(normal), metalnessFactor, roughnessFactor)",
+      GBUFFER_NORMAL_WRITE_PHYSICAL,
       `
 ${MODEL_BASE_SHADER_MARKERS.fragment.FINAL_NORMAL_START}
 vec3 finalNormal = normal;
 ${MODEL_BASE_SHADER_MARKERS.fragment.FINAL_NORMAL_END}
-normalBuffer = vec4(packNormalToVec2(finalNormal), metalnessFactor, roughnessFactor)
+GBUFFER_WRITE_NORMAL(finalNormal, metalnessFactor, roughnessFactor)
 `,
     ).source;
 };

package/src/material/enhancer/polygon/polygonBaseEnhancer/index.ts

@@ -71,9 +71,6 @@ export function createPolygonBaseEnhancer(
       if (props.batchDataTexture) {
         mutates.setBatchDataTexture(props.batchDataTexture);
       }
-      if (props.globeNormalTexture) {
-        mutates.setGlobeNormalTexture(props.globeNormalTexture);
-      }
       updateMaterialProps(material, mergedProps);
     },
 
@@ -85,9 +82,6 @@ export function createPolygonBaseEnhancer(
       if (props.batchDataTexture) {
         mutates.setBatchDataTexture(props.batchDataTexture);
       }
-      if (props.globeNormalTexture) {
-        mutates.setGlobeNormalTexture(props.globeNormalTexture);
-      }
       updateMaterialProps(material, props);
     },
 

package/src/material/enhancer/polygon/polygonBaseEnhancer/mutates.ts

@@ -60,9 +60,6 @@ export const createBaseMutates = (useRTE: boolean): PolygonBaseMutates => {
     },
     updateUniforms: (uniforms, state) => {
       // Assign core uniform refs to shader.uniforms
-      if (refs.uGlobeNormal) {
-        uniforms.uGlobeNormal = refs.uGlobeNormal;
-      }
       uniforms.nvr_uPickable = refs.nvr_uPickable;
       uniforms.uEffectIdsMask = refs.uEffectIdsMask;
       uniforms.uEmissiveIntensity = refs.uEmissiveIntensity;
@@ -100,9 +97,6 @@ export const createBaseMutates = (useRTE: boolean): PolygonBaseMutates => {
     setBatchDataTexture: (texture: UniformValue<Texture | null>): void => {
       refs.batchDataTexture = texture;
     },
-    setGlobeNormalTexture: (texture: UniformValue<Texture | null>): void => {
-      refs.uGlobeNormal = texture;
-    },
     updateRteUniforms: (
       modelViewMatrixRTE: Matrix4,
       cameraPositionHigh: Vector3,

package/src/material/enhancer/polygon/polygonBaseEnhancer/shader.ts

@@ -21,6 +21,7 @@ import { ShaderChunk } from "three";
 import type { WebGLProgramParametersWithUniforms } from "three";
 
 import { createReplacer } from "../../../../utils";
+import { GBUFFER_NORMAL_WRITE_BASIC } from "../../../gbufferLayout";
 
 import { POLYGON_BASE_SHADER_MARKERS } from "./markers";
 import type { SupportedMaterial } from "./material";
@@ -156,7 +157,6 @@ vPosition = (modelMatrix * vec4(transformed, 1.0)).xyz;
 ${POLYGON_BASE_SHADER_MARKERS.fragment.UNIFORM_START}
 uniform vec3 diffuse;
 uniform bool uClampToGround;
-uniform sampler2D uGlobeNormal;
 uniform float nvr_uPickable;
 // uEffectIdsMask is declared by overrideMaterialsForMRT (#ifdef USE_SELECTIVE_EFFECT block)
 uniform bool uIsTexturized;
@@ -205,13 +205,7 @@ ${POLYGON_BASE_SHADER_MARKERS.fragment.NORMAL_START}
 vec3 origNormal = vec3(normal);
 vec3 specular;
 
-if(uClampToGround) {
-  vec2 uv = gl_FragCoord.xy / vec2(textureSize(uGlobeNormal, 0));
-  vec3 mapN = unpackVec2ToNormal(texture2D( uGlobeNormal, uv ).xy);
-  normal = normalize( mapN );
-} else {
- #include <normal_fragment_maps>
-}
+#include <normal_fragment_maps>
 
 ${POLYGON_BASE_SHADER_MARKERS.fragment.NORMAL_END}
 `,
@@ -242,12 +236,12 @@ if (nvr_uPickable > 0.0 && diffuseColor.a > 0.0) {
 `,
     )
     .replace(
-      "normalBuffer = vec4(packNormalToVec2(normal), reflectivity, roughnessFactor);",
+      GBUFFER_NORMAL_WRITE_BASIC,
       `
 ${POLYGON_BASE_SHADER_MARKERS.fragment.FINAL_NORMAL_START}
 vec3 finalNormal = origNormal;
 ${POLYGON_BASE_SHADER_MARKERS.fragment.FINAL_NORMAL_END}
-normalBuffer = vec4(packNormalToVec2(finalNormal), reflectivity, roughnessFactor);
+GBUFFER_WRITE_NORMAL(finalNormal, reflectivity, roughnessFactor)
 `,
     ).source;
 };

package/src/material/enhancer/polygon/polygonBaseEnhancer/state.ts

@@ -1,10 +1,7 @@
 import type { PolygonBaseProps, PolygonBaseState } from "./types";
 
 export const DEFAULT_BASE_PROPS: Required<
-  Omit<
-    PolygonBaseProps,
-    "globeNormalTexture" | "batchDataTexture" | "minMaxHeight"
-  >
+  Omit<PolygonBaseProps, "batchDataTexture" | "minMaxHeight">
 > = {
   color: 0,
   opacity: 1,

package/src/material/enhancer/polygon/polygonBaseEnhancer/types.ts

@@ -42,9 +42,6 @@ export type PolygonBaseProps = {
   emissiveColor?: number;
   emissiveIntensity?: number;
 
-  // External uniforms (passed from CommonUniforms)
-  globeNormalTexture?: UniformValue<Texture | null>;
-
   // Batch texture
   batchDataTexture?: UniformValue<Texture | null>;
 
@@ -102,7 +99,6 @@ export type PolygonBaseRefs = {
 
   // Optional uniforms
   batchDataTexture?: UniformValue<Texture | null>;
-  uGlobeNormal?: UniformValue<Texture | null>;
 
   // RTE uniforms (only present if useRTE is true)
   modelViewMatrixRTE?: UniformValue<Matrix4>;
@@ -143,10 +139,5 @@ export type PolygonBaseMutates = Mutates<
      * This is needed because batchDataTexture is an external ref passed via props.
      */
     setBatchDataTexture: (texture: UniformValue<Texture | null>) => void;
-    /**
-     * Set the globe normal texture ref.
-     * This is needed because globeNormalTexture is an external ref passed via props.
-     */
-    setGlobeNormalTexture: (texture: UniformValue<Texture | null>) => void;
   }
 >;

package/src/material/enhancer/sdfText/sdfTextBaseEnhancer/coverage.ts

@@ -0,0 +1,31 @@
+/**
+ * Screen-size thresholds for the distance-field text shader.
+ *
+ * A single distance lookup is sufficient while a glyph has enough screen
+ * pixels for every stroke to own several fragments. Below that point, a CJK
+ * glyph can place multiple contours inside one fragment footprint, so the
+ * shader averages four subpixel coverage evaluations. The blend interval keeps
+ * animated/world-sized labels from popping as their projected size changes.
+ */
+export const SMALL_TEXT_SUPERSAMPLE_FULL_PPEM = 24;
+export const SMALL_TEXT_SUPERSAMPLE_END_PPEM = 32;
+
+/**
+ * Expand the fill contour slightly at tiny display sizes. This is the
+ * distance-field equivalent of stem darkening: it prevents a nominally
+ * one-pixel stroke from becoming a low-contrast gray line after correct area
+ * antialiasing. The adjustment is in screen pixels per side and disappears
+ * before normal-size text, so layout and atlas geometry remain unchanged.
+ */
+export const SMALL_TEXT_STEM_DARKEN_MAX_PX = 0.15;
+export const SMALL_TEXT_STEM_DARKEN_FULL_PPEM = 12;
+export const SMALL_TEXT_STEM_DARKEN_END_PPEM = 32;
+
+/**
+ * MTSDF's RGB median preserves corners at normal sizes, but under strong
+ * minification its independently filtered channels can select the wrong edge.
+ * The alpha channel is a true SDF, so use it at small sizes and blend back to
+ * RGB as the glyph gains enough screen pixels.
+ */
+export const MSDF_TRUE_SDF_END_PPEM = 16;
+export const MSDF_FULL_DETAIL_PPEM = 32;

package/src/material/enhancer/sdfText/sdfTextBaseEnhancer/shader.test.ts

@@ -1,7 +1,17 @@
+import { SDF_PX_SIZE, atlasRangePx } from "@navaramap/font";
 import sdfTextFragmentShader from "@shaders/glsl/sdfText.frag.glsl";
 import sdfTextVertexShader from "@shaders/glsl/sdfText.vert.glsl";
 import { describe, expect, it } from "vitest";
 
+import {
+  MSDF_FULL_DETAIL_PPEM,
+  MSDF_TRUE_SDF_END_PPEM,
+  SMALL_TEXT_SUPERSAMPLE_END_PPEM,
+  SMALL_TEXT_SUPERSAMPLE_FULL_PPEM,
+  SMALL_TEXT_STEM_DARKEN_END_PPEM,
+  SMALL_TEXT_STEM_DARKEN_FULL_PPEM,
+  SMALL_TEXT_STEM_DARKEN_MAX_PX,
+} from "./coverage";
 import { LABEL_ROWS, LabelRow } from "./types";
 
 import { createSdfTextBaseEnhancer, type SupportedMaterial } from ".";
@@ -46,6 +56,71 @@ describe("sdfTextBaseEnhancer shader", () => {
     expect(transform({ useMsdf: false }).defines.USE_MSDF).toBeUndefined();
   });
 
+  describe("small-text coverage contract", () => {
+    it("injects the SDF raster size and quality-specific distance range", () => {
+      expect(transform({ useMsdf: false }).defines).toMatchObject({
+        NVR_SDF_PX_SIZE: SDF_PX_SIZE,
+        NVR_SDF_PX_RANGE: atlasRangePx(false),
+      });
+      expect(transform({ useMsdf: true }).defines).toMatchObject({
+        NVR_SDF_PX_SIZE: SDF_PX_SIZE,
+        NVR_SDF_PX_RANGE: atlasRangePx(true),
+      });
+    });
+
+    it("injects ordered supersampling and MTSDF transition thresholds", () => {
+      expect(SMALL_TEXT_SUPERSAMPLE_FULL_PPEM).toBeLessThan(
+        SMALL_TEXT_SUPERSAMPLE_END_PPEM,
+      );
+      expect(MSDF_TRUE_SDF_END_PPEM).toBeLessThan(MSDF_FULL_DETAIL_PPEM);
+      expect(SMALL_TEXT_STEM_DARKEN_FULL_PPEM).toBeLessThan(
+        SMALL_TEXT_STEM_DARKEN_END_PPEM,
+      );
+      expect(SMALL_TEXT_STEM_DARKEN_MAX_PX).toBeGreaterThan(0);
+      expect(transform({}).defines).toMatchObject({
+        NVR_SMALL_TEXT_SS_FULL_PPEM: SMALL_TEXT_SUPERSAMPLE_FULL_PPEM,
+        NVR_SMALL_TEXT_SS_END_PPEM: SMALL_TEXT_SUPERSAMPLE_END_PPEM,
+        NVR_SMALL_TEXT_DARKEN_MAX_PX: SMALL_TEXT_STEM_DARKEN_MAX_PX,
+        NVR_SMALL_TEXT_DARKEN_FULL_PPEM: SMALL_TEXT_STEM_DARKEN_FULL_PPEM,
+        NVR_SMALL_TEXT_DARKEN_END_PPEM: SMALL_TEXT_STEM_DARKEN_END_PPEM,
+        NVR_MSDF_TRUE_SDF_END_PPEM: MSDF_TRUE_SDF_END_PPEM,
+        NVR_MSDF_FULL_DETAIL_PPEM: MSDF_FULL_DETAIL_PPEM,
+      });
+    });
+
+    it("uses UV-derived coverage and clamps supersamples to the padded glyph boundary", () => {
+      expect(sdfTextFragmentShader).toContain("nvr_screenPxRange()");
+      expect(sdfTextFragmentShader).toContain("nvr_edgeCoverage(");
+      expect(sdfTextFragmentShader).toContain(
+        "clamp(atlasUv, vAtlasUvMin, vAtlasUvMax)",
+      );
+      expect(sdfTextFragmentShader).not.toContain("vAtlasUvMin + halfTexel");
+      expect(sdfTextFragmentShader).not.toContain("vAtlasUvMax - halfTexel");
+      expect(sdfTextVertexShader).toContain(
+        "vAtlasUvMin = glyphUvRect.xy / atlasSize",
+      );
+      expect(sdfTextVertexShader).toContain(
+        "vAtlasUvMax = glyphUvRect.zw / atlasSize",
+      );
+      expect(sdfTextFragmentShader).not.toContain("fwidth(dist)");
+    });
+
+    it("composites translucent outlines behind partially covered fills", () => {
+      expect(sdfTextFragmentShader).toContain(
+        "float behindFill = outlineLayer * (1.0 - fillAlpha)",
+      );
+      expect(sdfTextFragmentShader).toContain(
+        "float alpha = fillAlpha + behindFill",
+      );
+      expect(sdfTextFragmentShader).not.toContain(
+        "mix(uOutlineColor, vColor, fillAlpha)",
+      );
+      expect(sdfTextFragmentShader).toMatch(
+        /alpha \*= opacity;\s*if \(alpha <= 0\.0\) discard;/,
+      );
+    });
+  });
+
   // The shader indexes the label data texture as `slot * LABEL_ROWS + row`.
   // If the define and the CPU-side row table disagree, every label reads
   // another label's state — hence injecting it rather than hard-coding it.

package/src/material/enhancer/sdfText/sdfTextBaseEnhancer/shader.ts

@@ -1,9 +1,20 @@
+import { SDF_PX_SIZE } from "@navaramap/font";
 import sdfTextFragmentShader from "@shaders/glsl/sdfText.frag.glsl";
 import sdfTextVertexShader from "@shaders/glsl/sdfText.vert.glsl";
 import type { WebGLProgramParametersWithUniforms } from "three";
 
+import {
+  MSDF_FULL_DETAIL_PPEM,
+  MSDF_TRUE_SDF_END_PPEM,
+  SMALL_TEXT_SUPERSAMPLE_END_PPEM,
+  SMALL_TEXT_SUPERSAMPLE_FULL_PPEM,
+  SMALL_TEXT_STEM_DARKEN_END_PPEM,
+  SMALL_TEXT_STEM_DARKEN_FULL_PPEM,
+  SMALL_TEXT_STEM_DARKEN_MAX_PX,
+} from "./coverage";
 import {
   LABEL_ROWS,
+  sdfRadiusFor,
   type SdfTextBaseMutates,
   type SdfTextBaseState,
 } from "./types";
@@ -31,6 +42,21 @@ export const transformShader = (
   // Stride of the per-label data texture. Injected rather than hard-coded in
   // GLSL so the shader's row addressing always matches `LabelRow`.
   shader.defines.LABEL_ROWS = LABEL_ROWS;
+  // These values are compile-time constants for a material: quality is
+  // immutable, and all glyphs in an atlas use the same raster density/range.
+  // Injecting them from the TypeScript sources of truth prevents the shader's
+  // screen-pixel coverage math from drifting from the worker.
+  shader.defines.NVR_SDF_PX_SIZE = SDF_PX_SIZE;
+  shader.defines.NVR_SDF_PX_RANGE = sdfRadiusFor(state.useMsdf);
+  shader.defines.NVR_SMALL_TEXT_SS_FULL_PPEM = SMALL_TEXT_SUPERSAMPLE_FULL_PPEM;
+  shader.defines.NVR_SMALL_TEXT_SS_END_PPEM = SMALL_TEXT_SUPERSAMPLE_END_PPEM;
+  shader.defines.NVR_SMALL_TEXT_DARKEN_MAX_PX = SMALL_TEXT_STEM_DARKEN_MAX_PX;
+  shader.defines.NVR_SMALL_TEXT_DARKEN_FULL_PPEM =
+    SMALL_TEXT_STEM_DARKEN_FULL_PPEM;
+  shader.defines.NVR_SMALL_TEXT_DARKEN_END_PPEM =
+    SMALL_TEXT_STEM_DARKEN_END_PPEM;
+  shader.defines.NVR_MSDF_TRUE_SDF_END_PPEM = MSDF_TRUE_SDF_END_PPEM;
+  shader.defines.NVR_MSDF_FULL_DETAIL_PPEM = MSDF_FULL_DETAIL_PPEM;
 
   if (state.useRTE) {
     shader.defines.USE_RTE = 1;

package/src/material/enhancer/sdfText/sdfTextBaseEnhancer/types.ts

@@ -7,7 +7,7 @@ import type { Mutates } from "../../MaterialEnhancer";
 /** Pixel range covered by a quality's atlas distance field; defines how
  *  outline-width pixels translate to a distance-value delta. SDF (`useMsdf=false`)
  *  uses the classic 35 px radius from `sdf_glyph_renderer`; MSDF uses
- *  `MSDF_RANGE_PX` (8 px). See [`atlasRangePx`] in `@navaramap/font`. */
+ *  `MSDF_RANGE_PX` (16 px). See [`atlasRangePx`] in `@navaramap/font`. */
 export const sdfRadiusFor = (useMsdf: boolean): number => atlasRangePx(useMsdf);
 
 /**

package/src/material/gbufferLayout.test.ts

@@ -0,0 +1,171 @@
+import {
+  HalfFloatType,
+  NearestFilter,
+  UnsignedByteType,
+  WebGLRenderTarget,
+} from "three";
+import { describe, expect, it } from "vitest";
+
+import {
+  GBUFFER_ATTACHMENT_NAMES,
+  GBUFFER_DEFINE_NAMES,
+  GBUFFER_NORMAL_LOCATION_DEFINE,
+  GBUFFER_NORMAL_WRITE_BASIC,
+  GBUFFER_NORMAL_WRITE_PHYSICAL,
+  GBUFFER_EMISSIVE_LOCATION_DEFINE,
+  GBUFFER_PARS_FRAGMENT,
+  USE_GBUFFER_EMISSIVE_DEFINE,
+  computeGBufferDefines,
+  computeGBufferTextureIndex,
+  createGBufferAttachments,
+  resolveGBufferOptions,
+  unionGBufferRequirements,
+} from "./gbufferLayout";
+
+describe("gbufferLayout", () => {
+  it("keeps the GLSL chunk in sync with the TS define names", () => {
+    // Only strings link the two sides: a one-sided rename silently stops the
+    // buffer from being written, with no compile error.
+    for (const name of GBUFFER_DEFINE_NAMES) {
+      expect(GBUFFER_PARS_FRAGMENT).toContain(name);
+    }
+    // Every normal write goes through the macro, so the output can be
+    // compiled out wholesale — a direct assignment would not be.
+    expect(GBUFFER_PARS_FRAGMENT).toContain("#define GBUFFER_WRITE_NORMAL(");
+    expect(GBUFFER_NORMAL_WRITE_BASIC).toMatch(/^GBUFFER_WRITE_NORMAL\(/);
+    expect(GBUFFER_NORMAL_WRITE_PHYSICAL).toMatch(/^GBUFFER_WRITE_NORMAL\(/);
+  });
+
+  it("packs optional attachment indices without gaps", () => {
+    expect(
+      computeGBufferTextureIndex(
+        resolveGBufferOptions({
+          normal: true,
+          selectiveEffect: true,
+          emissive: true,
+          shadow: true,
+        }),
+      ),
+    ).toEqual({ color: 0, normal: 1, effectIds: 2, emissive: 3, shadow: 4 });
+    // A disabled buffer never leaves a hole: later buffers slide down. Normal
+    // is optional too, so shadow lands directly after color without it.
+    expect(
+      computeGBufferTextureIndex(resolveGBufferOptions({ shadow: true })),
+    ).toEqual({ color: 0, shadow: 1 });
+    // Defaults allocate nothing beyond color.
+    expect(computeGBufferTextureIndex(resolveGBufferOptions())).toEqual({
+      color: 0,
+    });
+  });
+
+  it("stamps location defines matching the computed indices", () => {
+    expect(
+      computeGBufferDefines(
+        resolveGBufferOptions({ normal: true, emissive: true }),
+      ),
+    ).toEqual({
+      [GBUFFER_NORMAL_LOCATION_DEFINE]: 1,
+      [USE_GBUFFER_EMISSIVE_DEFINE]: 1,
+      [GBUFFER_EMISSIVE_LOCATION_DEFINE]: 2,
+    });
+    expect(computeGBufferDefines(resolveGBufferOptions())).toEqual({});
+  });
+
+  it("derives the buffer configuration as the union of effect requirements", () => {
+    expect(unionGBufferRequirements([])).toEqual({
+      normal: false,
+      selectiveEffect: false,
+      emissive: false,
+      shadow: false,
+      globeNormal: false,
+    });
+    expect(
+      unionGBufferRequirements([
+        ["selectiveEffect"],
+        ["selectiveEffect", "emissive"],
+        ["shadow"],
+      ]),
+    ).toEqual({
+      normal: false,
+      selectiveEffect: true,
+      emissive: true,
+      shadow: true,
+      globeNormal: false,
+    });
+
+    // The globe normal is a copy of the normal attachment, so requesting it
+    // pulls the attachment in even when nothing asked for it directly.
+    expect(unionGBufferRequirements([["globeNormal"]])).toEqual({
+      normal: true,
+      selectiveEffect: false,
+      emissive: false,
+      shadow: false,
+      globeNormal: true,
+    });
+  });
+
+  it("allocates only enabled attachments, with their texture settings", () => {
+    const rt = new WebGLRenderTarget(4, 4);
+    const buffers = resolveGBufferOptions({
+      normal: true,
+      selectiveEffect: true,
+      emissive: true,
+      shadow: true,
+    });
+    createGBufferAttachments(rt, buffers);
+
+    expect(rt.textures.length).toBe(5);
+    const index = computeGBufferTextureIndex(buffers);
+    invariantDefined(index.effectIds);
+    invariantDefined(index.emissive);
+    const effectIds = rt.textures[index.effectIds];
+    expect(effectIds.type).toBe(HalfFloatType);
+    expect(effectIds.minFilter).toBe(NearestFilter);
+    expect(effectIds.magFilter).toBe(NearestFilter);
+    expect(rt.textures[index.emissive].type).toBe(HalfFloatType);
+    invariantDefined(index.shadow);
+    expect(rt.textures[index.shadow].type).toBe(UnsignedByteType);
+
+    // No placeholder textures for disabled buffers – indices would shift.
+    const defaultRt = new WebGLRenderTarget(4, 4);
+    createGBufferAttachments(defaultRt, resolveGBufferOptions());
+    expect(defaultRt.textures.length).toBe(1);
+  });
+});
+
+function invariantDefined(value: number | undefined): asserts value is number {
+  expect(value).toBeDefined();
+}
+
+describe("globeNormal", () => {
+  // It rides on requiredBuffers but is a separate copy target, not an MRT
+  // attachment, so it must not consume a slot, an index, or a location define.
+  const buffers = resolveGBufferOptions({ globeNormal: true, shadow: true });
+
+  it("takes no attachment index of its own", () => {
+    // normal is present because globeNormal implies it, not because
+    // globeNormal took a slot.
+    expect(computeGBufferTextureIndex(buffers)).toEqual({
+      color: 0,
+      normal: 1,
+      shadow: 2,
+    });
+  });
+
+  it("allocates no texture of its own", () => {
+    const rt = new WebGLRenderTarget(4, 4);
+    createGBufferAttachments(rt, buffers);
+    // color + normal (implied) + shadow — globeNormal itself adds nothing.
+    expect(rt.textures.length).toBe(3);
+  });
+
+  it("stamps no define of its own", () => {
+    expect(
+      computeGBufferDefines(unionGBufferRequirements([["globeNormal"]])),
+    ).toEqual({ [GBUFFER_NORMAL_LOCATION_DEFINE]: 1 });
+  });
+
+  it("is excluded from the attachment-backed names", () => {
+    expect(GBUFFER_ATTACHMENT_NAMES).not.toContain("globeNormal");
+  });
+});