@expofp/renderer 3.2.5 → 3.27.1

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

@@ -0,0 +1,41 @@
+import { type Material } from 'three';
+/** Props for {@link ModelMaterial}. */
+export interface ModelMaterialProps {
+    /**
+     * The material the GLB authored. Shared across every layer drawing the same model, so it is never
+     * mutated — this clones it and adjusts the clone.
+     */
+    source: Material;
+    /**
+     * The name of a per-instance `float` uniform to multiply alpha by, so one mesh can hold instances
+     * of differing opacity. The mesh owns the name and declares it; the material only patches its
+     * shader to read it.
+     */
+    opacityUniform: string;
+    /**
+     * Whether any instance drawing this material is translucent.
+     *
+     * Per-instance opacity is a *fragment* multiplier, but whether alpha blends at all is a **material**
+     * decision: three drops a `NormalBlending` material with `transparent: false` to `NoBlending`
+     * (`WebGLState.setMaterial`), which discards the alpha entirely — the instance then composites
+     * against the page rather than against the scene. So the mesh has to tell the material that at
+     * least one of its instances needs blending.
+     */
+    translucent?: boolean;
+}
+/**
+ * The material a model draws with: the GLB's own, cloned and adjusted for the plan's depth rules and
+ * for per-instance opacity.
+ *
+ * A model is one of the two kinds of content that **write depth**, translucent ones included — that
+ * is what makes it occlude itself, other models, and any 2D content drawn after it. The rest of the
+ * scene draws with `depthWrite: false` and a small polygon offset precisely so it can be biased
+ * against surfaces like these, so a model carries no offset of its own.
+ *
+ * Everything else about the material is left as the GLB authored it — maps, roughness, metalness,
+ * emissive, side. A model's appearance is the asset's business, not the renderer's.
+ * @param props - The source material and the per-instance opacity uniform's name.
+ * @returns The material element.
+ */
+export declare function ModelMaterial(props: ModelMaterialProps): import("react").JSX.Element;
+//# sourceMappingURL=ModelMaterial.d.ts.map

package/dist/objects/materials/ModelMaterial.js

