@expofp/renderer 3.38.0 → 3.39.1

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 { memo, 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, useDimChain, useLayerOverlay, } from './layer-context';
 import { useStagedChildren } from './mount-scheduler';
 import { useVisibilityGui } from './visibility-gui';
 /**
@@ -17,15 +17,45 @@ 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(MemoLayerNode, { layer: layer, hidden: false, orderBase: 0, orderStep: 1, children: children }));
+}
+/**
+ * The content of one leaf layer: the container for its defs' kind, inside a Suspense boundary of
+ * the leaf's own.
+ *
+ * The boundary means a content component that suspends — a loader hook, a lazily imported one —
+ * costs this leaf alone. Without it the nearest boundary is the one R3F's `<Canvas>` wraps
+ * everything in, and falling back to it hides *every* object in the scene (R3F's `hideInstance`
+ * writes `visible = false`) while the admission queue stalls forever, since the leaf never commits
+ * and so never reports mounted. With it, a suspended leaf behaves exactly like an empty one: the
+ * layer still commits, still reports, the next leaf is admitted on schedule, and the content mounts
+ * when it resolves.
+ * @param props - The leaf's defs.
+ * @returns The container for the defs' kind.
+ */
+function LeafContent(props) {
+    const { defs, mounted } = props;
+    let content = null;
+    if (isShapeDefs(defs))
+        content = _jsx(Shapes, { defs: defs, mounted: mounted });
+    else if (isImageDefs(defs))
+        content = _jsx(Images, { defs: defs, mounted: mounted });
+    else if (isTextDefs(defs))
+        content = _jsx(Texts, { defs: defs, mounted: mounted });
+    else if (isLineDefs(defs))
+        content = _jsx(Lines, { defs: defs, mounted: mounted });
+    else if (isModelDefs(defs))
+        content = _jsx(Models, { defs: defs, mounted: mounted });
+    return _jsx(Suspense, { fallback: null, children: content });
 }
 /**
  * One layer of the tree as a three.js `<group>`, recursing into its child layers.
@@ -43,72 +73,62 @@ 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.
+ *
+ * **Dim is handed down as a source, and the node is rendered memoized.** An `update(layer)` renders this node
+ * alone: its child layers receive identical props, and the dim they inherit reaches its consumers
+ * through subscriptions to the layers themselves rather than a context value, so an eased dim — an update per frame
+ * on the root — renders one node instead of the whole tree.
  * @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 parentChain = useDimChain();
+    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 first, so the chain resolves to this layer's own dim when it declares one. Stable for a
+    // mounted layer, so the consumers below follow its dim by subscription, never by render.
+    const dimChain = [layer, ...parentChain];
+    // 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(MemoLayerNode, { 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: dimChain, children: _jsx(LayerOverlayContext, { value: overlay, children: group }) }));
 }
 /**
- * The content of one leaf layer: the container for its defs' kind, inside a Suspense boundary of
- * the leaf's own.
- *
- * The boundary means a content component that suspends — a loader hook, a lazily imported one —
- * costs this leaf alone. Without it the nearest boundary is the one R3F's `<Canvas>` wraps
- * everything in, and falling back to it hides *every* object in the scene (R3F's `hideInstance`
- * writes `visible = false`) while the admission queue stalls forever, since the leaf never commits
- * and so never reports mounted. With it, a suspended leaf behaves exactly like an empty one: the
- * layer still commits, still reports, the next leaf is admitted on schedule, and the content mounts
- * when it resolves.
- * @param props - The leaf's defs.
- * @returns The container for the defs' kind.
+ * {@link LayerNode}, memoized — what both the root and the recursion render, so an update renders
+ * the one node it names and its child layers bail out on equal props.
  */
