@expofp/renderer 3.34.2 → 3.35.1

package/dist/core/text/glyph-packing.d.ts

@@ -1,5 +1,5 @@
 import { type GlyphsGeometry, type TextRenderInfo } from 'troika-three-text';
-import { type TextExt } from './Text';
+import { type TextImpl } from './Text';
 /**
  * Rewrites a batch's glyph attributes from its members' render info.
  *
@@ -13,5 +13,5 @@ import { type TextExt } from './Text';
  * @returns The render info the batch should adopt as its own — any member's will do, since a batch
  *   shares one SDF atlas — or `undefined` when no member has synced.
  */
-export declare function packGlyphs(geometry: GlyphsGeometry, ordered: readonly number[], textAt: (memberId: number) => TextExt | undefined): TextRenderInfo | undefined;
+export declare function packGlyphs(geometry: GlyphsGeometry, ordered: readonly number[], textAt: (memberId: number) => TextImpl | undefined): TextRenderInfo | undefined;
 //# sourceMappingURL=glyph-packing.d.ts.map

package/dist/debug/components/Gui.d.ts

@@ -12,6 +12,8 @@ import { type PropsWithChildren } from 'react';
  * unmount/remount, the same element is re-attached and the scene's own effects
  * re-add their folders. Rendered as an ancestor of the scene, so on unmount
  * React tears the scene's folders down before this component destroys the panel.
+ * It also registers the panel's single change handler, which asks for a redraw. Every folder in the
+ * panel inherits it, so no controller carries one of its own.
  * @param props - Component props; `children` is the scene subtree that consumes
  *   the GUI via `useGui`.
  * @returns The children wrapped with the GUI provided through context.

package/dist/debug/components/Gui.js

@@ -1,5 +1,6 @@
 import { jsx as _jsx } from "react/jsx-runtime";
 import './Gui.module.css'; // Global overrides of lil-gui's stock styling (checkbox row layout).
+import { useThree } from '@react-three/fiber';
 import { GUI } from 'lil-gui';
 import { useEffect, useState } from 'react';
 import { GuiContext } from '../debug-context';
@@ -15,6 +16,8 @@ import { GuiContext } from '../debug-context';
  * unmount/remount, the same element is re-attached and the scene's own effects
  * re-add their folders. Rendered as an ancestor of the scene, so on unmount
  * React tears the scene's folders down before this component destroys the panel.
+ * It also registers the panel's single change handler, which asks for a redraw. Every folder in the
+ * panel inherits it, so no controller carries one of its own.
  * @param props - Component props; `children` is the scene subtree that consumes
  *   the GUI via `useGui`.
  * @returns The children wrapped with the GUI provided through context.
@@ -22,11 +25,18 @@ import { GuiContext } from '../debug-context';
 export function Gui(props) {
     const { children } = props;
     const [gui] = useState(() => new GUI({ autoPlace: false, closeFolders: true }));
+    const invalidate = useThree((state) => state.invalidate);
     useEffect(() => {
         gui.domElement.classList.add('lil-auto-place', 'autoPlace');
         document.body.appendChild(gui.domElement);
         gui.close();
+        // One handler for the whole panel: lil-gui walks a changed controller up its parent chain, so
+        // this fires for every controller in every folder and no folder registers its own. It calls
+        // whichever `invalidate` the current mount installed — in the external embed `ExternalCanvas`
+        // replaces it with the host's `requestFrame`, which is how a GUI change reaches a host that owns
+        // the frame.
+        gui.onChange(() => invalidate());
         return () => gui.destroy();
-    }, [gui]);
+    }, [gui, invalidate]);
     return _jsx(GuiContext, { value: gui, children: children });
 }

package/dist/events/layout-targets.d.ts

