@expofp/renderer 3.2.5 → 3.27.1

package/dist/objects/models/Models.d.ts

@@ -0,0 +1,22 @@
+import { type ModelDef } from '../../types/defs';
+import { type DefsProps } from '../containers';
+/** Props for {@link Models}. */
+export type ModelsProps = DefsProps<ModelDef>;
+/**
+ * Draws a layer's models. Every def sharing a URL draws from the same loaded asset, and every part of
+ * that asset — one per source material, merged at load — becomes a single `InstancedMesh`. A layer
+ * holding twenty copies of a two-material chair is therefore **two draw calls**, not forty.
+ *
+ * `InstancedMesh` rather than `BatchedMesh` on purpose. Nothing here ever addresses a sub-mesh
+ * individually — the addressable unit is the def — so merging at load is strictly better than
+ * carrying per-sub-mesh bookkeeping, and it avoids the `WEBGL_multi_draw` path a batched mesh needs,
+ * which is slow in Firefox.
+ *
+ * **Loading is an effect, not Suspense.** A suspended leaf would never run the effect that reports
+ * back to the mount scheduler, so the scene's admission queue would stall permanently on the first
+ * model layer. Instead nothing renders until the assets resolve.
+ * @param props - The models to draw.
+ * @returns One mesh per part of every loaded model, with an instance component per def.
+ */
+export declare function Models(props: ModelsProps): import("react").JSX.Element;
+//# sourceMappingURL=Models.d.ts.map

package/dist/objects/models/Models.js

