@expofp/renderer 0.0.0-experimental.cf063fc

package/dist/objects/lighting/occlusion-targets.d.ts

@@ -0,0 +1,143 @@
+import { Vector2, type WebGLRenderer, WebGLRenderTarget } from 'three';
+/**
+ * The three render targets the occlusion passes draw into, over two color textures.
+ *
+ * | Target  | Color texture          | Depth attachment       | Written by | Read by         |
+ * | ------- | ---------------------- | ---------------------- | ---------- | --------------- |
+ * | `depth` | its own, never written | `DepthTexture`, 24-bit | prepass    | nothing         |
+ * | `ao`    | its own                | none                   | AO pass    | the blur pass   |
+ * | `blur`  | the `depth` target's   | none                   | blur pass  | the lit shaders |
+ *
+ * The sharing brings rules, and they live here because this class is the only place that can keep
+ * them.
+ *
+ * A target must not carry a texture that the pass drawing into it samples. WebGL2 calls that a
+ * rendering feedback loop, leaves the result undefined, and browsers refuse the draw. Both the AO
+ * pass and the blur pass sample the prepass depth, so neither one can bind a target that carries it.
+ * That is why two of these three targets carry no depth attachment.
+ *
+ * Three targets over two color textures. The prepass writes depth with `colorWrite` off, so nothing
+ * writes its color attachment and nothing reads it. The blur pass writes what the lit shaders read,
+ * so it takes that attachment. The handover costs one framebuffer and no GL texture at all. three's
+ * `setupRenderTarget` creates a texture only for a target that has none. `RenderTarget` has a
+ * `texture` setter, so this is supported API rather than a reach into internals.
+ *
+ * Two textures and not one, because the blur pass reads the AO pass's output while it writes its own.
+ * One texture for both is the feedback loop above.
+ *
+ * The set costs `1.5` bytes for each canvas pixel: `1.0` for 24-bit depth and `0.25` for each `R8`
+ * color texture, all at a quarter of the canvas area. A `2880 × 1800` canvas therefore holds about
+ * `7.8 MB` of them.
+ *
+ * Never call `setSize`. It calls `dispose()`, and three's deallocation deletes the GL texture of
+ * every entry in `renderTarget.textures`, a shared one included. A size change rebuilds all three
+ * instead.
+ *
+ * Dispose all three together, from here. The first disposal of a shared texture deletes it and
+ * removes its properties, and the second disposal then finds nothing to delete. No one of the three
+ * can outlive the others.
+ *
+ * The completeness check stays, because a required format is no promise that a particular driver
+ * reports the combination complete.
+ */
+export declare class OcclusionTargets {
+    /** The prepass's target, or `null` until this builds a complete set. */
+    private depthTarget;
+    /** The AO pass's target, over a color texture of its own, or `null` beside it. */
+    private aoTarget;
+    /** The blur pass's target, over the prepass's color texture, or `null` beside them. */
+    private blurTarget;
+    /** The set's pixel size, which is the canvas size at {@link CANVAS_FRACTION}. */
+    private readonly targetSize;
+    /** Whether this context cannot give a complete set. Once this turns true it stays true. */
+    private unavailable;
+    /** The prepass's target, or `null` until {@link OcclusionTargets.sync} returns `true`. */
+    get depth(): WebGLRenderTarget | null;
+    /** The AO pass's target, or `null` until {@link OcclusionTargets.sync} returns `true`. */
+    get ao(): WebGLRenderTarget | null;
+    /** The blur pass's target, or `null` until {@link OcclusionTargets.sync} returns `true`. */
+    get blur(): WebGLRenderTarget | null;
+    /** The set's pixel size. Read-only in spirit: the set owns it and rewrites it on a rebuild. */
+    get size(): Vector2;
+    /**
+     * Whether a set is allocated right now.
+     *
+     * A caller frees the set once when the debug GUI switches occlusion off, rather than on every frame
+     * after. This getter tells the caller which frame that is. A flag kept beside the set drifts the
+     * first time a sync fails or a rebuild releases the set on its own.
+     */
+    get held(): boolean;
+    /**
+     * Frees all three targets and the depth texture, and forgets their size.
+     *
+     * This takes no renderer. A `RenderTarget` disposal is an event three's own renderer listens for,
+     * so an unmount effect with nothing else in hand can call it.
+     */
+    dispose(): void;
+    /**
+     * Brings the set to the canvas's current size, and rebuilds it when that size moves.
+     * @param gl - The renderer, for the canvas size and for the completeness check.
+     * @returns Whether a complete set now exists to draw into.
+     */
+    sync(gl: WebGLRenderer): boolean;
+    /**
+     * Allocates the set at a size, at one of the two depth widths.
+     * @param width - The set's width in pixels.
+     * @param height - Its height.
+     * @param depthType - The depth texture's type, which decides its bit width.
+     */
+    private allocate;
+    /**
+     * Rebuilds the set, and falls back to 16-bit depth once before it gives up for good.
+     * @param gl - The renderer, for the completeness check.
+     * @param width - The set's width in pixels.
+     * @param height - Its height.
+     * @returns Whether a complete set now exists.
+     */
+    private build;
+    /**
+     * Frees whatever is allocated, together and in one place, and forgets its size.
+     */
+    private release;
+    /**
+     * Asks the driver whether the two framebuffer combinations this set uses came back complete, once
+     * per allocation.
+     *
+     * Binding each target through three is what builds its framebuffer, so the check runs against the
+     * real thing rather than against an intention. This puts the previously bound target back, which
+     * keeps a shared context unaware that the check ran. The MapLibre embed is that shared context.
+     *
+     * **Two checks cover three targets, because two of the targets are one combination.** The depth
+     * target is a color attachment beside a sampleable depth texture, at whichever of the two widths
+     * `build` is trying, and it is the only one of the three carrying depth at all. That is its own
+     * risk and it takes its own check. The blur target is a single `R8` color attachment over a
+     * texture the depth target already owns. The AO target is that same single `R8` attachment over a
+     * texture of its own, so the blur target covers the AO target's combination and adds the sharing,
+     * which is the part of this design a driver is most likely to refuse. A third bind would ask a
+     * question the second one already answers.
+     *
+     * **three's own renderer never calls `checkFramebufferStatus`**, so this is the only thing that
+     * detects a driver refusing either combination. What it buys is the 16-bit retry and, after that,
+     * occlusion switching itself off, rather than a plan drawing out of an incomplete framebuffer.
+     *
+     * A context that throws while three binds it answers the same question the status code answers, so
+     * this catches the throw. Occlusion switching itself off is the documented outcome. Taking the
+     * frame loop down with it is the worse one.
+     * @param gl - The renderer whose context answers.
+     * @returns Whether both combinations are complete.
+     */
+    private verify;
+}
+/**
+ * The share of the canvas size each axis of the set takes.
+ *
+ * Half, so each pass bills a quarter of the texels a full-size pass bills. Occlusion is a
+ * low-frequency signal. The lit read finds its own fragment by normalized coordinates, so the texel
+ * count behind that read changes nothing anyone can see.
+ *
+ * The canvas size and not the drawing buffer's, which is what `gl.getSize()` reports. A device pixel
+ * ratio of `2` squares into four times the texels, and both passes bill per texel. A set sized from
+ * the buffer therefore costs four times as much on a retina screen, for detail nothing asks of it.
+ */
+export declare const CANVAS_FRACTION = 0.5;
+//# sourceMappingURL=occlusion-targets.d.ts.map

