@expofp/renderer 0.0.0-experimental.2d6c681

package/dist/objects/materials/effects/contact-shadow.d.ts

@@ -0,0 +1,100 @@
+import { Color, type IUniform, Matrix4, type WebGLProgramParametersWithUniforms } from 'three';
+/**
+ * The scene-wide state this term owns: the uniforms every lit material reads, and the hex string a
+ * lil-gui color controller writes.
+ *
+ * Declared here rather than in `effects-context.ts`, because these are the term's own — the bundle
+ * that publishes them only assembles what each term declares. {@link CONTACT_SHADOW_DEFAULTS} sits
+ * here for the same reason.
+ *
+ * **Every field carries a `shadow` prefix**, because the bundle is flat and ambient occlusion brings
+ * a `strength` and a `color` of its own; the prefix is what keeps the two apart.
+ * {@link ContactShadow.planFromWorld} is the exception, because it names the plan rather than the
+ * shadow: it is the plan's own matrix, and the shadow is only its one reader today.
+ */
+export interface ContactShadow {
+    /** The shadow's reach above a volume's base, in plan units. */
+    shadowDistance: IUniform<number>;
+    /** The shadow's depth, from `0` to `1`. */
+    shadowStrength: IUniform<number>;
+    /**
+     * The shade both darkening terms blend toward.
+     *
+     * Shared rather than one per term, so a plan has one shade of shadow rather than two — ambient
+     * occlusion binds this very object under a name of its own.
+     */
+    shadowColor: IUniform<Color>;
+    /**
+     * The shade as a hex string, which is what a lil-gui color controller reads and writes.
+     *
+     * Beside the uniform rather than inside it because three holds a `Color` in the working space
+     * while lil-gui writes display sRGB, and `Color.set` on a string is the conversion.
+     */
+    shadowHex: string;
+    /**
+     * World space back to the plan's own, which is the space's own `Space.matrixInverse`.
+     *
+     * `SceneGraph` points this uniform at that matrix once. The space recomputes the matrix in place
+     * on every refit and never replaces it, so the shader reads the current fit with no copy. Never
+     * write through this value, because the write lands in the space itself.
+     *
+     * The height a volume is shaded by is a height in the plan, and nothing else in the vertex shader
+     * knows the plan. A mesh's own matrices place it in the world, and the world is the fit, whose z
+     * the fit mirrors. This uniform takes a placed vertex back.
+     */
+    planFromWorld: IUniform<Matrix4>;
+}
+/**
+ * Installs the contact shadow into a lit shader about to be compiled.
+ *
+ * A fake, not a measurement. It reads the vertex's height above the plan and darkens toward the base
+ * of every volume, which separates a wall side from a wall top and stands in for the shadow a wall
+ * casts onto the floor it meets. Ambient occlusion is a separate term, applied at the same anchor by
+ * `ao/ambient-occlusion-patch.ts`.
+ *
+ * The reach is a fixed world distance rather than each volume's own height. It needs no new data and
+ * stays consistent across a plan. A roof above the reach keeps its authored color exactly; a volume
+ * shorter than the reach blends its roof as it blends the rest of its height.
+ *
+ * The blend goes toward an authored color rather than multiplying down toward black, so the shade is
+ * a choice and not only its depth. MapLibre multiplies toward black and clamps.
+ *
+ * The patch lands above three's output chain, where the dim patch lands, so the color it changes is
+ * still linear and scene-referred.
+ *
+ * **This reaches solid shape batches and models.** Floors and zones are planar defs drawn with
+ * `MeshBasicMaterial`, which no light and no darkening term reaches — and whose unit plane sits at
+ * `z = 0`, where it would take the whole shadow.
+ * @param parameters - The shader being compiled.
+ * @param shadow - The mount's own shadow state, whose uniform objects the compiled program captures.
+ * @throws {Error} If the shader has no output chain, or no placement to read a vertex's height
+ *   after, either of which would leave the shadow silently absent from a material that asked for it.
+ */
+export declare function applyContactShadow(parameters: WebGLProgramParametersWithUniforms, shadow: ContactShadow): void;
+/**
+ * Builds this term's scene-wide state, at the agreed defaults.
+ *
+ * One object per mounted scene, never module state: a texture is not the only thing two `Renderer`
+ * mounts on one page would fight over — a program built in one context captures these very objects,
+ * so a singleton would let one scene's slider move the other's materials. `createSceneEffects`
+ * spreads this into the bundle it publishes.
+ * @returns A fresh object, whose identity is meant to outlive every write into it.
+ */
+export declare function createContactShadow(): ContactShadow;
+/**
+ * The contact shadow values this design agreed.
+ *
+ * Each one is a starting point rather than a settled number. The distance is an absolute figure in
+ * plan units, so it suits one plan's booth heights and not another's: a plan whose walls are a few
+ * units tall wants a few units of reach, and one whose walls are hundreds wants hundreds. It is
+ * tuned per plan through the GUI.
+ */
+export declare const CONTACT_SHADOW_DEFAULTS: {
+    /** How far above a volume's base the shadow reaches, in plan units. */
+    distance: number;
+    /** How far the base is blended toward the shadow color, from `0` to `1`. */
+    strength: number;
+    /** The shade the shadow blends toward. */
+    color: string;
+};
+//# sourceMappingURL=contact-shadow.d.ts.map

