@expofp/renderer 3.34.2 → 3.35.1

package/dist/objects/models/Models.js

@@ -5,6 +5,7 @@ import { InstancedMesh } from '../../core/instanced/InstancedMesh';
 import { sameSequence } from '../../utils/arrays';
 import { createLogger } from '../../utils/logging';
 import { defKey, useContainer } from '../containers';
+import { useOccluder } from '../lighting/occluder';
 import { ModelMaterial } from '../materials/ModelMaterial';
 import { loadModel } from './gltf-cache';
 import { MODEL_KINDS, ModelContainer, modelKindOf, OPACITY_UNIFORM, } from './model-container';
@@ -28,6 +29,10 @@ const logger = createLogger('models');
  */
 export function Models(props) {
     const { defs } = props;
+    // Handed to each part's mesh as a prefix of *its* members, the way `Shapes` hands one to each of
+    // its batches: a model layer is small and its meshes are few, and the scheduler sizes the next
+    // slice from what this one actually cost.
+    const mounted = props.mounted ?? defs.length;
     // The layer split two ways at once: by url, because that is what a mesh's geometry comes from,
     // and by kind, because `transparent` is a material property and a translucent copy of a model
     // therefore cannot share a mesh with an opaque one (see `modelKindOf`).
@@ -84,7 +89,7 @@ export function Models(props) {
                 const members = partition.batches[kind].get(asset.url);
                 if (!members)
                     return null;
-                return (_jsx(Fragment, { children: asset.parts.map((part) => (_jsx(ModelPartMesh, { asset: asset, part: part, defs: members, kind: kind, renderOrder: renderOrder, onKindMismatch: repartition }, part.id))) }, kind));
+                return (_jsx(Fragment, { children: asset.parts.map((part) => (_jsx(ModelPartMesh, { asset: asset, part: part, defs: members, mounted: mounted, kind: kind, renderOrder: renderOrder, onKindMismatch: repartition }, part.id))) }, kind));
             }) }, asset.url))) }));
 }
 /**
@@ -128,11 +133,14 @@ function emptied(previous) {
  */
 function ModelPartMesh(props) {
     const { asset, part, defs, kind, renderOrder, onKindMismatch } = props;
+    // Only the instances are staged; the container is sized and ordered from every member.
+    const mounted = props.mounted ?? defs.length;
     // Ordering is a no-op for models — their container declares it so, and the mesh depth-sorts itself
-    // instead — but the hit resolution is not: `InstancedMeshExt.raycast` walks the live slots,
+    // 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 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.
@@ -142,7 +150,7 @@ function ModelPartMesh(props) {
     }, [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 `InstancedMeshExt` never writes to the geometry it is handed: its draw list lives in
+    // safe because `InstancedMeshImpl` never writes to the geometry it is handed: its draw list lives in
     // a texture of its own, addressed by `gl_InstanceID`. The material cannot be shared the same way —
     // the mesh wraps it in a closure over its own textures — so `ModelMaterial` clones it per mesh.
     //
@@ -150,7 +158,15 @@ function ModelPartMesh(props) {
     // needs (see `ModelContainer.meshMatrix`); `matrixAutoUpdate` off because it is composed, not
     // decomposed from position/rotation/scale. `sortObjects` is what a depth-writing draw wants in
     // place of paint order — nearest first while opaque, farthest first once the material blends.
-    return (_jsxs(_Fragment, { children: [_jsxs(InstancedMesh, { args: container.args, ref: (mesh) => container.bind(mesh), matrixAutoUpdate: false, matrix: container.meshMatrix, sortObjects: true, renderOrder: renderOrder, children: [_jsx("primitive", { object: part.geometry, attach: "geometry", dispose: null }), _jsx(ModelMaterial, { source: part.material, opacityUniform: OPACITY_UNIFORM, translucent: kind === 'translucent' })] }), defs.map((def) => (_jsx(ModelInstance, { def: def, container: container }, defKey(def))))] }));
+    //
+    // The opaque mesh asks for occlusion, or a model would neither occlude nor be occluded; the
+    // translucent one stays out, because a surface you can see through must not cast full occlusion,
+    // and asks with `null` — which is also what a detaching `ref` says, so the layer number and the
+    // scene's registry are `useOccluder`'s alone.
+    return (_jsxs(_Fragment, { children: [_jsxs(InstancedMesh, { args: container.args, ref: (mesh) => {
+                    container.bind(mesh);
+                    occluder(kind === 'opaque' ? mesh : null);
+                }, matrixAutoUpdate: false, matrix: container.meshMatrix, sortObjects: true, renderOrder: renderOrder, children: [_jsx("primitive", { object: part.geometry, attach: "geometry", dispose: null }), _jsx(ModelMaterial, { source: part.material, opacityUniform: OPACITY_UNIFORM, translucent: kind === 'translucent' })] }), defs.slice(0, mounted).map((def) => (_jsx(ModelInstance, { def: def, container: container }, defKey(def))))] }));
 }
 /**
  * Loads one model, reporting a failure rather than rejecting — one missing model should not cost a

package/dist/objects/models/model-container.d.ts

@@ -1,6 +1,6 @@
 import { type Rect } from '@expofp/geometry';
 import { type Box3, Matrix4 } from 'three';
-import { type InstancedMeshExt, type InstancedMeshExtParams } from '../../core/instanced/InstancedMesh';
+import { type InstancedMeshImpl, type InstancedMeshImplParams } from '../../core/instanced/InstancedMesh';
 import { type ModelDef } from '../../types/defs';
 import { SlotContainer } from '../containers';
 /**
@@ -10,7 +10,7 @@ import { SlotContainer } from '../containers';
  */
 export declare const OPACITY_UNIFORM = "instanceOpacity";
 /** The constructor tuple R3F builds one model mesh from. Frozen, so R3F never rebuilds the mesh. */
-export type ModelMeshArgs = [params: InstancedMeshExtParams];
+export type ModelMeshArgs = [params: InstancedMeshImplParams];
 /**
  * Every kind of model batch, **in the order they draw within a layer** — which is what `Models`
  * numbers them by.
@@ -34,11 +34,11 @@ export declare function modelKindOf(def: ModelDef): ModelKind;
  * twenty copies of a chair are one draw call rather than twenty.
  *
  * Much simpler than a shape container. The geometry is the part's — shared, never per instance — so
- * there is no geometry cache and no capacity pre-scan, and `InstancedMeshExt` grows its own buffers,
+ * there is no geometry cache and no capacity pre-scan, and `InstancedMeshImpl` grows its own buffers,
  * so nothing here has to size anything. What is left is a slot per def and the transform each one
  * draws with.
  */
-export declare class ModelContainer extends SlotContainer<null, InstancedMeshExt, ModelDef> {
+export declare class ModelContainer extends SlotContainer<null, InstancedMeshImpl, ModelDef> {
     /** The constructor args R3F builds the mesh from; a frozen snapshot, never mutated. */
     readonly args: ModelMeshArgs;
     /** Which kind of member this container holds, and so which render list its mesh draws from. */
@@ -50,7 +50,6 @@ export declare class ModelContainer extends SlotContainer<null, InstancedMeshExt
     readonly meshMatrix: Matrix4;
     /** The model's bounds in plan units; every instance is fitted against them. */
     private readonly extents;
-    private kindMismatchHandler;
     /**
      * Builds the bookkeeping for one model part.
      * @param extents - The model's own bounds, y-up, as `bakeGltf` left them.
@@ -74,21 +73,6 @@ export declare class ModelContainer extends SlotContainer<null, InstancedMeshExt
      * quietly appear to order this one.
      */
     setPaintOrder(): void;
-    /**
-     * Registers what to do when a member turns out to be the wrong kind. `Models` supplies a re-split;
-     * `undefined` clears it.
-     *
-     * A method rather than an assignable field because the container is held in `useState`, and the
-     * React Compiler rejects writing to a property of a state value.
-     * @param handler - The re-split to run, or `undefined` to clear it.
-     */
-    setKindMismatchHandler(handler: (() => void) | undefined): void;
-    /**
-     * Reports that a member no longer matches {@link kind} — its `opacity` crossed 1 — so it is
-     * drawing from a mesh whose material describes the wrong render list. Runs the registered handler,
-     * if any; a container mounted outside `Models` has none and the report is simply dropped.
-     */
-    reportKindMismatch(): void;
     /**
      * Writes a def's placement into its slot: the model's extents fitted into `bounds`.
      *

package/dist/objects/models/model-container.js

@@ -1,6 +1,6 @@
 import { Matrix4, Quaternion, Vector3 } from 'three';
 import { SlotContainer } from '../containers';
-import { DIM_SCHEMA } from '../materials/dim';
+import { DIM_SCHEMA } from '../materials/effects/color-dim';
 /**
  * The per-instance uniform a model mesh reads its opacity from. The container owns the name: it
  * declares the schema on bind and writes each slot's value, and hands the name to `ModelMaterial`,
@@ -30,7 +30,7 @@ export function modelKindOf(def) {
  * twenty copies of a chair are one draw call rather than twenty.
  *
  * Much simpler than a shape container. The geometry is the part's — shared, never per instance — so
- * there is no geometry cache and no capacity pre-scan, and `InstancedMeshExt` grows its own buffers,
+ * there is no geometry cache and no capacity pre-scan, and `InstancedMeshImpl` grows its own buffers,
  * so nothing here has to size anything. What is left is a slot per def and the transform each one
  * draws with.
  */
@@ -46,7 +46,6 @@ export class ModelContainer extends SlotContainer {
     meshMatrix = PLAN_FROM_GLTF;
     /** The model's bounds in plan units; every instance is fitted against them. */
     extents;
-    kindMismatchHandler;
     /**
      * Builds the bookkeeping for one model part.
      * @param extents - The model's own bounds, y-up, as `bakeGltf` left them.
@@ -78,25 +77,6 @@ export class ModelContainer extends SlotContainer {
     setPaintOrder() {
         // Nothing: the depth buffer orders models, and a layer's parts are separate meshes regardless.
     }
-    /**
-     * Registers what to do when a member turns out to be the wrong kind. `Models` supplies a re-split;
-     * `undefined` clears it.
-     *
-     * A method rather than an assignable field because the container is held in `useState`, and the
-     * React Compiler rejects writing to a property of a state value.
-     * @param handler - The re-split to run, or `undefined` to clear it.
-     */
-    setKindMismatchHandler(handler) {
-        this.kindMismatchHandler = handler;
-    }
-    /**
-     * Reports that a member no longer matches {@link kind} — its `opacity` crossed 1 — so it is
-     * drawing from a mesh whose material describes the wrong render list. Runs the registered handler,
-     * if any; a container mounted outside `Models` has none and the report is simply dropped.
-     */
-    reportKindMismatch() {
-        this.kindMismatchHandler?.();
-    }
     /**
      * Writes a def's placement into its slot: the model's extents fitted into `bounds`.
      *

package/dist/objects/shapes/Shapes.js

@@ -2,6 +2,7 @@ import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-run
 import { useEffect, useState } from 'react';
 import { BatchedMesh } from '../../core/batch/BatchedMesh';
 import { defKey, useContainer } from '../containers';
+import { useOccluder } from '../lighting/occluder';
 import { ColorMaterial } from '../materials/ColorMaterial';
 import { SHAPE_KINDS, ShapeContainer, shapeKindOf } from './shape-container';
 import { ShapeInstance } from './ShapeInstance';
@@ -22,6 +23,11 @@ import { ShapeInstance } from './ShapeInstance';
  */
 export function Shapes(props) {
     const { defs } = props;
+    // Handed to each batch as a prefix of *its* members rather than apportioned between them: the
+    // batches are three at most, so a slice can overshoot the scheduler's budget by that factor at
+    // worst, and the scheduler measures what a slice actually cost and sizes the next one from it.
+    // Apportioning would cost a walk of the layer's defs per render to find where the prefix falls.
+    const mounted = props.mounted ?? defs.length;
     // Held in state rather than derived each render, the same "adjust on prop change" shape `Images`
     // uses for its pack — because the split has a second trigger besides `defs`. A def's color and its
     // shape are ordinary slot writes that never re-render this component, so either one crossing a
@@ -64,7 +70,7 @@ export function Shapes(props) {
             const members = batches[kind];
             if (!members)
                 return null;
-            return (_jsx(ShapeBatch, { defs: members, kind: kind, renderOrder: renderOrder, onKindMismatch: repartition }, kind));
+            return (_jsx(ShapeBatch, { defs: members, mounted: mounted, kind: kind, renderOrder: renderOrder, onKindMismatch: repartition }, kind));
         }) }));
 }
 /**
@@ -92,6 +98,8 @@ function partitionShapes(defs, mounted) {
  */
 function ShapeBatch(props) {
     const { defs, kind, renderOrder, onKindMismatch } = props;
+    // Only the instances are staged; the container is sized, reserved and ordered from every member.
+    const mounted = props.mounted ?? defs.length;
     // Sized from the first render's defs; membership changes grow the mesh in place, never rebuild
     // it. The container is bookkeeping plus CPU-side template geometries, so the copy StrictMode's
     // double-invoked initializer discards and the one an unmount strands are both plain garbage.
@@ -99,6 +107,7 @@ 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 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.
@@ -116,5 +125,14 @@ function ShapeBatch(props) {
     // claimed slot — `capacity` is a frozen snapshot, so that never happens. The `ref` arrow is
     // deliberate: `ref={container.bind}` would make the React Compiler infer `container` itself as a
     // ref and reject its render-time reads.
-    return (_jsxs(_Fragment, { children: [_jsx(BatchedMesh, { args: container.capacity, ref: (mesh) => container.bind(mesh), customSort: container.customSort, renderOrder: renderOrder, children: _jsx(ColorMaterial, { solid: kind !== 'planar', translucent: kind === 'translucent' }) }), defs.map((def) => (_jsx(ShapeInstance, { def: def, container: container }, defKey(def))))] }));
+    //
+    // The opaque volumes are what the depth prepass draws, so their batch asks for occlusion: the
+    // translucent ones stay out because a surface you can see through must not cast full occlusion,
+    // and the planar ones stay out because that is what keeps ambient occlusion and the contact
+    // shadow disjoint. A batch of either of those kinds asks with `null`, which is also what a
+    // detaching `ref` says — so the layer number and the scene's registry are `useOccluder`'s alone.
+    return (_jsxs(_Fragment, { children: [_jsx(BatchedMesh, { args: container.capacity, ref: (mesh) => {
+                    container.bind(mesh);
+                    occluder(kind === 'solid' ? mesh : null);
+                }, customSort: container.customSort, renderOrder: renderOrder, children: _jsx(ColorMaterial, { solid: kind !== 'planar', translucent: kind === 'translucent' }) }), defs.slice(0, mounted).map((def) => (_jsx(ShapeInstance, { def: def, container: container }, defKey(def))))] }));
 }

package/dist/objects/shapes/shape-container.d.ts

@@ -1,6 +1,6 @@
 import { type Shape } from '@expofp/geometry';
 import { type BufferGeometry, type Intersection } from 'three';
-import { type BatchedMeshExt } from '../../core/batch/BatchedMesh';
+import { type BatchedMeshImpl } from '../../core/batch/BatchedMesh';
 import { type RenderableDef, type ShapeDef } from '../../types/defs';
 import { SlotContainer } from '../containers';
 /**
@@ -21,7 +21,7 @@ export declare const SHAPE_KINDS: readonly ['planar', 'solid', 'translucent'];
  * One value rather than the `solid`/`translucent` pair it replaces. The pair could express a
  * translucent-but-flat batch, which nothing partitions for and no material describes, and it split
  * one fact across a field each reader needed and a field none did. This is also the "kind" that
- * {@link ShapeContainer.reportKindMismatch} and its handler have always named.
+ * {@link SlotContainer.reportKindMismatch} and its handler have always named.
  *
  * Derived from {@link SHAPE_KINDS} rather than listed again, so the two cannot drift.
  */
@@ -67,7 +67,7 @@ export declare function shapeKindOf(def: ShapeDef): ShapeKind;
  * which of its geometry ids each template was given. Building the templates is not its work either;
  * they come from {@link shapeGeometry}, which caches them across every container.
  */
-export declare class ShapeContainer extends SlotContainer<BufferGeometry, BatchedMeshExt, ShapeDef> {
+export declare class ShapeContainer extends SlotContainer<BufferGeometry, BatchedMeshImpl, ShapeDef> {
     /**
      * The mesh's constructor args, sized to hold the defs the container was created with exactly.
      * Passed as `<batchedMesh args={container.capacity}>`; R3F diffs `args` element-wise and a change
@@ -96,7 +96,6 @@ export declare class ShapeContainer extends SlotContainer<BufferGeometry, Batche
      * going to do anyway.
      */
     private readonly target;
-    private kindMismatchHandler;
     /**
      * Builds a shape layer's container, sized to hold `defs` exactly so a layer that mounts full never
      * reallocates. The mesh itself is R3F's: the component renders `<batchedMesh>` from
@@ -130,22 +129,6 @@ export declare class ShapeContainer extends SlotContainer<BufferGeometry, Batche
      * @param defs - The shapes this container is about to hold.
      */
     reserve(defs: readonly ShapeDef[]): void;
-    /**
-     * Registers what to do when a member turns out to be the wrong kind. `Shapes` supplies a re-split;
-     * `undefined` clears it.
-     *
-     * A method rather than an assignable field because the container is held in `useState`, and the
-     * React Compiler rejects writing to a property of a state value ("This value cannot be modified").
-     * Calling a method is fine, which is how {@link reserve} already mutates.
-     * @param handler - The re-split to run, or `undefined` to clear it.
-     */
-    setKindMismatchHandler(handler: (() => void) | undefined): void;
-    /**
-     * Reports that a member no longer matches {@link kind} — its color crossed alpha 1, or its shape
-     * was replaced with one of another kind — so it is drawing from the wrong batch. Runs the registered handler, if any;
-     * a container mounted outside `Shapes` has none and the report is simply dropped.
-     */
-    reportKindMismatch(): void;
     /**
      * A batched mesh reports the instance it hit as `batchId`, which is the slot this container
      * allocated.

package/dist/objects/shapes/shape-container.js

@@ -84,7 +84,6 @@ export class ShapeContainer extends SlotContainer {
      * going to do anyway.
      */
     target;
-    kindMismatchHandler;
     /**
      * Builds a shape layer's container, sized to hold `defs` exactly so a layer that mounts full never
      * reallocates. The mesh itself is R3F's: the component renders `<batchedMesh>` from
@@ -152,26 +151,6 @@ export class ShapeContainer extends SlotContainer {
         this.target.vertices = vertices;
         this.target.indices = indices;
     }
-    /**
-     * Registers what to do when a member turns out to be the wrong kind. `Shapes` supplies a re-split;
-     * `undefined` clears it.
-     *
-     * A method rather than an assignable field because the container is held in `useState`, and the
-     * React Compiler rejects writing to a property of a state value ("This value cannot be modified").
-     * Calling a method is fine, which is how {@link reserve} already mutates.
-     * @param handler - The re-split to run, or `undefined` to clear it.
-     */
-    setKindMismatchHandler(handler) {
-        this.kindMismatchHandler = handler;
-    }
-    /**
-     * Reports that a member no longer matches {@link kind} — its color crossed alpha 1, or its shape
-     * was replaced with one of another kind — so it is drawing from the wrong batch. Runs the registered handler, if any;
-     * a container mounted outside `Shapes` has none and the report is simply dropped.
-     */
-    reportKindMismatch() {
-        this.kindMismatchHandler?.();
-    }
     /**
      * A batched mesh reports the instance it hit as `batchId`, which is the slot this container
      * allocated.

package/dist/objects/text/Texts.js

@@ -31,11 +31,13 @@ import { TextInstance } from './TextInstance';
  */
 export function Texts(props) {
     const { defs } = props;
+    // Only the instances are staged; the container is built and ordered from the whole membership.
+    const mounted = props.mounted ?? defs.length;
     const invalidate = useThree((state) => state.invalidate);
     // The container is bookkeeping only — the members and the mesh are created against R3F's object —
     // so the copy StrictMode's double-invoked initializer discards is plain garbage.
     const container = useContainer(() => new TextContainer(invalidate), defs);
     // The `ref` arrow (not `ref={container.bind}`) keeps the React Compiler from inferring `container`
     // itself as a ref and rejecting its render-time reads.
-    return (_jsxs(_Fragment, { children: [_jsx(BatchedText, { ref: (mesh) => container.bind(mesh), children: _jsx(ColorMaterial, {}) }), defs.map((def) => (_jsx(TextInstance, { def: def, container: container }, defKey(def))))] }));
+    return (_jsxs(_Fragment, { children: [_jsx(BatchedText, { ref: (mesh) => container.bind(mesh), children: _jsx(ColorMaterial, {}) }), defs.slice(0, mounted).map((def) => (_jsx(TextInstance, { def: def, container: container }, defKey(def))))] }));
 }

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

@@ -1,12 +1,12 @@
 import { type Intersection } from 'three';
-import { type BatchedTextExt } from '../../core/text/BatchedText';
-import { TextExt } from '../../core/text/Text';
+import { type BatchedTextImpl } from '../../core/text/BatchedText';
+import { TextImpl } from '../../core/text/Text';
 import { type RenderableDef, type TextDef } from '../../types/defs';
 import { SlotContainer } from '../containers';
-/** One def's members: a `TextExt` per line, and the batch slot each of them occupies. */
+/** One def's members: a `TextImpl` per line, and the batch slot each of them occupies. */
 export interface LineGroup {
     /** The members, in the def's line order. */
-    readonly texts: readonly TextExt[];
+    readonly texts: readonly TextImpl[];
     /** Each member's batch slot, index-parallel to {@link texts}. */
     readonly slots: readonly number[];
 }
@@ -14,7 +14,7 @@ export interface LineGroup {
  * One text layer's bookkeeping: a group of members per def, and the paint order across them.
  *
  * The slot a def claims here is a **group**, not a batch member — a `TextDef` holds an array of
- * lines and each line is its own `TextExt`. That is the one place this differs from the shape and
+ * lines and each line is its own `TextImpl`. That is the one place this differs from the shape and
  * image containers, and it falls out of the def type rather than being a choice: the lines of one
  * def are laid out together (a centered block needs every line's height before it can place the
  * first), so they cannot be independent instances.
@@ -27,7 +27,7 @@ export interface LineGroup {
  * draw list, so {@link applyOrder} hands the batch a rebuilt member list instead of labeling slots,
  * and the inherited `customSort` goes unused.
  */
-export declare class TextContainer extends SlotContainer<number, BatchedTextExt, TextDef> {
+export declare class TextContainer extends SlotContainer<number, BatchedTextImpl, TextDef> {
     /** Groups by slot, with holes for released ones. */
     private readonly groups;
     private readonly freeGroups;

package/dist/objects/text/text-container.js

@@ -1,13 +1,13 @@
-import { TextExt } from '../../core/text/Text';
+import { TextImpl } from '../../core/text/Text';
 import { sameSequence } from '../../utils/arrays';
 import { SlotContainer } from '../containers';
-import { dimOrdered, isDimmed } from '../materials/dim';
+import { dimOrdered, isDimmed } from '../materials/effects/color-dim';
 import { LAYOUT_FONT_SIZE, LINE_HEIGHT } from './text-layout';
 /**
  * One text layer's bookkeeping: a group of members per def, and the paint order across them.
  *
  * The slot a def claims here is a **group**, not a batch member — a `TextDef` holds an array of
- * lines and each line is its own `TextExt`. That is the one place this differs from the shape and
+ * lines and each line is its own `TextImpl`. That is the one place this differs from the shape and
  * image containers, and it falls out of the def type rather than being a choice: the lines of one
  * def are laid out together (a centered block needs every line's height before it can place the
  * first), so they cannot be independent instances.
@@ -194,7 +194,7 @@ export class TextContainer extends SlotContainer {
  * @returns The member.
  */
 function makeMember() {
-    const text = new TextExt();
+    const text = new TextImpl();
     text.fontSize = LAYOUT_FONT_SIZE;
     text.lineHeight = LINE_HEIGHT;
     // Wrapping is the floorplan's job: it measures and breaks lines itself, then hands over the

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

@@ -1,5 +1,5 @@
 import { type Rect } from '@expofp/geometry';
-import { type TextExt } from '../../core/text/Text';
+import { type TextImpl } from '../../core/text/Text';
 import { type TextDef, type TextLineDef } from '../../types/defs';
 /**
  * The em size every member lays out at, fixed for its lifetime.
@@ -70,7 +70,7 @@ export declare function layoutText(def: TextDef): LaidOutLine[];
  * @param line - The line's local placement.
  * @param bounds - The def's bounds, supplying the rotation, center and elevation.
  */
-export declare function applyPlacement(text: TextExt, line: LaidOutLine, bounds: Rect): void;
+export declare function applyPlacement(text: TextImpl, line: LaidOutLine, bounds: Rect): void;
 /**
  * The height one line's box occupies.
  *

package/dist/space/Scene.d.ts

@@ -1,5 +1,6 @@
 import { type Box } from '@expofp/geometry';
 import { type ReactNode } from 'react';
+import { type LightingProps } from '../objects/lighting';
 import { type SceneDef } from '../types/defs';
 import { type CameraProps } from './Camera';
 /** Props for {@link Scene}: the scene to draw, plus the camera limits it passes straight down. */
@@ -15,6 +16,8 @@ export interface SceneProps extends CameraProps {
      * The part of the canvas the plan should be framed inside; see {@link RendererProps.visibleRect}.
      */
     visibleRect?: Box;
+    /** The lighting and darkening values a caller set; see {@link RendererProps.lighting}. */
+    lighting?: LightingProps;
     /**
      * Whether an external host owns the camera. When set, the scene mounts no {@link Camera} — and
      * with it no fit, no `visibleRect` framing and no camera commands: the view arrives from the

package/dist/space/Scene.js

@@ -6,7 +6,8 @@ import { Background } from '../objects/Background';
 import { TextureBudget, TextureBudgetContext } from '../objects/images/texture-budget';
 import { Layer } from '../objects/layer/index';
 import { createMountScheduler, MountSchedulerContext } from '../objects/layer/mount-scheduler';
-import { Lighting } from '../objects/Lighting';
+import { Lighting, OcclusionPasses } from '../objects/lighting';
+import { createSceneEffects, SceneEffectsContext, } from '../objects/materials/effects/effects-context';
 import { createLogger, printScene } from '../utils/logging';
 import { Camera } from './Camera';
 import { useCanvasSize } from './canvas-size';
@@ -26,14 +27,14 @@ const logger = createLogger('scene');
  * @returns The scene.
  */
 export function Scene(props) {
-    const { sceneDef, memoryLimit, visibleRect, external, children, ...cameraProps } = props;
+    const { sceneDef, memoryLimit, lighting, visibleRect, external, children, ...cameraProps } = props;
     const { viewbox, staticTransform } = sceneDef;
     useEffect(() => {
         if (visibleRect && staticTransform) {
             logger.warn('visibleRect is ignored for a scene with a staticTransform');
         }
     }, [visibleRect, staticTransform]);
-    const graph = (_jsx(SceneGraph, { sceneDef: sceneDef, memoryLimit: memoryLimit, children: children }));
+    const graph = (_jsx(SceneGraph, { sceneDef: sceneDef, memoryLimit: memoryLimit, lighting: lighting, children: children }));
     return (_jsx(PlanSpace, { sceneDef: sceneDef, children: external ? (graph) : (_jsxs(Camera, { ...cameraProps, children: [visibleRect && !staticTransform && _jsx(VisibleRect, { rect: visibleRect, viewbox: viewbox }), graph] })) }));
 }
 /**
@@ -78,7 +79,7 @@ function PlanSpace(props) {
  * @returns The graph.
  */
 function SceneGraph(props) {
-    const { sceneDef, memoryLimit, children } = props;
+    const { sceneDef, memoryLimit, lighting, children } = props;
     const { viewbox, staticTransform, rootLayer } = sceneDef;
     const { width, height, dpr } = useCanvasSize();
     const invalidate = useThree((state) => state.invalidate);
@@ -87,6 +88,17 @@ function SceneGraph(props) {
     // One budget for the scene's lifetime; the limit is synced rather than the budget rebuilt, so an
     // atlas's registration survives a `memoryLimit` change.
     const [budget] = useState(() => new TextureBudget(memoryLimit));
+    // One object for the scene's lifetime, published above both halves of the tree: the passes write
+    // into it and the lit materials inside the world group read it, and neither may import the other.
+    // The plan matrix uniform holds the space's own `matrixInverse`. The space recomputes that matrix
+    // in place on every refit and never replaces it, so a lit material reads the current fit with no
+    // copy, from its very first commit. Never write through `planFromWorld.value`, because the write
+    // lands in the space itself.
+    const [effects] = useState(() => {
+        const effects = createSceneEffects();
+        effects.planFromWorld.value = space.matrixInverse;
+        return effects;
+    });
     const worldRef = useRef(null);
     useLayoutEffect(() => {
         space.refit({ viewbox, width, height, dpr, staticTransform });
@@ -108,5 +120,5 @@ function SceneGraph(props) {
     useEffect(() => {
         printScene(sceneDef, logger.debug);
     }, [sceneDef]);
-    return (_jsxs(LayoutDriver, { children: [_jsxs("group", { name: "world", ref: worldRef, matrixAutoUpdate: false, matrix: space.matrix, children: [_jsx(Lighting, {}), _jsx(TextureBudgetContext, { value: budget, children: _jsx(MountSchedulerContext, { value: scheduler, children: _jsx(Layer, { layer: rootLayer, children: sceneDef.background !== undefined && _jsx(Background, { color: sceneDef.background }) }) }) })] }), children] }));
+    return (_jsx(SceneEffectsContext, { value: effects, children: _jsxs(LayoutDriver, { children: [_jsxs("group", { name: "world", ref: worldRef, matrixAutoUpdate: false, matrix: space.matrix, children: [_jsx(TextureBudgetContext, { value: budget, children: _jsx(MountSchedulerContext, { value: scheduler, children: _jsx(Layer, { layer: rootLayer, children: sceneDef.background !== undefined && _jsx(Background, { color: sceneDef.background }) }) }) }), _jsx(Lighting, { ...lighting })] }), _jsx(OcclusionPasses, {}), children] }) }));
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@expofp/renderer",
-  "version": "3.34.2",
+  "version": "3.35.1",
   "repository": {
     "type": "git",
     "url": "https://github.com/expofp/efp-app.git",
@@ -42,7 +42,7 @@
     "troika-three-text": "^0.52.5",
     "tslib": "^2.3.0",
     "webgl-memory": "^1.1.3",
-    "@expofp/geometry": "3.34.2"
+    "@expofp/geometry": "3.35.1"
   },
   "devDependencies": {
     "@react-three/test-renderer": "^9.1.0",

package/dist/objects/Lighting.d.ts

@@ -1,20 +0,0 @@
-/**
- * Scene lighting: a hemisphere fill from above the plan plus a directional key that follows the
- * camera, so a surface square-on to the viewer is shaded by exactly its own color (see
- * {@link HALF_ALBEDO}).
- *
- * Only lit materials see any of this — solid shape batches and models. Every 2D primitive draws
- * through a `MeshBasicMaterial`, so lines, text and images are unaffected by a light no matter what
- * the scene holds. That is deliberate: a route line or a booth label has no meaningful surface
- * normal, and shading one would make its color depend on where the camera is.
- *
- * **These sit inside the scene's world matrix**, so every direction below is expressed in the plan's
- * own space and taken there through {@link Space.matrixInverse} — one inverse, shared, rather than
- * one per light. Three reads a light's direction from where it ends up in the *world*, so the two
- * transforms cancel and the light points where it was aimed under any fit. The key light needs a
- * target inside the same space for that to hold: its direction is the difference of two world
- * positions, and only a target under the same matrix cancels the fit's translation.
- * @returns The fill and key lights, and the key's target.
- */
-export declare function Lighting(): import("react").JSX.Element;
-//# sourceMappingURL=Lighting.d.ts.map

package/dist/objects/Lighting.js

@@ -1,85 +0,0 @@
-import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { useFrame } from '@react-three/fiber';
-import { useLayoutEffect, useRef } from 'react';
-import { Color } from 'three';
-import { useSpace } from '../space/Space';
-/**
- * Scene lighting: a hemisphere fill from above the plan plus a directional key that follows the
- * camera, so a surface square-on to the viewer is shaded by exactly its own color (see
- * {@link HALF_ALBEDO}).
- *
- * Only lit materials see any of this — solid shape batches and models. Every 2D primitive draws
- * through a `MeshBasicMaterial`, so lines, text and images are unaffected by a light no matter what
- * the scene holds. That is deliberate: a route line or a booth label has no meaningful surface
- * normal, and shading one would make its color depend on where the camera is.
- *
- * **These sit inside the scene's world matrix**, so every direction below is expressed in the plan's
- * own space and taken there through {@link Space.matrixInverse} — one inverse, shared, rather than
- * one per light. Three reads a light's direction from where it ends up in the *world*, so the two
- * transforms cancel and the light points where it was aimed under any fit. The key light needs a
- * target inside the same space for that to hold: its direction is the difference of two world
- * positions, and only a target under the same matrix cancels the fit's translation.
- * @returns The fill and key lights, and the key's target.
- */
-export function Lighting() {
-    const fillRef = useRef(null);
-    const keyRef = useRef(null);
-    const targetRef = useRef(null);
-    const space = useSpace();
-    useLayoutEffect(() => {
-        keyRef.current.target = targetRef.current;
-    }, []);
-    // Taken from the camera's own backward axis rather than from the controls' target: only the
-    // direction matters for a directional light — the target below pins the other end — so this needs
-    // no access to `controls`, and unlike normalizing the camera's *position* it stays correct when
-    // the plan's coordinates are far from the origin, which SVG viewboxes routinely are.
-    //
-    // Column 2 of `matrixWorld` is that backward axis: where the light belongs, shining from the
-    // camera toward what it looks at. Read with `setFromMatrixColumn` rather than through
-    // `Camera.getWorldDirection`, which negates the axis and, worse, re-runs `updateWorldMatrix` —
-    // leaving the camera's `matrixWorldNeedsUpdate` set on every single call, which kept the scene
-    // perpetually dirty and no screenshot ever settled.
-    //
-    // Under the on-demand loop this runs only on frames something already asked for, and camera
-    // movement is what asks for them, so a still plan costs nothing.
-    useFrame((state) => {
-        keyRef.current.position
-            .setFromMatrixColumn(state.camera.matrixWorld, 2)
-            .transformDirection(space.matrixInverse);
-        // The plan's own up axis, as a point whose world position lands back on it — which is what three
-        // reads a hemisphere light's sky axis from. It is world -z either way, the side the camera is
-        // on: every path into world space ends with handedness flip.
-        //
-        // Computed here rather than memoized against the space because the space is refitted in place
-        // and so never changes identity — and it is four vector operations on a frame that was going to
-        // aim the key light anyway.
-        fillRef.current.position
-            .setFromMatrixColumn(space.matrix, 2)
-            .normalize()
-            .applyMatrix4(space.matrixInverse);
-    });
-    return (_jsxs(_Fragment, { children: [_jsx("hemisphereLight", { ref: fillRef, color: LIGHT_COLOR, groundColor: GROUND_COLOR, intensity: HALF_ALBEDO }), _jsx("directionalLight", { ref: keyRef, color: LIGHT_COLOR, intensity: HALF_ALBEDO }), _jsx("object3D", { ref: targetRef })] }));
-}
-/**
- * Each light's intensity, so the two together sum to `π`.
- *
- * three's diffuse BRDF is `albedo / π`, so a light of intensity `I` reaching a surface head-on
- * contributes `I · albedo / π`. At `0.5π` each contributes half the albedo, and the pair sums to
- * exactly the albedo — a surface facing the camera therefore renders at precisely the color the plan
- * author picked, and only faces turning away darken. The key light tracks the camera and the fill's
- * sky axis points at it too, so "facing the camera" is the same set of surfaces for both.
- *
- * Two things elsewhere are load-bearing for that identity rather than cosmetic: the lit material sets
- * `ior = 1` and `specularIntensity = 0`, which drive `F0` to zero so no specular lobe pushes a facing
- * surface *above* its albedo, and `<Canvas flat>` keeps tone mapping off, which would remap the
- * result. Change either and the identity quietly stops holding.
- */
-const HALF_ALBEDO = 0.5 * Math.PI;
-/**
- * Both lights' color — one shared constant, because the {@link HALF_ALBEDO} identity is a property
- * of the pair: two halves sum back to the author's color only when they are halves of the *same*
- * color. Each light copies it on mount, so writing to a light's own color never reaches the other.
- */
-const LIGHT_COLOR = new Color('white');
-/** The fill's ground half: pure black, so the side facing away from the sky axis adds nothing. */
-const GROUND_COLOR = new Color('black');