@expofp/renderer 3.2.5 → 3.27.1

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

@@ -0,0 +1,227 @@
+import { Matrix4, Quaternion, Vector3 } from 'three';
+import { SlotContainer } from '../containers';
+import { DIM_SCHEMA } from '../materials/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`,
+ * which patches its shader to multiply by it.
+ */
+export const OPACITY_UNIFORM = 'instanceOpacity';
+/**
+ * Every kind of model batch, **in the order they draw within a layer** — which is what `Models`
+ * numbers them by.
+ */
+export const MODEL_KINDS = ['opaque', 'translucent'];
+/**
+ * Which batch a model belongs in: `translucent` exactly when its `opacity` is below 1.
+ *
+ * A partition rather than a per-instance flag, because `transparent` is a **material** property —
+ * three decides which render list an *object* belongs to, never which instance — so two copies of
+ * one model differing only in opacity cannot share a mesh. `opacity` is updatable, so a def can
+ * cross the boundary at any time; that is what `reportKindMismatch` is for.
+ * @param def - The model to classify.
+ * @returns The kind of batch it draws from.
+ */
+export function modelKindOf(def) {
+    return (def.opacity ?? 1) < 1 ? 'translucent' : 'opaque';
+}
+/**
+ * One model part's slot bookkeeping: every def in the layer drawing that part gets an instance, so
+ * 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,
+ * so nothing here has to size anything. What is left is a slot per def and the transform each one
+ * draws with.
+ */
+export class ModelContainer extends SlotContainer {
+    /** The constructor args R3F builds the mesh from; a frozen snapshot, never mutated. */
+    args;
+    /** Which kind of member this container holds, and so which render list its mesh draws from. */
+    kind;
+    /**
+     * What the mesh drawing this part must carry, so that three sees the mirror the plan's frame
+     * requires and {@link place}'s plan-space answers land where they say. See {@link PLAN_FROM_GLTF}.
+     */
+    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.
+     * @param count - How many defs the layer holds for this part, used as the mesh's initial capacity.
+     * @param kind - Which of the layer's batches this is; its material is built for that one alone.
+     */
+    constructor(extents, count, kind = 'opaque') {
+        super({ schema: MODEL_SCHEMA });
+        // Mapped once, here, so that everything below reads plan units — `fitToBounds` included.
+        this.extents = extents.clone().applyMatrix4(PLAN_FROM_GLTF);
+        this.kind = kind;
+        this.args = [{ capacity: Math.max(count, 1) }];
+    }
+    /**
+     * Paint order is not implemented for models, so this does nothing.
+     *
+     * Not an omission, and not a limitation either — the mesh takes a `customSort` like any other, and
+     * wiring the inherited pass to it would take a line. Def order is simply the wrong rule here. It
+     * is the 2D painter's rule, and it earns its keep only where nothing writes depth; a model does
+     * write depth, so which of two overlapping models is in front is settled by the depth buffer
+     * whatever order they draw in, and a *translucent* one wants farthest-first — depth order, which
+     * def order cannot express and which the mesh already applies for itself (`sortObjects`, see
+     * `Models`). Nor would def order reach across a layer: a model layer is one mesh per source
+     * material, and no sort inside a mesh orders a def against one drawn from another part.
+     *
+     * A no-op rather than the inherited pass, so a caller that orders every other layer kind does not
+     * quietly appear to order this one.
+     */
+    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`.
+     *
+     * The mesh carries {@link PLAN_FROM_GLTF}, so its instances are placed in the model's own space,
+     * while {@link fitToBounds} answers in the plan's. Conjugating moves the placement across — undo
+     * the mesh's map, place, redo it — and is unavoidable: the instance matrix is innermost, so
+     * anything the mesh applies outside it has to be taken back inside.
+     * @param slot - The instance's slot.
+     * @param def - The def supplying the bounds.
+     */
+    place(slot, def) {
+        this.mesh.setMatrixAt(slot, 
+        // Read right to left: into the plan, placed there, and back out again.
+        _placement
+            .multiplyMatrices(GLTF_FROM_PLAN, fitToBounds(this.extents, def.bounds))
+            .multiply(PLAN_FROM_GLTF));
+    }
+    /**
+     * Writes a def's opacity into its slot — **clamped to opaque unless this batch blends**.
+     *
+     * An opaque batch's material is `transparent: false`, which three answers by dropping
+     * `NormalBlending` to `NoBlending` (`WebGLState.setMaterial`). With blending off a fragment alpha
+     * below 1 is not composited but *written*, into a framebuffer the page shows through — so the
+     * model does not fade, it turns white.
+     *
+     * That is not a hypothetical: an opacity leaving 1 re-splits the layer, and until React commits it
+     * the def is still in this batch with its new opacity already written. Clamping is what makes the
+     * gap invisible — the model simply stays solid until the batch that can blend it takes over —
+     * without anything having to be fast enough.
+     * @param slot - The instance's slot.
+     * @param def - The def supplying the opacity.
+     */
+    setOpacity(slot, def) {
+        const opacity = this.kind === 'translucent' ? (def.opacity ?? 1) : 1;
+        this.mesh.setUniformAt(slot, OPACITY_UNIFORM, opacity);
+    }
+    addInstance() {
+        // `addInstances` grows the buffers itself if the layer outgrows its sized capacity, so there is
+        // nothing to pre-scan; the id comes back through the creation callback.
+        let slot = -1;
+        this.mesh.addInstances(1, (id) => {
+            slot = id;
+        });
+        return slot;
+    }
+    removeInstance(slot) {
+        this.mesh.removeInstances(slot);
+    }
+}
+/**
+ * Composes the transform that lands a baked model inside a def's bounds.
+ *
+ * The model is scaled uniformly — by the *smaller* of the two axis ratios, so it fits inside the
+ * rect rather than being stretched to it — then spun about z by the bounds' rotation and moved so its
+ * center sits at the bounds' center with its base at the bounds' elevation.
+ *
+ * Uniform scale is what keeps a model's proportions: a chair placed in a rect twice as wide as it is
+ * deep should not become a wide chair.
+ *
+ * Plan units throughout, in and out — {@link ModelContainer.place} is what carries the answer into
+ * the frame the mesh draws in.
+ * @param extents - The model's bounds, in plan units.
+ * @param bounds - Where the def wants it, in plan space.
+ * @returns The shared scratch matrix, composed. Valid until the next call.
+ */
+export function fitToBounds(extents, bounds) {
+    extents.getSize(_size);
+    extents.getCenter(_center);
+    const scale = Math.min(_size.x > 0 ? bounds.size.x / _size.x : 1, _size.y > 0 ? bounds.size.y / _size.y : 1);
+    // Centered on xy and sitting on its base in z, before anything else moves it.
+    _recenter.makeTranslation(-_center.x, -_center.y, -extents.min.z);
+    _position.set(bounds.center.x, bounds.center.y, bounds.elevation);
+    _quaternion.setFromAxisAngle(Z_AXIS, bounds.rotation);
+    _scale.setScalar(scale);
+    return _matrix.compose(_position, _quaternion, _scale).multiply(_recenter);
+}
+/**
+ * glTF → plan, and its own inverse.
+ *
+ * glTF is y-up with +z toward the viewer; the plan reads x right, y down, z up. Composed rather than
+ * written out as sixteen numbers because it *is* the pair legacy applies to a loaded scene — a mirror
+ * on y, then a quarter turn about x — and three composes a matrix as `T·R·S`, so the scale is the
+ * one that goes first: `(x, y, z)_gltf → (x, z, y)_plan`.
+ *
+ * The determinant is negative, and has to be: on screen the plan is left-handed — x right, y down, z
+ * toward the viewer — while glTF is right-handed, so the only maps between them that leave a model
+ * **unmirrored** are themselves mirrors.
+ *
+ * Which is why a **mesh** carries this and the geometry does not. three decides face orientation
+ * from `matrixWorld.determinant()` alone: a mirror baked into vertices is invisible to it and
+ * culling comes out inverted, drawing a closed model as a hollow shell; a mirror living only in the
+ * instance matrix is invisible to it too, and — worse — leaves the CPU raycaster correct while the
+ * rasterizer is wrong. The mesh transform is the one place three accounts for it.
+ *
+ * {@link ModelContainer.place} conjugates with it and with {@link GLTF_FROM_PLAN}.
+ */
+const PLAN_FROM_GLTF = new Matrix4()
+    .makeRotationX(-Math.PI / 2)
+    .multiply(new Matrix4().makeScale(1, -1, 1));
+/**
+ * Plan → glTF, the way back.
+ *
+ * It happens to equal {@link PLAN_FROM_GLTF} — swapping two axes twice returns you to where you
+ * started — so the inverse could be spelled with the same constant and cost nothing. It is not,
+ * because {@link ModelContainer.place} is a conjugation and should look like one: written with a
+ * single constant on both sides, it reads as an error, and it would quietly *become* one the day the
+ * mapping stops being its own inverse.
+ */
+const GLTF_FROM_PLAN = PLAN_FROM_GLTF.clone().invert();
+/**
+ * The schema the mesh declares so it can hold an {@link OPACITY_UNIFORM} and a dim per slot.
+ *
+ * Both in one call although the two come from different places: `InstanceUniforms.add` merges and
+ * rebuilds the backing texture, so declaring them separately would build it twice per bind.
+ */
+const MODEL_SCHEMA = {
+    fragment: { [OPACITY_UNIFORM]: 'float' },
+    vertex: { ...DIM_SCHEMA.vertex },
+};
+const Z_AXIS = new Vector3(0, 0, 1);
+const _size = new Vector3();
+const _center = new Vector3();
+const _position = new Vector3();
+const _scale = new Vector3();
+const _quaternion = new Quaternion();
+const _recenter = new Matrix4();
+const _matrix = new Matrix4();
+const _placement = new Matrix4();

package/dist/objects/shapes/ShapeInstance.d.ts

@@ -0,0 +1,26 @@
+import { type ShapeDef } from '../../types/defs';
+import { type InstanceProps } from '../containers';
+import { type ShapeContainer } from './shape-container';
+/** Props for {@link ShapeInstance}. */
+export type ShapeInstanceProps = InstanceProps<ShapeDef, ShapeContainer>;
+/**
+ * Keeps one shape's instance current: claims a slot on mount, writes the def's transform, color,
+ * and visibility on mount and after every `update(def)`, and releases the slot on unmount.
+ *
+ * Renders no scene node — the mesh belongs to the container. All shape-specific knowledge lives
+ * here rather than in the container, so "how does one `ShapeDef` become GPU state" is answered by
+ * the file you would open to ask it; visibility is the exception, because `hidden` is common to
+ * every def type and `useDefSync` writes it for all of them.
+ *
+ * Memoized at declaration, deliberately, despite the React Compiler: a structural change hands the
+ * layer a fresh `defs` snapshot, so its compiled cache rebuilds every instance element and
+ * element-identity bailout never applies — only `memo`'s prop-equality bailout keeps the unchanged
+ * siblings from re-rendering. The bailout works because both props are identity-stable across
+ * structural changes — paint order is deliberately not a prop; the container writes it for the
+ * whole sibling list in one pass (`useContainer`). Correctness never depends on the memo: without
+ * it every instance re-renders to the same result.
+ * @param props - The def and its container.
+ * @returns `null`; the instance lives in the mesh, not the scene graph.
+ */
+export declare const ShapeInstance: import("react").MemoExoticComponent<(props: ShapeInstanceProps) => null>;
+//# sourceMappingURL=ShapeInstance.d.ts.map

package/dist/objects/shapes/ShapeInstance.js

@@ -0,0 +1,40 @@
+import { memo } from 'react';
+import { createLogger } from '../../utils/logging';
+import { shapeToMatrix, useDefSync, writeColorIfChanged, writeMatrixIfChanged, } from '../containers';
+import { shapeKindOf } from './shape-container';
+const logger = createLogger('shape-instance');
+/**
+ * Keeps one shape's instance current: claims a slot on mount, writes the def's transform, color,
+ * and visibility on mount and after every `update(def)`, and releases the slot on unmount.
+ *
+ * Renders no scene node — the mesh belongs to the container. All shape-specific knowledge lives
+ * here rather than in the container, so "how does one `ShapeDef` become GPU state" is answered by
+ * the file you would open to ask it; visibility is the exception, because `hidden` is common to
+ * every def type and `useDefSync` writes it for all of them.
+ *
+ * Memoized at declaration, deliberately, despite the React Compiler: a structural change hands the
+ * layer a fresh `defs` snapshot, so its compiled cache rebuilds every instance element and
+ * element-identity bailout never applies — only `memo`'s prop-equality bailout keeps the unchanged
+ * siblings from re-rendering. The bailout works because both props are identity-stable across
+ * structural changes — paint order is deliberately not a prop; the container writes it for the
+ * whole sibling list in one pass (`useContainer`). Correctness never depends on the memo: without
+ * it every instance re-renders to the same result.
+ * @param props - The def and its container.
+ * @returns `null`; the instance lives in the mesh, not the scene graph.
+ */
+export const ShapeInstance = memo(function ShapeInstance(props) {
+    const { def, container } = props;
+    const geometry = container.geometryFor(def.shape);
+    useDefSync(container, def, geometry, (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
+        // kind two ways: its alpha crosses 1, or its `shape` is replaced with one of another kind.
+        // Neither re-renders this layer on its own — an update reaches the instance and stops there — so
+        // this is where a batch learns it is holding something it should not. `shapeKindOf` returns
+        // before it looks at the color for a planar shape, so a flat layer pays nothing for the check.
+        if (shapeKindOf(def) !== container.kind)
+            container.reportKindMismatch();
+    });
+    return null;
+});

package/dist/objects/shapes/Shapes.d.ts

@@ -0,0 +1,21 @@
+import { type ShapeDef } from '../../types/defs';
+import { type DefsProps } from '../containers';
+/** Props for {@link Shapes}. */
+export type ShapesProps = DefsProps<ShapeDef>;
+/**
+ * Draws a collection of shapes as instances of one `BatchedMesh`, so they render in a single draw
+ * call.
+ *
+ * The container owns the capacity, the geometry cache, and paint order; the mesh itself is created
+ * by R3F from the container's capacity and bound back through `ref`, so R3F owns its lifetime —
+ * including
+ * disposal on unmount and StrictMode's simulated remount, where the mesh survives because the
+ * element is never deleted. Each def gets a {@link ShapeInstance} that owns the writes for its own
+ * slot; refs attach before passive effects run, so the mesh is bound before the first claim.
+ * Membership is reconciled by React: a new `defs` array re-renders this component, and React mounts
+ * or unmounts exactly the defs that entered or left — there is no differ of our own.
+ * @param props - The shapes to draw.
+ * @returns The mesh and one instance component per shape.
+ */
+export declare function Shapes(props: ShapesProps): import("react").JSX.Element;
+//# sourceMappingURL=Shapes.d.ts.map

package/dist/objects/shapes/Shapes.js

@@ -0,0 +1,120 @@
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useEffect, useState } from 'react';
+import { BatchedMesh } from '../../core/batch/BatchedMesh';
+import { defKey, useContainer } from '../containers';
+import { ColorMaterial } from '../materials/ColorMaterial';
+import { SHAPE_KINDS, ShapeContainer, shapeKindOf } from './shape-container';
+import { ShapeInstance } from './ShapeInstance';
+/**
+ * Draws a collection of shapes as instances of one `BatchedMesh`, so they render in a single draw
+ * call.
+ *
+ * The container owns the capacity, the geometry cache, and paint order; the mesh itself is created
+ * by R3F from the container's capacity and bound back through `ref`, so R3F owns its lifetime —
+ * including
+ * disposal on unmount and StrictMode's simulated remount, where the mesh survives because the
+ * element is never deleted. Each def gets a {@link ShapeInstance} that owns the writes for its own
+ * slot; refs attach before passive effects run, so the mesh is bound before the first claim.
+ * Membership is reconciled by React: a new `defs` array re-renders this component, and React mounts
+ * or unmounts exactly the defs that entered or left — there is no differ of our own.
+ * @param props - The shapes to draw.
+ * @returns The mesh and one instance component per shape.
+ */
+export function Shapes(props) {
+    const { defs } = props;
+    // 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
+    // kind boundary would otherwise leave the def in a batch that no longer suits it. `repartition` is
+    // what the containers call when they notice. It is also what carries the mounted batches forward,
+    // so the updater form is load-bearing in both places: a re-split must not forget which exist.
+    const [partition, setPartition] = useState(() => partitionShapes(defs, {}));
+    if (partition.defs !== defs)
+        setPartition((current) => partitionShapes(defs, current.batches));
+    /** Re-splits the current membership, for a batch that found a member of the wrong kind. */
+    function repartition() {
+        setPartition((current) => partitionShapes(defs, current.batches));
+    }
+    const { batches } = partition;
+    // A batch is **sticky**: once mounted it stays, standing empty rather than unmounting when its
+    // last member leaves. A color whose alpha oscillates across 1 (a selection pulse) would otherwise
+    // tear down and rebuild a batch per crossing — a `ShapeContainer`, a `BatchedMesh` with its typed
+    // arrays and data textures, and a material whose compiled program three frees along with the last
+    // reference to it. Between two batches that both already exist, the same crossing is a
+    // `deleteInstance` and an `addInstance`. That is what an entry in `batches` means: the kind has
+    // held a member at some point, so its batch renders whether or not it holds one now.
+    //
+    // Mounting all three up front was rejected instead: the tax is the material, not the mesh, and it
+    // would fall on every shape layer of every plan, including the many with no solid content at all.
+    // Stickiness charges it once, and only to a layer that has actually held that kind. An emptied
+    // batch keeps its buffers, since the container never shrinks, and draws nothing — three's
+    // multi-draw path returns early at zero draws.
+    //
+    // `renderOrder` is each kind's place in `SHAPE_KINDS` rather than insertion order, for the reason
+    // layers carry one: these batches tie on `groupOrder`, so the tiebreak would fall to
+    // `material.id`, which ascends in *mount* order. A layer that starts with only solids and later
+    // gains a flat rect would mount the planar batch second, give it the higher id, and draw it after
+    // the solid — the inversion Phase 1 removed at layer level, reappearing one level down.
+    //
+    // The translucent batch's number barely matters on its own: `transparent: true` puts it in three's
+    // transparent list, drawn after every opaque object in the scene whatever the order says. It is
+    // numbered anyway so the intent reads correctly and so it still orders against any other
+    // translucent batch tying with it.
+    return (_jsx(_Fragment, { children: SHAPE_KINDS.map((kind, renderOrder) => {
+            const members = batches[kind];
+            if (!members)
+                return null;
+            return (_jsx(ShapeBatch, { defs: members, kind: kind, renderOrder: renderOrder, onKindMismatch: repartition }, kind));
+        }) }));
+}
+/**
+ * Splits a layer's shapes three ways — the flat ones, the opaque volumes, and the translucent
+ * volumes — by the same {@link shapeKindOf} an instance checks itself against.
+ * @param defs - The layer's shapes, in paint order.
+ * @param mounted - The batches already mounted, whose entries are carried forward emptied.
+ * @returns The membership and the batches to render, each still in paint order.
+ */
+function partitionShapes(defs, mounted) {
+    const batches = {};
+    for (const kind of SHAPE_KINDS)
+        if (mounted[kind])
+            batches[kind] = [];
+    for (const def of defs)
+        (batches[shapeKindOf(def)] ??= []).push(def);
+    return { defs, batches };
+}
+/**
+ * One `BatchedMesh` and its instances — a layer's flat shapes or its volumes, never both. It may
+ * hold none: `Shapes` keeps a batch mounted after its last member leaves, and an empty one draws
+ * nothing until a def of its kind arrives.
+ * @param props - The shapes, and which kind they are.
+ * @returns The mesh and one instance component per shape.
+ */
+function ShapeBatch(props) {
+    const { defs, kind, renderOrder, onKindMismatch } = props;
+    // 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.
+    //
+    // 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);
+    // Assigned after mount rather than passed to the constructor: the container is built once and
+    // outlives every render, so it cannot close over a current callback. Nothing can fire before this
+    // runs — the split that placed these defs was computed from the same colors they mount with.
+    useEffect(() => {
+        container.setKindMismatchHandler(onKindMismatch);
+        return () => container.setKindMismatchHandler(undefined);
+    }, [container, onKindMismatch]);
+    // Declares the incoming membership before React mounts the delta, so a change that outgrows the
+    // mesh resizes each buffer once, to exactly this size, instead of once per claiming instance.
+    // During render on purpose: instances claim in their mount effects, which run before any effect
+    // of this component could — and the call writes idempotent bookkeeping, so a repeated or
+    // discarded render is harmless.
+    container.reserve(defs);
+    // `args` is diffed element-wise and a change would dispose and rebuild the mesh, orphaning every
+    // 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))))] }));
+}

package/dist/objects/shapes/index.d.ts

@@ -0,0 +1,2 @@
+export { Shapes, type ShapesProps } from './Shapes';
+//# sourceMappingURL=index.d.ts.map

package/dist/objects/shapes/index.js

@@ -0,0 +1 @@
+export { Shapes } from './Shapes';

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

@@ -0,0 +1,165 @@
+import { type Shape } from '@expofp/geometry';
+import { type BufferGeometry, type Intersection } from 'three';
+import { type BatchedMeshExt } from '../../core/batch/BatchedMesh';
+import { type RenderableDef, type ShapeDef } from '../../types/defs';
+import { SlotContainer } from '../containers';
+/**
+ * Every kind of shape batch, **in the order they draw within a layer** — which is what `Shapes`
+ * takes each batch's `renderOrder` from, so this list is the one place that order is stated.
+ *
+ * Solids draw after the flat shapes, so a volume occludes the flat content of its own layer rather
+ * than being painted over by it — the same rule that governs whole layers, applied within one.
+ */
+export declare const SHAPE_KINDS: readonly ['planar', 'solid', 'translucent'];
+/**
+ * Which of a layer's three shape batches a def belongs in, and what that batch is for:
+ *
+ * - `planar` — flat content: unlit, no depth writes, placed by draw order alone.
+ * - `solid` — opaque volumes: lit and depth-writing, drawn in the ordered stream.
+ * - `translucent` — the same volumes, drawn in three's transparent pass.
+ *
+ * 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.
+ *
+ * Derived from {@link SHAPE_KINDS} rather than listed again, so the two cannot drift.
+ */
+export type ShapeKind = (typeof SHAPE_KINDS)[number];
+/**
+ * The batch a def belongs in.
+ *
+ * A shape is **solid** exactly when it is a `Mesh` whose vertices span more than one z — elevation is
+ * placement, not volume, so a quad or a lifted-but-flat mesh stays planar and is placed correctly by
+ * draw order alone. A solid is **translucent** when its color carries an alpha below 1. That has to
+ * be a partition rather than a per-instance flag because `transparent` is a *material* property:
+ * three decides which render list an object belongs to, never which instance, so two solids of
+ * differing transparency cannot share a mesh.
+ *
+ * **Only volumes split on translucency.** A flat shape with an alpha below 1 stays `planar`, because
+ * flat content already blends without leaving the opaque list: `sharedParams` reaches alpha blending
+ * through `CustomBlending` rather than through `transparent: true`, which three honors either way,
+ * and nothing planar writes depth. So array order is the whole of it — a translucent flat shape
+ * blends over whatever precedes it, and an opaque one authored later paints straight over it. That
+ * last part is a capability, not an accident: ordering an opaque fill after a translucent one is how
+ * a caller occludes it, and a batch of its own would take that away by forcing it after every opaque
+ * object in the scene, where nothing in its layer could cover it again.
+ *
+ * A volume has no such freedom. It writes depth and is depth-tested, so what ends up on top is the
+ * depth buffer's answer rather than the author's, and blending correctly means being drawn after the
+ * opaque content it blends with — which is a render pass, and therefore a batch.
+ *
+ * One function rather than a predicate in `Shapes` that places a def and another in `ShapeInstance`
+ * that notices it no longer belongs. Those are the same question, and two expressions of it can
+ * drift — a def placed by one rule and checked by the other would either sit in the wrong batch or
+ * ask to be re-split forever. A planar shape returns before the color is looked at, so the parse
+ * costs nothing on the many layers holding only flat content.
+ * @param def - The def to classify.
+ * @returns The kind of batch it draws from.
+ */
+export declare function shapeKindOf(def: ShapeDef): ShapeKind;
+/**
+ * One shape layer's mesh bookkeeping: reserved buffer space, slot allocation, which geometries the
+ * mesh has registered, and the paint-order table.
+ *
+ * Slot allocation is the mesh's own — `addInstance`/`deleteInstance` maintain its free list — so
+ * what this adds is what the mesh will not track: how much vertex and index space is reserved, and
+ * 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> {
+    /**
+     * 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
+     * disposes and rebuilds the mesh, orphaning every claimed slot — so this is a snapshot taken at
+     * creation, which growth never mutates.
+     */
+    readonly capacity: [instances: number, vertices: number, indices: number];
+    /**
+     * Which kind of member this container holds, and so what its mesh is laid out for: a volume batch
+     * carries creased normals for the lit material and is non-indexed because that is what
+     * `toCreasedNormals` produces, and a translucent one draws in three's transparent pass. A member
+     * whose color stops matching is in the wrong pass, which is what {@link reportKindMismatch} exists
+     * to correct.
+     */
+    readonly kind: ShapeKind;
+    /**
+     * Which id the mesh gave each geometry it has registered. Per container even though the templates
+     * behind them are shared, because an id is the mesh's own numbering into its own buffers.
+     */
+    private readonly geometryIds;
+    /** What is allocated now, which growth mutates — unlike the {@link capacity} snapshot. */
+    private readonly allocated;
+    /**
+     * What the next growth jumps to, refreshed by {@link reserve}. Kept apart from {@link allocated}:
+     * a reservation must not resize anything by itself, only size the resize an overflowing claim was
+     * 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
+     * {@link capacity} and hands it over through {@link SlotContainer.bind}, and R3F disposes it on
+     * unmount. Nothing else needs disposal — `addGeometry` copies the template geometries' data into
+     * the mesh, so the templates are never uploaded to the GPU. They are not this container's to free
+     * in any case: {@link shapeGeometry} shares them across every container, and each is collected
+     * with the shape that keyed it.
+     * @param defs - The layer's shapes, used only to size the initial capacity.
+     * @param kind - Which of the layer's batches this is. A batched mesh mirrors its first geometry's
+     *   attributes *and* its index-ness, and three rejects any later geometry that disagrees — so this
+     *   decides the layout for every geometry in it, the shared unit plane included. It also decides
+     *   the render pass its members belong to, and therefore which colors are at home in it.
+     */
+    constructor(defs: readonly ShapeDef[], kind?: ShapeKind);
+    /**
+     * The geometry a shape draws with, in this container's layout. Resolved through the shared cache,
+     * so a shape drawn by two containers — the same volume in the opaque and the translucent batch —
+     * is built once and handed to both.
+     * @param shape - The shape to resolve.
+     * @returns The geometry, built on first use.
+     */
+    geometryFor(shape: Shape): BufferGeometry;
+    /**
+     * Declares the membership this container is about to hold, setting the size the next growth jumps
+     * to. The component calls this from render, before React mounts the instances that will claim in
+     * their effects — so a membership change that outgrows the buffers costs one resize per buffer,
+     * sized exactly, instead of one per claim. Bookkeeping only: nothing resizes until a claim or
+     * geometry registration actually overflows, so a reservation from a discarded or repeated render
+     * is harmless.
+     * @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.
+     * @param hit - The intersection to trace.
+     * @returns The def, or `undefined` when the hit cannot be traced to one.
+     */
+    defFromHit(hit: Intersection): RenderableDef | undefined;
+    protected addInstance(geometry: BufferGeometry): number;
+    protected removeInstance(slot: number): void;
+    /**
+     * Registers a geometry with the mesh if it is not already, growing the buffers first.
+     * @param geometry - The geometry to register.
+     * @returns The mesh's geometry id.
+     */
+    private geometryIdFor;
+}
+//# sourceMappingURL=shape-container.d.ts.map