@@ -0,0 +1,84 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useEffect, useState } from 'react';
+import { LessEqualDepth, } from 'three';
+import { useDimPatch } from './dim';
+/**
+ * The material a model draws with: the GLB's own, cloned and adjusted for the plan's depth rules and
+ * for per-instance opacity.
+ *
+ * A model is one of the two kinds of content that **write depth**, translucent ones included — that
+ * is what makes it occlude itself, other models, and any 2D content drawn after it. The rest of the
+ * scene draws with `depthWrite: false` and a small polygon offset precisely so it can be biased
+ * against surfaces like these, so a model carries no offset of its own.
+ *
+ * Everything else about the material is left as the GLB authored it — maps, roughness, metalness,
+ * emissive, side. A model's appearance is the asset's business, not the renderer's.
+ * @param props - The source material and the per-instance opacity uniform's name.
+ * @returns The material element.
+ */
+export function ModelMaterial(props) {
+    const { source, opacityUniform } = props;
+    const dimPatch = useDimPatch();
+    const translucent = props.translucent ?? false;
+    // Cloned once and held in state: R3F would dispose a material it created on unmount, and the
+    // source belongs to the module-level model cache, which may still be serving other layers. The
+    // dim patch is installed with it, once — the patch is stable and reads the current amount through
+    // the uniform it owns.
+    const [material] = useState(() => adjust(source.clone(), opacityUniform, dimPatch, translucent));
+    useEffect(() => () => material.dispose(), [material]);
+    return _jsx("primitive", { object: material, attach: "material" });
+}
+/**
+ * Applies the plan's depth rules and the per-instance opacity patch to a cloned GLB material.
+ * @param material - The clone to adjust.
+ * @param opacityUniform - The per-instance uniform's name.
+ * @param dimPatch - Installs dimming on the compiled shader.
+ * @param translucent - Whether any instance drawing it needs its alpha blended.
+ * @returns The same material.
+ */
+function adjust(material, opacityUniform, dimPatch, translucent) {
+    material.depthFunc = LessEqualDepth;
+    material.polygonOffset = false;
+    // `transparent` moves a material into three's transparent list, drawn after *every* opaque object
+    // in the scene whatever the layer order says — which is what lets a translucent model blend with
+    // the content behind it instead of with an empty frame. It is a **material** property and never a
+    // per-instance one, so which list a def belongs in is a partition rather than a flag: `Models`
+    // keeps a layer's translucent copies in a batch of their own and re-splits when a def's opacity
+    // crosses 1, exactly as `Shapes` splits its volumes. `ColorMaterial` makes the same trade and
+    // records what it costs — a planar def sitting *on* a translucent one is drawn before it.
+    material.transparent =
+        material.transparent || translucent || material.opacity < 1;
+    // Depth writes stay on even when translucent, which is not three's usual convention and is
+    // deliberate. Two of the plan's rules depend on it: a translucent model must still be occluded by
+    // anything nearer the camera, and a planar def drawn after it — a label or logo on a booth roof —
+    // must be occluded by it. Both are depth-buffer questions, and switching writes off answers them
+    // wrongly: a *farther* solid drawn later would have nothing to reject it and would paint straight
+    // over the translucent one in front of it.
+    //
+    // What it costs is seeing *through* a translucent surface to content drawn after it, which no
+    // painter's-order renderer can offer — blending needs depth order, and array order is authoring
+    // order. MapLibre makes the same trade for `fill-extrusion` (`DepthMode.ReadWrite` in both of its
+    // passes), degrading to a color error rather than a structural one. The obligation it puts on
+    // callers — order a translucent model's layer after whatever should show through it — is spelled
+    // out in the design spec's Decision 2, along with the two alternatives and why each loses more
+    // than it gains.
+    material.depthWrite = true;
+    const chained = material.onBeforeCompile.bind(material);
+    material.onBeforeCompile = (parameters, ...rest) => {
+        chained(parameters, ...rest);
+        // Applied at the very end of the fragment chain, after `<dithering_fragment>`, so it multiplies
+        // the final composed alpha rather than an intermediate one. The instanced mesh injects the
+        // uniform fetch at the top of `main()`, so the name is in scope by the time this runs.
+        parameters.fragmentShader = parameters.fragmentShader.replace('#include <dithering_fragment>', 
+        /*glsl*/ `
+        #include <dithering_fragment>
+        gl_FragColor.a *= ${opacityUniform};
+      `.trim());
+        // Dim touches rgb and opacity touches alpha, so the two patches are independent however they
+        // are ordered — and dim lands ahead of the colorspace conversion either way, which is where a
+        // gamma-corrected darken has to be.
+        dimPatch(parameters);
+    };
+    material.needsUpdate = true;
+    return material;
+}

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

@@ -0,0 +1,30 @@
+import { type Texture } from 'three';
+/** Props for {@link TextureMaterial}. */
+export interface TextureMaterialProps {
+    /**
+     * Texture map. Atlas textures are uploaded with `flipY = false`, so v runs down the canvas and
+     * the region coordinates need no vertical inversion anywhere.
+     */
+    map: Texture;
+    /**
+     * The name of a per-instance `vec4` uniform to source the texture region from — for a texture
+     * atlas on an instanced/batched mesh that declares and writes it. The mesh owns the name; the
+     * material only patches its shader to sample `map` through it. Omit it for a plain textured
+     * material: the shader is left unpatched, so the material draws its whole `map` and works in any
+     * context, not only an instanced one.
+     */
+    uvOffset?: string;
+}
+/**
+ * The material used to render a texture, optionally through a per-instance uv-offset uniform so an
+ * instanced/batched mesh can pack many regions into one atlas.
+ *
+ * When {@link TextureMaterialProps.uvOffset} is set, the patch overwrites `vMapUv` after
+ * `<uv_vertex>` has run, so the instance's atlas region replaces whatever the stock chunk computed.
+ * Instanced meshes wrap this `onBeforeCompile` rather than replacing it, and inject their uniform
+ * fetch at the top of `main()`, so the uniform is in scope by the time this line runs.
+ * @param props - The material's texture and optional uv-offset uniform name.
+ * @returns The material element.
+ */
+export declare function TextureMaterial(props: TextureMaterialProps): import("react").JSX.Element;
+//# sourceMappingURL=TextureMaterial.d.ts.map

