@expofp/renderer 0.0.0-experimental.2d6c681

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

@@ -0,0 +1,92 @@
+import { type ColorRepresentation, type WebGLProgramParametersWithUniforms } from 'three';
+/** Props for {@link ColorMaterial}. */
+export interface ColorMaterialProps {
+    /** Base color. Defaults to white, which is what a per-instance tint multiplies against. */
+    color?: ColorRepresentation;
+    /**
+     * Whether this batch draws volumes, which are the meshes carrying real z. A volume needs shading
+     * to read as solid, and depth testing to occlude itself and its neighbors. Defaults to `false`,
+     * which is the flat content every 2D primitive in a plan draws as.
+     */
+    solid?: boolean;
+    /**
+     * Whether those volumes are translucent, which moves them into three's transparent pass.
+     *
+     * This means something only together with {@link solid}. Flat content never uses it, for the reason
+     * the note below gives.
+     */
+    translucent?: boolean;
+    /**
+     * Runs on the shader before the dim patch runs. This is the slot for a caller's own shader surgery,
+     * such as the background quad's clip-space projection and its dim-uniform stand-in.
+     *
+     * This component captures the handler at the first render and keeps it for the material's lifetime,
+     * the way it keeps every other axis. A handler identity that changes risks a recompile per render.
+     */
+    onBeforeCompile?: (parameters: WebGLProgramParametersWithUniforms) => void;
+}
+/**
+ * The material a shape batch draws with. It renders as a child of the mesh, so R3F attaches, updates
+ * and disposes it. It is also troika's base material for text, which never asks for `solid`. See
+ * `Texts`.
+ *
+ * One component with a branch rather than two files. The two are the same thing along one axis, which
+ * is what a batch of shapes draws with. The three differences read best side by side:
+ *
+ * | | flat (default) | `solid` |
+ * | --- | --- | --- |
+ * | base | `MeshBasicMaterial`, unlit | `MeshLambertMaterial`, lit |
+ * | `depthWrite` | off, from {@link sharedParams} | on |
+ * | polygon offset | on, from {@link sharedParams} | off |
+ *
+ * Each difference carries its own weight. A volume is the one kind of content that writes depth. That
+ * is how its own faces resolve against each other, and it is what lets 2D content drawn afterwards be
+ * occluded by it. A volume carries no polygon offset, because solids are what everything else is
+ * biased against. An offset on the solids too only moves the problem.
+ *
+ * The lit branch is `MeshLambertMaterial` alone. It has no specular lobe at all, so this never sets
+ * `ior` or `specularIntensity`. three evaluates it per fragment with `BRDF_Lambert`, which is
+ * `albedo / π`. Its vertex shader carries `batching_vertex` and `color_vertex`, so
+ * `BatchedMesh.setColorAt` keeps working. Its fragment shader carries the output chain, so the dim
+ * patch keeps its anchor.
+ *
+ * The light rig alone holds a roof to its authored color now. `Lighting` derives both intensities from
+ * the one `contrast` control every frame. An up-facing surface then lands on the color it was authored
+ * with, and no surface the design accounts for clips.
+ *
+ * Per-instance color arrives through `BatchedMesh.setColorAt` on either branch. three injects the
+ * batching-color chunk for whatever material the batch draws with.
+ *
+ * `translucent` is the one place the array-order contract bends, and it bends on purpose. It sets
+ * `transparent: true`, which moves the batch into three's transparent list. three draws that list
+ * after every opaque object in the scene, whatever `renderOrder` says. See
+ * `WebGLRenderer.renderScene`. That is what lets a translucent volume blend with the opaque content
+ * behind it, even when that content lives in a later layer. No position in the ordered stream can do
+ * the same, because a translucent surface can only blend with what already sits in the framebuffer.
+ *
+ * The reverse case is what it costs. Take a planar def sitting on a translucent volume, such as a
+ * label or a logo on a glass roof. It draws in the opaque pass, so it lands before the volume. The
+ * label composites against whatever was under the glass rather than onto it, and the volume then
+ * glazes over the label. So a translucent solid is right about what is behind it and wrong about what is on it. Flat
+ * content never takes this flag for the same reason, and for one of its own: 2D content is coplanar,
+ * so it has no depth order to sort by and order is all it has.
+ *
+ * `forceSinglePass` is switched off here alone. three draws a `DoubleSide` transparent material
+ * twice, back faces and then front. See `WebGLRenderer.js:1348`. That is a correctly ordered two-pass
+ * for free. It is why a closed translucent volume does not blend its own far and near surfaces in
+ * whatever order the batch packed them.
+ *
+ * Depth writes stay on even when translucent, which is not three's usual convention. Two rules depend
+ * on it. A translucent volume must still be occluded by anything nearer, and a farther volume drawn
+ * later must not paint over it. MapLibre makes the same choice for `fill-extrusion`, with
+ * `DepthMode.ReadWrite` in both of its passes. The design spec's Decision 2 records the trade and the
+ * two rejected alternatives.
+ *
+ * The branch is stable for a mounted batch, because `Shapes` renders a separate element per kind and
+ * each one carries a constant `solid`. So R3F never swaps one base class for the other under a live
+ * mesh.
+ * @param props - The material's base color, and whether it draws volumes.
+ * @returns The material element.
+ */
+export declare function ColorMaterial(props: ColorMaterialProps): import("react").JSX.Element;
+//# sourceMappingURL=ColorMaterial.d.ts.map

