@expofp/renderer 3.38.0 → 3.39.0

package/dist/objects/images/image-container.d.ts

@@ -1,7 +1,7 @@
 import { type InstancedMeshImpl, type InstancedMeshImplParams } from '../../core/instanced/InstancedMesh';
 import { type ImageDef } from '../../types/defs';
 import { SlotContainer } from '../containers';
-import { type Atlas, type PackedImage } from './atlas-packer';
+import { type PackedImage } from './atlas-packer';
 /**
  * The per-instance uniform each atlas mesh reads its texture region from. The container owns the
  * name: it writes each slot's region here (`setUniformAt`) and hands it to the mesh's
@@ -42,9 +42,20 @@ export declare class ImageContainer extends SlotContainer<PackedImage, Instanced
      * component renders `<instancedMesh args={container.args}>` with the geometry and material as
      * children, and hands the mesh back through {@link SlotContainer.bind} — so R3F owns their
      * lifetimes, including disposal on unmount and survival across StrictMode's simulated remount.
-     * @param atlas - The packed atlas this container draws; only its image count sizes the mesh.
+     * @param capacity - How many instances to size the mesh for. This is the atlas's whole placement
+     *   count, not one kind's share of it, so moving a def between the two meshes never resizes a
+     *   buffer. The mesh grows past it on demand in any case.
      */
-    constructor(atlas: Atlas);
+    constructor(capacity: number);
+    /**
+     * Whether the bound mesh draws its members facing the camera.
+     *
+     * Read off the mesh rather than stored, so one field cannot disagree with another. `screenSpace` is
+     * an ordinary def field, so flipping it re-renders nothing and only an instance can notice that it
+     * is drawing from the wrong mesh.
+     * @returns Whether this container holds a sprite batch.
+     */
+    get facesCamera(): boolean;
     protected addInstance(packed: PackedImage): number;
     protected removeInstance(slot: number): void;
 }

package/dist/objects/images/image-container.js

@@ -1,4 +1,5 @@
 import { Vector4 } from 'three';
+import { isBatchedSprites } from '../../core/sprites/BatchedSprites';
 import { SlotContainer } from '../containers';
 import { DIM_SCHEMA } from '../materials/effects/color-dim';
 /**
@@ -31,11 +32,24 @@ export class ImageContainer extends SlotContainer {
      * component renders `<instancedMesh args={container.args}>` with the geometry and material as
      * children, and hands the mesh back through {@link SlotContainer.bind} — so R3F owns their
      * lifetimes, including disposal on unmount and survival across StrictMode's simulated remount.
-     * @param atlas - The packed atlas this container draws; only its image count sizes the mesh.
+     * @param capacity - How many instances to size the mesh for. This is the atlas's whole placement
+     *   count, not one kind's share of it, so moving a def between the two meshes never resizes a
+     *   buffer. The mesh grows past it on demand in any case.
      */