@@ -0,0 +1,177 @@
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useThree } from '@react-three/fiber';
+import { Fragment, useEffect, useState } from 'react';
+import { InstancedMesh } from '../../core/instanced/InstancedMesh';
+import { sameSequence } from '../../utils/arrays';
+import { createLogger } from '../../utils/logging';
+import { defKey, useContainer } from '../containers';
+import { ModelMaterial } from '../materials/ModelMaterial';
+import { loadModel } from './gltf-cache';
+import { MODEL_KINDS, ModelContainer, modelKindOf, OPACITY_UNIFORM, } from './model-container';
+import { ModelInstance } from './ModelInstance';
+const logger = createLogger('models');
+/**
+ * Draws a layer's models. Every def sharing a URL draws from the same loaded asset, and every part of
+ * that asset — one per source material, merged at load — becomes a single `InstancedMesh`. A layer
+ * holding twenty copies of a two-material chair is therefore **two draw calls**, not forty.
+ *
+ * `InstancedMesh` rather than `BatchedMesh` on purpose. Nothing here ever addresses a sub-mesh
+ * individually — the addressable unit is the def — so merging at load is strictly better than
+ * carrying per-sub-mesh bookkeeping, and it avoids the `WEBGL_multi_draw` path a batched mesh needs,
+ * which is slow in Firefox.
+ *
+ * **Loading is an effect, not Suspense.** A suspended leaf would never run the effect that reports
+ * back to the mount scheduler, so the scene's admission queue would stall permanently on the first
+ * model layer. Instead nothing renders until the assets resolve.
+ * @param props - The models to draw.
+ * @returns One mesh per part of every loaded model, with an instance component per def.
+ */
+export function Models(props) {
+    const { defs } = props;
+    // 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`).
+    //
+    // 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 `opacity` is
+    // an ordinary slot write that never re-renders this component, so one crossing 1 would otherwise
+    // leave the def in a batch whose material describes the wrong render list. `repartition` is what
+    // the containers call when they notice.
+    const [partition, setPartition] = useState(() => partitionModels(defs, undefined));
+    if (partition.defs !== defs)
+        setPartition((current) => partitionModels(defs, current.batches));
+    /** Re-splits the current membership, for a batch that found a member of the wrong kind. */
+    function repartition() {
+        setPartition((current) => partitionModels(defs, current.batches));
+    }
+    // The distinct urls the layer draws, held in state so the load effect depends on a value that
+    // changes exactly when the *set* does: the snapshot from `useStagedChildren` is rebuilt on every
+    // `update(layer)`, including one that only flipped the layer's own `hidden`, so an effect
+    // depending on `defs` would reload for changes that touched no model at all. Derived as a value
+    // rather than suppressed in the dependency list: a `react-hooks/exhaustive-deps` suppression makes
+    // the React Compiler bail on the whole module, which fails every spec that transitively imports
+    // it. Sorted, so comparing two of them position by position answers the question actually being
+    // asked — same *set*? — and a layer whose models were merely reordered loads nothing.
+    const wanted = distinctUrls(defs);
+    const [urls, setUrls] = useState(wanted);
+    if (!sameSequence(urls, wanted))
+        setUrls(wanted);
+    const [assets, setAssets] = useState([]);
+    const invalidate = useThree((state) => state.invalidate);
+    useEffect(() => {
+        let live = true;
+        void Promise.all(urls.map(loadOrWarn)).then((loaded) => {
+            if (!live)
+                return;
+            // `filter(Boolean)` does not narrow a union, so the guard is spelled out.
+            setAssets(loaded.filter((asset) => asset !== undefined));
+            invalidate();
+        });
+        return () => {
+            live = false;
+        };
+    }, [urls, invalidate]);
+    // Nested rather than flattened because React scopes keys to their parent, so each level only has
+    // to be unique among its siblings — and `ModelPart.id` is, where `material.uuid` is not.
+    //
+    // `renderOrder` is the kind's place in `MODEL_KINDS` rather than mount order, for the reason
+    // layers carry one: these meshes tie on `groupOrder`, so the tiebreak would otherwise fall to
+    // `material.id`, which ascends in the order materials were built. It barely matters for the
+    // translucent batch on its own — `transparent: true` puts it in three's transparent list, drawn
+    // after every opaque object whatever the number says — but it is numbered anyway so the intent
+    // reads correctly and so it still orders against another translucent batch tying with it.
+    return (_jsx(_Fragment, { children: assets.map((asset) => (_jsx(Fragment, { children: MODEL_KINDS.map((kind, renderOrder) => {
+                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));
+            }) }, asset.url))) }));
+}
+/**
+ * Splits a layer's models by kind and url, keeping every batch that is already mounted.
+ * @param defs - The layer's models, in paint order.
+ * @param mounted - The batches already on screen, whose keys are carried forward emptied.
+ * @returns The split.
+ */
+function partitionModels(defs, mounted) {
+    const batches = {
+        opaque: emptied(mounted?.opaque),
+        translucent: emptied(mounted?.translucent),
+    };
+    for (const def of defs) {
+        const byUrl = batches[modelKindOf(def)];
+        const members = byUrl.get(def.url);
+        if (members)
+            members.push(def);
+        else
+            byUrl.set(def.url, [def]);
+    }
+    return { defs, batches };
+}
+/**
+ * The same urls, each with an empty membership — how a mounted batch survives losing its last
+ * member. See {@link ModelBatches}.
+ * @param previous - The batch to carry forward, if it has been mounted.
+ * @returns The emptied batch.
+ */
+function emptied(previous) {
+    const next = new Map();
+    if (previous)
+        for (const url of previous.keys())
+            next.set(url, []);
+    return next;
+}
+/**
+ * One model part as a single instanced draw, with an instance per def placing it.
+ * @param props - The part and the defs drawing it.
+ * @returns The mesh and one instance component per def.
+ */
+function ModelPartMesh(props) {
+    const { asset, part, defs, kind, renderOrder, onKindMismatch } = props;
+    // 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,
+    // 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);
+    // Assigned after mount rather than passed to the constructor: the container is built once and
+    // outlives every render, so it cannot close over a current callback. Nothing can fire before this
+    // runs — the split that placed these defs was computed from the same opacities they mount with.
+    useEffect(() => {
+        container.setKindMismatchHandler(onKindMismatch);
+        return () => container.setKindMismatchHandler(undefined);
+    }, [container, onKindMismatch]);
+    // The geometry belongs to the module-level cache and may be drawing in another layer, so it is
+    // mounted as a `primitive` with `dispose={null}` — R3F must not free it on unmount. Sharing it is
+    // safe because `InstancedMeshExt` 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.
+    //
+    // The mesh's own matrix is glTF → plan, which is where three can see the mirror that mapping
+    // 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))))] }));
+}
+/**
+ * Loads one model, reporting a failure rather than rejecting — one missing model should not cost a
+ * layer the rest of them.
+ * @param url - The model to load.
+ * @returns The asset, or `undefined` if it could not be loaded.
+ */
+async function loadOrWarn(url) {
+    try {
+        return await loadModel(url);
+    }
+    catch (error) {
+        logger.warn('failed to load model %s: %O', url, error);
+        return undefined;
+    }
+}
+/**
+ * The distinct urls a layer draws, sorted so that an equal set is an equal sequence.
+ * @param defs - The layer's models.
+ * @returns The urls to load.
+ */
+function distinctUrls(defs) {
+    return [...new Set(defs.map((def) => def.url))].sort();
+}