package/dist/objects/materials/effects/contact-shadow.js

@@ -0,0 +1,167 @@
+import { Color, Matrix4 } from 'three';
+import { declareBeforeMain, replaceAnchor, sceneColorAnchor } from '../../../core/shader-source';
+/**
+ * Installs the contact shadow into a lit shader about to be compiled.
+ *
+ * A fake, not a measurement. It reads the vertex's height above the plan and darkens toward the base
+ * of every volume, which separates a wall side from a wall top and stands in for the shadow a wall
+ * casts onto the floor it meets. Ambient occlusion is a separate term, applied at the same anchor by
+ * `ao/ambient-occlusion-patch.ts`.
+ *
+ * The reach is a fixed world distance rather than each volume's own height. It needs no new data and
+ * stays consistent across a plan. A roof above the reach keeps its authored color exactly; a volume
+ * shorter than the reach blends its roof as it blends the rest of its height.
+ *
+ * The blend goes toward an authored color rather than multiplying down toward black, so the shade is
+ * a choice and not only its depth. MapLibre multiplies toward black and clamps.
+ *
+ * The patch lands above three's output chain, where the dim patch lands, so the color it changes is
+ * still linear and scene-referred.
+ *
+ * **This reaches solid shape batches and models.** Floors and zones are planar defs drawn with
+ * `MeshBasicMaterial`, which no light and no darkening term reaches — and whose unit plane sits at
+ * `z = 0`, where it would take the whole shadow.
+ * @param parameters - The shader being compiled.
+ * @param shadow - The mount's own shadow state, whose uniform objects the compiled program captures.
+ * @throws {Error} If the shader has no output chain, or no placement to read a vertex's height
+ *   after, either of which would leave the shadow silently absent from a material that asked for it.
+ */
+export function applyContactShadow(parameters, shadow) {
+    // Already installed, which is how a repeated compile stays harmless.
+    if (parameters.fragmentShader.includes(SHADOW_FUNCTION))
+        return;
+    const anchor = sceneColorAnchor(parameters.fragmentShader);
+    if (!anchor) {
+        throw new Error('applyContactShadow: the shader has no output chain to darken before.');
+    }
+    // Both rewrites before any write, so this either installs the shadow or leaves the parameters
+    // exactly as it found them. A shader whose vertex stage places its vertices some other way throws
+    // from `replaceAnchor` below, and a caller that means to carry on — a material whose asset is not
+    // one three built — must not be left holding four bindings for a program nothing patched.
+    const vertexShader = replaceAnchor(declareBeforeMain(parameters.vertexShader, VERTEX_DEFS), PLACEMENT_ANCHOR, `${PLACEMENT_ANCHOR}\n${VERTEX_APPLY}`);
+    const fragmentShader = declareBeforeMain(parameters.fragmentShader, FRAGMENT_DEFS).replace(anchor, `${SHADOW_APPLY}\n${anchor}`);
+    parameters.uniforms[SHADOW_DISTANCE] = shadow.shadowDistance;
+    parameters.uniforms[SHADOW_STRENGTH] = shadow.shadowStrength;
+    parameters.uniforms[SHADOW_COLOR] = shadow.shadowColor;
+    parameters.uniforms[PLAN_FROM_WORLD] = shadow.planFromWorld;
+    parameters.vertexShader = vertexShader;
+    parameters.fragmentShader = fragmentShader;
+}
+/**
+ * Builds this term's scene-wide state, at the agreed defaults.
+ *
+ * One object per mounted scene, never module state: a texture is not the only thing two `Renderer`
+ * mounts on one page would fight over — a program built in one context captures these very objects,
+ * so a singleton would let one scene's slider move the other's materials. `createSceneEffects`
+ * spreads this into the bundle it publishes.
+ * @returns A fresh object, whose identity is meant to outlive every write into it.
+ */
+export function createContactShadow() {
+    return {
+        shadowDistance: { value: CONTACT_SHADOW_DEFAULTS.distance },
+        shadowStrength: { value: CONTACT_SHADOW_DEFAULTS.strength },
+        shadowColor: { value: new Color(CONTACT_SHADOW_DEFAULTS.color) },
+        shadowHex: CONTACT_SHADOW_DEFAULTS.color,
+        planFromWorld: { value: new Matrix4() },
+    };
+}
+/**
+ * The contact shadow values this design agreed.
+ *
+ * Each one is a starting point rather than a settled number. The distance is an absolute figure in
+ * plan units, so it suits one plan's booth heights and not another's: a plan whose walls are a few
+ * units tall wants a few units of reach, and one whose walls are hundreds wants hundreds. It is
+ * tuned per plan through the GUI.
+ */
+export const CONTACT_SHADOW_DEFAULTS = {
+    /** How far above a volume's base the shadow reaches, in plan units. */
+    distance: 1.5,
+    /** How far the base is blended toward the shadow color, from `0` to `1`. */
+    strength: 0.2,
+    /** The shade the shadow blends toward. */
+    color: '#4a5260',
+};
+/** The uniform carrying the shadow's reach. */
+const SHADOW_DISTANCE = 'uShadowDistance';
+/** The uniform carrying the shadow's depth. */
+const SHADOW_STRENGTH = 'uShadowStrength';
+/** The uniform carrying the shade the shadow blends toward. */
+const SHADOW_COLOR = 'uShadowColor';
+/** The uniform carrying world space back to the plan's own. */
+const PLAN_FROM_WORLD = 'uPlanFromWorld';
+/** The signature {@link applyContactShadow} looks for, to tell a patched shader from a fresh one. */
+const SHADOW_FUNCTION = 'vec3 contactShadow(';
+/** The varying carrying a vertex's height above the plan. */
+const HEIGHT_VARYING = 'vHeight';
+/** The local three's own placement leaves the vertex's world position in. */
+const WORLD_POSITION = 'worldPosition';
+/**
+ * Where the height read lands: three's own placement of the vertex into world space.
+ *
+ * `<worldpos_vertex>` declares {@link WORLD_POSITION} and applies the batching matrix, the instance
+ * matrix and the model matrix to it, so the read below composes nothing of its own. This package
+ * widens that chunk's instancing guard to fire under indirect instancing as well. See
+ * `instanced-material.ts`.
+ *
+ * The read cannot ride on `openMain` the way the rest of this package's vertex injections do.
+ * `instanceMatrix` is the local that the indirect instancing prologue declares at the top of `main`,
+ * and it shadows the placeholder attribute three declares for any `isInstancedMesh` object.
+ * `openMain` inserts at the top and the last caller runs first, so a patch installed from a
+ * material's own handler would land above the mesh's prologue and read the empty attribute.
+ */
+const PLACEMENT_ANCHOR = /* glsl */ `#include <worldpos_vertex>`;
+/**
+ * The vertex-stage declarations, and the define that makes three build the world position at all.
+ *
+ * three guards the whole body of `<worldpos_vertex>` behind five conditions: `USE_ENVMAP`,
+ * `DISTANCE`, `USE_SHADOWMAP`, `USE_TRANSMISSION`, and a spot light coord count above zero. This
+ * renderer sets none of them, so the chunk expands to nothing and the shader declares no world
+ * position to read. `DISTANCE` is the one of the five that no chunk this renderer includes reads, in
+ * either stage, so defining it buys the world position and changes nothing else. three's own
+ * `distance` material defines it for itself, and nothing here draws with that material.
+ *
+ * `declareBeforeMain` puts this above `main`, which is above every `#include` inside `main`, so the
+ * preprocessor reads the define before it reaches the guard.
+ */
+const VERTEX_DEFS = /* glsl */ `
+  #define DISTANCE
+  uniform mat4 ${PLAN_FROM_WORLD};
+  varying float ${HEIGHT_VARYING};
+`;
+/**
+ * The vertex-stage read: the vertex's height in the plan's own space.
+ *
+ * `<worldpos_vertex>` runs one line above and leaves the vertex's world position in
+ * {@link WORLD_POSITION}. {@link PLAN_FROM_WORLD} takes that position back to the plan, and the
+ * height is its `z`.
+ *
+ * three's chunk composes the placement, which is what makes the read correct for content whose
+ * geometry is not authored in plan coordinates. A model carries GLB-local coordinates and a
+ * per-instance placement matrix, so its own `position.z` means nothing there. The solid shape batches
+ * do carry absolute plan coordinates, and they drew right only while their instance transform stayed
+ * identity. Nothing enforces that.
+ */
+const VERTEX_APPLY = /* glsl */ `
+  ${HEIGHT_VARYING} = (${PLAN_FROM_WORLD} * ${WORLD_POSITION}).z;
+`;
+/** The fragment-stage declarations. */
+const FRAGMENT_DEFS = /* glsl */ `
+  uniform float ${SHADOW_DISTANCE};
+  uniform float ${SHADOW_STRENGTH};
+  uniform vec3 ${SHADOW_COLOR};
+  varying float ${HEIGHT_VARYING};
+
+  ${SHADOW_FUNCTION}vec3 rgb, float height) {
+    float lit = clamp(height / max(${SHADOW_DISTANCE}, 1e-4), 0., 1.);
+    return mix(rgb, ${SHADOW_COLOR}, ${SHADOW_STRENGTH} * (1. - lit));
+  }
+`;
+/**
+ * The shadow applied while the color is still linear and scene-referred.
+ *
+ * The call is spelled out rather than built from {@link SHADOW_FUNCTION}, which stays the
+ * already-patched detector and nothing else.
+ */
+const SHADOW_APPLY = /* glsl */ `
+  gl_FragColor.rgb = contactShadow(gl_FragColor.rgb, ${HEIGHT_VARYING});
+`;