package/dist/objects/materials/ColorMaterial.js

@@ -0,0 +1,124 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useEffect, useState } from 'react';
+import { createLogger } from '../../utils/logging';
+import { useLayerOverlay } from '../layer/layer-context';
+import { applyAmbientOcclusion } from './effects/ao';
+import { useDimPatch } from './effects/color-dim';
+import { applyContactShadow } from './effects/contact-shadow';
+import { useSceneEffects } from './effects/effects-context';
+import { overlayParams, sharedParams } from './shared';
+const logger = createLogger('color-material');
+/**
+ * The material a shape batch draws with. It renders as a child of the mesh, so R3F attaches, updates
+ * and disposes it. It is also troika's base material for text, which never asks for `solid`. See
+ * `Texts`.
+ *
+ * One component with a branch rather than two files. The two are the same thing along one axis, which
+ * is what a batch of shapes draws with. The three differences read best side by side:
+ *
+ * | | flat (default) | `solid` |
+ * | --- | --- | --- |
+ * | base | `MeshBasicMaterial`, unlit | `MeshLambertMaterial`, lit |
+ * | `depthWrite` | off, from {@link sharedParams} | on |
+ * | polygon offset | on, from {@link sharedParams} | off |
+ *
+ * Each difference carries its own weight. A volume is the one kind of content that writes depth. That
+ * is how its own faces resolve against each other, and it is what lets 2D content drawn afterwards be
+ * occluded by it. A volume carries no polygon offset, because solids are what everything else is
+ * biased against. An offset on the solids too only moves the problem.
+ *
+ * The lit branch is `MeshLambertMaterial` alone. It has no specular lobe at all, so this never sets
+ * `ior` or `specularIntensity`. three evaluates it per fragment with `BRDF_Lambert`, which is
+ * `albedo / π`. Its vertex shader carries `batching_vertex` and `color_vertex`, so
+ * `BatchedMesh.setColorAt` keeps working. Its fragment shader carries the output chain, so the dim
+ * patch keeps its anchor.
+ *
+ * The light rig alone holds a roof to its authored color now. `Lighting` derives both intensities from
+ * the one `contrast` control every frame. An up-facing surface then lands on the color it was authored
+ * with, and no surface the design accounts for clips.
+ *
+ * Per-instance color arrives through `BatchedMesh.setColorAt` on either branch. three injects the
+ * batching-color chunk for whatever material the batch draws with.
+ *
+ * `translucent` is the one place the array-order contract bends, and it bends on purpose. It sets
+ * `transparent: true`, which moves the batch into three's transparent list. three draws that list
+ * after every opaque object in the scene, whatever `renderOrder` says. See
+ * `WebGLRenderer.renderScene`. That is what lets a translucent volume blend with the opaque content
+ * behind it, even when that content lives in a later layer. No position in the ordered stream can do
+ * the same, because a translucent surface can only blend with what already sits in the framebuffer.
+ *
+ * The reverse case is what it costs. Take a planar def sitting on a translucent volume, such as a
+ * label or a logo on a glass roof. It draws in the opaque pass, so it lands before the volume. The
+ * label composites against whatever was under the glass rather than onto it, and the volume then
+ * glazes over the label. So a translucent solid is right about what is behind it and wrong about what is on it. Flat
+ * content never takes this flag for the same reason, and for one of its own: 2D content is coplanar,
+ * so it has no depth order to sort by and order is all it has.
+ *
+ * `forceSinglePass` is switched off here alone. three draws a `DoubleSide` transparent material
+ * twice, back faces and then front. See `WebGLRenderer.js:1348`. That is a correctly ordered two-pass
+ * for free. It is why a closed translucent volume does not blend its own far and near surfaces in
+ * whatever order the batch packed them.
+ *
+ * Depth writes stay on even when translucent, which is not three's usual convention. Two rules depend
+ * on it. A translucent volume must still be occluded by anything nearer, and a farther volume drawn
+ * later must not paint over it. MapLibre makes the same choice for `fill-extrusion`, with
+ * `DepthMode.ReadWrite` in both of its passes. The design spec's Decision 2 records the trade and the
+ * two rejected alternatives.
+ *
+ * The branch is stable for a mounted batch, because `Shapes` renders a separate element per kind and
+ * each one carries a constant `solid`. So R3F never swaps one base class for the other under a live
+ * mesh.
+ * @param props - The material's base color, and whether it draws volumes.
+ * @returns The material element.
+ */
+export function ColorMaterial(props) {
+    // Read and then default, rather than a destructuring default. The React Compiler cannot lower
+    // `const { color = 'white' } = props` (BuildHIR::lowerAssignment, AssignmentPattern), and
+    // floorplan's dev build runs the compiler with `panicThreshold: 'all_errors'`, which turns that
+    // into a hard 500 for the whole app. Storybook's pass defaults to `panicThreshold: 'none'` and
+    // skips the component in silence, so only the running app shows the failure.
+    const color = props.color ?? 'white';
+    const solid = props.solid === true;
+    const overlay = useLayerOverlay();
+    // Overlay is a contract for planar content. A volume that stops depth testing loses its own self
+    // occlusion, because its far faces then paint over its near ones in pack order. Making it work
+    // needs a depth clear between the tiers, so a second render pass, which external mode does not
+    // own. So a volume ignores the flag completely and says once that it did.
+    useEffect(() => {
+        if (solid && overlay) {
+            logger.warn('overlay has no effect on a solid batch, so it is ignored.');
+        }
+    }, [solid, overlay]);
+    // Handed to both branches, because a volume dims the way flat content does. The patch runs on
+    // whatever `gl_FragColor` the material arrived at, which for a lit material is the shaded color.
+    const dimPatch = useDimPatch();
+    // The scene's own effect state, captured once. Its identity never changes, so the compiled program
+    // holds the uniform objects a frame and a slider write into, and neither one costs a recompile.
+    const effects = useSceneEffects();
+    // The caller's surgery first, then dimming. A pre-patch that declares the dim uniform's stand-in
+    // then sits in the shader before the dim patch looks for it. One stable handler, for the reason
+    // `useDimPatch` keeps its own.
+    const [onBeforeCompile] = useState(() => {
+        const pre = props.onBeforeCompile;
+        return (parameters) => {
+            pre?.(parameters);
+            // Volumes only. Flat content has no height to read, and its unit plane sits at `z = 0`, where
+            // the contact shadow takes the whole surface. Flat content also stays out of the depth prepass,
+            // so an occlusion read finds no stored depth that agrees with it.
+            //
+            // Both effects land ahead of the dim patch, so the three run in the order they describe: the
+            // shadow and the occlusion shade the surface, and dimming desaturates the result. All three
+            // insert above the same anchor, so the later install runs last.
+            if (solid) {
+                applyContactShadow(parameters, effects);
+                applyAmbientOcclusion(parameters, effects);
+            }
+            dimPatch(parameters);
+        };
+    });
+    if (solid) {
+        const translucent = props.translucent ?? false;
+        return (_jsx("meshLambertMaterial", { ...sharedParams, color: color, depthWrite: true, polygonOffset: false, transparent: translucent, forceSinglePass: !translucent, onBeforeCompile: onBeforeCompile }));
+    }
+    return (_jsx("meshBasicMaterial", { ...sharedParams, ...(overlay ? overlayParams : null), color: color, onBeforeCompile: onBeforeCompile }));
+}

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

