@expofp/renderer 3.2.5 → 3.27.0

package/dist/objects/layer/visibility-gui.js

@@ -0,0 +1,93 @@
+import { use, useEffect } from 'react';
+import { useGui } from '../../debug/debug-context';
+import { isLayerDefs } from '../../types/guards';
+import { childrenOf, subscribeDef, update } from '../../update';
+import { MountSchedulerContext } from './mount-scheduler';
+/**
+ * Adds a visibility checkbox for one layer: labeled with the layer's name, checked while the
+ * layer is visible. Toggling flips `layer.hidden` and calls `update(layer)` — exactly the write an
+ * SDK caller would make, so the checkbox exercises the real update path. The controller binds a
+ * getter/setter proxy over the def and `listen()`s, so a `hidden` change made elsewhere shows up
+ * in the checkbox too.
+ * @param folder - The folder to add the checkbox to.
+ * @param layer - The layer the checkbox controls.
+ */
+function addVisibilityToggle(folder, layer) {
+    const proxy = {
+        get visible() {
+            return !layer.hidden;
+        },
+        set visible(value) {
+            layer.hidden = !value;
+            update(layer);
+        },
+    };
+    folder.add(proxy, 'visible').name(layer.name).listen();
+}
+/**
+ * Returns a sync function that rebuilds `folder`'s checkboxes when the listed layers changed since
+ * the last call, and is a cheap no-op otherwise — safe to subscribe to chatty sources (every
+ * `update()` on a layer, every scheduler admission) without churning the GUI.
+ * @param folder - The folder holding the checkboxes.
+ * @param list - Reads the layers to list.
+ * @returns The sync function.
+ */
+function makeSyncToggles(folder, list) {
+    let shown = [];
+    return () => {
+        const layers = list();
+        if (layers.length === shown.length && layers.every((layer, i) => layer === shown[i]))
+            return;
+        shown = layers;
+        for (const controller of [...folder.controllers])
+            controller.destroy();
+        for (const layer of layers)
+            addVisibilityToggle(folder, layer);
+    };
+}
+/**
+ * Builds the layer-visibility debug GUI: called by the tree's root `Layer` alone, a no-op without
+ * a debug GUI in context. Two folders, one checkbox per layer:
+ *
+ * - **Main layers** — the root's direct child layers, in child order, kept current through the
+ *   same store subscription `update()` drives (a root membership change rebuilds the rows).
+ * - **Content layers** — every leaf (shape) layer in the tree, in the mount scheduler's
+ *   registration order, which is the flattened leaf order. No new bookkeeping tracks the leaves:
+ *   `useStagedMount` already registers each one with the scheduler, so this folder mirrors the
+ *   scheduler's queue and follows leaves as they mount and unmount. Without a scheduler in
+ *   context (a plain `<Layer>` mount outside `Scene`) the folder stays empty.
+ *
+ * The effect runs entirely against the defs and the GUI — toggles never re-render the layer tree
+ * beyond what `update()` itself triggers.
+ * @param layer - The tree's root layer def.
+ */
+export function useVisibilityGui(layer) {
+    const gui = useGui();
+    const scheduler = use(MountSchedulerContext);
+    // This effect runs after every descendant's, so by first sync the scheduler's queue already
+    // holds the whole initial tree's leaves.
+    useEffect(() => {
+        if (!gui)
+            return undefined;
+        const main = gui.addFolder('Main layers');
+        const syncMain = makeSyncToggles(main, () => {
+            const children = childrenOf(layer);
+            return isLayerDefs(children) ? children : [];
+        });
+        syncMain();
+        const unsubscribeMain = subscribeDef(layer, syncMain);
+        const content = gui.addFolder('Content layers');
+        let unsubscribeContent;
+        if (scheduler) {
+            const syncContent = makeSyncToggles(content, () => scheduler.leaves());
+            syncContent();
+            unsubscribeContent = scheduler.subscribe(syncContent);
+        }
+        return () => {
+            unsubscribeMain();
+            unsubscribeContent?.();
+            main.destroy();
+            content.destroy();
+        };
+    }, [gui, scheduler, layer]);
+}