@@ -57,9 +57,13 @@ export interface LayoutTargets {
      * Two passes, in the legacy `UpdatesSystem`'s shape: the stale defs first, except that a hidden
      * def or one the frustum rejects is *deferred* rather than laid out; then the deferred ones, with
      * whatever budget is left. Priority is all deferral buys — every def is still laid out before the
-     * sweep ends, because whether a def draws can be exactly what its rule decides. The budget is
-     * checked before each def, so even a blown budget lays at least one out and a sweep can never
-     * stall.
+     * sweep ends, because whether a def draws can be exactly what its rule decides.
+     *
+     * **A drain always takes at least one def**, across the two passes together, however little
+     * budget is left — including none, which is what a worker descheduled before the first check
+     * leaves. That is what makes a sweep unable to stall: each drain shortens the backlog, so the
+     * frames the driver keeps asking for eventually end it. Without the guarantee a drain can dequeue
+     * nothing, return "more to do", and be asked again on the next frame with the same result.
      * @param frustum - The camera's frustum in plan space, when the caller has one; without it only
      *   hidden defs are deferred.
      * @param budgetMs - How much of the frame a call may spend. Non-positive means no limit.

package/dist/events/layout-targets.js

@@ -208,14 +208,25 @@ export function createLayoutTargets(invalidate, pixelSize, roll = 0) {
             if (pending.size === 0 && deferred.size === 0)
                 return false;
             const start = performance.now();
-            const overBudget = () => budgetMs > 0 && performance.now() - start >= budgetMs;
             let wrote = 0;
+            /**
+             * Defs this drain has taken off a queue, laid out or deferred.
+             *
+             * It gates the budget so that the **first** def of a drain is always taken. Without that, a
+             * budget already spent before the loop began — the worker descheduled between `start` and the
+             * check, which a loaded machine does routinely — dequeues nothing at all, and a drain that
+             * dequeues nothing is the stall this budget exists to prevent. Shared across both passes, so
+             * the guarantee is one def per drain rather than one per pass.
+             */
+            let processed = 0;
+            const overBudget = () => processed > 0 && budgetMs > 0 && performance.now() - start >= budgetMs;
             // Sets iterate in insertion order and tolerate deletion mid-walk, which is what makes the two
             // passes below plain loops: the order moves arrived is the priority within a pass, and a
             // processed def leaves its set before its rules run.
             for (const def of pending) {
                 if (overBudget())
                     break;
+                processed++;
                 pending.delete(def);
                 // Deferral is priority, never a skip: a hidden def, or one the camera cannot see, joins the
                 // second pass rather than being laid out now. `def.hidden` needs no frustum — hidden is not
@@ -230,6 +241,7 @@ export function createLayoutTargets(invalidate, pixelSize, roll = 0) {
             for (const def of deferred) {
                 if (overBudget())
                     break;
+                processed++;
                 deferred.delete(def);
                 if (layOutStale(def))
                     wrote++;

package/dist/external/ExternalCanvas.js

@@ -82,8 +82,7 @@ function mountExternal(context, requestFrame, onFrame) {
     camera.matrixAutoUpdate = false;
     camera.matrixWorldAutoUpdate = false;
     camera.manual = true;
-    // Constructed bare on purpose: the plan is drawn in three's own defaults — no tonemapping, sRGB
-    // output — and anything the renderer would opine on is left unset.
+    // Constructed bare on purpose: anything the renderer would opine on is left unset.
     const glRenderer = new WebGLRenderer({ canvas, context });
     // Never clear: the host's own layers are already on the canvas when this renderer draws.
     glRenderer.autoClear = false;
@@ -106,10 +105,10 @@ function mountExternal(context, requestFrame, onFrame) {
     void root
         .configure({
         gl: glRenderer,
-        // `flat` is not an opinion here but a shield: R3F's first configure force-writes
-        // `toneMapping` onto any renderer it is handed — ACES filmic unless flat — and flat is the
-        // one value that lands on three's own default, NoToneMapping. Everything else stays as the
-        // bare constructor left it.
+        // R3F force-writes ACES filmic tone mapping onto a fresh renderer unless `flat` is set, which
+        // is the one value landing on three's own default, `NoToneMapping`. This renderer does not
+        // tone map: `Lighting` keeps the rig's light sum in range by construction, rather than
+        // compressing an unbounded one back into range afterward.
         flat: true,
         // The cast widens past R3F's frustum-camera union; `manual` above is what keeps R3F's own
         // camera handling off it.

package/dist/external/external-camera.js

@@ -50,21 +50,34 @@ export function setExternalCameraProjection(camera, mainMatrix) {
     _mainInverse.copy(M).invert();
     _near.set(0, 0, 1).applyMatrix4(_mainInverse);
     _far.set(0, 0, -1).applyMatrix4(_mainInverse);
-    if (_near.distanceToSquared(_position) > _far.distanceToSquared(_position)) {
-        _direction.copy(_near).sub(_far).normalize();
+    const nearZ = _near.distanceToSquared(_position) <= _far.distanceToSquared(_position) ? 1 : -1;
+    if (nearZ === 1) {
+        _direction.copy(_far).sub(_near).normalize();
     }
     else {
-        _direction.copy(_far).sub(_near).normalize();
+        _direction.copy(_near).sub(_far).normalize();
     }
-    // Step 3: synthesize a rigid view matrix via look-at.
+    // Step 3: the camera's up axis, measured rather than chosen, and a rigid view matrix from it.
+    //
+    // Any up not parallel to the view direction gives a valid (P′, V′) pair for *drawing*, because P
+    // is recomputed from M · matrixWorld at the end and absorbs whatever roll V′ was given. The axis
+    // is also *read*, though: `Lighting` takes the plan's heading from the camera's up axis, so a
+    // chosen one aims the key light at an angle the host never had — a fixed world +z aimed it from
+    // the far side of the plan at every bearing, and every face turned toward the camera lost its
+    // direct light.
+    //
+    // Two points at one clip x and one clip z, one at the top of the screen and one at the bottom,
+    // differ by a vector along the camera's up axis alone: a constant clip z is a constant view-space
+    // z, so the forward components cancel and the difference is (0, Δy, 0) in view space. Clip y
+    // grows upward under every projection, maplibre's reverse-z included, so this reads none of the
+    // host's own conventions — and unlike a chosen axis it has no degenerate view to fall back from,
+    // since the axis it recovers is perpendicular to the view direction by construction.
     //
-    // The choice of "up" is arbitrary as long as it is not parallel to the view direction: any
-    // non-degenerate choice yields a valid (P′, V′) pair, because P is recomputed from
-    // M · matrixWorld at the end. The fallback handles top-down or bottom-up views where world +z
-    // aligns with the view ray.
-    _up.set(0, 0, 1);
-    if (Math.abs(_up.dot(_direction)) > 0.999)
-        _up.set(0, 1, 0);
+    // Unprojected at `nearZ`, the near plane's own clip z: a point there is finite under either z
+    // convention, which an interior z is not.
+    _screenTop.set(0, 1, nearZ).applyMatrix4(_mainInverse);
+    _screenBottom.set(0, -1, nearZ).applyMatrix4(_mainInverse);
+    _up.copy(_screenTop).sub(_screenBottom).normalize();
     _target.copy(_position).add(_direction);
     camera.matrixWorld.lookAt(_position, _target, _up);
     camera.matrixWorld.setPosition(_position);
@@ -84,5 +97,7 @@ const _position = new Vector3();
 const _near = new Vector3();
 const _far = new Vector3();
 const _direction = new Vector3();
+const _screenTop = new Vector3();
+const _screenBottom = new Vector3();
 const _target = new Vector3();
 const _up = new Vector3();

package/dist/index.d.ts

@@ -1,6 +1,7 @@
 export { type CameraAPI, type CameraAxes, type CameraState, type ControlsConfig, type InertiaConfig, type PanConfig, type RollConfig, type TransitionOptions, useCameraAPI, useCameraMoveStart, useCameraState, type ZoomToOptions, } from './controls';
 export { prepareDebug } from './debug/debug-chunk';
 export { useDebugPanel } from './debug/debug-context';
+export { type LightingProps, type ShadowProps } from './objects/lighting';
 export * from './Renderer';
 export { type CameraProps, type SmoothTime } from './space/Camera';
 export { type CanvasPoint, type CanvasPointLike, type PlanPoint, type PlanPointLike, } from './space/Space';

package/dist/objects/Background.js

@@ -2,7 +2,7 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { useState } from 'react';
 import { declareBeforeMain } from '../core/shader-source';
 import { ColorMaterial } from './materials/ColorMaterial';
-import { DIM_INHERIT, DIM_UNIFORM } from './materials/dim';
+import { DIM_INHERIT, DIM_UNIFORM } from './materials/effects/color-dim';
 /**
  * The scene's background: a screen-space quad drawn below every layer, replacing what a clear
  * color would paint — and unlike one, dimmed with the venue. The root `Layer` renders it inside

package/dist/objects/containers/SlotContainer.d.ts

@@ -5,8 +5,8 @@ import { type RenderableDef } from '../../types/defs';
 /**
  * What a container needs from the mesh it writes into.
  *
- * A capability rather than a union of our mesh classes: `BatchedMeshExt`, `InstancedMeshExt`,
- * `BatchedLinesExt` and `BatchedTextExt` share no base below `Object3D`, yet every one of them
+ * A capability rather than a union of our mesh classes: `BatchedMeshImpl`, `InstancedMeshImpl`,
+ * `BatchedLinesImpl` and `BatchedTextImpl` share no base below `Object3D`, yet every one of them
  * declares per-instance uniforms and hides an instance the same way — which is all a container
  * touches generically. Everything else it reaches through its own mesh type, which the subclass
  * names.
@@ -148,6 +148,8 @@ export declare abstract class SlotContainer<R, M extends SlotMesh = SlotMesh, T
     private readonly sortDirection;
     /** Set by {@link bind}, which runs before any effect can claim a slot. */
     private boundMesh;
+    /** What to run when a member turns out to belong in a sibling container; see {@link reportKindMismatch}. */
+    private kindMismatchHandler;
     /**
      * @param options - How this container differs from the default.
      */
@@ -201,6 +203,29 @@ export declare abstract class SlotContainer<R, M extends SlotMesh = SlotMesh, T
      * @returns The def, or `undefined` when the hit cannot be traced to one.
      */
     defFromHit(hit: Intersection): RenderableDef | undefined;
+    /**
+     * Registers what to do when a member turns out to belong in a sibling container; `undefined`
+     * clears it.
+     *
+     * Here rather than on each subclass because the situation is one situation: a layer is split
+     * across several containers by some property of the def, and that property can move after the def
+     * was placed. What splits them differs — a shape's color crossing alpha 1, a model's `opacity`,
+     * an image's orientation — but what a container does about it does not, and the component that
+     * owns the split is always the one that can repair 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 belongs in this container, so it is drawing from the wrong mesh.
+     * Runs the registered handler, if any; a container mounted without one — in a spec, or bare —
+     * drops the report rather than failing, since nothing it could do would be more correct than
+     * carrying on.
+     */
+    reportKindMismatch(): void;
     /**
      * Shows or hides one instance. Every def type carries `hidden`, so `useDefSync` drives this for
      * all of them.

package/dist/objects/containers/SlotContainer.js

@@ -1,4 +1,4 @@
-import { DIM_SCHEMA, DIM_UNIFORM, dimOrdered, instanceDim, isDimmed } from '../materials/dim';
+import { DIM_SCHEMA, DIM_UNIFORM, dimOrdered, instanceDim, isDimmed, } from '../materials/effects/color-dim';
 /**
  * One layer's mesh bookkeeping: the bound mesh, which slot each def holds, and the paint order
  * across them.
@@ -79,6 +79,8 @@ export class SlotContainer {
     sortDirection;
     /** Set by {@link bind}, which runs before any effect can claim a slot. */
     boundMesh;
+    /** What to run when a member turns out to belong in a sibling container; see {@link reportKindMismatch}. */
+    kindMismatchHandler;
     /**
      * @param options - How this container differs from the default.
      */
@@ -133,6 +135,12 @@ export class SlotContainer {
         // `setPaintOrder` defaults to 0 and the component's order pass relabels it in the same effect
         // flush, before anything draws.
         this.orderBySlot[slot] = this.orderByDef.get(def) ?? 0;
+        // Seeded here as well, so the instance's first `setDimAt` — every instance writes its dim as it
+        // mounts — reads the split it already draws on rather than `undefined`, and leaves the order
+        // pass to the structural one. Without it, mounting a layer of n defs runs n full order passes.
+        // A dim that arrives with the sync still crosses the split and still re-orders, and a claim
+        // made before the layer's own dim is known is relabelled by `setPaintOrder` in the same flush.
+        this.dimmedBySlot[slot] = isDimmed(def.dim, this.layerDimmed);
         return slot;
     }
     /**
@@ -169,6 +177,33 @@ export class SlotContainer {
     defFromHit(hit) {
         return this.defAt(hit.instanceId);
     }
+    /**
+     * Registers what to do when a member turns out to belong in a sibling container; `undefined`
+     * clears it.
+     *
+     * Here rather than on each subclass because the situation is one situation: a layer is split
+     * across several containers by some property of the def, and that property can move after the def
+     * was placed. What splits them differs — a shape's color crossing alpha 1, a model's `opacity`,
+     * an image's orientation — but what a container does about it does not, and the component that
+     * owns the split is always the one that can repair 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 belongs in this container, so it is drawing from the wrong mesh.
+     * Runs the registered handler, if any; a container mounted without one — in a spec, or bare —
+     * drops the report rather than failing, since nothing it could do would be more correct than
+     * carrying on.
+     */
+    reportKindMismatch() {
+        this.kindMismatchHandler?.();
+    }
     /**
      * Shows or hides one instance. Every def type carries `hidden`, so `useDefSync` drives this for
      * all of them.

package/dist/objects/containers/hooks.js

@@ -2,7 +2,7 @@ import { useThree } from '@react-three/fiber';
 import { use, useEffect, useRef, useState, useSyncExternalStore } from 'react';
 import { registerHitResolver } from '../../events/pointer';
 import { registerSlotWriter, subscribeDef, syncNow, versionOf } from '../../update';
-import { LayerDimContext } from '../materials/dim';
+import { LayerDimContext } from '../materials/effects/color-dim';
 /**
  * Creates one layer's container and keeps it wired to its layer for as long as the component is
  * mounted: the membership's paint order, and how hits on its mesh resolve back to defs.

package/dist/objects/containers/mesh-writes.d.ts

@@ -6,7 +6,7 @@ import { type Logger } from '../../utils/logging';
  * A mesh whose instances carry a transform.
  *
  * Named as a capability rather than listed as a union of our mesh classes, because not every batch
- * has one: `BatchedLinesExt` places its members by their endpoints and has no per-instance matrix
+ * has one: `BatchedLinesImpl` places its members by their endpoints and has no per-instance matrix
  * at all, yet still writes colors through the helper below. A class that satisfies only one of
  * these two interfaces is the point — the alternative was no-op matrix methods on a class that has
  * no transforms, which would read as a capability it does not have.

package/dist/objects/containers/props.d.ts

@@ -12,6 +12,16 @@ export interface DefsProps<T extends RenderableDef> {
      * updated.
      */
     defs: readonly T[];
+    /**
+     * How many of `defs` may mount their instances now, counted from the start of the list — the
+     * staged-mount slice, from `useStagedChildren`. Defaults to all of them, which is what a caller
+     * mounting a layer outside the scheduler wants.
+     *
+     * Only the instances are sliced. The container is still built, sized and paint-ordered from the
+     * whole of `defs`, so a growing prefix claims into buffers that were allocated once, and the
+     * order pass that labels them runs per membership change rather than per slice.
+     */
+    mounted?: number;
 }
 /** Props for a component keeping one def's instance in sync. */
 export interface InstanceProps<T extends RenderableDef, C> {

package/dist/objects/images/Images.js

@@ -35,6 +35,11 @@ import { TextureBudgetContext, useResizeFactor } from './texture-budget';
  */
 export function Images(props) {
     const { defs, maxAtlasSize } = props;
+    // Handed to each atlas as a prefix of *its* placements rather than apportioned between them, and
+    // a split source has several placements per def — so a slice mounts somewhere between one and a
+    // few instances per granted child. The scheduler measures what a slice cost and sizes the next
+    // one from that, which is what keeps the budget whatever the ratio turns out to be here.
+    const mounted = props.mounted ?? defs.length;
     const gl = useThree((state) => state.gl);
     const maxTextureSize = maxAtlasSize ?? gl.capabilities.maxTextureSize;
     // Repack when the *set* of images changes, via the "adjust state on prop change" pattern. The
@@ -48,7 +53,7 @@ export function Images(props) {
     if (!sameSet(packed.defs, defs)) {
         setPacked((current) => packImages(defs, maxTextureSize, current.generation + 1));
     }
-    return (_jsx(_Fragment, { children: packed.atlases.map((atlas) => (_jsx(ImageAtlas, { atlas: atlas, defs: defs }, atlasKey(atlas, packed.generation)))) }));
+    return (_jsx(_Fragment, { children: packed.atlases.map((atlas) => (_jsx(ImageAtlas, { atlas: atlas, defs: defs, mounted: mounted }, atlasKey(atlas, packed.generation)))) }));
 }
 /**
  * Draws one atlas as an `InstancedMesh`: the R3F-owned mesh with the atlas texture as its
@@ -67,6 +72,8 @@ export function Images(props) {
  */
 function ImageAtlas(props) {
     const { atlas, defs } = props;
+    // Only the placements are staged; the container and the texture are built from the whole atlas.
+    const mounted = props.mounted ?? atlas.images.length;
     const [texture] = useState(() => makeAtlasTexture(atlas.canvas));
     const container = useContainer(() => new ImageContainer(atlas), defs);
     const invalidate = useThree((state) => state.invalidate);
@@ -92,9 +99,9 @@ function ImageAtlas(props) {
     // rejecting its render reads.
     // The quad and the material are children so R3F creates, attaches, and disposes both — the args
     // pair are placeholders the constructor demands (see `ImageMeshArgs`). The material has to be per
-    // mesh: `InstancedMeshExt` wraps whatever it draws with in a closure over its own textures, and two
+    // mesh: `InstancedMeshImpl` wraps whatever it draws with in a closure over its own textures, and two
     // instanced meshes on one material would both render against the first one's.
-    return (_jsxs(_Fragment, { children: [_jsxs(InstancedMesh, { args: container.args, ref: (mesh) => container.bind(mesh), sortObjects: true, customSort: container.customSort, perObjectFrustumCulled: true, children: [_jsx("planeGeometry", {}), _jsx(TextureMaterial, { map: texture, uvOffset: UV_OFFSET_UNIFORM })] }), atlas.images.map((packed) => (_jsx(ImageInstance, { def: packed.def, packed: packed, container: container }, `${defKey(packed.def)}:${packed.uv.u0}:${packed.uv.v0}`)))] }));
+    return (_jsxs(_Fragment, { children: [_jsxs(InstancedMesh, { args: container.args, ref: (mesh) => container.bind(mesh), sortObjects: true, customSort: container.customSort, perObjectFrustumCulled: true, children: [_jsx("planeGeometry", {}), _jsx(TextureMaterial, { map: texture, uvOffset: UV_OFFSET_UNIFORM })] }), atlas.images.slice(0, mounted).map((packed) => (_jsx(ImageInstance, { def: packed.def, packed: packed, container: container }, `${defKey(packed.def)}:${packed.uv.u0}:${packed.uv.v0}`)))] }));
 }
 /**
  * Whether two snapshots hold the same *set* of images, order aside — the question "does this need a

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

@@ -1,4 +1,4 @@
-import { type InstancedMeshExt, type InstancedMeshExtParams } from '../../core/instanced/InstancedMesh';
+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';
@@ -15,16 +15,16 @@ export declare const UV_OFFSET_UNIFORM = "uvOffset";
  * R3F diffs `args` element-wise and rebuilds the object when any element changes, so this is
  * snapshotted once and never mutated.
  *
- * Only the options: `InstancedMeshExt` takes no geometry or material, seeding throwaways that the
+ * Only the options: `InstancedMeshImpl` takes no geometry or material, seeding throwaways that the
  * element's `<planeGeometry>` and `<TextureMaterial>` children replace (R3F creates, attaches, and
  * disposes those).
  */
-export type ImageMeshArgs = [params: InstancedMeshExtParams];
+export type ImageMeshArgs = [params: InstancedMeshImplParams];
 /**
  * One atlas's mesh bookkeeping.
  *
  * Simpler than a shape container, and deliberately so: an atlas draws one shared quad, so there is
- * no geometry cache and no geometry-id juggling, and `InstancedMeshExt` grows its own buffers, so
+ * no geometry cache and no geometry-id juggling, and `InstancedMeshImpl` grows its own buffers, so
  * there is no capacity pre-scan — the mesh is merely sized to the atlas's packed-image count and
  * left to resize itself if a claim ever overflows it. What remains is a slot per packed image and
  * the uv region each one samples, written once at claim since a def's source never changes.
@@ -34,7 +34,7 @@ export type ImageMeshArgs = [params: InstancedMeshExtParams];
  * change to the *set* of images is the harder case and still repacks into a fresh container —
  * packing has no incremental path for that — but a pure reorder does not.
  */
-export declare class ImageContainer extends SlotContainer<PackedImage, InstancedMeshExt, ImageDef> {
+export declare class ImageContainer extends SlotContainer<PackedImage, InstancedMeshImpl, ImageDef> {
     /** The constructor args R3F builds the mesh from; a frozen snapshot, never mutated. */
     readonly args: ImageMeshArgs;
     /**

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

@@ -1,6 +1,6 @@
 import { Vector4 } from 'three';
 import { SlotContainer } from '../containers';
-import { DIM_SCHEMA } from '../materials/dim';
+import { DIM_SCHEMA } from '../materials/effects/color-dim';
 /**
  * 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
@@ -13,7 +13,7 @@ export const UV_OFFSET_UNIFORM = 'uvOffset';
  * One atlas's mesh bookkeeping.
  *
  * Simpler than a shape container, and deliberately so: an atlas draws one shared quad, so there is
- * no geometry cache and no geometry-id juggling, and `InstancedMeshExt` grows its own buffers, so
+ * no geometry cache and no geometry-id juggling, and `InstancedMeshImpl` grows its own buffers, so
  * there is no capacity pre-scan — the mesh is merely sized to the atlas's packed-image count and
  * left to resize itself if a claim ever overflows it. What remains is a slot per packed image and
  * the uv region each one samples, written once at claim since a def's source never changes.

package/dist/objects/layer/Layer.js

@@ -5,7 +5,7 @@ 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/dim';
+import { LayerDimContext } from '../materials/effects/color-dim';
 import { Models } from '../models';
 import { Shapes } from '../shapes';
 import { Texts } from '../text';
@@ -64,7 +64,7 @@ function LayerNode(props) {
     // 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 { children, admitted } = useStagedChildren(layer);
+    const { children, mounted } = useStagedChildren(layer);
     useLayoutTargets(layer, children);
     const pointerProps = usePointerProps(layer, visible);
     let contents = null;
@@ -72,8 +72,8 @@ function LayerNode(props) {
         const childStep = orderStep / children.length;
         contents = children.map((child, index) => (_jsx(LayerNode, { layer: child, parentVisible: visible, orderBase: orderBase + index * childStep, orderStep: childStep }, child.name)));
     }
-    else if (admitted) {
-        contents = _jsx(LeafContent, { defs: children });
+    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
@@ -98,17 +98,17 @@ function LayerNode(props) {
  * @returns The container for the defs' kind.
  */
 function LeafContent(props) {
-    const { defs } = props;
+    const { defs, mounted } = props;
     let content = null;
     if (isShapeDefs(defs))
-        content = _jsx(Shapes, { defs: defs });
+        content = _jsx(Shapes, { defs: defs, mounted: mounted });
     else if (isImageDefs(defs))
-        content = _jsx(Images, { defs: defs });
+        content = _jsx(Images, { defs: defs, mounted: mounted });
     else if (isTextDefs(defs))
-        content = _jsx(Texts, { defs: defs });
+        content = _jsx(Texts, { defs: defs, mounted: mounted });
     else if (isLineDefs(defs))
-        content = _jsx(Lines, { defs: defs });
+        content = _jsx(Lines, { defs: defs, mounted: mounted });
     else if (isModelDefs(defs))
-        content = _jsx(Models, { defs: defs });
+        content = _jsx(Models, { defs: defs, mounted: mounted });
     return _jsx(Suspense, { fallback: null, children: content });
 }