package/dist/objects/materials/TextureMaterial.js

@@ -0,0 +1,29 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useDimPatch } from './dim';
+import { sharedParams } from './shared';
+/**
+ * The material used to render a texture, optionally through a per-instance uv-offset uniform so an
+ * instanced/batched mesh can pack many regions into one atlas.
+ *
+ * When {@link TextureMaterialProps.uvOffset} is set, the patch overwrites `vMapUv` after
+ * `<uv_vertex>` has run, so the instance's atlas region replaces whatever the stock chunk computed.
+ * Instanced meshes wrap this `onBeforeCompile` rather than replacing it, and inject their uniform
+ * fetch at the top of `main()`, so the uniform is in scope by the time this line runs.
+ * @param props - The material's texture and optional uv-offset uniform name.
+ * @returns The material element.
+ */
+export function TextureMaterial(props) {
+    const { map, uvOffset } = props;
+    const applyDim = useDimPatch();
+    function onBeforeCompile(parameters) {
+        applyDim(parameters);
+        if (!uvOffset)
+            return;
+        parameters.vertexShader = parameters.vertexShader.replace('#include <uv_vertex>', 
+        /*glsl*/ `
+        #include <uv_vertex>
+        vMapUv = uv * ${uvOffset}.zw + ${uvOffset}.xy;
+      `.trim());
+    }
+    return _jsx("meshBasicMaterial", { ...sharedParams, map: map, onBeforeCompile: onBeforeCompile });
+}

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