@@ -0,0 +1,44 @@
+import { type ColorRepresentation } from 'three';
+/** Props for {@link LineMaterial}. */
+export interface LineMaterialProps {
+    /** Base color. Defaults to white, which is what a per-instance tint multiplies against. */
+    color?: ColorRepresentation;
+    /**
+     * Width every member without one of its own draws at, in screen-space pixels — `BatchedLinesImpl`
+     * resolves an unset per-member width to this. Defaults to 1.
+     */
+    width?: number;
+}
+/**
+ * The material line batches draw with, rendered as a child of the batch so R3F attaches, updates,
+ * and disposes it.
+ *
+ * Three's own, configured — it knows nothing about batching. What makes one of these draw members
+ * that differ in width and tint is a patch the batch installs on whatever material it is handed
+ * (`core/lines/lines-material`), so this stays a material a plain `LineSegments2` could draw with.
+ *
+ * `worldUnits` is left at three's default, so `width` is screen-space and a line keeps its
+ * thickness as the floorplan zooms. `depthFunc` and the blending come from the shared params, the
+ * same as every other 2D layer: order decides overlap, not depth.
+ *
+ * **The stencil is what keeps translucent lines from darkening where they overlap.** Alpha blending
+ * composites per fragment, so anywhere two line quads cover the same pixel — a route's shared
+ * endpoints, where two round caps land on top of each other, or two lines simply crossing — the
+ * color is blended twice and reads darker than either line. The three settings below make the first
+ * fragment to reach a pixel the only one that draws:
+ *
+ * - `stencilFunc: NotEqual` against {@link LINE_STENCIL_REF} passes only where the layer has not
+ *   drawn yet.
+ * - `stencilZPass: Replace` stamps the ref as it passes, so the next fragment there fails.
+ * - `stencilWrite` turns both on.
+ *
+ * Two consequences worth knowing. Lines within a layer never blend with *each other* — only the
+ * winner shows — so a line that must blend over another belongs in its own layer. And "first
+ * fragment wins" is why a line batch is drawn back to front: the one that paints on top has to
+ * rasterize first. Between layers nothing changes, because the clear below hands each
+ * batch a fresh stencil, so ordinary blending and occlusion still apply across them.
+ * @param props - The material's base color and fallback width.
+ * @returns The material element.
+ */
+export declare function LineMaterial(props: LineMaterialProps): import("react").JSX.Element;
+//# sourceMappingURL=LineMaterial.d.ts.map