package/dist/objects/lines/LineInstance.d.ts

@@ -0,0 +1,21 @@
+import { type LineDef } from '../../types/defs';
+import { type InstanceProps } from '../containers';
+import { type LineContainer } from './line-container';
+/** Props for {@link LineInstance}. */
+export type LineInstanceProps = InstanceProps<LineDef, LineContainer>;
+/**
+ * Keeps one line's instance current: claims a slot on mount, writes the def's endpoints, color,
+ * width and visibility on mount and after every `update(def)`, and releases the slot on unmount.
+ *
+ * Renders no scene node — the batch belongs to the container. Nothing here can force a re-claim:
+ * unlike a shape, whose geometry is its slot's resource, a line is the same segment template
+ * wherever it runs, so moving one is an ordinary write and its slot survives.
+ *
+ * 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 batch, not the scene graph.
+ */
+export declare const LineInstance: import("react").MemoExoticComponent<(props: LineInstanceProps) => null>;
+//# sourceMappingURL=LineInstance.d.ts.map

package/dist/objects/lines/LineInstance.js

@@ -0,0 +1,73 @@
+import { memo } from 'react';
+import { Vector3 } from 'three';
+import { createLogger } from '../../utils/logging';
+import { useDefSync, writeColorIfChanged } from '../containers';
+const logger = createLogger('line-instance');
+/**
+ * Keeps one line's instance current: claims a slot on mount, writes the def's endpoints, color,
+ * width and visibility on mount and after every `update(def)`, and releases the slot on unmount.
+ *
+ * Renders no scene node — the batch belongs to the container. Nothing here can force a re-claim:
+ * unlike a shape, whose geometry is its slot's resource, a line is the same segment template
+ * wherever it runs, so moving one is an ordinary write and its slot survives.
+ *
+ * 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 batch, not the scene graph.
+ */
+export const LineInstance = memo(function LineInstance(props) {
+    const { def, container } = props;
+    useDefSync(container, def, null, (slot) => {
+        writeLinePoints(container, slot, def);
+        writeColorIfChanged(container.mesh, slot, def, logger);
+        writeLineWidth(container, slot, def);
+    });
+    return null;
+});
+/**
+ * Writes a line's endpoints into its instance.
+ *
+ * A `LineLike` is 2D plus an optional elevation, which is what places the segment on its layer's
+ * plane; the batch compares and skips, so a def that only changed color pays two vector fills.
+ * @param container - The container holding the instance.
+ * @param slot - The instance's slot.
+ * @param def - The line def supplying the endpoints.
+ */
+function writeLinePoints(container, slot, def) {
+    const { p0, p1, elevation = 0 } = def.points;
+    _start.set(p0.x, p0.y, elevation);
+    _end.set(p1.x, p1.y, elevation);
+    // Compared before writing, like every other instance write: a color-only `update(def)` re-runs the
+    // whole sync, and an unchanged segment costs six comparisons instead of two uniform uploads and a
+    // bounds invalidation.
+    container.mesh.getPointsAt(slot, _heldStart, _heldEnd);
+    if (_heldStart.equals(_start) && _heldEnd.equals(_end))
+        return;
+    container.mesh.setPointsAt(slot, _start, _end);
+}
+/**
+ * Writes a line's width into its instance, skipping the upload when it did not change.
+ *
+ * Clamped at zero, which is where the def's contract and the batch's part ways: the batch reads a
+ * negative width as "this member has none of its own" and falls back to the material's, an
+ * affordance for callers that never set one. A `LineDef` always carries a width, so a negative one
+ * is bad input rather than a request to inherit — and it must not come out thicker than a zero.
+ * @param container - The container holding the instance.
+ * @param slot - The instance's slot.
+ * @param def - The line def supplying the width.
+ */
+function writeLineWidth(container, slot, def) {
+    const width = Math.max(def.width, 0);
+    if (container.mesh.getWidthAt(slot) === width)
+        return;
+    container.mesh.setWidthAt(slot, width);
+}
+// Scratch shared by every endpoint write: filled and consumed within a single synchronous
+// statement, so a write costs one buffer upload and no allocation. The `_held*` pair is only ever
+// read back and compared, so it never collides with the endpoints being written.
+const _start = new Vector3();
+const _end = new Vector3();
+const _heldStart = new Vector3();
+const _heldEnd = new Vector3();