package/dist/objects/models/gltf-cache.d.ts

@@ -0,0 +1,17 @@
+import { type ModelAsset } from './model-asset';
+/**
+ * Loads and parses a GLB, or returns the in-flight promise for one already being loaded.
+ *
+ * Keyed by URL and never evicted: a plan holds a handful of distinct models, often placed many times
+ * over, and the whole point of the cache is that the twentieth copy of a chair costs nothing. The
+ * entry is dropped on failure so a later attempt can retry.
+ *
+ * Ours rather than R3F's `useLoader` because what is cached is the *baked* asset, not the parsed
+ * glTF, and because `useLoader` is a Suspense hook: a suspended leaf never runs the effect that
+ * reports to the mount scheduler, so the scene's admission queue would stall on the first model
+ * layer (see `Models`). A hook could not be called per url in a loop either.
+ * @param url - The model's URL.
+ * @returns The parsed asset.
+ */
+export declare function loadModel(url: string): Promise<ModelAsset>;
+//# sourceMappingURL=gltf-cache.d.ts.map

package/dist/objects/models/gltf-cache.js

@@ -0,0 +1,50 @@
+import { MeshoptDecoder } from 'three/examples/jsm/libs/meshopt_decoder.module.js';
+import { GLTFLoader } from 'three/examples/jsm/loaders/GLTFLoader.js';
+import { bakeGltf } from './model-asset';
+/**
+ * Loads and parses a GLB, or returns the in-flight promise for one already being loaded.
+ *
+ * Keyed by URL and never evicted: a plan holds a handful of distinct models, often placed many times
+ * over, and the whole point of the cache is that the twentieth copy of a chair costs nothing. The
+ * entry is dropped on failure so a later attempt can retry.
+ *
+ * Ours rather than R3F's `useLoader` because what is cached is the *baked* asset, not the parsed
+ * glTF, and because `useLoader` is a Suspense hook: a suspended leaf never runs the effect that
+ * reports to the mount scheduler, so the scene's admission queue would stall on the first model
+ * layer (see `Models`). A hook could not be called per url in a loop either.
+ * @param url - The model's URL.
+ * @returns The parsed asset.
+ */
+export function loadModel(url) {
+    const pending = cache.get(url);
+    if (pending)
+        return pending;
+    const promise = parse(url).catch((error) => {
+        cache.delete(url);
+        throw error;
+    });
+    cache.set(url, promise);
+    return promise;
+}
+/**
+ * Fetches and bakes a GLB.
+ * @param url - The model's URL.
+ * @returns The parsed asset.
+ */
+async function parse(url) {
+    const gltf = await loader().loadAsync(url);
+    return bakeGltf(gltf.scene, url);
+}
+/**
+ * The loader, built once. Meshopt is wired in because its decoder ships inside three's addons and
+ * costs nothing at rest; Draco deliberately is not, since its decoder is fetched from a CDN at
+ * runtime and an offline plan copy could not satisfy that.
+ * @returns The shared loader.
+ */
+function loader() {
+    _loader ??= new GLTFLoader().setMeshoptDecoder(MeshoptDecoder);
+    return _loader;
+}
+/** In-flight and settled loads, keyed by URL. */
+const cache = new Map();
+let _loader;

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

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