package/dist/objects/materials/LineMaterial.js

@@ -0,0 +1,74 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { extend } from '@react-three/fiber';
+import { NotEqualStencilFunc, ReplaceStencilOp, } from 'three';
+import { LineMaterial as LineMaterialBase } from 'three/addons/lines/LineMaterial.js';
+import { useLayerOverlay } from '../layer/layer-context';
+import { useDimPatch } from './effects/color-dim';
+import { overlayParams, sharedParams } from './shared';
+/**
+ * The stencil value a line layer stamps on every pixel it covers.
+ *
+ * `255` is deliberate rather than arbitrary. In the MapLibre embed the SDK renders into the map's
+ * own canvas and GL context, so this is *MapLibre's* stencil buffer: it assigns tile clipping ids
+ * counting up from zero, and the floorplan draws last, so taking the top of the range keeps the two
+ * out of each other's way.
+ */
+const LINE_STENCIL_REF = 255;
+/**
+ * Registers three's line material as an R3F element, by value so the generated key cannot collide
+ * with anything three puts in the catalog when the canvas mounts.
+ */
+const LineMaterialElement = extend(LineMaterialBase);
+/**
+ * The material line batches draw with, rendered as a child of the batch so R3F attaches, updates,
+ * and disposes it.
+ *
+ * Three's own, configured — it knows nothing about batching. What makes one of these draw members
+ * that differ in width and tint is a patch the batch installs on whatever material it is handed
+ * (`core/lines/lines-material`), so this stays a material a plain `LineSegments2` could draw with.
+ *
+ * `worldUnits` is left at three's default, so `width` is screen-space and a line keeps its
+ * thickness as the floorplan zooms. `depthFunc` and the blending come from the shared params, the
+ * same as every other 2D layer: order decides overlap, not depth.
+ *
+ * **The stencil is what keeps translucent lines from darkening where they overlap.** Alpha blending
+ * composites per fragment, so anywhere two line quads cover the same pixel — a route's shared
+ * endpoints, where two round caps land on top of each other, or two lines simply crossing — the
+ * color is blended twice and reads darker than either line. The three settings below make the first
+ * fragment to reach a pixel the only one that draws:
+ *
+ * - `stencilFunc: NotEqual` against {@link LINE_STENCIL_REF} passes only where the layer has not
+ *   drawn yet.
+ * - `stencilZPass: Replace` stamps the ref as it passes, so the next fragment there fails.
+ * - `stencilWrite` turns both on.
+ *
+ * Two consequences worth knowing. Lines within a layer never blend with *each other* — only the
+ * winner shows — so a line that must blend over another belongs in its own layer. And "first
+ * fragment wins" is why a line batch is drawn back to front: the one that paints on top has to
+ * rasterize first. Between layers nothing changes, because the clear below hands each
+ * batch a fresh stencil, so ordinary blending and occlusion still apply across them.
+ * @param props - The material's base color and fallback width.
+ * @returns The material element.
+ */
+export function LineMaterial(props) {
+    // Read-then-default rather than destructuring defaults, which the React Compiler cannot lower —
+    // see `ColorMaterial` for what that costs.
+    const color = props.color ?? 'white';
+    const width = props.width ?? 1;
+    const onBeforeCompile = useDimPatch();
+    const overlay = useLayerOverlay();
+    /**
+     * Hands the batch about to draw a clean stencil to stamp.
+     *
+     * The stamps are per *layer*, not per frame: without this, a batch drawn later would be rejected
+     * everywhere an earlier one already covered, and a route's animated overlay would not appear over
+     * the route beneath it. Clearing here rather than in the batch keeps it beside the settings that
+     * make it necessary — this material is what each line layer mounts its own copy of, so "once per
+     * batch, before it draws" falls out of where the callback lives.
+     * @param renderer - The renderer about to draw the batch.
+     */
+    function onBeforeRender(renderer) {
+        renderer.clearStencil();
+    }
+    return (_jsx(LineMaterialElement, { ...sharedParams, ...(overlay ? overlayParams : null), color: color, linewidth: width, stencilWrite: true, stencilFunc: NotEqualStencilFunc, stencilZPass: ReplaceStencilOp, stencilRef: LINE_STENCIL_REF, onBeforeRender: onBeforeRender, onBeforeCompile: onBeforeCompile }));
+}

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