package/dist/objects/materials/effects/effects-context.d.ts

@@ -0,0 +1,53 @@
+import { type AmbientOcclusion } from './ao';
+import { type ContactShadow } from './contact-shadow';
+/**
+ * Everything one mounted scene's shared effects hold: the tuned values, the registry of what asks
+ * for ambient occlusion, and the uniforms the lit shaders read.
+ *
+ * **This is scene-wide shading state, not post processing.** Nothing here runs over the finished
+ * image: the ambient occlusion pass is a *pre*pass, and every term is applied inside the lit shader
+ * itself, so there is no compositing stage for this to be a part of.
+ *
+ * **Each term owns its own state, and this only assembles it.** Every field here is declared by the
+ * term that owns it, and this alias gathers them. The two terms share one shade of shadow, which the
+ * contact shadow declares and ambient occlusion binds under a name of its own.
+ *
+ * **An alias over an intersection, rather than an interface that extends.** An intersection states
+ * what the bundle is, an assembly of what the terms declare, where `extends` reads as a subtype
+ * relationship, which is not what is meant. And an interface that extends exactly one parent and
+ * declares nothing of its own is what `@typescript-eslint/no-empty-object-type` exists to flag, so
+ * that form would need a suppression this one does not.
+ *
+ * **One object per mount, never module state.** Two `Renderer` mounts on one page have two GL
+ * contexts and two sets of render targets, and a module singleton would hand both of their materials
+ * whichever texture wrote last. The identity never changes once created, so the passes write into it
+ * every frame with no React render and no shader recompile behind them — the discipline
+ * `contact-shadow.ts` uses for its three uniforms, published the way `SpaceContext` publishes a
+ * `Space` that is refitted in place.
+ *
+ * **`LayerDimContext` and `LayerOverlayContext` stay where they are and are not merged in.** Each
+ * carries one primitive of a layer's inherited state, is re-provided by every layer, and nests.
+ * This bundle is one object per renderer mount whose identity must never change, which is what
+ * lets a material capture it in `onBeforeCompile` and a frame write `.value` with no recompile.
+ * Merging either one in would either re-provide this object at every layer boundary or flatten
+ * that nesting.
+ */
+export type SceneEffects = AmbientOcclusion & ContactShadow;
+/**
+ * Builds one scene's effect state, from each term's own factory.
+ * @returns A fresh object, whose identity is meant to outlive every write into it.
+ */
+export declare function createSceneEffects(): SceneEffects;
+/**
+ * The effect state of the enclosing scene.
+ * @returns The object `Scene` published, or a standalone one when rendered outside a scene.
+ */
+export declare function useSceneEffects(): SceneEffects;
+/**
+ * The effect state every lit material and both passes read.
+ *
+ * The default is a standalone object rather than `null`, so a material rendered outside a scene
+ * still compiles and simply shades with the terms switched off — the same shape `SpaceContext` takes.
+ */
+export declare const SceneEffectsContext: import("react").Context<SceneEffects>;
+//# sourceMappingURL=effects-context.d.ts.map