-function LeafContent(props) {
-    const { defs, mounted } = props;
-    let content = null;
-    if (isShapeDefs(defs))
-        content = _jsx(Shapes, { defs: defs, mounted: mounted });
-    else if (isImageDefs(defs))
-        content = _jsx(Images, { defs: defs, mounted: mounted });
-    else if (isTextDefs(defs))
-        content = _jsx(Texts, { defs: defs, mounted: mounted });
-    else if (isLineDefs(defs))
-        content = _jsx(Lines, { defs: defs, mounted: mounted });
-    else if (isModelDefs(defs))
-        content = _jsx(Models, { defs: defs, mounted: mounted });
-    return _jsx(Suspense, { fallback: null, children: content });
-}
+const MemoLayerNode = memo(LayerNode);
+/**
+ * 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,74 @@
+import { type LayerDef } from '../../types/defs';
+/**
+ * The layers whose `dim` decides a subtree's, nearest first: the enclosing layer, then each of its
+ * ancestors. Nearest declaration wins, and a layer's own `0` un-dims it inside a dimmed ancestor.
+ *
+ * The chain rather than the resolved amount, because the amount animates — floorplan eases the
+ * venue's dim over 300ms, an `update(layer)` per frame — and a number in context re-rendered every
+ * consumer and every layer between on each of those frames. A chain never changes for a mounted
+ * layer, so the tree stays still: consumers read it with {@link resolveDim} and follow it with
+ * {@link subscribeDim}, which is the def store's own notification.
+ */
+export type DimChain = readonly LayerDef[];
+/**
+ * The dim amount a layer draws at, as a value, so the caller re-renders whenever it changes. A
+ * consumer that only writes the amount somewhere reads {@link useDimChain} and subscribes instead.
+ * @returns The nearest declared amount, or `0` with no layer above.
+ */
+export declare function useLayerDim(): number;
+/**
+ * The enclosing layer's {@link DimChain}, for consumers that follow the dim without rendering: a
+ * material writing it into a uniform, a container re-running paint order when it crosses zero.
+ * @returns The chain, empty outside any layer.
+ */
+export declare function useDimChain(): DimChain;
+/**
+ * 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;
+/**
+ * Resolves a chain's dim amount.
+ * @param chain - The layers, nearest first.
+ * @returns The nearest declared dim, or `0` when none declares one.
+ */
+export declare function resolveDim(chain: DimChain): number;
+/**
+ * Follows every `update()` of a chain's layers — each one a possible dim change. The listener
+ * compares for itself; a membership update reaches it too and changes nothing.
+ * @param chain - The layers, nearest first.
+ * @param listener - Called after an update of any of them.
+ * @returns The unsubscribe function.
+ */
+export declare function subscribeDim(chain: DimChain, listener: () => void): () => void;
+/**
+ * The {@link DimChain} 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} or {@link useDimChain} 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 an empty chain, which reads `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<DimChain>;
+/**
+ * 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,82 @@
+import { createContext, use, useSyncExternalStore } from 'react';
+import { subscribeDef } from '../../update';
+/**
+ * The dim amount a layer draws at, as a value, so the caller re-renders whenever it changes. A
+ * consumer that only writes the amount somewhere reads {@link useDimChain} and subscribes instead.
+ * @returns The nearest declared amount, or `0` with no layer above.
+ */
+export function useLayerDim() {
+    const chain = use(LayerDimContext);
+    return useSyncExternalStore((listener) => subscribeDim(chain, listener), () => resolveDim(chain));
+}
+/**
+ * The enclosing layer's {@link DimChain}, for consumers that follow the dim without rendering: a
+ * material writing it into a uniform, a container re-running paint order when it crosses zero.
+ * @returns The chain, empty outside any layer.
+ */
+export function useDimChain() {
+    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);
+}
+/**
+ * Resolves a chain's dim amount.
+ * @param chain - The layers, nearest first.
+ * @returns The nearest declared dim, or `0` when none declares one.
+ */
+export function resolveDim(chain) {
+    for (const layer of chain) {
+        if (layer.dim !== undefined)
+            return layer.dim;
+    }
+    return 0;
+}
+/**
+ * Follows every `update()` of a chain's layers — each one a possible dim change. The listener
+ * compares for itself; a membership update reaches it too and changes nothing.
+ * @param chain - The layers, nearest first.
+ * @param listener - Called after an update of any of them.
+ * @returns The unsubscribe function.
+ */
+export function subscribeDim(chain, listener) {
+    const unsubscribes = chain.map((layer) => subscribeDef(layer, listener));
+    return () => {
+        for (const unsubscribe of unsubscribes)
+            unsubscribe();
+    };
+}
+/**
+ * The {@link DimChain} 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} or {@link useDimChain} 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 an empty chain, which reads `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([]);
+/**
+ * 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, following the layer amount from {@link useDimChain}.
  *
  * 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
@@ -17,7 +17,8 @@ export type DimPatch = (parameters: WebGLProgramParametersWithUniforms) => void;
  *
  * The amount is held in one `IUniform` object per material and mutated in place, never replaced, so
  * an animated dim — floorplan eases the venue's dim over 300ms — costs a number per material per
- * frame with no recompile.
+ * frame with no recompile. The amount is followed by subscription, not read in render, so that frame
+ * renders nothing either.
  * @returns The patch to call from the material's `onBeforeCompile`.
  */
 export declare function useDimPatch(): DimPatch;