package/dist/objects/lighting/occlusion-targets.js

@@ -0,0 +1,276 @@
+import { DepthTexture, NearestFilter, RedFormat, UnsignedByteType, UnsignedIntType, UnsignedShortType, Vector2, WebGLRenderTarget, } from 'three';
+import { createLogger } from '../../utils/logging';
+const logger = createLogger('occlusion');
+/**
+ * The three render targets the occlusion passes draw into, over two color textures.
+ *
+ * | Target  | Color texture          | Depth attachment       | Written by | Read by         |
+ * | ------- | ---------------------- | ---------------------- | ---------- | --------------- |
+ * | `depth` | its own, never written | `DepthTexture`, 24-bit | prepass    | nothing         |
+ * | `ao`    | its own                | none                   | AO pass    | the blur pass   |
+ * | `blur`  | the `depth` target's   | none                   | blur pass  | the lit shaders |
+ *
+ * The sharing brings rules, and they live here because this class is the only place that can keep
+ * them.
+ *
+ * A target must not carry a texture that the pass drawing into it samples. WebGL2 calls that a
+ * rendering feedback loop, leaves the result undefined, and browsers refuse the draw. Both the AO
+ * pass and the blur pass sample the prepass depth, so neither one can bind a target that carries it.
+ * That is why two of these three targets carry no depth attachment.
+ *
+ * Three targets over two color textures. The prepass writes depth with `colorWrite` off, so nothing
+ * writes its color attachment and nothing reads it. The blur pass writes what the lit shaders read,
+ * so it takes that attachment. The handover costs one framebuffer and no GL texture at all. three's
+ * `setupRenderTarget` creates a texture only for a target that has none. `RenderTarget` has a
+ * `texture` setter, so this is supported API rather than a reach into internals.
+ *
+ * Two textures and not one, because the blur pass reads the AO pass's output while it writes its own.
+ * One texture for both is the feedback loop above.
+ *
+ * The set costs `1.5` bytes for each canvas pixel: `1.0` for 24-bit depth and `0.25` for each `R8`
+ * color texture, all at a quarter of the canvas area. A `2880 × 1800` canvas therefore holds about
+ * `7.8 MB` of them.
+ *
+ * Never call `setSize`. It calls `dispose()`, and three's deallocation deletes the GL texture of
+ * every entry in `renderTarget.textures`, a shared one included. A size change rebuilds all three
+ * instead.
+ *
+ * Dispose all three together, from here. The first disposal of a shared texture deletes it and
+ * removes its properties, and the second disposal then finds nothing to delete. No one of the three
+ * can outlive the others.
+ *
+ * The completeness check stays, because a required format is no promise that a particular driver
+ * reports the combination complete.
+ */
+export class OcclusionTargets {
+    /** The prepass's target, or `null` until this builds a complete set. */
+    depthTarget = null;
+    /** The AO pass's target, over a color texture of its own, or `null` beside it. */
+    aoTarget = null;
+    /** The blur pass's target, over the prepass's color texture, or `null` beside them. */
+    blurTarget = null;
+    /** The set's pixel size, which is the canvas size at {@link CANVAS_FRACTION}. */
+    targetSize = new Vector2();
+    /** Whether this context cannot give a complete set. Once this turns true it stays true. */
+    unavailable = false;
+    /** The prepass's target, or `null` until {@link OcclusionTargets.sync} returns `true`. */
+    get depth() {
+        return this.depthTarget;
+    }
+    /** The AO pass's target, or `null` until {@link OcclusionTargets.sync} returns `true`. */
+    get ao() {
+        return this.aoTarget;
+    }
+    /** The blur pass's target, or `null` until {@link OcclusionTargets.sync} returns `true`. */
+    get blur() {
+        return this.blurTarget;
+    }
+    /** The set's pixel size. Read-only in spirit: the set owns it and rewrites it on a rebuild. */
+    get size() {
+        return this.targetSize;
+    }
+    /**
+     * Whether a set is allocated right now.
+     *
+     * A caller frees the set once when the debug GUI switches occlusion off, rather than on every frame
+     * after. This getter tells the caller which frame that is. A flag kept beside the set drifts the
+     * first time a sync fails or a rebuild releases the set on its own.
+     */
+    get held() {
+        return this.depthTarget !== null;
+    }
+    /**
+     * Frees all three targets and the depth texture, and forgets their size.
+     *
+     * This takes no renderer. A `RenderTarget` disposal is an event three's own renderer listens for,
+     * so an unmount effect with nothing else in hand can call it.
+     */
+    dispose() {
+        this.release();
+    }
+    /**
+     * Brings the set to the canvas's current size, and rebuilds it when that size moves.
+     * @param gl - The renderer, for the canvas size and for the completeness check.
+     * @returns Whether a complete set now exists to draw into.
+     */
+    sync(gl) {
+        if (this.unavailable)
+            return false;
+        const canvas = gl.getSize(_canvas);
+        const width = Math.floor(canvas.x * CANVAS_FRACTION);
+        const height = Math.floor(canvas.y * CANVAS_FRACTION);
+        // A canvas with no area yet, during a layout or before one. The next resize can undo that, so
+        // this is no reason to give up for good.
+        if (width < 1 || height < 1)
+            return false;
+        if (this.depthTarget && this.targetSize.x === width && this.targetSize.y === height) {
+            return true;
+        }
+        return this.build(gl, width, height);
+    }
+    /**
+     * Allocates the set at a size, at one of the two depth widths.
+     * @param width - The set's width in pixels.
+     * @param height - Its height.
+     * @param depthType - The depth texture's type, which decides its bit width.
+     */
+    allocate(width, height, depthType) {
+        this.depthTarget = new WebGLRenderTarget(width, height, {
+            ...SINGLE_CHANNEL_TEXTURE,
+            depthBuffer: true,
+            depthTexture: new DepthTexture(width, height, depthType),
+        });
+        this.aoTarget = new WebGLRenderTarget(width, height, {
+            ...SINGLE_CHANNEL_TEXTURE,
+            depthBuffer: false,
+        });
+        // No format of its own. The next line drops the texture this target is built with, so the
+        // missing depth attachment is the only option that outlives the constructor.
+        this.blurTarget = new WebGLRenderTarget(width, height, { depthBuffer: false });
+        // The sharing, in one line. `RenderTarget` has a `texture` setter, so this is supported API
+        // rather than a reach into internals. This drops the target's own fresh texture, which never
+        // uploaded. Nothing writes the prepass's color attachment and nothing reads it, so the blur pass
+        // can take it.
+        this.blurTarget.texture = this.depthTarget.texture;
+        this.targetSize.set(width, height);
+    }
+    /**
+     * Rebuilds the set, and falls back to 16-bit depth once before it gives up for good.
+     * @param gl - The renderer, for the completeness check.
+     * @param width - The set's width in pixels.
+     * @param height - Its height.
+     * @returns Whether a complete set now exists.
+     */
+    build(gl, width, height) {
+        this.release();
+        for (const depthType of DEPTH_TYPES) {
+            this.allocate(width, height, depthType);
+            if (this.verify(gl))
+                return true;
+            this.release();
+        }
+        // Off for good, and silent as far as a caller can tell. The SDK runs in old Android WebViews,
+        // and nobody can do anything about a driver that will not report these targets complete. The
+        // debug log is for whoever has to find out why a plan shipped without occlusion.
+        logger.debug('ambient occlusion off: this context gives no complete render targets');
+        this.unavailable = true;
+        return false;
+    }
+    /**
+     * Frees whatever is allocated, together and in one place, and forgets its size.
+     */
+    release() {
+        // The order does not matter. The first disposal of the shared texture deletes it and removes its
+        // properties, and the second one finds nothing left to delete. All three still have to happen.
+        // The AO target's own texture belongs to nobody else, so either order deletes it once.
+        this.depthTarget?.dispose();
+        this.aoTarget?.dispose();
+        this.blurTarget?.dispose();
+        this.depthTarget?.depthTexture?.dispose();
+        this.depthTarget = null;
+        this.aoTarget = null;
+        this.blurTarget = null;
+        this.targetSize.set(0, 0);
+    }
+    /**
+     * Asks the driver whether the two framebuffer combinations this set uses came back complete, once
+     * per allocation.
+     *
+     * Binding each target through three is what builds its framebuffer, so the check runs against the
+     * real thing rather than against an intention. This puts the previously bound target back, which
+     * keeps a shared context unaware that the check ran. The MapLibre embed is that shared context.
+     *
+     * **Two checks cover three targets, because two of the targets are one combination.** The depth
+     * target is a color attachment beside a sampleable depth texture, at whichever of the two widths
+     * `build` is trying, and it is the only one of the three carrying depth at all. That is its own
+     * risk and it takes its own check. The blur target is a single `R8` color attachment over a
+     * texture the depth target already owns. The AO target is that same single `R8` attachment over a
+     * texture of its own, so the blur target covers the AO target's combination and adds the sharing,
+     * which is the part of this design a driver is most likely to refuse. A third bind would ask a
+     * question the second one already answers.
+     *
+     * **three's own renderer never calls `checkFramebufferStatus`**, so this is the only thing that
+     * detects a driver refusing either combination. What it buys is the 16-bit retry and, after that,
+     * occlusion switching itself off, rather than a plan drawing out of an incomplete framebuffer.
+     *
+     * A context that throws while three binds it answers the same question the status code answers, so
+     * this catches the throw. Occlusion switching itself off is the documented outcome. Taking the
+     * frame loop down with it is the worse one.
+     * @param gl - The renderer whose context answers.
+     * @returns Whether both combinations are complete.
+     */
+    verify(gl) {
+        const context = webgl2(gl);
+        if (!context)
+            return false;
+        const previous = gl.getRenderTarget();
+        try {
+            let complete = true;
+            for (const target of [this.depthTarget, this.blurTarget]) {
+                gl.setRenderTarget(target);
+                if (context.checkFramebufferStatus(context.FRAMEBUFFER) !== context.FRAMEBUFFER_COMPLETE) {
+                    complete = false;
+                }
+            }
+            return complete;
+        }
+        catch {
+            return false;
+        }
+        finally {
+            gl.setRenderTarget(previous);
+        }
+    }
+}
+/**
+ * The renderer's context, when it is one these targets can be built on.
+ *
+ * A runtime feature detection, and not a type narrowing a reader can drop. The SDK still runs in
+ * WebViews whose context can be neither WebGL2 nor able to carry a readable depth texture. The
+ * constructor itself can be missing, so this checks for it before it uses it.
+ * @param gl - The renderer to read.
+ * @returns The context, or `undefined` when the targets cannot be built on it.
+ */
+function webgl2(gl) {
+    const context = gl.getContext();
+    if (typeof WebGL2RenderingContext !== 'function')
+        return undefined;
+    return context instanceof WebGL2RenderingContext ? context : undefined;
+}
+/**
+ * The share of the canvas size each axis of the set takes.
+ *
+ * Half, so each pass bills a quarter of the texels a full-size pass bills. Occlusion is a
+ * low-frequency signal. The lit read finds its own fragment by normalized coordinates, so the texel
+ * count behind that read changes nothing anyone can see.
+ *
+ * The canvas size and not the drawing buffer's, which is what `gl.getSize()` reports. A device pixel
+ * ratio of `2` squares into four times the texels, and both passes bill per texel. A set sized from
+ * the buffer therefore costs four times as much on a retina screen, for detail nothing asks of it.
+ */
+export const CANVAS_FRACTION = 0.5;
+/**
+ * The depth widths this tries, in order.
+ *
+ * 24 bits first, because 16-bit depth at this size over a plan's range bands visibly in the
+ * occlusion. 16 bits is the one retry worth making before occlusion latches off for good. It saves
+ * memory rather than costing it, which makes it a fallback rather than a default.
+ */
+const DEPTH_TYPES = [UnsignedIntType, UnsignedShortType];
+/**
+ * The shared settings for the two color textures the occlusion passes draw into.
+ *
+ * `R8` holds one byte a texel. It is a color-renderable sized internal format in WebGL 2, so it is
+ * required to work rather than merely likely to.
+ *
+ * Both the blur pass and the lit read weight their samples by depth, so hardware filtering only
+ * smears occlusion across the edges those reads respect.
+ */
+const SINGLE_CHANNEL_TEXTURE = {
+    format: RedFormat,
+    type: UnsignedByteType,
+    minFilter: NearestFilter,
+    magFilter: NearestFilter,
+};
+/** Scratch for the canvas size, read once per sync. */
+const _canvas = new Vector2();

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,31 @@
+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;
+    // Only the instances are staged; the container is sized and ordered from the whole membership.
+    const mounted = props.mounted ?? defs.length;
+    // 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.slice(0, mounted).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 InstancedMeshImplParams } from '../../core/instanced/InstancedMesh';
+import { type BatchedLinesImpl } 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: InstancedMeshImplParams];
+/**
+ * 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, BatchedLinesImpl, 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);
+    }
+}