@@ -0,0 +1,53 @@
+import { type Material } from 'three';
+/** Props for {@link ModelMaterial}. */
+export interface ModelMaterialProps {
+    /**
+     * The material the GLB authored. Every layer drawing the same model shares it, so nothing mutates
+     * it. This component 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, and whether alpha blends at all is a material
+     * decision. three drops a `NormalBlending` material with `transparent: false` to `NoBlending`, in
+     * `WebGLState.setMaterial`, which discards the alpha. 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, for
+ * the plan's shading, and for per-instance opacity.
+ *
+ * A model is one of the two kinds of content that write depth, translucent models included. That is
+ * what makes a model 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 so that it can be biased against
+ * surfaces like these, so a model carries no offset of its own.
+ *
+ * A model takes both darkening terms, the way a solid shape batch does. The GLTF loader produces a
+ * `MeshStandardMaterial`, which carries the same output chain and the same placement chunk, so both
+ * patches apply unchanged. The contact shadow reads a plan-space height. That is what makes it correct
+ * for geometry authored in the GLB's own coordinates and placed by a per-instance matrix.
+ *
+ * An asset declaring `KHR_materials_unlit` takes both terms too, on purpose. The loader hands such a
+ * material over as a `MeshBasicMaterial`, which carries both anchors, so nothing here has to sniff a
+ * type to include it. Neither term is a light. They are the plan's own depth cue, applied to whatever
+ * color the material arrived at. The design asks for one shade of shadow across the plan. An unlit
+ * booth with no darkening at its base reads as floating beside a lit one. That is a worse answer to
+ * "unlit" than shading it.
+ *
+ * Everything else about the material stays as the GLB authored it: maps, roughness, metalness,
+ * emissive, side. A model's own appearance is the asset's business. How the plan is shaded is not.
+ * @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,111 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useEffect, useState } from 'react';
+import { LessEqualDepth, } from 'three';
+import { applyAmbientOcclusion } from './effects/ao';
+import { useDimPatch } from './effects/color-dim';
+import { applyContactShadow } from './effects/contact-shadow';
+import { useSceneEffects } from './effects/effects-context';
+/**
+ * The material a model draws with: the GLB's own, cloned and adjusted for the plan's depth rules, for
+ * the plan's shading, and for per-instance opacity.
+ *
+ * A model is one of the two kinds of content that write depth, translucent models included. That is
+ * what makes a model 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 so that it can be biased against
+ * surfaces like these, so a model carries no offset of its own.
+ *
+ * A model takes both darkening terms, the way a solid shape batch does. The GLTF loader produces a
+ * `MeshStandardMaterial`, which carries the same output chain and the same placement chunk, so both
+ * patches apply unchanged. The contact shadow reads a plan-space height. That is what makes it correct
+ * for geometry authored in the GLB's own coordinates and placed by a per-instance matrix.
+ *
+ * An asset declaring `KHR_materials_unlit` takes both terms too, on purpose. The loader hands such a
+ * material over as a `MeshBasicMaterial`, which carries both anchors, so nothing here has to sniff a
+ * type to include it. Neither term is a light. They are the plan's own depth cue, applied to whatever
+ * color the material arrived at. The design asks for one shade of shadow across the plan. An unlit
+ * booth with no darkening at its base reads as floating beside a lit one. That is a worse answer to
+ * "unlit" than shading it.
+ *
+ * Everything else about the material stays as the GLB authored it: maps, roughness, metalness,
+ * emissive, side. A model's own appearance is the asset's business. How the plan is shaded is not.
+ * @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();
+    // The scene's own effect state, captured once. Its identity never changes, so the compiled program
+    // holds the uniform objects a frame and a slider write into, and neither one costs a recompile.
+    const effects = useSceneEffects();
+    const translucent = props.translucent ?? false;
+    // Cloned once and held in state. R3F disposes a material it created on unmount, and the source
+    // belongs to the module-level model cache, which can still be serving other layers. Every patch
+    // goes on with the clone, once. Each patch is stable and reads its current values through the
+    // uniforms it owns.
+    const [material] = useState(() => adjust(source.clone(), opacityUniform, dimPatch, effects, translucent));
+    useEffect(() => () => material.dispose(), [material]);
+    return _jsx("primitive", { object: material, attach: "material" });
+}
+/**
+ * Applies the plan's depth rules, its two darkening terms 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 effects - The scene's shared effect state, which both darkening terms read.
+ * @param translucent - Whether any instance drawing it needs its alpha blended.
+ * @returns The same material.
+ */
+function adjust(material, opacityUniform, dimPatch, effects, translucent) {
+    material.depthFunc = LessEqualDepth;
+    material.polygonOffset = false;
+    // `transparent` moves a material into three's transparent list, which three draws after every
+    // opaque object in the scene whatever the layer order says. That 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,
+    // the way `Shapes` splits its volumes. It re-splits when a def's opacity crosses 1. `ColorMaterial`
+    // makes the same trade and records what it costs: a planar def sitting on a translucent one draws
+    // 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 the
+    // choice this renderer makes. Two of the plan's rules depend on it. A translucent model must still
+    // be occluded by anything nearer the camera. A planar def drawn after it, a label or a 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 has nothing to reject it, and it
+    // paints straight over the translucent one in front of it.
+    //
+    // What it costs is a view through a translucent surface to content drawn after it, and no
+    // painter's-order renderer can offer that. Blending needs depth order, and array order is authoring
+    // order. MapLibre makes the same trade for `fill-extrusion`, with `DepthMode.ReadWrite` in both of
+    // its passes, and degrades to a color error rather than a structural one. The obligation it puts on
+    // callers is to order a translucent model's layer after whatever has to show through it. The design
+    // spec's Decision 2 spells that out, along with the two alternatives and why each one loses more
+    // than it gains.
+    material.depthWrite = true;
+    const chained = material.onBeforeCompile.bind(material);
+    material.onBeforeCompile = (parameters, ...rest) => {
+        chained(parameters, ...rest);
+        // Applied at the 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());
+        // The plan's shading, ahead of the dim patch. All three insert above the same anchor, so the later
+        // install runs last, and the order they run in is the order they describe: the shadow and the
+        // occlusion shade the surface, and dimming desaturates the result.
+        applyContactShadow(parameters, effects);
+        applyAmbientOcclusion(parameters, effects);
+        // Dim touches rgb and opacity touches alpha, so the two patches stay independent in any order. 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,33 @@
+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 an 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 to draw the whole `map` unpatched, in any
+     * context.
+     */
+    uvOffset?: string;
+    /**
+     * The name of a per-instance `float` uniform holding the instance's opacity, for a mesh that
+     * declares and writes one. Omit it to leave the fragment shader unpatched.
+     */
+    opacityUniform?: 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>`, replacing the stock chunk's value. Instanced meshes wrap this `onBeforeCompile`
+ * and inject their uniform fetch at the top of `main()`, so the uniform is in scope here.
+ * @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,48 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { OneFactor } from 'three';
+import { useLayerOverlay } from '../layer/layer-context';
+import { useDimPatch } from './effects/color-dim';
+import { overlayParams, 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>`, replacing the stock chunk's value. Instanced meshes wrap this `onBeforeCompile`
+ * and inject their uniform fetch at the top of `main()`, so the uniform is in scope here.
+ * @param props - The material's texture and optional uv-offset uniform name.
+ * @returns The material element.
+ */
+export function TextureMaterial(props) {
+    const { map, uvOffset, opacityUniform } = props;
+    const applyDim = useDimPatch();
+    const overlay = useLayerOverlay();
+    function onBeforeCompile(parameters) {
+        applyDim(parameters);
+        if (uvOffset) {
+            parameters.vertexShader = parameters.vertexShader.replace('#include <uv_vertex>', 
+            /*glsl*/ `
+        #include <uv_vertex>
+        vMapUv = uv * ${uvOffset}.zw + ${uvOffset}.xy;
+      `.trim());
+        }
+        if (opacityUniform) {
+            // All four channels: the blend is premultiplied, so rgb already carries the texel's alpha and
+            // must carry the opacity too. Scaling `a` alone leaves a bright halo instead of a faded pin.
+            //
+            // After `colorspace_fragment`, so rgb is already sRGB-encoded and blends with the same weight
+            // as alpha. Before the encode, `0.5` would read about 73% opaque. Dim patches an earlier chunk
+            // (`tonemapping_fragment`), so the two never share an anchor.
+            parameters.fragmentShader = parameters.fragmentShader.replace('#include <colorspace_fragment>', 
+            /*glsl*/ `
+        #include <colorspace_fragment>
+        gl_FragColor *= ${opacityUniform};
+      `.trim());
+        }
+    }
+    // An atlas texture is premultiplied (see `makeAtlasTexture`), so this needs `blendSrc: OneFactor`
+    // rather than `sharedParams`'s straight-alpha source term; `blendDst` is unaffected. The override
+    // lives here because `ColorMaterial` and `LineMaterial` share `sharedParams` and are never
+    // premultiplied.
+    return (_jsx("meshBasicMaterial", { ...sharedParams, ...(overlay ? overlayParams : null), blendSrc: OneFactor, map: map, onBeforeCompile: onBeforeCompile }));
+}