@@ -0,0 +1,123 @@
+import { type IUniform, type WebGLProgramParametersWithUniforms } from 'three';
+import { type UniformSchemaShader } from '../../core/InstanceUniforms';
+import { type RenderableDef } from '../../types/defs';
+/**
+ * Patches a compiled shader to dim what it draws. Returned by {@link useDimPatch} and called from a
+ * material's own `onBeforeCompile`, so a material that already patches its shader composes the two
+ * rather than choosing between them.
+ */
+export type DimPatch = (parameters: WebGLProgramParametersWithUniforms) => void;
+/**
+ * The dim patch every material installs, reading the layer amount from {@link LayerDimContext}.
+ *
+ * Dimming is deliberately **not** a material prop. It cuts across every material and every def type,
+ * so threading it as a prop would put a `dim` on each material, each container, and each of their
+ * inner components, and any new one would have to remember to forward it. What a material needs to
+ * know is only *how* to be dimmed; what it is dimmed *by* belongs to the layer it draws under.
+ *
+ * The amount is held in one `IUniform` object per material and mutated in place, never replaced, so
+ * an animated dim — floorplan eases the venue's dim over 300ms — costs a number per material per
+ * frame with no recompile.
+ * @returns The patch to call from the material's `onBeforeCompile`.
+ */
+export declare function useDimPatch(): DimPatch;
+/**
+ * Installs dimming into a shader about to be compiled: the layer's uniform, the declarations, and
+ * the application.
+ *
+ * **Applies only once the mesh's uniform prologue is in the shader**, and that guard is what makes
+ * installation order stop mattering. The applied line reads the per-instance amount the prologue
+ * declares as a *local of `main`*, so it has to land in the same `main`. Most meshes inject their
+ * prologue and then call the material's handler, so a material-installed patch is already last. Text
+ * is the exception: troika calls the base material's handler first and then rebuilds `main` around
+ * it — renaming the original `troikaOrigMain` and calling it from a new one — so a patch installed
+ * there would land in a scope the prologue's local never reaches. With this guard that early call
+ * simply does nothing, and `BatchedTextExt` runs the same patch again once its prologue is in.
+ * @param parameters - The shader being compiled.
+ * @param uniform - The layer's dim amount.
+ * @returns Whether the shader was patched.
+ * @throws {Error} If the prologue is present but the shader converts no color, which would leave
+ *   dimming silently absent from a material that asked for it.
+ */
+export declare function applyDim(parameters: WebGLProgramParametersWithUniforms, uniform: IUniform<number>): boolean;
+/**
+ * Orders a layer's defs so the dimmed ones draw first and the undimmed ones last, on top.
+ *
+ * What this is for: dimming the venue behind a search leaves the few undimmed defs as the subject of
+ * the frame, and a subject that a dimmed neighbor happens to overlap would be covered by it. Paint
+ * order is the only thing that resolves overlap in a 2D layer — 2D content never writes depth,
+ * leaving depth testing nothing of its own to compare against — so being undimmed has to lift a def
+ * above the defs it is being distinguished from.
+ *
+ * **Stable**, and that is load-bearing rather than a nicety: within each group the defs keep their
+ * array order, which is the order the caller authored and the only thing that decides overlap
+ * between two defs that are both dimmed or both lit. A dim is allowed to lift a def over the dimmed
+ * ones; it is not allowed to reshuffle anything else.
+ *
+ * Returns the input array itself when the rule changes nothing — every def in one group, which is
+ * every layer that is uniformly dimmed or uniformly not. Callers key their order pass on the
+ * identity of what comes back, so an unchanged layer costs neither an allocation nor a re-label.
+ * @param defs - The layer's defs, in authored order.
+ * @param layerDimmed - Whether the layer is dimmed, which is what a def without a `dim` of its own
+ *   inherits. Only the fact is needed, never the amount: this is a two-way split, and every amount
+ *   above zero lands on the same side of it. That is also what keeps an eased layer dim cheap — the
+ *   order pass re-runs when the value crosses zero, not on each of the frames between.
+ * @returns The defs in draw order.
+ */
+export declare function dimOrdered<T extends RenderableDef>(defs: readonly T[], layerDimmed: boolean): readonly T[];
+/**
+ * Whether a def draws dimmed at all — the one question paint order asks about dimming, as opposed
+ * to the amount, which only the shader reads.
+ * @param dim - The def's own `dim`; `undefined` inherits.
+ * @param layerDimmed - Whether the layer it draws under is dimmed.
+ * @returns Whether it draws dimmed.
+ */
+export declare function isDimmed(dim: number | undefined, layerDimmed: boolean): boolean;
+/**
+ * Encodes a def's own `dim` for its per-instance uniform.
+ * @param dim - The def's `dim`; `undefined` defers to the layer.
+ * @returns The value to write.
+ */
+export declare function instanceDim(dim: number | undefined): number;
+/**
+ * Clamps a dim amount into the range the shader interpolates over, so `mix` never extrapolates into
+ * a color that is not a dim of the original.
+ * @param dim - The amount to clamp.
+ * @returns The amount, within `[0, 1]`.
+ */
+export declare function clampDim(dim: number): number;
+/**
+ * The dim amount a layer draws at, which every material beneath it reads.
+ *
+ * Context rather than a prop because the value crosses the whole subtree and concerns none of the
+ * components between: a container hands its material nothing, and a material that never asked about
+ * layers still dims correctly. `Layer` provides it, and only when it declares a `dim` of its own —
+ * a layer without one is transparent to this, which is exactly what inheritance means.
+ */
+export declare const LayerDimContext: import("react").Context<number>;
+/**
+ * The per-instance uniform a def's own dim is written to. Declared by every container that draws
+ * dimmable defs and read by {@link DIM_APPLY}; the material owns the name, the mesh only has to
+ * declare it before any slot writes one.
+ */
+export declare const DIM_UNIFORM = "instanceDim";
+/**
+ * What an instance writes to defer to its layer.
+ *
+ * Any negative value would do; the sentinel only has to fall outside `[0, 1]`, which is why the
+ * amount itself can be stored as-is rather than packed around a zero that means "inherit". The
+ * imperative renderer needed that packing because its texture zero-filled and nothing wrote an
+ * instance on mount — here every instance writes its own value through `useDefSync`, so the fill is
+ * never what a draw reads.
+ */
+export declare const DIM_INHERIT = -1;
+/**
+ * The schema a container declares to give its instances a dim of their own.
+ *
+ * Declared in the **vertex** stage although only the fragment shader reads it: that is what makes
+ * `InstanceUniforms` fetch it once per vertex and deliver it as a varying, instead of a texel fetch
+ * per fragment. It also moves any sibling uniform the same way, which costs nothing — images, lines
+ * and models already declare vertex uniforms, and shapes and text declare none besides this.
+ */
+export declare const DIM_SCHEMA: UniformSchemaShader;
+//# sourceMappingURL=dim.d.ts.map

