@expofp/renderer 3.0.1 → 3.1.0

package/dist/index.d.ts

@@ -274,8 +274,14 @@ export declare interface LayerDef extends SharedDef {
     interactive?: boolean;
     /** Collection of layer's children. Mixing different types of children is not supported. */
     children: RenderableDefCollection;
-    /** Layer's rendering mode, 2d or 3d. Optional, 2d by default. */
-    mode?: "2d" | "3d";
+    /**
+     * Layer's rendering mode. Propagates to children: child layers inherit the parent's mode
+     * unless they specify their own. Defaults to `"2D"` at the root.
+     * Resolved once during scene build and should not be changed afterwards.
+     * - `"2D"`: painter's algorithm (AlwaysDepth). Layer order determines overlap.
+     * - `"3D"`: depth testing (LessDepth). Closer geometry occludes farther geometry.
+     */
+    readonly mode?: "2D" | "3D";
 }
 
 /** Line definition */
@@ -338,7 +344,11 @@ export declare class Polygon {
     get vertices(): readonly Vector3Like[];
     /** Array of polygon indices. Each index is a triplet of vertex indices forming a triangle. */
     get indices(): readonly Index[];
-    /** Bounding rectangle of the polygon. */
+    /**
+     * Bounding rectangle of the polygon.
+     * This is a 2D axis-aligned bounding box computed from the X/Y projection of vertices.
+     * The Z extent of the polygon is not tracked.
+     */
     get bounds(): Rect;
     /**
      * Converts a {@link Rect} to a {@link Polygon}.
@@ -367,7 +377,8 @@ export declare class Polygon {
     rotate(rotation: number, center?: Vector2Like): Polygon;
     /**
      * Scales the polygon around the given origin.
-     * @param scaleFactor Can be a single number or a 2D vector. If a single number is provided, both horizontal and vertical axes will be scaled by the same factor.
+     * @param scaleFactor Can be a single number or a 2D vector. If a single number is provided, both horizontal and
+     * vertical axes will be scaled by the same factor. Z is unchanged in both cases.
      * @param origin Origin of the scaling. If omitted, defaults to the bounding rectangle center.
      * @returns this {@link Polygon} instance
      */
@@ -387,6 +398,8 @@ export declare interface PtScaleEventData {
 export declare class Rect {
     /** Optional rotation of the rectangle. In radians, around center. Positive values rotate clockwise. */
     rotation: number;
+    /** Optional elevation of the rectangle. Positive values raise geometry toward the viewer. Defaults to 0. */
+    elevation: number;
     private _min;
     private _max;
     private _center;
@@ -395,8 +408,9 @@ export declare class Rect {
      * @param min Top left corner of the rectangle.
      * @param max Bottom right corner of the rectangle.
      * @param rotation Optional rotation of the rectangle. In radians, around center. Positive values rotate clockwise.
+     * @param elevation Optional elevation. Positive values raise geometry toward the viewer. Defaults to 0.
      */
-    constructor(min: IVector2, max: IVector2, rotation?: number);
+    constructor(min: IVector2, max: IVector2, rotation?: number, elevation?: number);
     /** Top left corner of the rectangle. */
     get min(): Vector2Like;
     /** Set top left corner of the rectangle. */
@@ -417,9 +431,10 @@ export declare class Rect {
      * Creates a rectangle from an SVG rectangle element.
      * @param rect {@link SVGRectElement} or {@link SVGImageElement}
      * @param rotation Optional rotation of the rectangle. In radians, around center. Positive values rotate clockwise.
+     * @param elevation Optional elevation. Positive values raise geometry toward the viewer. Defaults to 0.
      * @returns new {@link Rect} instance
      */
-    static fromSvg(rect: SVGRectElement | SVGImageElement, rotation?: number): Rect;
+    static fromSvg(rect: SVGRectElement | SVGImageElement, rotation?: number, elevation?: number): Rect;
     /**
      * Moves the rectangle by the given offset.
      * @param offset Offset to move the rectangle by.

package/dist/index.js

@@ -2,7 +2,7 @@ var __defProp = Object.defineProperty;
 var __defNormalProp = (obj, key, value) => key in obj ? __defProp(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
 var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "symbol" ? key + "" : key, value);
 var _a;
-import { DataTexture, FloatType, UnsignedIntType, IntType, RGBAFormat, RGBAIntegerFormat, RGFormat, RGIntegerFormat, RedFormat, RedIntegerFormat, BatchedMesh as BatchedMesh$1, BufferAttribute, StreamDrawUsage, Color, Matrix4, Vector3, Frustum, Sphere, Box3, DynamicDrawUsage, Vector4, AlwaysDepth, DoubleSide, MeshBasicMaterial, Texture, Group, PlaneGeometry, SRGBColorSpace, Vector2, Quaternion, Mesh, LessEqualDepth, BufferGeometry, LinearSRGBColorSpace, Camera, Spherical, MathUtils, Plane, Raycaster, PerspectiveCamera, Scene, Clock, WebGLRenderer } from "three";
+import { DataTexture, FloatType, UnsignedIntType, IntType, RGBAFormat, RGBAIntegerFormat, RGFormat, RGIntegerFormat, RedFormat, RedIntegerFormat, BatchedMesh as BatchedMesh$1, BufferAttribute, StreamDrawUsage, Color, Matrix4, Vector3, Frustum, Sphere, Box3, DynamicDrawUsage, Vector4, AlwaysDepth, DoubleSide, MeshBasicMaterial, LessEqualDepth, Texture, Group, PlaneGeometry, SRGBColorSpace, Vector2, Quaternion, BufferGeometry, LinearSRGBColorSpace, Mesh, Camera, Spherical, MathUtils, Plane, Raycaster, PerspectiveCamera, Scene, Clock, WebGLRenderer } from "three";
 import { traverseAncestorsGenerator } from "three/examples/jsm/utils/SceneUtils.js";
 import createLog from "debug";
 import { BatchedText as BatchedText$1, Text as Text$1 } from "troika-three-text";
@@ -867,8 +867,6 @@ class Text extends Text$1 {
       if (!this._batchParent) this.geometry.applyClipRect(uniforms.uTroikaClipRect.value);
     }
     uniforms.uTroikaSDFDebug.value = !!this.debugSDF;
-    material.polygonOffset = !!this.depthOffset;
-    material.polygonOffsetFactor = material.polygonOffsetUnits = this.depthOffset || 0;
     const color = isOutline ? this.outlineColor || 0 : this.color;
     if (color == null) {
       delete material.color;
@@ -1050,6 +1048,7 @@ const dimColorFrag = (
     return vec4(m * col.a, col.a);
   }`
 );
+const POLYGON_OFFSET_MULTIPLIER = 12;
 const sharedParameters = {
   side: DoubleSide,
   transparent: true,
@@ -1094,47 +1093,47 @@ class MaterialSystem {
       }
     };
     addDimToMaterial(material);
+    this.addPolygonOffset(material);
     return material;
   }
   /**
    * Creates a color material.
-   * @param partialParams {@link MaterialColorParams}
+   * @param params {@link MaterialColorParams}
    * @returns MeshBasicMaterial instance
    */
-  createColorMaterial(partialParams = {}) {
-    const params = {
-      color: partialParams.color ?? 16777215,
-      opacity: partialParams.opacity ?? 1
-    };
+  createColorMaterial(params = {}) {
     const material = new MeshBasicMaterial({
       ...sharedParameters,
-      color: params.color,
-      opacity: params.opacity
+      color: params.color ?? 16777215,
+      opacity: params.opacity ?? 1
     });
+    if (params.is3D) material.depthFunc = LessEqualDepth;
     addDimToMaterial(material);
+    this.addPolygonOffset(material);
     return material;
   }
   /**
    * Creates a texture material.
-   * @param map {@link Texture}
-   * @param uvOffset whether to enable uv offset with per instance uniforms (for texture atlases)
+   * @param params {@link MaterialTextureParams}
    * @returns MeshBasicMaterial instance
    */
-  createTextureMaterial(map, uvOffset = false) {
-    const material = new MeshBasicMaterial({ ...sharedParameters, map });
-    if (uvOffset) {
+  createTextureMaterial(params) {
+    const material = new MeshBasicMaterial({ ...sharedParameters, map: params.map });
+    if (params.is3D) material.depthFunc = LessEqualDepth;
+    if (params.uvOffset) {
       material.onBeforeCompile = (shader) => {
         shader.vertexShader = shader.vertexShader.replace(
           "#include <uv_vertex>",
           /*glsl*/
           `
               #include <uv_vertex>
-              vMapUv = uv * uvOffset.zw + uvOffset.xy;      
+              vMapUv = uv * uvOffset.zw + uvOffset.xy;
             `
         );
       };
     }
     addDimToMaterial(material);
+    this.addPolygonOffset(material);
     return material;
   }
   /**
@@ -1158,6 +1157,40 @@ class MaterialSystem {
     }
     return this.backgroundMaterial;
   }
+  /**
+   * Patches a material's onBeforeRender to dynamically set polygonOffset based on the
+   * object's renderOrder. Later layers (higher renderOrder) get a larger negative offset,
+   * giving them a slight depth buffer advantage over earlier layers at the same elevation.
+   * This prevents z-fighting between coplanar 3D content across different layers.
+   *
+   * The units multiplier is derived from {@link CameraControls.maxPolarAngle}:
+   *
+   *   multiplier = ⌈tan(maxPolarAngle)⌉
+   *
+   * At steep camera pitch, coplanar surfaces from different draw calls (different
+   * BatchedMesh instances) compute slightly different depth values at the same pixel
+   * due to floating-point interpolation differences in the vertex shader. These errors
+   * are proportional to the depth gradient across the surface, which for a horizontal
+   * plane at pitch angle θ is proportional to tan(θ). The multiplier ensures the
+   * per-layer polygon offset exceeds these errors at the configured maximum pitch.
+   *
+   * For elevated content the effective viewing angle can exceed maxPolarAngle, but this
+   * is self-correcting: the screen-space height of the surface shrinks as cos(angle),
+   * so the total visible z-fighting (pixels × severity ∝ cos × tan = sin) is bounded
+   * and becomes subpixel as the effective angle approaches 90°.
+   *
+   * With maxPolarAngle = 85°: ⌈tan(85°)⌉ = ⌈11.43⌉ = 12.
+   * @param material Material to patch
+   */
+  addPolygonOffset(material) {
+    const onBeforeRender = material.onBeforeRender.bind(material);
+    material.onBeforeRender = (renderer, scene, camera, geometry, object, group) => {
+      onBeforeRender(renderer, scene, camera, geometry, object, group);
+      material.polygonOffset = true;
+      material.polygonOffsetFactor = 0;
+      material.polygonOffsetUnits = -object.renderOrder * POLYGON_OFFSET_MULTIPLIER;
+    };
+  }
 }
 function isShapeDef(def) {
   return def.shape !== void 0;
@@ -1189,36 +1222,14 @@ function isLineLayer(layer) {
 function isLayerLayer(layer) {
   return layer.children[0] && isLayerDef(layer.children[0]);
 }
-function groupBy(list, keyGetter) {
-  const map = /* @__PURE__ */ new Map();
-  list.forEach((item) => {
-    const key = keyGetter(item);
-    const collection = map.get(key);
-    if (!collection) {
-      map.set(key, [item]);
-    } else {
-      collection.push(item);
-    }
-  });
-  return map;
-}
-function partition(list, pred) {
-  const truthy = [];
-  const falsy = [];
-  for (const item of list) {
-    if (pred(item)) {
-      truthy.push(item);
-    } else {
-      falsy.push(item);
-    }
-  }
-  return [truthy, falsy];
-}
 const INTERACTIVE_LAYER = 1;
-function setInteractive(object, isInteractive) {
-  if (isInteractive) object.layers.enable(INTERACTIVE_LAYER);
+function isInteractive(object) {
+  return object.layers.isEnabled(INTERACTIVE_LAYER);
+}
+function setInteractive(object, isInteractive2) {
+  if (isInteractive2) object.layers.enable(INTERACTIVE_LAYER);
   else object.layers.disable(INTERACTIVE_LAYER);
-  object.children.forEach((child) => setInteractive(child, isInteractive));
+  object.children.forEach((child) => setInteractive(child, isInteractive2));
 }
 function isVisible(object) {
   if (!object.visible) return false;
@@ -1483,6 +1494,7 @@ class ImageSystem extends RenderableSystem {
   }
   buildLayer(layer) {
     var _a2;
+    const is3D = layer.mode === "3D";
     const group = new Group();
     const images = layer.children;
     const bins = this.packImages(images);
@@ -1497,7 +1509,7 @@ class ImageSystem extends RenderableSystem {
       ).sort((a, b) => a.originalIndex - b.originalIndex);
       const instanceCount = rectsWithDef.length;
       const texture = createAtlas(bin);
-      const instanceMaterial = this.materialSystem.createTextureMaterial(texture, true);
+      const instanceMaterial = this.materialSystem.createTextureMaterial({ map: texture, uvOffset: true, is3D });
       const instanceGeometry = new PlaneGeometry();
       const vertexCount = instanceGeometry.attributes["position"].count;
       const indexCount = ((_a2 = instanceGeometry.index) == null ? void 0 : _a2.count) ?? 0;
@@ -1582,7 +1594,7 @@ class ImageSystem extends RenderableSystem {
     const bounds = imageDef.bounds;
     const origin2 = imageDef.origin ?? [0.5, 0.5];
     this.originTranslationMatrix.makeTranslation(0.5 - origin2[0], 0.5 - origin2[1], 0);
-    this.globalTranslationMatrix.makeTranslation(bounds.center.x, bounds.center.y, 0);
+    this.globalTranslationMatrix.makeTranslation(bounds.center.x, bounds.center.y, bounds.elevation);
     this.scaleMatrix.makeScale(bounds.size.x, bounds.size.y, 1);
     this.rotationMatrix.makeRotationZ(bounds.rotation);
     const matrix = this.originTranslationMatrix.premultiply(this.scaleMatrix).premultiply(this.rotationMatrix).premultiply(this.globalTranslationMatrix);
@@ -1732,10 +1744,13 @@ class Rect {
    * @param min Top left corner of the rectangle.
    * @param max Bottom right corner of the rectangle.
    * @param rotation Optional rotation of the rectangle. In radians, around center. Positive values rotate clockwise.
+   * @param elevation Optional elevation. Positive values raise geometry toward the viewer. Defaults to 0.
    */
-  constructor(min, max, rotation) {
+  constructor(min, max, rotation, elevation) {
     /** Optional rotation of the rectangle. In radians, around center. Positive values rotate clockwise. */
     __publicField(this, "rotation");
+    /** Optional elevation of the rectangle. Positive values raise geometry toward the viewer. Defaults to 0. */
+    __publicField(this, "elevation");
     __publicField(this, "_min");
     __publicField(this, "_max");
     __publicField(this, "_center", new Vector2());
@@ -1743,6 +1758,7 @@ class Rect {
     this._min = createVector2(min);
     this._max = createVector2(max);
     this.rotation = rotation ?? 0;
+    this.elevation = elevation ?? 0;
     this.updateCenterAndSize();
   }
   /** Top left corner of the rectangle. */
@@ -1785,14 +1801,15 @@ class Rect {
    * Creates a rectangle from an SVG rectangle element.
    * @param rect {@link SVGRectElement} or {@link SVGImageElement}
    * @param rotation Optional rotation of the rectangle. In radians, around center. Positive values rotate clockwise.
+   * @param elevation Optional elevation. Positive values raise geometry toward the viewer. Defaults to 0.
    * @returns new {@link Rect} instance
    */
-  static fromSvg(rect, rotation) {
+  static fromSvg(rect, rotation, elevation) {
     const x = rect.x.baseVal.value;
     const y = rect.y.baseVal.value;
     const width = rect.width.baseVal.value;
     const height = rect.height.baseVal.value;
-    return new Rect([x, y], [x + width, y + height], rotation);
+    return new Rect([x, y], [x + width, y + height], rotation, elevation);
   }
   /**
    * Moves the rectangle by the given offset.
@@ -1848,7 +1865,11 @@ class Polygon {
   get indices() {
     return this._indices;
   }
-  /** Bounding rectangle of the polygon. */
+  /**
+   * Bounding rectangle of the polygon.
+   * This is a 2D axis-aligned bounding box computed from the X/Y projection of vertices.
+   * The Z extent of the polygon is not tracked.
+   */
   get bounds() {
     return this._bbox;
   }
@@ -1858,11 +1879,12 @@ class Polygon {
    * @returns new {@link Polygon} instance
    */
   static fromRect(rect) {
+    const z = rect.elevation;
     const vertices = [
-      { x: rect.min.x, y: rect.min.y },
-      { x: rect.max.x, y: rect.min.y },
-      { x: rect.max.x, y: rect.max.y },
-      { x: rect.min.x, y: rect.max.y }
+      { x: rect.min.x, y: rect.min.y, z },
+      { x: rect.max.x, y: rect.min.y, z },
+      { x: rect.max.x, y: rect.max.y, z },
+      { x: rect.min.x, y: rect.max.y, z }
     ];
     const indices = [
       [0, 1, 2],
@@ -1914,7 +1936,8 @@ class Polygon {
   }
   /**
    * Scales the polygon around the given origin.
-   * @param scaleFactor Can be a single number or a 2D vector. If a single number is provided, both horizontal and vertical axes will be scaled by the same factor.
+   * @param scaleFactor Can be a single number or a 2D vector. If a single number is provided, both horizontal and
+   * vertical axes will be scaled by the same factor. Z is unchanged in both cases.
    * @param origin Origin of the scaling. If omitted, defaults to the bounding rectangle center.
    * @returns this {@link Polygon} instance
    */
@@ -1942,6 +1965,31 @@ class Polygon {
   }
 }
 const tempVector2 = new Vector2();
+function groupBy(list, keyGetter) {
+  const map = /* @__PURE__ */ new Map();
+  list.forEach((item) => {
+    const key = keyGetter(item);
+    const collection = map.get(key);
+    if (!collection) {
+      map.set(key, [item]);
+    } else {
+      collection.push(item);
+    }
+  });
+  return map;
+}
+function partition(list, pred) {
+  const truthy = [];
+  const falsy = [];
+  for (const item of list) {
+    if (pred(item)) {
+      truthy.push(item);
+    } else {
+      falsy.push(item);
+    }
+  }
+  return [truthy, falsy];
+}
 function countGeometry(geometry) {
   var _a2;
   if (geometry.index == null) return { vertices: geometry.getAttribute("position").count, indices: 0 };
@@ -1950,6 +1998,18 @@ function countGeometry(geometry) {
     indices: ((_a2 = geometry.index) == null ? void 0 : _a2.count) ?? 0
   };
 }
+const sphereCenter = new Vector3();
+function computeBoundingSphere(bounds, origin2, out = new Sphere()) {
+  const ox = (origin2 == null ? void 0 : origin2[0]) ?? 0.5;
+  const oy = (origin2 == null ? void 0 : origin2[1]) ?? 0.5;
+  const w = bounds.size.x;
+  const h = bounds.size.y;
+  const dx = Math.max(ox, 1 - ox) * w;
+  const dy = Math.max(oy, 1 - oy) * h;
+  sphereCenter.set(bounds.center.x, bounds.center.y, bounds.elevation);
+  out.set(sphereCenter, Math.hypot(dx, dy));
+  return out;
+}
 const logger$a = createLogger("mesh");
 extend([namesPlugin]);
 class MeshSystem extends RenderableSystem {
@@ -1971,6 +2031,7 @@ class MeshSystem extends RenderableSystem {
     this.rectGeometry.deleteAttribute("uv");
   }
   buildLayer(layer) {
+    const is3D = layer.mode === "3D";
     const shapes = layer.children;
     const mapShapeToNormColor = /* @__PURE__ */ new Map();
     for (const shapeDef of shapes) {
@@ -1987,21 +2048,15 @@ class MeshSystem extends RenderableSystem {
     const transparentShapesGrouped = groupBy(transparentShapes, (shapeDef) => mapShapeToNormColor.get(shapeDef).a);
     const group = new Group();
     for (const [opacity, shapes2] of transparentShapesGrouped) {
-      const transparentMesh = this.buildBatchedMesh(shapes2, opacity);
+      const transparentMesh = this.buildBatchedMesh(shapes2, is3D, opacity);
       transparentMesh.name = "transparent";
       group.add(transparentMesh);
     }
     if (opaqueShapes.length) {
-      const opaqueMesh = this.buildBatchedMesh(opaqueShapes);
+      const opaqueMesh = this.buildBatchedMesh(opaqueShapes, is3D);
       opaqueMesh.name = "opaque";
       group.add(opaqueMesh);
     }
-    if (layer.mode === "3d") {
-      group.children.filter((child) => child instanceof Mesh).forEach((mesh) => {
-        const material = mesh.material;
-        material.depthFunc = LessEqualDepth;
-      });
-    }
     return group;
   }
   updateDefImpl(shapeDef, mesh, instanceIds, firstUpdate) {
@@ -2040,13 +2095,13 @@ class MeshSystem extends RenderableSystem {
     mesh.setColorAt(instanceId, this.color.setRGB(color.r / 255, color.g / 255, color.b / 255, SRGBColorSpace));
   }
   updateRect(shape, mesh, instanceId) {
-    this.position.set(shape.center.x, shape.center.y, 0);
-    this.rotation.setFromAxisAngle(new Vector3(0, 0, 1), shape.rotation ?? 0);
+    this.position.set(shape.center.x, shape.center.y, shape.elevation);
+    this.rotation.setFromAxisAngle(new Vector3(0, 0, 1), shape.rotation);
     this.scale.set(shape.size.x, shape.size.y, 1);
     this.matrix.compose(this.position, this.rotation, this.scale);
     mesh.setMatrixAt(instanceId, this.matrix);
   }
-  buildBatchedMesh(shapes, opacity = 1) {
+  buildBatchedMesh(shapes, is3D, opacity = 1) {
     let vertexCount = 0;
     let indexCount = 0;
     let rectAdded = false;
@@ -2065,7 +2120,7 @@ class MeshSystem extends RenderableSystem {
       vertexCount += vertices;
       indexCount += indices;
     }
-    const material = this.materialSystem.createColorMaterial({ opacity });
+    const material = this.materialSystem.createColorMaterial({ opacity, is3D });
     const batchedMesh = new BatchedMesh(shapes.length, vertexCount, indexCount, material);
     const rectGeometryId = rectAdded ? batchedMesh.addGeometry(this.rectGeometry) : void 0;
     batchedMesh.setCustomSort((list) => this.sortInstances(batchedMesh, list));
@@ -2201,9 +2256,10 @@ class TextSystem extends RenderableSystem {
     }
   }
   buildBatchedText(layer) {
+    const is3D = layer.mode === "3D";
     const textDefs = layer.children;
     const batchedText = new BatchedText();
-    batchedText.material = this.materialSystem.createColorMaterial();
+    batchedText.material = this.materialSystem.createColorMaterial({ is3D });
     const mappingData = [];
     let instanceId = 0;
     for (const textDef of textDefs) {
@@ -2247,7 +2303,7 @@ class TextSystem extends RenderableSystem {
       this.worldPosition.copy(this.localPosition).rotateAround({ x: 0, y: 0 }, textDef.bounds.rotation).add(textDef.bounds.center);
       this.textScale.copy(this.initialTextScale).multiplyScalar(fontSize * dpr);
       text.scale.set(this.textScale.x, this.textScale.y, 1);
-      text.position.set(this.worldPosition.x, this.worldPosition.y, 0);
+      text.position.set(this.worldPosition.x, this.worldPosition.y, textDef.bounds.elevation);
       text.rotation.set(0, 0, textDef.bounds.rotation);
       this.calculateClipRect(text, textDef, this.localPosition, this.textScale, this.localToMin, this.localToMax);
       this.localPosition.y += height * dpr;
@@ -2482,22 +2538,24 @@ class LayerSystem {
    * @returns sorted leaf layers for debug logging
    */
   initRenderOrder(rootLayer) {
-    const leafLayers = [];
-    const stack = [rootLayer];
+    const twoDLayers = [];
+    const threeDLayers = [];
+    const stack = [
+      { layer: rootLayer, inheritedMode: rootLayer.mode ?? "2D" }
+    ];
     while (stack.length) {
-      const layer = stack.pop();
+      const { layer, inheritedMode } = stack.pop();
       if (isLayerLayer(layer)) {
-        const children = [...layer.children];
-        children.reverse();
-        for (const child of children) {
+        for (let i = layer.children.length - 1; i >= 0; i--) {
+          const child = layer.children[i];
           this.mapLayerDefToParent.set(child, layer);
-          stack.push(child);
+          stack.push({ layer: child, inheritedMode: child.mode ?? inheritedMode });
         }
       } else {
-        leafLayers.push(layer);
+        layer.mode ?? (layer.mode = inheritedMode);
+        (layer.mode === "3D" ? threeDLayers : twoDLayers).push(layer);
       }
     }
-    const [threeDLayers, twoDLayers] = partition(leafLayers, (layer) => layer.mode === "3d");
     const sorted = [...twoDLayers, ...threeDLayers];
     for (let i = 0; i < sorted.length; i++) {
       this.renderOrderMap.set(sorted[i], i + 1);
@@ -2612,10 +2670,12 @@ class ExternalCameraSystem {
   }
 }
 const originalProjectionMatrix = new Matrix4();
+const patchedMeshes = /* @__PURE__ */ new WeakSet();
 function patchMatricesInExternalMode(scene) {
   scene.traverse((child) => {
     const mesh = child;
-    if (!mesh.isMesh) return;
+    if (!mesh.isMesh || patchedMeshes.has(mesh)) return;
+    patchedMeshes.add(mesh);
     const materials = Array.isArray(mesh.material) ? mesh.material : [mesh.material];
     for (const material of materials) {
       const onBeforeRender = material.onBeforeRender.bind(material);
@@ -3011,12 +3071,15 @@ class CoordinatesSystem {
     return out;
   }
   /**
-   * Converts a point from screen coordinates to world space.
+   * Converts a point from NDC to world space by intersecting the ground plane (z=0).
+   * Returns 2D world coordinates (z is always 0). This is appropriate for coordinate
+   * conversions that don't need to account for 3D geometry (e.g. canvasToSvg, camera controls).
+   * For pointer events that should land on 3D geometry, use scene raycasting instead.
    * @param ndcCoords Point in NDC (normalized device coordinates)
    * @param out Optional output vector
-   * @returns Point in world space
+   * @returns Point on the ground plane in world space, or undefined if the ray is parallel to the plane
    */
-  ndcToWorld(ndcCoords, out = new Vector3()) {
+  ndcToWorldPlane(ndcCoords, out = new Vector3()) {
     return this.pickingSystem.intersectPlane(ndcCoords, this.cameraSystem.camera, out);
   }
   /**
@@ -3046,7 +3109,7 @@ class CoordinatesSystem {
     const vec2 = new Vector2();
     const vec3 = new Vector3();
     const ndcPoint = this.canvasToNDC(point, vec2);
-    const worldPoint = this.ndcToWorld(ndcPoint, vec3);
+    const worldPoint = this.ndcToWorldPlane(ndcPoint, vec3);
     if (!worldPoint) return [];
     const result = [];
     for (const sceneState of this.sceneSystem.sceneStates) {
@@ -5665,6 +5728,9 @@ const subsetOfTHREE = {
 };
 CameraControls.install({ THREE: subsetOfTHREE });
 const logger$4 = createLogger("cameraController");
+const ELEVATION_PRECISION = 0.1;
+const ELEVATION_HEADROOM_RATIO = 0.98;
+const DEPTH_BUFFER_LEVELS = 2 ** 24;
 class CameraController extends CameraControls {
   /**
    * @param camera {@link PerspectiveCamera} instance
@@ -5686,6 +5752,7 @@ class CameraController extends CameraControls {
       three: CameraController.ACTION.NONE
     };
     this.touchCancelListener = () => this.cancel();
+    void this.rotatePolarTo(0, false);
   }
   /**
    * Get bearing angle between current camera orientation and true north (in radians).
@@ -5696,15 +5763,50 @@ class CameraController extends CameraControls {
   }
   update(delta) {
     const needsUpdate = super.update(delta);
-    if (needsUpdate && delta > 0) {
-      const position = this.camera.position.toArray().map((value) => +value.toFixed(2));
-      const target = this._target.toArray().map((value) => +value.toFixed(2));
-      const { theta, phi, radius } = this._spherical;
-      const spherical = [theta * RAD2DEG, phi * RAD2DEG, radius].map((value) => +value.toFixed(2));
-      logger$4.debug("camera update %O", { position, target, spherical });
+    if (needsUpdate) {
+      this.updateNearPlane();
+      if (delta > 0) {
+        const position = this.camera.position.toArray().map((value) => +value.toFixed(2));
+        const target = this._target.toArray().map((value) => +value.toFixed(2));
+        const { theta, phi, radius } = this._spherical;
+        const spherical = [theta * RAD2DEG, phi * RAD2DEG, radius].map((value) => +value.toFixed(2));
+        const clippingPlanes = [this.camera.near, this.camera.far];
+        logger$4.debug("camera update %O", { position, target, spherical, clippingPlanes });
+      }
     }
     return needsUpdate;
   }
+  /**
+   * Updates the near clipping plane to maintain consistent depth buffer precision
+   * at the scene plane regardless of zoom level.
+   *
+   * Two constraints determine the near plane:
+   * - **Headroom**: near = D × (1 − headroom ratio). Dominates at close/default zoom,
+   *   keeping headroom at exactly the target ratio. Precision exceeds the target.
+   * - **Precision**: near = D² / (2²⁴ × P). Dominates at far zoom, maintaining target
+   *   precision at the cost of reduced headroom.
+   *
+   * The larger of the two is used (precision is never sacrificed for headroom).
+   * The depth precision P is derived from {@link ELEVATION_PRECISION} and the current
+   * {@link CameraControls.maxPolarAngle}, so it adapts when pitch limits change.
+   *
+   * Depth precision at the floor plane (z=0) is the guaranteed minimum. Content above
+   * (closer to camera) has quadratically better precision: P × (d/D)². Content below the
+   * floor degrades quadratically but remains within ~1% for practical depths (< 1% of D).
+   */
+  updateNearPlane() {
+    const camera = this.camera;
+    const D = this.distance;
+    if (D <= 0) return;
+    const cosPitch = Math.max(Math.cos(this.maxPolarAngle), 0.01);
+    const depthPrecision = ELEVATION_PRECISION * cosPitch;
+    const headroomNear = D * (1 - ELEVATION_HEADROOM_RATIO);
+    const precisionNear = D * D / (DEPTH_BUFFER_LEVELS * depthPrecision);
+    const near = Math.max(headroomNear, precisionNear);
+    if (camera.near === near) return;
+    camera.near = near;
+    camera.updateProjectionMatrix();
+  }
   connect(domElement) {
     super.connect(domElement);
     domElement.addEventListener("touchcancel", this.touchCancelListener);
@@ -6074,7 +6176,7 @@ class RollHandler extends Handler {
   }
   setPivot(e) {
     this.coordinatesSystem.canvasToNDC(e.offsetCenter, this.pivotNDC);
-    if (!this.coordinatesSystem.ndcToWorld(this.pivotNDC, this.pivotWorld)) return false;
+    if (!this.coordinatesSystem.ndcToWorldPlane(this.pivotNDC, this.pivotWorld)) return false;
     this.controller.getPosition(this.cameraPosition);
     this.controller.getTarget(this.targetWorld);
     this.cameraForward.copy(this.targetWorld).sub(this.cameraPosition);
@@ -6160,7 +6262,7 @@ class InteractionsSystem {
     if (internalCameraSystem) {
       this.eventManager = new EventManager(this.canvas, {
         recognizers: [Rotate, [Pan, { event: "pitch", pointers: 2 }, "rotate"]]
-        // FIXME: Double click to zoom
+        // TODO: Double click to zoom
       });
       this.handlers = {
         pan: new PanHandler(this.canvas, this.eventManager, internalCameraSystem, coordinatesSystem),
@@ -6188,8 +6290,6 @@ class InteractionsSystem {
       });
       this.handlers.pan.enable();
       this.handlers.zoom.enable();
-      this.handlers.roll.enable();
-      this.handlers.pitch.enable();
     }
   }
   /**
@@ -6251,15 +6351,18 @@ class InteractionsSystem {
       if (isDragging || !hasListeners) return;
       const mousePointer = eventToCanvas(event);
       coordinatesSystem.canvasToNDC(mousePointer, this.mousePointerNDC);
-      if (!coordinatesSystem.ndcToWorld(this.mousePointerNDC, this.mousePointerWorld)) return;
-      const intersectionsByScene = this.viewportAccess.getIntersectedObjectsByScene(this.mousePointerNDC);
+      const raycastResults = this.viewportAccess.raycastByScene(this.mousePointerNDC);
       const data = [];
-      for (const { sceneId, intersections } of intersectionsByScene) {
-        const point = coordinatesSystem.worldToModel(this.mousePointerWorld, this.mousePointerModel, sceneId);
-        const defs = this.layerSystem.getIntersectedDefs(intersections);
+      for (const { sceneId, intersections } of raycastResults) {
+        const interactive = intersections.filter((i) => isInteractive(i.object));
+        const closestHit = interactive[0] ?? intersections[0];
+        const worldPoint = closestHit ? this.mousePointerWorld.copy(closestHit.point) : coordinatesSystem.ndcToWorldPlane(this.mousePointerNDC, this.mousePointerWorld);
+        if (!worldPoint) continue;
+        const point = coordinatesSystem.worldToModel(worldPoint, this.mousePointerModel, sceneId);
+        const defs = this.layerSystem.getIntersectedDefs(interactive);
         data.push({ point: { x: point.x, y: point.y }, defs, sceneId });
       }
-      this.events.emit(eventType, { event, data });
+      if (data.length > 0) this.events.emit(eventType, { event, data });
     };
     const mousemove = (event) => sharedMouseHandler("mousemove", event);
     const mouseout = (event) => sharedMouseHandler("mouseout", event);
@@ -6295,7 +6398,7 @@ class UpdatesSystem {
   constructor(ctx, layerSystem) {
     __publicField(this, "pendingDefs", /* @__PURE__ */ new Set());
     __publicField(this, "culledDefs", /* @__PURE__ */ new Set());
-    __publicField(this, "defBounds", new Box3());
+    __publicField(this, "defSphere", new Sphere());
     __publicField(this, "useUpdateBuffering", true);
     this.ctx = ctx;
     this.layerSystem = layerSystem;
@@ -6336,10 +6439,9 @@ class UpdatesSystem {
       let culled = false;
       this.pendingDefs.delete(def);
       if (isTextDef(def) || isImageDef(def)) {
-        const bounds = def.bounds;
-        this.defBounds.min.set(bounds.min.x, bounds.min.y, 0);
-        this.defBounds.max.set(bounds.max.x, bounds.max.y, 0);
-        culled = !frustum2.intersectsBox(this.defBounds);
+        const origin2 = isImageDef(def) ? def.origin : void 0;
+        computeBoundingSphere(def.bounds, origin2, this.defSphere);
+        culled = !frustum2.intersectsSphere(this.defSphere);
       }
       if (culled) this.culledDefs.add(def);
       else {
@@ -6384,8 +6486,8 @@ class InternalCameraSystem {
     const h = ctx.getDrawingBufferSizePx()[1];
     this.prevViewportHeightPx = h;
     this.camera = new PerspectiveCamera(this.defaultFov);
+    this.camera.up.set(0, 0, -1);
     this.controller = new CameraController(this.camera);
-    void this.controller.rotatePolarTo(0, false);
   }
   /** Current camera zoom factor. */
   get zoomFactor() {
@@ -6418,12 +6520,8 @@ class InternalCameraSystem {
   initCamera(viewbox) {
     this.zoomBounds = [0.1, viewbox.size.x > 1e4 ? 100 : 35];
     this.updateCamera();
-    this.camera.up.set(0, -1, 0);
-    this.camera.position.set(0, 0, -this.zoomIdentityDistance);
-    this.camera.lookAt(0, 0, 0);
+    this.controller.update(0);
     this.camera.updateMatrixWorld();
-    this.camera.up.set(0, 0, -1);
-    this.controller.updateCameraUp();
   }
   /** Updates the camera when the renderer size changes. */
   updateCamera() {
@@ -6435,8 +6533,7 @@ class InternalCameraSystem {
     const maxDistance = Math.abs(newZoomIdentity / this.zoomBounds[0]);
     const minDistance = Math.abs(newZoomIdentity / this.zoomBounds[1]);
     this.camera.aspect = w / (h || 1);
-    this.camera.near = 0.01;
-    this.camera.far = Math.max(maxDistance, this.camera.near) * 2;
+    this.camera.far = Math.max(maxDistance, 0.1) * 2;
     this.camera.updateProjectionMatrix();
     this.controller.minDistance = minDistance;
     this.controller.maxDistance = maxDistance;
@@ -6471,21 +6568,21 @@ class InternalCameraSystem {
   }
 }
 class PickingSystem {
-  /** */
   constructor() {
     __publicField(this, "raycaster", new Raycaster());
     __publicField(this, "ndcPoint", new Vector2());
     __publicField(this, "viewboxPlane", new Plane(new Vector3(0, 0, 1), 0));
-    this.raycaster.layers.set(INTERACTIVE_LAYER);
   }
   /**
-   * Gets the objects intersected by the raycaster.
+   * Raycasts the scene and returns all visible intersections sorted by distance.
+   * Does not filter by interaction layer — consumers are responsible for partitioning
+   * interactive vs non-interactive results using {@link isInteractive}.
    * @param ndcCoords raycast point in NDC (normalized device coordinates)
    * @param scene {@link Scene} instance
    * @param camera {@link Camera} instance
-   * @returns Array of {@link Intersection} instances
+   * @returns Array of {@link Intersection} instances, nearest first
    */
-  getIntersectedObjects(ndcCoords, scene, camera) {
+  raycast(ndcCoords, scene, camera) {
     this.setRaycasterFromCamera(ndcCoords, camera);
     const intersections = this.raycaster.intersectObject(scene, true);
     return intersections.filter((i) => isVisible(i.object));
@@ -6608,7 +6705,7 @@ class SceneSystem {
     const scaleFactor = Math.min(visibleRectSize.width, visibleRectSize.height);
     const { x: centerX, y: centerY } = viewbox.center;
     this.translationMatrix.makeTranslation(-centerX, -centerY, 0);
-    this.scaleMatrix.makeScale(scaleFactor, scaleFactor, 1);
+    this.scaleMatrix.makeScale(scaleFactor, scaleFactor, -1);
     targetMatrix.copy(this.translationMatrix).premultiply(this.scaleMatrix);
     const viewportRectCenter = this.tempVector2.copy(viewportRectPx.center);
     const offset = viewportRectCenter.sub({ x: bufferW / 2, y: bufferH / 2 });
@@ -6680,15 +6777,16 @@ class ViewportSystem {
     this.visibleRectCss = rect;
   }
   /**
-   * Get the objects intersected by the raycaster grouped by scene.
+   * Raycasts all loaded scenes and returns all visible intersections per scene.
+   * Results are not filtered by interaction layer — consumers partition as needed.
    * @param ndcCoords raycast point in NDC (normalized device coordinates)
-   * @returns Array of {@link IntersectionsWithinScene} instances
+   * @returns Array of {@link SceneRaycastResult} instances
    */
-  getIntersectedObjectsByScene(ndcCoords) {
+  raycastByScene(ndcCoords) {
     const result = [];
     for (const sceneState of this.sceneSystem.sceneStates) {
       if (!sceneState.loaded) continue;
-      const intersections = this.pickingSystem.getIntersectedObjects(ndcCoords, sceneState.scene, this.camera);
+      const intersections = this.pickingSystem.raycast(ndcCoords, sceneState.scene, this.camera);
       result.push({ intersections, sceneId: sceneState.id });
     }
     return result;
@@ -7046,7 +7144,6 @@ class Renderer {
         } else if (sceneState.scene.children.length === 0) {
           const root = this.layerSystem.buildScene(sceneState.sceneDef);
           scene.add(root);
-          if (this.isExternalMode) patchMatricesInExternalMode(scene);
         }
       }
       const justLoaded = loadedChanged && sceneState.loaded;
@@ -7054,6 +7151,7 @@ class Renderer {
       this.viewportSystem.updatePtScale(id);
       const hasDefsUpdated = this.updatesSystem.processPendingUpdates(frustum2, 3);
       const forceRedraw = hasControlsUpdated || hasDefsUpdated || justLoaded || this.isExternalMode || this.ui;
+      if (this.isExternalMode) patchMatricesInExternalMode(scene);
       if (this.needsRedraw || forceRedraw) this.renderer.render(scene, camera);
       if (hasDefsUpdated || this.needsRedraw) this.viewportSystem.invalidateSceneBounds(sceneState);
     }
@@ -7090,8 +7188,7 @@ class Renderer {
   }
   initScene(sceneDef, sceneId) {
     const root = this.layerSystem.buildScene(sceneDef);
-    const scene = this.viewportSystem.initScene(sceneDef, sceneId).add(root);
-    if (this.isExternalMode) patchMatricesInExternalMode(scene);
+    this.viewportSystem.initScene(sceneDef, sceneId).add(root);
   }
   // https://webgl2fundamentals.org/webgl/lessons/webgl-resizing-the-canvas.html
   resizeCanvasToDisplaySize() {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@expofp/renderer",
-  "version": "3.0.1",
+  "version": "3.1.0",
   "type": "module",
   "files": [
     "dist"