package/dist/objects/materials/effects/effects-context.js

@@ -0,0 +1,24 @@
+import { createContext, use } from 'react';
+import { createAmbientOcclusion } from './ao';
+import { createContactShadow } from './contact-shadow';
+/**
+ * Builds one scene's effect state, from each term's own factory.
+ * @returns A fresh object, whose identity is meant to outlive every write into it.
+ */
+export function createSceneEffects() {
+    return { ...createAmbientOcclusion(), ...createContactShadow() };
+}
+/**
+ * The effect state of the enclosing scene.
+ * @returns The object `Scene` published, or a standalone one when rendered outside a scene.
+ */
+export function useSceneEffects() {
+    return use(SceneEffectsContext);
+}
+/**
+ * The effect state every lit material and both passes read.
+ *
+ * The default is a standalone object rather than `null`, so a material rendered outside a scene
+ * still compiles and simply shades with the terms switched off — the same shape `SpaceContext` takes.
+ */
+export const SceneEffectsContext = createContext(createSceneEffects());

package/dist/objects/materials/shared.d.ts

@@ -0,0 +1,24 @@
+import { type MaterialParameters } from 'three';
+/**
+ * Material parameter defaults, shared between all types
+ */
+export declare const sharedParams: MaterialParameters;
+/**
+ * What an overlay layer's planar materials add on top of {@link sharedParams}.
+ *
+ * Two obstacles, and render order clears neither.
+ *
+ * Depth. A solid shape sets `depthWrite: true`, so booth volumes fill the depth buffer. A planar def
+ * drawn later is still depth tested against them and loses. Turning the test off leaves order inside
+ * the tier as pure painter's order, because nothing in the tier writes depth.
+ *
+ * Pass. A translucent solid carries `transparent: true`, so it lives in three's transparent list.
+ * three draws that list after every opaque object, whatever render order says. An overlay that
+ * stayed in the opaque list would lose to a glass roof. So it opts back in. Inside the transparent
+ * list `reversePainterSortStable` compares `groupOrder` first, and the overlay tier's value of at
+ * least 1 beats every plan-tier value.
+ *
+ * `forceSinglePass` is not touched, so a double-sided overlay quad still blends once per pixel.
+ */
+export declare const overlayParams: MaterialParameters;
+//# sourceMappingURL=shared.d.ts.map