package/dist/objects/materials/dim.js

@@ -0,0 +1,213 @@
+import { useThree } from '@react-three/fiber';
+import { createContext, use, useEffect, useRef, useState } from 'react';
+import { declareBeforeMain } from '../../core/shader-source';
+/**
+ * The dim patch every material installs, reading the layer amount from {@link LayerDimContext}.
+ *
+ * Dimming is deliberately **not** a material prop. It cuts across every material and every def type,
+ * so threading it as a prop would put a `dim` on each material, each container, and each of their
+ * inner components, and any new one would have to remember to forward it. What a material needs to
+ * know is only *how* to be dimmed; what it is dimmed *by* belongs to the layer it draws under.
+ *
+ * The amount is held in one `IUniform` object per material and mutated in place, never replaced, so
+ * an animated dim — floorplan eases the venue's dim over 300ms — costs a number per material per
+ * frame with no recompile.
+ * @returns The patch to call from the material's `onBeforeCompile`.
+ */
+export function useDimPatch() {
+    const dim = use(LayerDimContext);
+    const invalidate = useThree((state) => state.invalidate);
+    // A ref, not state: this object is written after render, every frame of an eased dim, and a ref is
+    // the container React sanctions that for. Its identity is what three holds onto, so the value can
+    // move underneath a program that is already built.
+    const uniformRef = useRef({ value: 0 });
+    // Created once and kept: R3F writes every changed prop onto the material, so handing it a fresh
+    // handler each render risks a recompile per frame — the one thing an animated dim must not cost.
+    const [patch] = useState(() => (parameters) => applyDim(parameters, uniformRef.current));
+    const amount = clampDim(dim);
+    useEffect(() => {
+        uniformRef.current.value = amount;
+        invalidate();
+    }, [amount, invalidate]);
+    return patch;
+}
+/**
+ * Installs dimming into a shader about to be compiled: the layer's uniform, the declarations, and
+ * the application.
+ *
+ * **Applies only once the mesh's uniform prologue is in the shader**, and that guard is what makes
+ * installation order stop mattering. The applied line reads the per-instance amount the prologue
+ * declares as a *local of `main`*, so it has to land in the same `main`. Most meshes inject their
+ * prologue and then call the material's handler, so a material-installed patch is already last. Text
+ * is the exception: troika calls the base material's handler first and then rebuilds `main` around
+ * it — renaming the original `troikaOrigMain` and calling it from a new one — so a patch installed
+ * there would land in a scope the prologue's local never reaches. With this guard that early call
+ * simply does nothing, and `BatchedTextExt` runs the same patch again once its prologue is in.
+ * @param parameters - The shader being compiled.
+ * @param uniform - The layer's dim amount.
+ * @returns Whether the shader was patched.
+ * @throws {Error} If the prologue is present but the shader converts no color, which would leave
+ *   dimming silently absent from a material that asked for it.
+ */
+export function applyDim(parameters, uniform) {
+    const fragment = parameters.fragmentShader;
+    // Nothing to read, so nothing to do — either the mesh declared no per-instance dim, or its
+    // prologue has not been injected yet.
+    if (!fragment.includes(DIM_UNIFORM))
+        return false;
+    // Already installed, which is how a second call after the prologue arrives stays harmless.
+    if (fragment.includes(DIM_FUNCTION))
+        return false;
+    const anchor = colorspaceAnchor(fragment);
+    if (!anchor)
+        throw new Error('applyDim: the shader has no colorspace conversion to dim before.');
+    parameters.uniforms[LAYER_DIM] = uniform;
+    // Ahead of `main`, because these are file-scope declarations — and `dimColor` takes the amount as a
+    // parameter precisely so it needs nothing `main` declares.
+    parameters.fragmentShader = declareBeforeMain(fragment, DIM_DEFS).replace(anchor, `${DIM_APPLY}\n${anchor}`);
+    return true;
+}
+/**
+ * Orders a layer's defs so the dimmed ones draw first and the undimmed ones last, on top.
+ *
+ * What this is for: dimming the venue behind a search leaves the few undimmed defs as the subject of
+ * the frame, and a subject that a dimmed neighbor happens to overlap would be covered by it. Paint
+ * order is the only thing that resolves overlap in a 2D layer — 2D content never writes depth,
+ * leaving depth testing nothing of its own to compare against — so being undimmed has to lift a def
+ * above the defs it is being distinguished from.
+ *
+ * **Stable**, and that is load-bearing rather than a nicety: within each group the defs keep their
+ * array order, which is the order the caller authored and the only thing that decides overlap
+ * between two defs that are both dimmed or both lit. A dim is allowed to lift a def over the dimmed
+ * ones; it is not allowed to reshuffle anything else.
+ *
+ * Returns the input array itself when the rule changes nothing — every def in one group, which is
+ * every layer that is uniformly dimmed or uniformly not. Callers key their order pass on the
+ * identity of what comes back, so an unchanged layer costs neither an allocation nor a re-label.
+ * @param defs - The layer's defs, in authored order.
+ * @param layerDimmed - Whether the layer is dimmed, which is what a def without a `dim` of its own
+ *   inherits. Only the fact is needed, never the amount: this is a two-way split, and every amount
+ *   above zero lands on the same side of it. That is also what keeps an eased layer dim cheap — the
+ *   order pass re-runs when the value crosses zero, not on each of the frames between.
+ * @returns The defs in draw order.
+ */
+export function dimOrdered(defs, layerDimmed) {
+    const dimmed = [];
+    const lit = [];
+    for (const def of defs)
+        (isDimmed(def.dim, layerDimmed) ? dimmed : lit).push(def);
+    return dimmed.length === 0 || lit.length === 0 ? defs : [...dimmed, ...lit];
+}
+/**
+ * Whether a def draws dimmed at all — the one question paint order asks about dimming, as opposed
+ * to the amount, which only the shader reads.
+ * @param dim - The def's own `dim`; `undefined` inherits.
+ * @param layerDimmed - Whether the layer it draws under is dimmed.
+ * @returns Whether it draws dimmed.
+ */
+export function isDimmed(dim, layerDimmed) {
+    return dim === undefined ? layerDimmed : dim > 0;
+}
+/**
+ * Encodes a def's own `dim` for its per-instance uniform.
+ * @param dim - The def's `dim`; `undefined` defers to the layer.
+ * @returns The value to write.
+ */
+export function instanceDim(dim) {
+    return dim === undefined ? DIM_INHERIT : clampDim(dim);
+}
+/**
+ * Clamps a dim amount into the range the shader interpolates over, so `mix` never extrapolates into
+ * a color that is not a dim of the original.
+ * @param dim - The amount to clamp.
+ * @returns The amount, within `[0, 1]`.
+ */
+export function clampDim(dim) {
+    return Math.min(Math.max(dim, 0), 1);
+}
+/**
+ * Where the fragment's color is final and still linear — the point dimming has to land in front of,
+ * spelled whichever way the shader currently spells it.
+ *
+ * Two spellings because three resolves `#include` late, after every `onBeforeCompile`, while troika
+ * resolves them itself while rebuilding `main`. A patch running after troika's rebuild therefore
+ * finds the conversion already expanded to its chunk body. Both name the same line; neither is a
+ * private marker of troika's.
+ * @param fragmentShader - The shader to search.
+ * @returns The anchor found, or `undefined` if the shader converts no color.
+ */
+function colorspaceAnchor(fragmentShader) {
+    const include = /*glsl*/ `#include <colorspace_fragment>`;
+    const expanded = /*glsl*/ `gl_FragColor = linearToOutputTexel( gl_FragColor );`;
+    if (fragmentShader.includes(include))
+        return include;
+    return fragmentShader.includes(expanded) ? expanded : undefined;
+}
+/**
+ * The dim amount a layer draws at, which every material beneath it reads.
+ *
+ * Context rather than a prop because the value crosses the whole subtree and concerns none of the
+ * components between: a container hands its material nothing, and a material that never asked about
+ * layers still dims correctly. `Layer` provides it, and only when it declares a `dim` of its own —
+ * a layer without one is transparent to this, which is exactly what inheritance means.
+ */
+export const LayerDimContext = createContext(0);
+/**
+ * The per-instance uniform a def's own dim is written to. Declared by every container that draws
+ * dimmable defs and read by {@link DIM_APPLY}; the material owns the name, the mesh only has to
+ * declare it before any slot writes one.
+ */
+export const DIM_UNIFORM = 'instanceDim';
+/**
+ * What an instance writes to defer to its layer.
+ *
+ * Any negative value would do; the sentinel only has to fall outside `[0, 1]`, which is why the
+ * amount itself can be stored as-is rather than packed around a zero that means "inherit". The
+ * imperative renderer needed that packing because its texture zero-filled and nothing wrote an
+ * instance on mount — here every instance writes its own value through `useDefSync`, so the fill is
+ * never what a draw reads.
+ */
+export const DIM_INHERIT = -1;
+/**
+ * The schema a container declares to give its instances a dim of their own.
+ *
+ * Declared in the **vertex** stage although only the fragment shader reads it: that is what makes
+ * `InstanceUniforms` fetch it once per vertex and deliver it as a varying, instead of a texel fetch
+ * per fragment. It also moves any sibling uniform the same way, which costs nothing — images, lines
+ * and models already declare vertex uniforms, and shapes and text declare none besides this.
+ */
+export const DIM_SCHEMA = { vertex: { [DIM_UNIFORM]: 'float' } };
+/** The uniform carrying the layer-level amount an instance without one of its own falls back to. */
+const LAYER_DIM = 'uDim';
+/** The signature {@link applyDim} looks for to tell an already-patched shader from a fresh one. */
+const DIM_FUNCTION = 'vec4 dimColor(';
+/**
+ * Dimming's file-scope declarations.
+ *
+ * Dim is a desaturation toward gray, not a darkening — which is why it cannot be baked into a
+ * per-instance tint: a texel sampled per fragment has no tint to bake into.
+ *
+ * `dimColor` takes straight (non-premultiplied) `gl_FragColor` and returns it the same way. The
+ * imperative renderer divided rgb by alpha here and multiplied it back at the end; the round-trip
+ * cancels — `mix(c, dot(w, c) / k, t)` is linear and homogeneous in `c`, so `f(c / a) * a == f(c)`
+ * for every alpha — and it was the one thing that could produce a NaN, at `a == 0`, which SDF text
+ * edges generate in quantity. Dropping it changes no pixel.
+ */
+const DIM_DEFS = /* glsl */ `
+  uniform float ${LAYER_DIM};
+
+  const vec3 grayWeights = vec3(0.299, 0.587, 0.114);
+  const float darkenFactor = pow(2., 2.2); // Gamma corrected
+
+  ${DIM_FUNCTION}vec4 col, float amount) {
+    vec3 gray = vec3(dot(grayWeights, col.rgb));
+    return vec4(mix(col.rgb, gray / darkenFactor, amount), col.a);
+  }
+`;
+/**
+ * Dimming applied to the fragment, while the color is still linear — which is what
+ * `darkenFactor`'s gamma correction assumes.
+ */
+const DIM_APPLY = /* glsl */ `
+  gl_FragColor = dimColor(gl_FragColor, ${DIM_UNIFORM} < 0. ? ${LAYER_DIM} : ${DIM_UNIFORM});
+`;

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

@@ -0,0 +1,6 @@
+import { type MaterialParameters } from 'three';
+/**
+ * Material parameter defaults, shared between all types
+ */
+export declare const sharedParams: MaterialParameters;
+//# sourceMappingURL=shared.d.ts.map

package/dist/objects/materials/shared.js

@@ -0,0 +1,51 @@
+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,
+};

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;
+});