package/dist/objects/lines/Lines.d.ts

@@ -0,0 +1,17 @@
+import { type LineDef } from '../../types/defs';
+import { type DefsProps } from '../containers';
+/** Props for {@link Lines}. */
+export type LinesProps = DefsProps<LineDef>;
+/**
+ * Draws a collection of lines as members of one `BatchedLines`, so a layer of route segments
+ * renders in a single instanced draw.
+ *
+ * Membership is reconciled by React exactly as it is for shapes: a new `defs` array re-renders this
+ * component and React mounts or unmounts only the delta, with no differ of our own. Order is applied
+ * as it is for images — the container labels each slot with its def's place in the layer, and the
+ * batch's `customSort` orders the draw list by it, so a reorder writes nothing to the GPU.
+ * @param props - The lines to draw.
+ * @returns The batch and one instance component per line.
+ */
+export declare function Lines(props: LinesProps): import("react").JSX.Element;
+//# sourceMappingURL=Lines.d.ts.map

package/dist/objects/lines/Lines.js

@@ -0,0 +1,29 @@
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { BatchedLines } from '../../core/lines/BatchedLines';
+import { defKey, useContainer } from '../containers';
+import { LineMaterial } from '../materials/LineMaterial';
+import { LineContainer } from './line-container';
+import { LineInstance } from './LineInstance';
+/**
+ * Draws a collection of lines as members of one `BatchedLines`, so a layer of route segments
+ * renders in a single instanced draw.
+ *
+ * Membership is reconciled by React exactly as it is for shapes: a new `defs` array re-renders this
+ * component and React mounts or unmounts only the delta, with no differ of our own. Order is applied
+ * as it is for images — the container labels each slot with its def's place in the layer, and the
+ * batch's `customSort` orders the draw list by it, so a reorder writes nothing to the GPU.
+ * @param props - The lines to draw.
+ * @returns The batch and one instance component per line.
+ */
+export function Lines(props) {
+    const { defs } = props;
+    // Sized from the first render's defs; membership changes grow the batch in place, never rebuild
+    // it. The container is bookkeeping only, so the copy StrictMode's double-invoked initializer
+    // discards is plain garbage.
+    const container = useContainer(() => new LineContainer(defs), defs);
+    // `args` is diffed element-wise and a change would dispose and rebuild the batch, orphaning every
+    // claimed slot — it is a frozen snapshot, so that never happens. The `ref` arrow is
+    // deliberate: `ref={container.bind}` would make the React Compiler infer `container` itself as a
+    // ref and reject its render-time reads.
+    return (_jsxs(_Fragment, { children: [_jsx(BatchedLines, { args: container.args, ref: (mesh) => container.bind(mesh), customSort: container.customSort, children: _jsx(LineMaterial, {}) }), defs.map((def) => (_jsx(LineInstance, { def: def, container: container }, defKey(def))))] }));
+}

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

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

package/dist/objects/lines/index.js

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

package/dist/objects/lines/line-container.d.ts