package/dist/objects/models/index.js

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

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

@@ -0,0 +1,48 @@
+import { Box3, type BufferGeometry, type Group, type Material } from 'three';
+/** One drawable piece of a loaded model: everything in it that shares a source material. */
+export interface ModelPart {
+    /**
+     * Identifies the part within its asset, and so keys the mesh drawing it. The material alone will
+     * not do: parts are bucketed by material **and** merge signature, so one material can yield more
+     * than one part and two parts can share a `material.uuid`.
+     */
+    readonly id: string;
+    /** Every mesh in the GLB using {@link material}, flattened and merged into one. */
+    readonly geometry: BufferGeometry;
+    /** The material the GLB authored for those meshes. Shared; clone before mutating. */
+    readonly material: Material;
+}
+/** A parsed GLB, ready to be instanced. */
+export interface ModelAsset {
+    /** Where it was loaded from; also what picks out the defs drawing it. */
+    readonly url: string;
+    /** One entry per distinct source material, so a whole layer costs one draw call per entry. */
+    readonly parts: readonly ModelPart[];
+    /**
+     * The union of every baked part's bounds, in the model's own y-up space. `ModelContainer` maps
+     * them into the plan's once, which is the only place the two frames meet.
+     */
+    readonly extents: Box3;
+}
+/**
+ * Flattens a loaded glTF scene and merges it down to one geometry per source material.
+ *
+ * Per mesh node, its geometry is cloned and transformed by the node's world matrix, so every vertex
+ * lands relative to the model's root and the node hierarchy is no longer needed — which is what lets
+ * the merge happen at all. Then it is filed under its material, sub-keyed by {@link mergeSignature},
+ * because `mergeGeometries` requires its inputs to agree about their attributes.
+ *
+ * **Nothing here knows about the plan.** The geometry stays in the model's own space, glTF's y-up,
+ * and the mapping onto the plan is a transform the *mesh* carries — see `ModelContainer`. That is
+ * not a tidiness argument: a mapping baked into vertices is one three cannot see when it decides
+ * face culling from `matrixWorld`, and the map is a mirror.
+ *
+ * Merging is what replaces legacy's `BatchedMesh`: we never address a sub-mesh individually — the
+ * addressable unit is the def — so one geometry per material is strictly better, and it costs no
+ * `WEBGL_multi_draw` path.
+ * @param scene - The glTF scene to bake.
+ * @param url - Where it came from; carried on the asset, and names the model in diagnostics.
+ * @returns The parsed asset.
+ */
+export declare function bakeGltf(scene: Group, url: string): ModelAsset;
+//# sourceMappingURL=model-asset.d.ts.map

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