package/dist/objects/materials/shared.js

@@ -0,0 +1,72 @@
+import { CustomBlending, DoubleSide, LessEqualDepth, OneFactor, OneMinusSrcAlphaFactor, SrcAlphaFactor, } from 'three';
+/**
+ * Setting transparent: true on material changes render order, these parameters imitate transparent blending
+ * without reordering layers
+ */
+const blendingParams = {
+    blending: CustomBlending,
+    blendSrc: SrcAlphaFactor,
+    blendSrcAlpha: OneFactor,
+    blendDst: OneMinusSrcAlphaFactor,
+    blendDstAlpha: OneMinusSrcAlphaFactor,
+};
+/**
+ * Resolvable depth steps of camera-ward bias on every 2D fragment — `polygonOffsetUnits`, negated.
+ *
+ * The flat, face-on term of the decal offset: with no tilt there is no depth slope for `factor` to
+ * scale, and all that separates a label from the roof it sits on is how two different transform
+ * chains rounded the same plane. Each chain lands within a float ULP or two of the exact depth, and
+ * one ULP of view depth is worth up to two resolvable steps behind a near plane keeping 98%
+ * headroom — so a couple of ULPs of disagreement is about four steps, which is what this covers.
+ */
+const FLAT_BIAS_UNITS = 4;
+/**
+ * Material parameter defaults, shared between all types
+ */
+export const sharedParams = {
+    ...blendingParams,
+    side: DoubleSide,
+    depthFunc: LessEqualDepth,
+    depthWrite: false,
+    // 2D content never writes depth, so the buffer only ever holds what 3D content put there — and a
+    // 2D fragment coplanar with a solid surface (a label on a booth roof) is compared against a depth
+    // some other triangle interpolated. A small bias toward the camera wins that comparison; it is
+    // inert while nothing writes depth.
+    //
+    // `factor` covers camera tilt: the hardware scales it by the polygon's own window-space depth
+    // slope, making the bias one pixel's worth of that slope at any pitch — clear of every
+    // slope-proportional interpolation difference, yet unable to climb through anything that occludes
+    // the surface by more than a pixel. The imperative renderer had to carry this term as a constant,
+    // `⌈tan(maxPolarAngle)⌉ = 12`: with every layer writing depth, coplanar layers were kept apart by
+    // per-layer `units` steps, and surfaces sharing a plane share a slope, so `factor` cancelled
+    // between them and only a worst-case constant could size the step. With a single bias level there
+    // is no step, the real slope replaces the ceiling, and nothing here derives from `MAX_PITCH`.
+    //
+    // `units` covers the flat, top-down case, where the slope is zero and `factor` contributes
+    // nothing — sized by `FLAT_BIAS_UNITS`.
+    polygonOffset: true,
+    polygonOffsetFactor: -1,
+    polygonOffsetUnits: -FLAT_BIAS_UNITS,
+    forceSinglePass: true,
+};
+/**
+ * What an overlay layer's planar materials add on top of {@link sharedParams}.
+ *
+ * Two obstacles, and render order clears neither.
+ *
+ * Depth. A solid shape sets `depthWrite: true`, so booth volumes fill the depth buffer. A planar def
+ * drawn later is still depth tested against them and loses. Turning the test off leaves order inside
+ * the tier as pure painter's order, because nothing in the tier writes depth.
+ *
+ * Pass. A translucent solid carries `transparent: true`, so it lives in three's transparent list.
+ * three draws that list after every opaque object, whatever render order says. An overlay that
+ * stayed in the opaque list would lose to a glass roof. So it opts back in. Inside the transparent
+ * list `reversePainterSortStable` compares `groupOrder` first, and the overlay tier's value of at
+ * least 1 beats every plan-tier value.
+ *
+ * `forceSinglePass` is not touched, so a double-sided overlay quad still blends once per pixel.
+ */
+export const overlayParams = {
+    depthTest: false,
+    transparent: true,
+};

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