@@ -0,0 +1,35 @@
+import { type InstancedMeshExtParams } from '../../core/instanced/InstancedMesh';
+import { type BatchedLinesExt } from '../../core/lines/BatchedLines';
+import { type LineDef } from '../../types/defs';
+import { SlotContainer } from '../containers';
+/**
+ * The constructor tuple R3F builds a line batch from, passed as `<BatchedLines args={…}>`. R3F diffs
+ * `args` element-wise and rebuilds the object when any element changes, so this is snapshotted once
+ * and never mutated.
+ *
+ * Only the options: the batch builds its own segment template and takes its material from the
+ * `<LineMaterial>` child R3F mounts under it.
+ */
+export type LineMeshArgs = [params: InstancedMeshExtParams];
+/**
+ * One line layer's bookkeeping.
+ *
+ * Thinner than the shape container and the image one alike, because a line has no per-instance
+ * resource to allocate against — every member draws the same segment template, placed by its own
+ * endpoints. That is why the resource type is `null` here: nothing about a `LineDef` can force a
+ * re-claim, so a def keeps its slot for as long as it is mounted, `points` included.
+ */
+export declare class LineContainer extends SlotContainer<null, BatchedLinesExt, LineDef> {
+    /** The constructor args R3F builds the batch from; a frozen snapshot, never mutated. */
+    readonly args: LineMeshArgs;
+    /**
+     * Builds a line layer's bookkeeping, sized to hold `defs` exactly so a layer that mounts full
+     * never reallocates. The batch itself is R3F's — the component renders `<BatchedLines>` and hands
+     * it over through {@link SlotContainer.bind} — so R3F disposes it on unmount.
+     * @param defs - The layer's lines, used only to size the initial capacity.
+     */
+    constructor(defs: readonly LineDef[]);
+    protected addInstance(): number;
+    protected removeInstance(slot: number): void;
+}
+//# sourceMappingURL=line-container.d.ts.map

package/dist/objects/lines/line-container.js

@@ -0,0 +1,40 @@
+import { SlotContainer } from '../containers';
+/**
+ * One line layer's bookkeeping.
+ *
+ * Thinner than the shape container and the image one alike, because a line has no per-instance
+ * resource to allocate against — every member draws the same segment template, placed by its own
+ * endpoints. That is why the resource type is `null` here: nothing about a `LineDef` can force a
+ * re-claim, so a def keeps its slot for as long as it is mounted, `points` included.
+ */
+export class LineContainer extends SlotContainer {
+    /** The constructor args R3F builds the batch from; a frozen snapshot, never mutated. */
+    args;
+    /**
+     * Builds a line layer's bookkeeping, sized to hold `defs` exactly so a layer that mounts full
+     * never reallocates. The batch itself is R3F's — the component renders `<BatchedLines>` and hands
+     * it over through {@link SlotContainer.bind} — so R3F disposes it on unmount.
+     * @param defs - The layer's lines, used only to size the initial capacity.
+     */
+    constructor(defs) {
+        // Reversed, and that is the material's doing rather than this layer's: a line batch stencils
+        // first-fragment-wins so translucent lines do not darken where they overlap, which hands the
+        // pixel to whichever member rasterizes *first*. Draw order is therefore the reverse of paint
+        // order. Slots are still labeled in paint order, so "last sibling on top" holds here as
+        // everywhere else.
+        super({ reverse: true });
+        this.args = [{ capacity: Math.max(defs.length, 1) }];
+    }
+    addInstance() {
+        // The batch grows its own buffers if the layer ever outgrows the capacity it was sized to, so
+        // there is nothing to pre-scan; the id is captured from the creation callback.
+        let slot = -1;
+        this.mesh.addInstances(1, (id) => {
+            slot = id;
+        });
+        return slot;
+    }
+    removeInstance(slot) {
+        this.mesh.removeInstances(slot);
+    }
+}

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