-    constructor(atlas) {
+    constructor(capacity) {
         super({ schema: IMAGE_SCHEMA });
-        this.args = [{ capacity: Math.max(1, atlas.images.length) }];
+        this.args = [{ capacity: Math.max(1, capacity) }];
+    }
+    /**
+     * Whether the bound mesh draws its members facing the camera.
+     *
+     * Read off the mesh rather than stored, so one field cannot disagree with another. `screenSpace` is
+     * an ordinary def field, so flipping it re-renders nothing and only an instance can notice that it
+     * is drawing from the wrong mesh.
+     * @returns Whether this container holds a sprite batch.
+     */
+    get facesCamera() {
+        return isBatchedSprites(this.mesh);
     }
     addInstance(packed) {
         // `addInstances` grows the buffers itself if the atlas ever overflows its sized capacity, so
@@ -65,6 +79,6 @@ export class ImageContainer extends SlotContainer {
 const IMAGE_SCHEMA = {
     vertex: { [UV_OFFSET_UNIFORM]: 'vec4', ...DIM_SCHEMA.vertex },
 };
-// Scratch for the one uv-region upload a claim performs, filled and read within a single
-// synchronous statement.
+// Scratch for the one uv-region upload a claim performs, filled and read within a single synchronous
+// statement.
 const _uvOffset = new Vector4();

package/dist/objects/layer/Layer.d.ts

@@ -5,10 +5,10 @@ export interface LayerProps {
     /** The layer definition to render, together with its descendants. */
     layer: LayerDef;
     /**
-     * Rendered inside the root group, before the tree's own content — under the root layer's dim
-     * provider, which is what the scene's background quad mounts here for: the root's dim reaches it
-     * like any layer's, and its material exists before every layer's, which its draw order relies
-     * on.
+     * Rendered inside the root group, before the tree's own content. This sits under the root
+     * layer's dim and overlay providers. The scene's background quad mounts here for that reason:
+     * the root's dim reaches it like any layer's, and its material exists before every layer's,
+     * which its draw order relies on.
      */
     children?: ReactNode;
 }
@@ -18,8 +18,9 @@ export interface LayerProps {
  * This root component owns the tree-wide concerns — in debug mode the layer-visibility GUI, a
  * "Main layers" folder for its direct child layers and a "Content layers" folder mirroring the
  * scheduler's leaf queue (see `visibility-gui.ts`) — and seeds the recursion {@link LayerNode}
- * carries: nothing above the root can hide it, and the whole tree's draw order lives inside
- * `[0, 1)`.
+ * carries with `hidden`, at `false`. Dim and overlay need no seed: `LayerDimContext` and
+ * `LayerOverlayContext` already default to undimmed and plan tier, which is what "no layer above
+ * me" means for either one. The whole tree's draw order lives inside `[0, 1)`.
  * @param props - The layer props.
  * @returns The tree's root group.
  */

package/dist/objects/layer/Layer.js

@@ -1,14 +1,14 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { Suspense, use } from 'react';
+import { Suspense } from 'react';
 import { useLayoutTargets } from '../../events/layout-targets';
 import { usePointerProps } from '../../events/pointer';
 import { isImageDefs, isLayerDefs, isLineDefs, isModelDefs, isShapeDefs, isTextDefs, } from '../../types/guards';
 import { Images } from '../images';
 import { Lines } from '../lines';
-import { LayerDimContext } from '../materials/effects/color-dim';
 import { Models } from '../models';
 import { Shapes } from '../shapes';
 import { Texts } from '../text';
+import { LayerDimContext, LayerOverlayContext, useLayerDim, useLayerOverlay, } from './layer-context';
 import { useStagedChildren } from './mount-scheduler';
 import { useVisibilityGui } from './visibility-gui';
 /**
@@ -17,15 +17,16 @@ import { useVisibilityGui } from './visibility-gui';
  * This root component owns the tree-wide concerns — in debug mode the layer-visibility GUI, a
  * "Main layers" folder for its direct child layers and a "Content layers" folder mirroring the
  * scheduler's leaf queue (see `visibility-gui.ts`) — and seeds the recursion {@link LayerNode}
- * carries: nothing above the root can hide it, and the whole tree's draw order lives inside
- * `[0, 1)`.
+ * carries with `hidden`, at `false`. Dim and overlay need no seed: `LayerDimContext` and
+ * `LayerOverlayContext` already default to undimmed and plan tier, which is what "no layer above
+ * me" means for either one. The whole tree's draw order lives inside `[0, 1)`.
  * @param props - The layer props.
  * @returns The tree's root group.
  */
 export function Layer(props) {
     const { layer, children } = props;
     useVisibilityGui(layer);
-    return (_jsx(LayerNode, { layer: layer, parentVisible: true, orderBase: 0, orderStep: 1, children: children }));
+    return (_jsx(LayerNode, { layer: layer, hidden: false, orderBase: 0, orderStep: 1, children: children }));
 }
 /**
  * One layer of the tree as a three.js `<group>`, recursing into its child layers.
@@ -43,45 +44,43 @@ export function Layer(props) {
  * whose membership depends on the camera re-derives it. From then on a pixel-size change reaches
  * those defs through the frame loop, with no render of this component involved.
  *
- * **Draw order is a group prop.** three propagates a group's `renderOrder` down its subtree as
- * `groupOrder`, which `painterSortStable` compares before `renderOrder` and `material.id` — so
- * numbering the groups is all it takes to make array order the draw order. A nested group
- * overwrites `groupOrder` for its own subtree, so the value that decides a mesh's place is its
- * nearest enclosing layer's; the numbers on layers above it are overwritten and simply do not
- * matter. Without this the order falls out of `material.id`, which ascends in mount order and
- * therefore puts any material built after first paint — every model's, since they exist only once
- * its GLB has loaded — last in the scene regardless of where its layer sits.
+ * Draw order is a pair: the tier, then the layer's own place. `overlay` adds a whole band above
+ * every plan-tier value. Array order still decides strictly within each band.
  * @param props - The node props.
  * @returns The `<group>` for a layer def.
  */
 function LayerNode(props) {
-    const { layer, children: prelude, parentVisible, orderBase, orderStep } = props;
-    // On screen only if nothing above hides it either — the value picking hangs off, and what the
-    // children inherit in turn.
-    const visible = parentVisible && !layer.hidden;
-    // Nearest declaration wins and reaches every material beneath through context — so only
-    // `undefined` inherits, and a layer's own `0` un-dims it inside a dimmed ancestor. Unlike
-    // visibility this is never a prop: nothing between here and the material has any use for it.
-    const inheritedDim = use(LayerDimContext);
-    const dim = layer.dim ?? inheritedDim;
+    const { layer, children: prelude, hidden: parentHidden, orderBase, orderStep } = props;
+    // What the nearest ancestor already resolved for dim and overlay. A layer cannot see its
+    // ancestors any other way.
+    const parentDim = useLayerDim();
+    const parentOverlay = useLayerOverlay();
+    // Once hidden or once in the overlay tier, a subtree stays that way. A descendant that dropped
+    // back into the plan tier would invert the nesting, and a descendant of a hidden layer is not on
+    // screen whatever it says about itself.
+    const hidden = parentHidden || layer.hidden === true;
+    const overlay = parentOverlay || layer.overlay === true;
+    // Nearest declaration wins, so only `undefined` inherits. A layer's own 0 un-dims it inside a
+    // dimmed ancestor.
+    const dim = layer.dim ?? parentDim;
+    // On screen only if nothing above hides it either. This is the value picking hangs off.
+    const visible = !hidden;
     const { children, mounted } = useStagedChildren(layer);
     useLayoutTargets(layer, children);
     const pointerProps = usePointerProps(layer, visible);
     let contents = null;
     if (isLayerDefs(children)) {
         const childStep = orderStep / children.length;
-        contents = children.map((child, index) => (_jsx(LayerNode, { layer: child, parentVisible: visible, orderBase: orderBase + index * childStep, orderStep: childStep }, child.name)));
+        contents = children.map((child, index) => (_jsx(LayerNode, { layer: child, hidden: hidden, orderBase: orderBase + index * childStep, orderStep: childStep }, child.name)));
     }
     else if (mounted > 0) {
         contents = _jsx(LeafContent, { defs: children, mounted: mounted });
     }
-    const group = (_jsxs("group", { name: layer.name, visible: !layer.hidden, renderOrder: orderBase, ...pointerProps, children: [prelude, contents] }));
-    // Always provided, never conditionally on the layer declaring a `dim`: making the provider appear
-    // when one is first set would change this component's element type, and React would remount the
-    // subtree — releasing and re-claiming every GPU slot beneath it, exactly what an eased dim must
-    // not do. A layer that declares none provides what it inherited, which no consumer can tell apart
-    // from not providing at all.
-    return _jsx(LayerDimContext, { value: dim, children: group });
+    const group = (_jsxs("group", { name: layer.name, visible: !layer.hidden, renderOrder: (overlay ? OVERLAY_TIER : PLAN_TIER) + orderBase, ...pointerProps, children: [prelude, contents] }));
+    // Always provided, never only when the layer declares one. Making a provider appear on first use
+    // would change this component's element type and remount the subtree, which releases and re-claims
+    // every GPU slot beneath it.
+    return (_jsx(LayerDimContext, { value: dim, children: _jsx(LayerOverlayContext, { value: overlay, children: group }) }));
 }
 /**
  * The content of one leaf layer: the container for its defs' kind, inside a Suspense boundary of
@@ -112,3 +111,14 @@ function LeafContent(props) {
         content = _jsx(Models, { defs: defs, mounted: mounted });
     return _jsx(Suspense, { fallback: null, children: content });
 }
+/**
+ * Where the plan's own layers are numbered from. The tree subdivides `[0, 1)` depth first, so the
+ * mantissa stays free for nesting.
+ */
+const PLAN_TIER = 0;
+/**
+ * Where an overlay subtree is numbered from, which puts it in `[1, 2)`. That is after every
+ * plan-tier layer, whatever renderOrder those layers hold. The whole cost is one bit of mantissa for
+ * subdivision.
+ */
+const OVERLAY_TIER = 1;

package/dist/objects/layer/layer-context.d.ts

@@ -0,0 +1,41 @@
+/**
+ * The dim amount a layer draws at, which every material beneath it reads.
+ * @returns The nearest provided amount, or `0` with no layer above.
+ */
+export declare function useLayerDim(): number;
+/**
+ * Whether the current layer draws in the overlay tier.
+ * @returns `true` if this layer or an ancestor opted into the overlay tier, `false` otherwise.
+ */
+export declare function useLayerOverlay(): boolean;
+/**
+ * The dim amount the current layer hands down to its descendants.
+ *
+ * Context rather than a prop, because the value crosses the whole subtree and concerns none of the
+ * components between. A container hands its material nothing about layers, and a material that
+ * never asked about them still dims correctly. Threading it as a prop would put a `dim` on every
+ * material, every container, and every one of their inner components.
+ *
+ * Read through {@link useLayerDim} instead of directly. A `LayerNode` provides it, always, never
+ * only when it declares a `dim` of its own. See `Layer.tsx` for why.
+ *
+ * Defaults to `0`, undimmed, which is what "no layer above me" means for a component rendered
+ * outside a `Layer` tree. A fourth inherited field belongs in a context and a hook of its own here,
+ * not folded into this one.
+ */
+export declare const LayerDimContext: import("react").Context<number>;
+/**
+ * Whether the current layer hands its overlay tier down to its descendants.
+ *
+ * Context rather than a prop, for the reason {@link LayerDimContext} is. It is also not a shading
+ * term, which is why `overlayParams`, the material parameters this tier unlocks, stays in
+ * `objects/materials/shared.ts` instead of moving here.
+ *
+ * Read through {@link useLayerOverlay} instead of directly. A `LayerNode` provides it, always,
+ * never only when it declares an `overlay` of its own. See `Layer.tsx` for why.
+ *
+ * Defaults to `false`, the plan tier, which is what "no layer above me" means for a component
+ * rendered outside a `Layer` tree.
+ */
+export declare const LayerOverlayContext: import("react").Context<boolean>;
+//# sourceMappingURL=layer-context.d.ts.map

package/dist/objects/layer/layer-context.js

@@ -0,0 +1,45 @@
+import { createContext, use } from 'react';
+/**
+ * The dim amount a layer draws at, which every material beneath it reads.
+ * @returns The nearest provided amount, or `0` with no layer above.
+ */
+export function useLayerDim() {
+    return use(LayerDimContext);
+}
+/**
+ * Whether the current layer draws in the overlay tier.
+ * @returns `true` if this layer or an ancestor opted into the overlay tier, `false` otherwise.
+ */
+export function useLayerOverlay() {
+    return use(LayerOverlayContext);
+}
+/**
+ * The dim amount the current layer hands down to its descendants.
+ *
+ * Context rather than a prop, because the value crosses the whole subtree and concerns none of the
+ * components between. A container hands its material nothing about layers, and a material that
+ * never asked about them still dims correctly. Threading it as a prop would put a `dim` on every
+ * material, every container, and every one of their inner components.
+ *
+ * Read through {@link useLayerDim} instead of directly. A `LayerNode` provides it, always, never
+ * only when it declares a `dim` of its own. See `Layer.tsx` for why.
+ *
+ * Defaults to `0`, undimmed, which is what "no layer above me" means for a component rendered
+ * outside a `Layer` tree. A fourth inherited field belongs in a context and a hook of its own here,
+ * not folded into this one.
+ */
+export const LayerDimContext = createContext(0);
+/**
+ * Whether the current layer hands its overlay tier down to its descendants.
+ *
+ * Context rather than a prop, for the reason {@link LayerDimContext} is. It is also not a shading
+ * term, which is why `overlayParams`, the material parameters this tier unlocks, stays in
+ * `objects/materials/shared.ts` instead of moving here.
+ *
+ * Read through {@link useLayerOverlay} instead of directly. A `LayerNode` provides it, always,
+ * never only when it declares an `overlay` of its own. See `Layer.tsx` for why.
+ *
+ * Defaults to `false`, the plan tier, which is what "no layer above me" means for a component
+ * rendered outside a `Layer` tree.
+ */
+export const LayerOverlayContext = createContext(false);

package/dist/objects/materials/ColorMaterial.js

@@ -1,10 +1,13 @@
 import { jsx as _jsx } from "react/jsx-runtime";
-import { useState } from 'react';
+import { useEffect, useState } from 'react';
+import { createLogger } from '../../utils/logging';
+import { useLayerOverlay } from '../layer/layer-context';
 import { applyAmbientOcclusion } from './effects/ao';
 import { useDimPatch } from './effects/color-dim';
 import { applyContactShadow } from './effects/contact-shadow';
 import { useSceneEffects } from './effects/effects-context';
-import { sharedParams } from './shared';
+import { overlayParams, sharedParams } from './shared';
+const logger = createLogger('color-material');
 /**
  * The material a shape batch draws with. It renders as a child of the mesh, so R3F attaches, updates
  * and disposes it. It is also troika's base material for text, which never asks for `solid`. See
@@ -76,6 +79,16 @@ export function ColorMaterial(props) {
     // skips the component in silence, so only the running app shows the failure.
     const color = props.color ?? 'white';
     const solid = props.solid === true;
+    const overlay = useLayerOverlay();
+    // Overlay is a contract for planar content. A volume that stops depth testing loses its own self
+    // occlusion, because its far faces then paint over its near ones in pack order. Making it work
+    // needs a depth clear between the tiers, so a second render pass, which external mode does not
+    // own. So a volume ignores the flag completely and says once that it did.
+    useEffect(() => {
+        if (solid && overlay) {
+            logger.warn('overlay has no effect on a solid batch, so it is ignored.');
+        }
+    }, [solid, overlay]);
     // Handed to both branches, because a volume dims the way flat content does. The patch runs on
     // whatever `gl_FragColor` the material arrived at, which for a lit material is the shaded color.
     const dimPatch = useDimPatch();
@@ -107,5 +120,5 @@ export function ColorMaterial(props) {
         const translucent = props.translucent ?? false;
         return (_jsx("meshLambertMaterial", { ...sharedParams, color: color, depthWrite: true, polygonOffset: false, transparent: translucent, forceSinglePass: !translucent, onBeforeCompile: onBeforeCompile }));
     }
-    return _jsx("meshBasicMaterial", { ...sharedParams, color: color, onBeforeCompile: onBeforeCompile });
+    return (_jsx("meshBasicMaterial", { ...sharedParams, ...(overlay ? overlayParams : null), color: color, onBeforeCompile: onBeforeCompile }));
 }

package/dist/objects/materials/LineMaterial.js

@@ -2,8 +2,9 @@ import { jsx as _jsx } from "react/jsx-runtime";
 import { extend } from '@react-three/fiber';
 import { NotEqualStencilFunc, ReplaceStencilOp, } from 'three';
 import { LineMaterial as LineMaterialBase } from 'three/addons/lines/LineMaterial.js';
+import { useLayerOverlay } from '../layer/layer-context';
 import { useDimPatch } from './effects/color-dim';
-import { sharedParams } from './shared';
+import { overlayParams, sharedParams } from './shared';
 /**
  * The stencil value a line layer stamps on every pixel it covers.
  *
@@ -55,6 +56,7 @@ export function LineMaterial(props) {
     const color = props.color ?? 'white';
     const width = props.width ?? 1;
     const onBeforeCompile = useDimPatch();
+    const overlay = useLayerOverlay();
     /**
      * Hands the batch about to draw a clean stencil to stamp.
      *
@@ -68,5 +70,5 @@ export function LineMaterial(props) {
     function onBeforeRender(renderer) {
         renderer.clearStencil();
     }
-    return (_jsx(LineMaterialElement, { ...sharedParams, color: color, linewidth: width, stencilWrite: true, stencilFunc: NotEqualStencilFunc, stencilZPass: ReplaceStencilOp, stencilRef: LINE_STENCIL_REF, onBeforeRender: onBeforeRender, onBeforeCompile: onBeforeCompile }));
+    return (_jsx(LineMaterialElement, { ...sharedParams, ...(overlay ? overlayParams : null), color: color, linewidth: width, stencilWrite: true, stencilFunc: NotEqualStencilFunc, stencilZPass: ReplaceStencilOp, stencilRef: LINE_STENCIL_REF, onBeforeRender: onBeforeRender, onBeforeCompile: onBeforeCompile }));
 }

package/dist/objects/materials/TextureMaterial.js

@@ -1,7 +1,8 @@
 import { jsx as _jsx } from "react/jsx-runtime";
 import { OneFactor } from 'three';
+import { useLayerOverlay } from '../layer/layer-context';
 import { useDimPatch } from './effects/color-dim';
-import { sharedParams } from './shared';
+import { overlayParams, sharedParams } from './shared';
 /**
  * The material used to render a texture, optionally through a per-instance uv-offset uniform so an
  * instanced/batched mesh can pack many regions into one atlas.
@@ -16,6 +17,7 @@ import { sharedParams } from './shared';
 export function TextureMaterial(props) {
     const { map, uvOffset } = props;
     const applyDim = useDimPatch();
+    const overlay = useLayerOverlay();
     function onBeforeCompile(parameters) {
         applyDim(parameters);
         if (!uvOffset)
@@ -35,5 +37,5 @@ export function TextureMaterial(props) {
     //
     // The override lives here, not in `sharedParams`, because `ColorMaterial` and `LineMaterial`
     // share that object and their colors are never premultiplied.
-    return (_jsx("meshBasicMaterial", { ...sharedParams, blendSrc: OneFactor, map: map, onBeforeCompile: onBeforeCompile }));
+    return (_jsx("meshBasicMaterial", { ...sharedParams, ...(overlay ? overlayParams : null), blendSrc: OneFactor, map: map, onBeforeCompile: onBeforeCompile }));
 }

package/dist/objects/materials/effects/color-dim.d.ts

@@ -8,7 +8,7 @@ import { type RenderableDef } from '../../../types/defs';
  */
 export type DimPatch = (parameters: WebGLProgramParametersWithUniforms) => void;
 /**
- * The dim patch every material installs, reading the layer amount from {@link LayerDimContext}.
+ * The dim patch every material installs, reading the layer amount from {@link useLayerDim}.
  *
  * Dimming is deliberately **not** a material prop. It cuts across every material and every def type,
  * so threading it as a prop would put a `dim` on each material, each container, and each of their
@@ -86,15 +86,6 @@ export declare function instanceDim(dim: number | undefined): number;
  * @returns The amount, within `[0, 1]`.
  */
 export declare function clampDim(dim: number): number;
-/**
- * The dim amount a layer draws at, which every material beneath it reads.
- *
- * Context rather than a prop because the value crosses the whole subtree and concerns none of the
- * components between: a container hands its material nothing, and a material that never asked about
- * layers still dims correctly. `Layer` provides it, and only when it declares a `dim` of its own —
- * a layer without one is transparent to this, which is exactly what inheritance means.
- */
-export declare const LayerDimContext: import("react").Context<number>;
 /**
  * The per-instance uniform a def's own dim is written to. Declared by every container that draws
  * dimmable defs and read by {@link DIM_APPLY}; the material owns the name, the mesh only has to

package/dist/objects/materials/effects/color-dim.js

@@ -1,8 +1,9 @@
 import { useThree } from '@react-three/fiber';
-import { createContext, use, useEffect, useRef, useState } from 'react';
+import { useEffect, useRef, useState } from 'react';
 import { declareBeforeMain, sceneColorAnchor } from '../../../core/shader-source';
+import { useLayerDim } from '../../layer/layer-context';
 /**
- * The dim patch every material installs, reading the layer amount from {@link LayerDimContext}.
+ * The dim patch every material installs, reading the layer amount from {@link useLayerDim}.
  *
  * Dimming is deliberately **not** a material prop. It cuts across every material and every def type,
  * so threading it as a prop would put a `dim` on each material, each container, and each of their
@@ -15,7 +16,7 @@ import { declareBeforeMain, sceneColorAnchor } from '../../../core/shader-source
  * @returns The patch to call from the material's `onBeforeCompile`.
  */
 export function useDimPatch() {
-    const dim = use(LayerDimContext);
+    const dim = useLayerDim();
     const invalidate = useThree((state) => state.invalidate);
     // A ref, not state: this object is written after render, every frame of an eased dim, and a ref is
     // the container React sanctions that for. Its identity is what three holds onto, so the value can
@@ -125,15 +126,6 @@ export function instanceDim(dim) {
 export function clampDim(dim) {
     return Math.min(Math.max(dim, 0), 1);
 }
-/**
- * The dim amount a layer draws at, which every material beneath it reads.
- *
- * Context rather than a prop because the value crosses the whole subtree and concerns none of the
- * components between: a container hands its material nothing, and a material that never asked about
- * layers still dims correctly. `Layer` provides it, and only when it declares a `dim` of its own —
- * a layer without one is transparent to this, which is exactly what inheritance means.
- */
-export const LayerDimContext = createContext(0);
 /**
  * The per-instance uniform a def's own dim is written to. Declared by every container that draws
  * dimmable defs and read by {@link DIM_APPLY}; the material owns the name, the mesh only has to

package/dist/objects/materials/effects/effects-context.d.ts

@@ -25,11 +25,12 @@ import { type ContactShadow } from './contact-shadow';
  * `contact-shadow.ts` uses for its three uniforms, published the way `SpaceContext` publishes a
  * `Space` that is refitted in place.
  *
- * **`LayerDimContext` stays where it is and is not merged in.** It carries a single number, it is
- * re-provided by every `Layer`, and it nests. This bundle is one object per renderer mount whose
- * identity must never change, which is what lets a material capture it in `onBeforeCompile` and a
- * frame write `.value` with no recompile. Merging the two would either re-provide this object at
- * every layer boundary or flatten dim's nesting.
+ * **`LayerDimContext` and `LayerOverlayContext` stay where they are and are not merged in.** Each
+ * carries one primitive of a layer's inherited state, is re-provided by every layer, and nests.
+ * This bundle is one object per renderer mount whose identity must never change, which is what
+ * lets a material capture it in `onBeforeCompile` and a frame write `.value` with no recompile.
+ * Merging either one in would either re-provide this object at every layer boundary or flatten
+ * that nesting.
  */
 export type SceneEffects = AmbientOcclusion & ContactShadow;
 /**

package/dist/objects/materials/shared.d.ts

@@ -3,4 +3,22 @@ import { type MaterialParameters } from 'three';
  * Material parameter defaults, shared between all types
  */
 export declare const sharedParams: MaterialParameters;
+/**
+ * What an overlay layer's planar materials add on top of {@link sharedParams}.
+ *
+ * Two obstacles, and render order clears neither.
+ *
+ * Depth. A solid shape sets `depthWrite: true`, so booth volumes fill the depth buffer. A planar def
+ * drawn later is still depth tested against them and loses. Turning the test off leaves order inside
+ * the tier as pure painter's order, because nothing in the tier writes depth.
+ *
+ * Pass. A translucent solid carries `transparent: true`, so it lives in three's transparent list.
+ * three draws that list after every opaque object, whatever render order says. An overlay that
+ * stayed in the opaque list would lose to a glass roof. So it opts back in. Inside the transparent
+ * list `reversePainterSortStable` compares `groupOrder` first, and the overlay tier's value of at
+ * least 1 beats every plan-tier value.
+ *
+ * `forceSinglePass` is not touched, so a double-sided overlay quad still blends once per pixel.
+ */
+export declare const overlayParams: MaterialParameters;
 //# sourceMappingURL=shared.d.ts.map

package/dist/objects/materials/shared.js

@@ -49,3 +49,24 @@ export const sharedParams = {
     polygonOffsetUnits: -FLAT_BIAS_UNITS,
     forceSinglePass: true,
 };
+/**
+ * What an overlay layer's planar materials add on top of {@link sharedParams}.
+ *
+ * Two obstacles, and render order clears neither.
+ *
+ * Depth. A solid shape sets `depthWrite: true`, so booth volumes fill the depth buffer. A planar def
+ * drawn later is still depth tested against them and loses. Turning the test off leaves order inside
+ * the tier as pure painter's order, because nothing in the tier writes depth.
+ *
+ * Pass. A translucent solid carries `transparent: true`, so it lives in three's transparent list.
+ * three draws that list after every opaque object, whatever render order says. An overlay that
+ * stayed in the opaque list would lose to a glass roof. So it opts back in. Inside the transparent
+ * list `reversePainterSortStable` compares `groupOrder` first, and the overlay tier's value of at
+ * least 1 beats every plan-tier value.
+ *
+ * `forceSinglePass` is not touched, so a double-sided overlay quad still blends once per pixel.
+ */
+export const overlayParams = {
+    depthTest: false,
+    transparent: true,
+};

package/dist/objects/models/Models.js

@@ -139,15 +139,8 @@ function ModelPartMesh(props) {
     // instead — but the hit resolution is not: `InstancedMeshImpl.raycast` walks the live slots,
     // skipping deleted and hidden ones, and raycasts the real merged geometry, so a hit names the
     // model's actual triangles and the slot that drew them.
-    const container = useContainer(() => new ModelContainer(asset.extents, defs.length, kind), defs);
+    const container = useContainer(() => new ModelContainer(asset.extents, defs.length, kind), defs, onKindMismatch);
     const occluder = useOccluder();
-    // Assigned after mount rather than passed to the constructor: the container is built once and
-    // outlives every render, so it cannot close over a current callback. Nothing can fire before this
-    // runs — the split that placed these defs was computed from the same opacities they mount with.
-    useEffect(() => {
-        container.setKindMismatchHandler(onKindMismatch);
-        return () => container.setKindMismatchHandler(undefined);
-    }, [container, onKindMismatch]);
     // The geometry belongs to the module-level cache and may be drawing in another layer, so it is
     // mounted as a `primitive` with `dispose={null}` — R3F must not free it on unmount. Sharing it is
     // safe because `InstancedMeshImpl` never writes to the geometry it is handed: its draw list lives in

package/dist/objects/shapes/Shapes.js

@@ -1,5 +1,5 @@
 import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { useEffect, useState } from 'react';
+import { useState } from 'react';
 import { BatchedMesh } from '../../core/batch/BatchedMesh';
 import { defKey, useContainer } from '../containers';
 import { useOccluder } from '../lighting/occluder';
@@ -106,15 +106,8 @@ function ShapeBatch(props) {
     //
     // Stickiness costs this nothing: a batch mounts on the render that first fills it, so the defs
     // sizing the container are a real membership rather than the empty one it may later stand at.
-    const container = useContainer(() => new ShapeContainer(defs, kind), defs);
+    const container = useContainer(() => new ShapeContainer(defs, kind), defs, onKindMismatch);
     const occluder = useOccluder();
-    // Assigned after mount rather than passed to the constructor: the container is built once and
-    // outlives every render, so it cannot close over a current callback. Nothing can fire before this
-    // runs — the split that placed these defs was computed from the same colors they mount with.
-    useEffect(() => {
-        container.setKindMismatchHandler(onKindMismatch);
-        return () => container.setKindMismatchHandler(undefined);
-    }, [container, onKindMismatch]);
     // Declares the incoming membership before React mounts the delta, so a change that outgrows the
     // mesh resizes each buffer once, to exactly this size, instead of once per claiming instance.
     // During render on purpose: instances claim in their mount effects, which run before any effect

package/dist/objects/text/TextInstance.js

@@ -77,7 +77,7 @@ function writeLine(mesh, lineSlot, text, line, placed, def) {
         writeColorAndOpacity(text, line.stroke.color, 'outline');
         text.outlineWidth = line.fontSize == 0 ? 0 : line.stroke.width / line.fontSize;
     }
-    applyPlacement(text, placed, def.bounds);
+    applyPlacement(text, placed, def.bounds, def.screenSpace === true);
 }
 function writeColorAndOpacity(text, color, field) {
     const colorFieldName = field == 'fill' ? 'color' : 'outlineColor';

package/dist/objects/text/text-layout.d.ts

@@ -61,16 +61,25 @@ export interface LaidOutLine {
  */
 export declare function layoutText(def: TextDef): LaidOutLine[];
 /**
- * Writes a laid-out line onto its member: the bounds' rotation and position applied to the local
+ * Writes a laid-out line onto its member: the bounds rotation and position applied to the local
  * offset, the line's scale, and its clip rect.
  *
- * The post-transform half of {@link layoutText}. `updateMatrix` is what reports the move to the
- * batch — members are not in the scene graph, so nothing else would.
+ * The post-transform half of `layoutText`. `updateMatrix` is what reports the move to the batch,
+ * because members are not in the scene graph and nothing else would.
+ *
+ * A screen-space def also gets its sprite anchor. That is the def's bounds center, shared by every
+ * line: each line's member sits at its own plan position, and pivoting each about itself would
+ * compress the stack under tilt. The anchor carries no elevation, because every line already sits at
+ * the def's own elevation on `position`, and `MemberTexture` reads it from there instead.
+ * `MemberTexture` then composes the member per draw, so `matrixAutoUpdate` goes off and the
+ * position, rotation and scale written here become the inputs that compose reads rather than the
+ * matrix itself.
  * @param text - The member to place.
  * @param line - The line's local placement.
  * @param bounds - The def's bounds, supplying the rotation, center and elevation.
+ * @param screenSpace - Whether the def faces the camera.
  */
-export declare function applyPlacement(text: TextImpl, line: LaidOutLine, bounds: Rect): void;
+export declare function applyPlacement(text: TextImpl, line: LaidOutLine, bounds: Rect, screenSpace: boolean): void;
 /**
  * The height one line's box occupies.
  *