@@ -0,0 +1,77 @@
+import { Box3, Mesh } from 'three';
+import { mergeGeometries } from 'three/examples/jsm/utils/BufferGeometryUtils.js';
+import { createLogger } from '../../utils/logging';
+const logger = createLogger('model');
+/**
+ * Flattens a loaded glTF scene and merges it down to one geometry per source material.
+ *
+ * Per mesh node, its geometry is cloned and transformed by the node's world matrix, so every vertex
+ * lands relative to the model's root and the node hierarchy is no longer needed — which is what lets
+ * the merge happen at all. Then it is filed under its material, sub-keyed by {@link mergeSignature},
+ * because `mergeGeometries` requires its inputs to agree about their attributes.
+ *
+ * **Nothing here knows about the plan.** The geometry stays in the model's own space, glTF's y-up,
+ * and the mapping onto the plan is a transform the *mesh* carries — see `ModelContainer`. That is
+ * not a tidiness argument: a mapping baked into vertices is one three cannot see when it decides
+ * face culling from `matrixWorld`, and the map is a mirror.
+ *
+ * Merging is what replaces legacy's `BatchedMesh`: we never address a sub-mesh individually — the
+ * addressable unit is the def — so one geometry per material is strictly better, and it costs no
+ * `WEBGL_multi_draw` path.
+ * @param scene - The glTF scene to bake.
+ * @param url - Where it came from; carried on the asset, and names the model in diagnostics.
+ * @returns The parsed asset.
+ */
+export function bakeGltf(scene, url) {
+    const buckets = new Map();
+    const extents = new Box3();
+    scene.updateMatrixWorld(true);
+    scene.traverse((node) => {
+        // `instanceof` on a generic class instantiates its parameters as `any`, so the narrowed node is
+        // re-typed rather than used directly.
+        if (!(node instanceof Mesh))
+            return;
+        const mesh = node;
+        if (!mesh.geometry || !mesh.material)
+            return;
+        // A multi-material mesh splits its draws by geometry group; we take the first, as legacy did.
+        const material = Array.isArray(mesh.material) ? mesh.material[0] : mesh.material;
+        if (!material)
+            return;
+        const baked = mesh.geometry.clone();
+        baked.applyMatrix4(mesh.matrixWorld);
+        baked.computeBoundingBox();
+        if (baked.boundingBox)
+            extents.union(baked.boundingBox);
+        const signature = mergeSignature(baked);
+        const id = `${material.uuid}|${signature}`;
+        const bucket = buckets.get(id) ?? { material, signature, geometries: [] };
+        bucket.geometries.push(baked);
+        buckets.set(id, bucket);
+    });
+    const parts = [];
+    for (const [id, { material, signature, geometries }] of buckets) {
+        const merged = geometries.length === 1 ? geometries[0] : mergeGeometries(geometries);
+        // `mergeGeometries` still returns null when its inputs disagree about something the signature
+        // does not cover — an attribute's item size or array type, a morph target. Reported rather than
+        // thrown: one unmergeable material should not cost the whole model. The message has to name
+        // enough of the asset to find the offending meshes inside it, since nothing else will.
+        if (!merged) {
+            logger.warn('model %s: dropped a part, %d geometries would not merge — material "%s" (%s), %s', url, geometries.length, material.name, material.uuid, signature);
+            continue;
+        }
+        parts.push({ id, geometry: merged, material });
+    }
+    return { url, parts, extents };
+}
+/**
+ * A stable description of what `mergeGeometries` insists its inputs agree about: whether they are
+ * indexed, and which attributes they carry. Geometries sharing a material but not this are bucketed
+ * apart and drawn as separate parts, rather than handed to a merge that would reject the lot.
+ * @param geometry - The geometry to describe.
+ * @returns The description.
+ */
+function mergeSignature(geometry) {
+    const indexed = geometry.getIndex() ? 'indexed' : 'non-indexed';
+    return `${indexed} [${Object.keys(geometry.attributes).sort().join(', ')}]`;
+}

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

@@ -0,0 +1,139 @@
+import { type Rect } from '@expofp/geometry';
+import { type Box3, Matrix4 } from 'three';
+import { type InstancedMeshExt, type InstancedMeshExtParams } from '../../core/instanced/InstancedMesh';
+import { type ModelDef } from '../../types/defs';
+import { SlotContainer } from '../containers';
+/**
+ * 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 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];
+/**
+ * Every kind of model batch, **in the order they draw within a layer** — which is what `Models`
+ * numbers them by.
+ */
+export declare const MODEL_KINDS: readonly ['opaque', 'translucent'];
+/** Which batch a model draws from; see {@link modelKindOf}. */
+export type ModelKind = (typeof MODEL_KINDS)[number];
+/**
+ * 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 declare function modelKindOf(def: ModelDef): ModelKind;
+/**
+ * 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 declare class ModelContainer extends SlotContainer<null, InstancedMeshExt, 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. */
+    readonly kind: ModelKind;
+    /**
+     * 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}.
+     */
+    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.
+     * @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: Box3, count: number, kind?: ModelKind);
+    /**
+     * 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(): 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`.
+     *
+     * 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: number, def: ModelDef): void;
+    /**
+     * 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: number, def: ModelDef): void;
+    protected addInstance(): number;
+    protected removeInstance(slot: number): void;
+}
+/**
+ * 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 declare function fitToBounds(extents: Box3, bounds: Rect): Matrix4;
+//# sourceMappingURL=model-container.d.ts.map