@@ -0,0 +1,85 @@
+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** — meshes carrying real z, which need shading to read as
+     * solid and depth testing to occlude themselves and each other. Defaults to `false`, the flat
+     * content that is every 2D primitive in a plan.
+     */
+    solid?: boolean;
+    /**
+     * Whether those volumes are translucent, which moves them into three's transparent pass. Only
+     * meaningful together with {@link solid}; flat content never uses it (see the note below on why 2D
+     * stays in the opaque list).
+     */
+    translucent?: boolean;
+    /**
+     * Runs on the shader before the dim patch does — the slot for a caller's own shader surgery,
+     * like the background quad's clip-space projection and its dim-uniform stand-in. Captured at
+     * first render and fixed for the material's lifetime, like every other axis of this component:
+     * a changing handler identity would risk a recompile per render.
+     */
+    onBeforeCompile?: (parameters: WebGLProgramParametersWithUniforms) => void;
+}
+/**
+ * The material a shape batch draws with, rendered as a child of the mesh so R3F attaches, updates,
+ * and disposes it. Also troika's base material for text (see `Texts`), which never asks for `solid`.
+ *
+ * One component with a branch rather than two files, because the two are the same thing along one
+ * axis — what a batch of shapes draws with — and the three differences are the whole point, best
+ * read side by side:
+ *
+ * | | flat (default) | `solid` |
+ * | --- | --- | --- |
+ * | base | `MeshBasicMaterial`, unlit | `MeshPhysicalMaterial`, lit |
+ * | `depthWrite` | off, from {@link sharedParams} | **on** |
+ * | polygon offset | on, from {@link sharedParams} | **off** |
+ *
+ * Each difference is load-bearing. A volume is the one kind of content that writes depth: that is how
+ * its own faces resolve against each other, and what lets 2D content drawn afterwards be occluded by
+ * it. It carries no polygon offset because solids are what everything else is biased *against* —
+ * offsetting them too would only move the problem.
+ *
+ * `ior: 1` and `specularIntensity: 0` drive the lit material's `F0` to zero, so no specular lobe sits
+ * on top of the diffuse term. That is what makes the lighting identity exact: with the two lights
+ * summing to intensity `π`, a face square-on to the camera renders at precisely the authored color
+ * (see `Lighting`). A default `MeshPhysicalMaterial` would put a sheen on every wall and push it
+ * above its albedo.
+ *
+ * Per-instance color arrives through `BatchedMesh.setColorAt` either way: 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 is deliberate.** It sets
+ * `transparent: true`, which moves the batch into three's transparent list — drawn after *every*
+ * opaque object in the scene, whatever `renderOrder` says (`WebGLRenderer.renderScene`). That is
+ * exactly what makes a translucent volume blend with the opaque content behind it even when that
+ * content lives in a later layer, which no position in the ordered stream can achieve: a translucent
+ * surface can only blend with what is already in the framebuffer.
+ *
+ * What it costs is the reverse case. A planar def sitting *on* a translucent volume — a label or logo
+ * on a glass roof — draws in the opaque pass and so lands **before** it: 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 is
+ * never given this flag for the same reason, plus one of its own: 2D is coplanar, so it has no depth
+ * order to sort by and order is all it has.
+ *
+ * `forceSinglePass` is switched off here alone. three renders a `DoubleSide` transparent material
+ * twice — back faces, then front (`WebGLRenderer.js:1348`) — which is a correctly ordered two-pass
+ * for free, and the reason a closed translucent volume does not blend its own far and near surfaces
+ * in whatever order the batch happened to pack 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 one
+ * drawn later must not paint over it. MapLibre makes the same choice for `fill-extrusion`
+ * (`DepthMode.ReadWrite` in both of its passes). The trade and the two rejected alternatives are
+ * recorded in the design spec's Decision 2.
+ *
+ * The branch is stable for a mounted batch — `Shapes` renders a separate element per kind, each with
+ * 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,89 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useState } from 'react';
+import { useDimPatch } from './dim';
+import { sharedParams } from './shared';
+/**
+ * The material a shape batch draws with, rendered as a child of the mesh so R3F attaches, updates,
+ * and disposes it. Also troika's base material for text (see `Texts`), which never asks for `solid`.
+ *
+ * One component with a branch rather than two files, because the two are the same thing along one
+ * axis — what a batch of shapes draws with — and the three differences are the whole point, best
+ * read side by side:
+ *
+ * | | flat (default) | `solid` |
+ * | --- | --- | --- |
+ * | base | `MeshBasicMaterial`, unlit | `MeshPhysicalMaterial`, lit |
+ * | `depthWrite` | off, from {@link sharedParams} | **on** |
+ * | polygon offset | on, from {@link sharedParams} | **off** |
+ *
+ * Each difference is load-bearing. A volume is the one kind of content that writes depth: that is how
+ * its own faces resolve against each other, and what lets 2D content drawn afterwards be occluded by
+ * it. It carries no polygon offset because solids are what everything else is biased *against* —
+ * offsetting them too would only move the problem.
+ *
+ * `ior: 1` and `specularIntensity: 0` drive the lit material's `F0` to zero, so no specular lobe sits
+ * on top of the diffuse term. That is what makes the lighting identity exact: with the two lights
+ * summing to intensity `π`, a face square-on to the camera renders at precisely the authored color
+ * (see `Lighting`). A default `MeshPhysicalMaterial` would put a sheen on every wall and push it
+ * above its albedo.
+ *
+ * Per-instance color arrives through `BatchedMesh.setColorAt` either way: 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 is deliberate.** It sets
+ * `transparent: true`, which moves the batch into three's transparent list — drawn after *every*
+ * opaque object in the scene, whatever `renderOrder` says (`WebGLRenderer.renderScene`). That is
+ * exactly what makes a translucent volume blend with the opaque content behind it even when that
+ * content lives in a later layer, which no position in the ordered stream can achieve: a translucent
+ * surface can only blend with what is already in the framebuffer.
+ *
+ * What it costs is the reverse case. A planar def sitting *on* a translucent volume — a label or logo
+ * on a glass roof — draws in the opaque pass and so lands **before** it: 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 is
+ * never given this flag for the same reason, plus one of its own: 2D is coplanar, so it has no depth
+ * order to sort by and order is all it has.
+ *
+ * `forceSinglePass` is switched off here alone. three renders a `DoubleSide` transparent material
+ * twice — back faces, then front (`WebGLRenderer.js:1348`) — which is a correctly ordered two-pass
+ * for free, and the reason a closed translucent volume does not blend its own far and near surfaces
+ * in whatever order the batch happened to pack 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 one
+ * drawn later must not paint over it. MapLibre makes the same choice for `fill-extrusion`
+ * (`DepthMode.ReadWrite` in both of its passes). The trade and the two rejected alternatives are
+ * recorded in the design spec's Decision 2.
+ *
+ * The branch is stable for a mounted batch — `Shapes` renders a separate element per kind, each with
+ * 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-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
+    // silently skips the component instead, so only the running app surfaces it.
+    const color = props.color ?? 'white';
+    // Before the branch, because it is a hook — and passed to both, because a volume dims exactly as
+    // 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 caller's surgery first, then dimming — so a pre-patch that declares the dim uniform's
+    // stand-in is already in the shader when the dim patch looks for it. One stable handler, for the
+    // same reason `useDimPatch` keeps its own.
+    const [onBeforeCompile] = useState(() => {
+        const pre = props.onBeforeCompile;
+        return (parameters) => {
+            pre?.(parameters);
+            dimPatch(parameters);
+        };
+    });
+    if (props.solid) {
+        const translucent = props.translucent ?? false;
+        return (_jsx("meshPhysicalMaterial", { ...sharedParams, color: color, depthWrite: true, polygonOffset: false, ior: 1, specularIntensity: 0, transparent: translucent, forceSinglePass: !translucent, onBeforeCompile: onBeforeCompile }));
+    }
+    return _jsx("meshBasicMaterial", { ...sharedParams, 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 — `BatchedLinesExt`
+     * 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,72 @@
+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 { useDimPatch } from './dim';
+import { 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();
+    /**
+     * 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, color: color, linewidth: width, stencilWrite: true, stencilFunc: NotEqualStencilFunc, stencilZPass: ReplaceStencilOp, stencilRef: LINE_STENCIL_REF, onBeforeRender: onBeforeRender, onBeforeCompile: onBeforeCompile }));
+}