@@ -0,0 +1,22 @@
+import { type ModelDef } from '../../types/defs';
+import { type InstanceProps } from '../containers';
+import { type ModelContainer } from './model-container';
+/** Props for {@link ModelInstance}. */
+export type ModelInstanceProps = InstanceProps<ModelDef, ModelContainer>;
+/**
+ * Keeps one model's instance current: claims a slot on mount, writes the def's placement, opacity
+ * 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. Nothing here can force a re-claim: the
+ * geometry is the model part's, shared by every def drawing it, so moving a model is an ordinary
+ * write and its slot survives. `url` is not updatable by contract, which is what makes that true: a
+ * different model is a different def, and a different def a different instance.
+ *
+ * Memoized for the same reason as `ShapeInstance`: a structural change hands the layer a fresh
+ * `defs` snapshot, so element-identity bailout never applies and only prop equality keeps unchanged
+ * siblings from re-rendering. Correctness never depends on it.
+ * @param props - The def and its container.
+ * @returns `null`; the instance lives in the mesh, not the scene graph.
+ */
+export declare const ModelInstance: import("react").MemoExoticComponent<(props: ModelInstanceProps) => null>;
+//# sourceMappingURL=ModelInstance.d.ts.map

package/dist/objects/models/ModelInstance.js

@@ -0,0 +1,33 @@
+import { memo } from 'react';
+import { useDefSync } from '../containers';
+import { modelKindOf } from './model-container';
+/**
+ * Keeps one model's instance current: claims a slot on mount, writes the def's placement, opacity
+ * 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. Nothing here can force a re-claim: the
+ * geometry is the model part's, shared by every def drawing it, so moving a model is an ordinary
+ * write and its slot survives. `url` is not updatable by contract, which is what makes that true: a
+ * different model is a different def, and a different def a different instance.
+ *
+ * Memoized for the same reason as `ShapeInstance`: a structural change hands the layer a fresh
+ * `defs` snapshot, so element-identity bailout never applies and only prop equality keeps unchanged
+ * siblings from re-rendering. Correctness never depends on it.
+ * @param props - The def and its container.
+ * @returns `null`; the instance lives in the mesh, not the scene graph.
+ */
+export const ModelInstance = memo(function ModelInstance(props) {
+    const { def, container } = props;
+    // No per-instance resource: every def on this mesh draws the same merged geometry, so the slot is
+    // backed by nothing and nothing can invalidate it.
+    useDefSync(container, def, null, (slot) => {
+        container.place(slot, def);
+        container.setOpacity(slot, def);
+        // Checked on every sync, because a def leaves its batch's kind without re-rendering this layer:
+        // `opacity` crossing 1 reaches the instance through `update()` and stops there, so this is where
+        // a batch learns it is holding something whose material describes the wrong render list.
+        if (modelKindOf(def) !== container.kind)
+            container.reportKindMismatch();
+    });
+    return null;
+});

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