@@ -86,15 +87,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 { resolveDim, subscribeDim, useDimChain } from '../../layer/layer-context';
 /**
- * The dim patch every material installs, reading the layer amount from {@link LayerDimContext}.
+ * The dim patch every material installs, following the layer amount from {@link useDimChain}.
  *
  * 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
@@ -11,11 +12,12 @@ import { declareBeforeMain, sceneColorAnchor } from '../../../core/shader-source
  *
  * The amount is held in one `IUniform` object per material and mutated in place, never replaced, so
  * an animated dim — floorplan eases the venue's dim over 300ms — costs a number per material per
- * frame with no recompile.
+ * frame with no recompile. The amount is followed by subscription, not read in render, so that frame
+ * renders nothing either.
  * @returns The patch to call from the material's `onBeforeCompile`.
  */
 export function useDimPatch() {
-    const dim = use(LayerDimContext);
+    const chain = useDimChain();
     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
@@ -24,11 +26,18 @@ export function useDimPatch() {
     // Created once and kept: R3F writes every changed prop onto the material, so handing it a fresh
     // handler each render risks a recompile per frame — the one thing an animated dim must not cost.
     const [patch] = useState(() => (parameters) => applyDim(parameters, uniformRef.current));
-    const amount = clampDim(dim);
     useEffect(() => {
-        uniformRef.current.value = amount;
-        invalidate();
-    }, [amount, invalidate]);
+        /** Writes the layer's current amount into the uniform, and asks for a frame when it moved. */
+        function follow() {
+            const amount = clampDim(resolveDim(chain));
+            if (uniformRef.current.value === amount)
+                return;
+            uniformRef.current.value = amount;
+            invalidate();
+        }
+        follow();
+        return subscribeDim(chain, follow);
+    }, [chain, invalidate]);
     return patch;
 }
 /**
@@ -125,15 +134,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/ShapeInstance.js

@@ -24,8 +24,7 @@ const logger = createLogger('shape-instance');
  */
 export const ShapeInstance = memo(function ShapeInstance(props) {
     const { def, container } = props;
-    const geometry = container.geometryFor(def.shape);
-    useDefSync(container, def, geometry, (slot) => {
+    useDefSync(container, def, () => container.geometryFor(def.shape), (slot) => {
         writeMatrixIfChanged(container.mesh, slot, shapeToMatrix(def.shape));
         writeColorIfChanged(container.mesh, slot, def, logger);
         // Checked on every sync rather than only behind a color write, because a def leaves its batch's