@expofp/renderer 0.0.0-experimental.2d6c681

package/dist/objects/shapes/shape-container.js

@@ -0,0 +1,242 @@
+import { isMesh } from '@expofp/geometry';
+import { isTranslucentColor } from '../../utils/colors';
+import { SlotContainer } from '../containers';
+import { shapeGeometry } from './shape-geometry';
+/**
+ * Every kind of shape batch, **in the order they draw within a layer** — which is what `Shapes`
+ * takes each batch's `renderOrder` from, so this list is the one place that order is stated.
+ *
+ * Solids draw after the flat shapes, so a volume occludes the flat content of its own layer rather
+ * than being painted over by it — the same rule that governs whole layers, applied within one.
+ */
+export const SHAPE_KINDS = ['planar', 'solid', 'translucent'];
+/**
+ * The batch a def belongs in.
+ *
+ * A shape is **solid** exactly when it is a `Mesh` whose vertices span more than one z — elevation is
+ * placement, not volume, so a quad or a lifted-but-flat mesh stays planar and is placed correctly by
+ * draw order alone. A solid is **translucent** when its color carries an alpha below 1. That has to
+ * be a partition rather than a per-instance flag because `transparent` is a *material* property:
+ * three decides which render list an object belongs to, never which instance, so two solids of
+ * differing transparency cannot share a mesh.
+ *
+ * **Only volumes split on translucency.** A flat shape with an alpha below 1 stays `planar`, because
+ * flat content already blends without leaving the opaque list: `sharedParams` reaches alpha blending
+ * through `CustomBlending` rather than through `transparent: true`, which three honors either way,
+ * and nothing planar writes depth. So array order is the whole of it — a translucent flat shape
+ * blends over whatever precedes it, and an opaque one authored later paints straight over it. That
+ * last part is a capability, not an accident: ordering an opaque fill after a translucent one is how
+ * a caller occludes it, and a batch of its own would take that away by forcing it after every opaque
+ * object in the scene, where nothing in its layer could cover it again.
+ *
+ * A volume has no such freedom. It writes depth and is depth-tested, so what ends up on top is the
+ * depth buffer's answer rather than the author's, and blending correctly means being drawn after the
+ * opaque content it blends with — which is a render pass, and therefore a batch.
+ *
+ * One function rather than a predicate in `Shapes` that places a def and another in `ShapeInstance`
+ * that notices it no longer belongs. Those are the same question, and two expressions of it can
+ * drift — a def placed by one rule and checked by the other would either sit in the wrong batch or
+ * ask to be re-split forever. A planar shape returns before the color is looked at, so the parse
+ * costs nothing on the many layers holding only flat content.
+ * @param def - The def to classify.
+ * @returns The kind of batch it draws from.
+ */
+export function shapeKindOf(def) {
+    if (!isMesh(def.shape) || def.shape.isPlanar)
+        return 'planar';
+    return isTranslucentColor(def.color) ? 'translucent' : 'solid';
+}
+/**
+ * One shape layer's mesh bookkeeping: reserved buffer space, slot allocation, which geometries the
+ * mesh has registered, and the paint-order table.
+ *
+ * Slot allocation is the mesh's own — `addInstance`/`deleteInstance` maintain its free list — so
+ * what this adds is what the mesh will not track: how much vertex and index space is reserved, and
+ * which of its geometry ids each template was given. Building the templates is not its work either;
+ * they come from {@link shapeGeometry}, which caches them across every container.
+ */
+export class ShapeContainer extends SlotContainer {
+    /**
+     * The mesh's constructor args, sized to hold the defs the container was created with exactly.
+     * Passed as `<batchedMesh args={container.capacity}>`; R3F diffs `args` element-wise and a change
+     * disposes and rebuilds the mesh, orphaning every claimed slot — so this is a snapshot taken at
+     * creation, which growth never mutates.
+     */
+    capacity;
+    /**
+     * Which kind of member this container holds, and so what its mesh is laid out for: a volume batch
+     * carries creased normals for the lit material and is non-indexed because that is what
+     * `toCreasedNormals` produces, and a translucent one draws in three's transparent pass. A member
+     * whose color stops matching is in the wrong pass, which is what {@link reportKindMismatch} exists
+     * to correct.
+     */
+    kind;
+    /**
+     * Which id the mesh gave each geometry it has registered. Per container even though the templates
+     * behind them are shared, because an id is the mesh's own numbering into its own buffers.
+     */
+    geometryIds = new Map();
+    /** What is allocated now, which growth mutates — unlike the {@link capacity} snapshot. */
+    allocated;
+    /**
+     * What the next growth jumps to, refreshed by {@link reserve}. Kept apart from {@link allocated}:
+     * a reservation must not resize anything by itself, only size the resize an overflowing claim was
+     * going to do anyway.
+     */
+    target;
+    /**
+     * Builds a shape layer's container, sized to hold `defs` exactly so a layer that mounts full never
+     * reallocates. The mesh itself is R3F's: the component renders `<batchedMesh>` from
+     * {@link capacity} and hands it over through {@link SlotContainer.bind}, and R3F disposes it on
+     * unmount. Nothing else needs disposal — `addGeometry` copies the template geometries' data into
+     * the mesh, so the templates are never uploaded to the GPU. They are not this container's to free
+     * in any case: {@link shapeGeometry} shares them across every container, and each is collected
+     * with the shape that keyed it.
+     * @param defs - The layer's shapes, used only to size the initial capacity.
+     * @param kind - Which of the layer's batches this is. A batched mesh mirrors its first geometry's
+     *   attributes *and* its index-ness, and three rejects any later geometry that disagrees — so this
+     *   decides the layout for every geometry in it, the shared unit plane included. It also decides
+     *   the render pass its members belong to, and therefore which colors are at home in it.
+     */
+    constructor(defs, kind = 'planar') {
+        super();
+        this.kind = kind;
+        this.allocated = measureCapacity(defs, (shape) => this.geometryFor(shape));
+        // A snapshot, not a live view: growth mutates `allocated.vertices`/`indices`, and leaking that
+        // into the mounted element's `args` would make R3F rebuild the mesh.
+        this.capacity = [this.allocated.instances, this.allocated.vertices, this.allocated.indices];
+        this.target = {
+            instances: this.allocated.instances,
+            vertices: this.allocated.vertices,
+            indices: this.allocated.indices,
+        };
+    }
+    /**
+     * The geometry a shape draws with, in this container's layout. Resolved through the shared cache,
+     * so a shape drawn by two containers — the same volume in the opaque and the translucent batch —
+     * is built once and handed to both.
+     * @param shape - The shape to resolve.
+     * @returns The geometry, built on first use.
+     */
+    geometryFor(shape) {
+        // Both volume kinds share one layout, which is what lets the cache serve a def crossing between
+        // them without rebuilding anything.
+        return shapeGeometry(shape, this.kind !== 'planar');
+    }
+    /**
+     * Declares the membership this container is about to hold, setting the size the next growth jumps
+     * to. The component calls this from render, before React mounts the instances that will claim in
+     * their effects — so a membership change that outgrows the buffers costs one resize per buffer,
+     * sized exactly, instead of one per claim. Bookkeeping only: nothing resizes until a claim or
+     * geometry registration actually overflows, so a reservation from a discarded or repeated render
+     * is harmless.
+     * @param defs - The shapes this container is about to hold.
+     */
+    reserve(defs) {
+        this.target.instances = defs.length;
+        // Geometry space is a high-water mark like the instance count — registered geometries are never
+        // removed — so the target is what is used now plus every geometry the new membership will
+        // register on its first claim.
+        let vertices = this.allocated.usedVertices;
+        let indices = this.allocated.usedIndices;
+        const seen = new Set();
+        for (const def of defs) {
+            const geometry = this.geometryFor(def.shape);
+            if (this.geometryIds.has(geometry) || seen.has(geometry))
+                continue;
+            seen.add(geometry);
+            vertices += vertexCountOf(geometry);
+            indices += indexCountOf(geometry);
+        }
+        this.target.vertices = vertices;
+        this.target.indices = indices;
+    }
+    addInstance(geometry) {
+        const geometryId = this.geometryIdFor(geometry);
+        // Full exactly when no slot is free and no room remains to append one; `addInstance` would
+        // throw. Growth jumps to the reserved membership's size — releases run before claims within a
+        // commit, so that size is enough for every claim the change brings and the resize happens once —
+        // with one appended slot as the floor when the reservation is stale or smaller. Never shrunk on
+        // release: freed ids keep later ids live, so the mesh forbids shrinking past them, and capacity
+        // kept as a high-water mark lets membership oscillate without rebuilding the instance textures.
+        if (this.mesh.instanceCount === this.mesh.maxInstanceCount) {
+            this.mesh.setInstanceCount(Math.max(this.target.instances, this.mesh.maxInstanceCount + 1));
+        }
+        return this.mesh.addInstance(geometryId);
+    }
+    removeInstance(slot) {
+        // In act environments R3F disposes an unmounting mesh synchronously, before this passive cleanup
+        // runs (in the browser disposal is deferred to idle priority, after it). Safe today: r185's
+        // `deleteInstance` touches only bookkeeping arrays, never the nulled textures. A three upgrade
+        // that changes that will fail the unmount specs.
+        this.mesh.deleteInstance(slot);
+    }
+    /**
+     * Registers a geometry with the mesh if it is not already, growing the buffers first.
+     * @param geometry - The geometry to register.
+     * @returns The mesh's geometry id.
+     */
+    geometryIdFor(geometry) {
+        const existing = this.geometryIds.get(geometry);
+        if (existing !== undefined)
+            return existing;
+        // Sizing has to happen before `addGeometry`: the mesh throws once its reserved vertex or index
+        // space runs out. Growth jumps to the reserved membership's size, so a change that brings
+        // several new geometries resizes the buffers once, on the first registration, and exactly.
+        const vertices = this.allocated.usedVertices + vertexCountOf(geometry);
+        const indices = this.allocated.usedIndices + indexCountOf(geometry);
+        if (vertices > this.allocated.vertices || indices > this.allocated.indices) {
+            this.allocated.vertices = Math.max(vertices, this.target.vertices);
+            this.allocated.indices = Math.max(indices, this.target.indices);
+            this.mesh.setGeometrySize(this.allocated.vertices, this.allocated.indices);
+        }
+        this.allocated.usedVertices = vertices;
+        this.allocated.usedIndices = indices;
+        const id = this.mesh.addGeometry(geometry);
+        this.geometryIds.set(geometry, id);
+        return id;
+    }
+}
+/**
+ * Sizes a container to hold the given shapes exactly, floored at 1 so a layer that mounts empty is
+ * not built at a degenerate zero size.
+ * @param defs - The layer's shapes.
+ * @param geometryFor - Resolves a shape's geometry.
+ * @returns The initial capacity, with nothing used yet.
+ */
+function measureCapacity(defs, geometryFor) {
+    let vertices = 0;
+    let indices = 0;
+    const seen = new Set();
+    for (const def of defs) {
+        const geometry = geometryFor(def.shape);
+        if (seen.has(geometry))
+            continue;
+        seen.add(geometry);
+        vertices += vertexCountOf(geometry);
+        indices += indexCountOf(geometry);
+    }
+    return {
+        instances: Math.max(defs.length, 1),
+        vertices: Math.max(vertices, 1),
+        indices: Math.max(indices, 1),
+        usedVertices: 0,
+        usedIndices: 0,
+    };
+}
+/**
+ * Vertices a geometry reserves.
+ * @param geometry - The geometry.
+ * @returns The vertex count.
+ */
+function vertexCountOf(geometry) {
+    return geometry.getAttribute('position').count;
+}
+/**
+ * Indices a geometry reserves, or `0` when it is non-indexed.
+ * @param geometry - The geometry.
+ * @returns The index count.
+ */
+function indexCountOf(geometry) {
+    return geometry.getIndex()?.count ?? 0;
+}

package/dist/objects/shapes/shape-geometry.d.ts

@@ -0,0 +1,27 @@
+import { type Shape } from '@expofp/geometry';
+import { BufferGeometry } from 'three';
+/**
+ * The template geometry a shape draws with, in the layout its batch locks itself into. Boxes and
+ * rects share one unit plane and are placed by their instance transform; meshes and polygons carry
+ * absolute coordinates in their own geometry.
+ *
+ * The cache is process-wide rather than per container, because the two solid batches — opaque and
+ * translucent — build byte-identical geometry for the same shape. Without sharing, a volume moving
+ * between them as its alpha crosses 1 re-runs `toNonIndexed`, `computeVertexNormals` and
+ * `toCreasedNormals` over every vertex, and does so for the batch's *whole* membership, since a
+ * container resolves every member's geometry to measure its capacity before anything claims a slot.
+ *
+ * Sharing one template across several meshes is safe because `BatchedMesh.addGeometry` **copies** its
+ * data in: a template is never uploaded to the GPU, and nothing mutates one after it is built. What
+ * it costs is that a template now outlives the container that first asked for it — the mesh-like
+ * ones until their shape is collected, the two planes for the life of the process, which is a few
+ * hundred bytes of vertex data against a plane rebuilt per shape layer of every plan.
+ * @param shape - The shape to resolve.
+ * @param solid - Whether the container drawing it holds volumes. A batched mesh mirrors its first
+ *   geometry's attributes *and* its index-ness and three rejects any later geometry that disagrees,
+ *   so the container's own flag decides the layout rather than anything derived here — a container
+ *   holding a shape it should not is then caught by `addGeometry` rather than served quietly.
+ * @returns The geometry, built on first use.
+ */
+export declare function shapeGeometry(shape: Shape, solid: boolean): BufferGeometry;
+//# sourceMappingURL=shape-geometry.d.ts.map

package/dist/objects/shapes/shape-geometry.js

@@ -0,0 +1,94 @@
+import { isBox, isRect } from '@expofp/geometry';
+import { BufferGeometry, PlaneGeometry } from 'three';
+import { toCreasedNormals } from 'three/examples/jsm/utils/BufferGeometryUtils.js';
+/**
+ * The template geometry a shape draws with, in the layout its batch locks itself into. Boxes and
+ * rects share one unit plane and are placed by their instance transform; meshes and polygons carry
+ * absolute coordinates in their own geometry.
+ *
+ * The cache is process-wide rather than per container, because the two solid batches — opaque and
+ * translucent — build byte-identical geometry for the same shape. Without sharing, a volume moving
+ * between them as its alpha crosses 1 re-runs `toNonIndexed`, `computeVertexNormals` and
+ * `toCreasedNormals` over every vertex, and does so for the batch's *whole* membership, since a
+ * container resolves every member's geometry to measure its capacity before anything claims a slot.
+ *
+ * Sharing one template across several meshes is safe because `BatchedMesh.addGeometry` **copies** its
+ * data in: a template is never uploaded to the GPU, and nothing mutates one after it is built. What
+ * it costs is that a template now outlives the container that first asked for it — the mesh-like
+ * ones until their shape is collected, the two planes for the life of the process, which is a few
+ * hundred bytes of vertex data against a plane rebuilt per shape layer of every plan.
+ * @param shape - The shape to resolve.
+ * @param solid - Whether the container drawing it holds volumes. A batched mesh mirrors its first
+ *   geometry's attributes *and* its index-ness and three rejects any later geometry that disagrees,
+ *   so the container's own flag decides the layout rather than anything derived here — a container
+ *   holding a shape it should not is then caught by `addGeometry` rather than served quietly.
+ * @returns The geometry, built on first use.
+ */
+export function shapeGeometry(shape, solid) {
+    const layout = solid ? 'solid' : 'planar';
+    if (isBox(shape) || isRect(shape))
+        return (planes[layout] ??= makePlaneGeometry(solid));
+    let layouts = shapeGeometries.get(shape);
+    if (!layouts) {
+        layouts = {};
+        shapeGeometries.set(shape, layouts);
+    }
+    return (layouts[layout] ??= makeMeshGeometry(shape, solid));
+}
+/**
+ * The unit plane every box and rect draws with, scaled and placed by its instance transform.
+ *
+ * A planar container strips it to positions: `MeshBasicMaterial` is unlit, so normals and uvs go
+ * unused, and stripping them matches the position-only mesh geometry beside it — a batched mesh
+ * locks its attribute layout to the first geometry it sees, so every geometry in it must agree. A
+ * solid container keeps the normals for the lit material and drops the index, because creased mesh
+ * geometry is non-indexed and three refuses to mix the two.
+ * @param solid - Whether the container draws volumes.
+ * @returns The unit plane, in the container's layout.
+ */
+function makePlaneGeometry(solid) {
+    const plane = new PlaneGeometry().deleteAttribute('uv');
+    return solid ? plane.toNonIndexed() : plane.deleteAttribute('normal');
+}
+/**
+ * Builds geometry from a mesh-like shape: indexed and position-only for a planar container,
+ * non-indexed with creased normals for a solid one.
+ *
+ * The creasing is what makes an extruded shape read as architecture rather than as a smoothed blob —
+ * faces meeting at more than 30° keep a hard edge, so walls stay flat and corners stay sharp.
+ * @param mesh - The shape supplying vertices and triangle indices.
+ * @param solid - Whether the container draws volumes.
+ * @returns The geometry.
+ */
+function makeMeshGeometry(mesh, solid) {
+    const geometry = new BufferGeometry()
+        .setFromPoints(mesh.vertices)
+        .setIndex(mesh.indices.flat());
+    if (!solid)
+        return geometry;
+    // Not chained: `computeVertexNormals` returns void rather than `this`, and `toCreasedNormals`
+    // needs the seed normals it writes.
+    const expanded = geometry.toNonIndexed();
+    expanded.computeVertexNormals();
+    return toCreasedNormals(expanded, CREASE_ANGLE);
+}
+/**
+ * Template geometry per mesh-like shape, weak so it is collected with the shape that keyed it.
+ *
+ * Both layouts hang off one entry rather than the key carrying the layout, because a shape can be
+ * asked for either. Its own kind fixes which one it is *placed* in, but a def whose `shape` is
+ * replaced with one of another kind draws from its old batch for the commit between the mismatch
+ * report and the re-split — long enough to resolve a geometry there. Keyed by shape alone, that
+ * first ask would decide the layout for every later one, and a lit batch would end up drawing a
+ * position-only geometry with no normals to shade: dark, and no error to say why.
+ *
+ * Identity is the right key for the same reason it is the right key for a slot's resource: a shape
+ * is replaced rather than mutated when a def's geometry changes, so a new shape arrives as a new
+ * key and the entry it supersedes is collected with the old one. An in-place topology mutation is
+ * not a supported update either way.
+ */
+const shapeGeometries = new WeakMap();
+/** The unit plane in each layout, built on the first box or rect a container of that kind draws. */
+const planes = {};
+/** Above this angle between neighboring faces, a shared edge stays hard instead of being smoothed. */
+const CREASE_ANGLE = Math.PI / 6;

package/dist/objects/text/TextInstance.d.ts

@@ -0,0 +1,22 @@
+import { type TextDef } from '../../types/defs';
+import { type InstanceProps } from '../containers';
+import { type TextContainer } from './text-container';
+/** Props for {@link TextInstance}. */
+export type TextInstanceProps = InstanceProps<TextDef, TextContainer>;
+/**
+ * Keeps one text def's lines current: claims a group of members on mount, writes each line's
+ * content, placement and visibility on mount and after every `update(def)`, and releases the group
+ * on unmount.
+ *
+ * Renders no scene node — the batch belongs to the container. The claim keys on `def.lines.length`,
+ * so adding or removing a line re-claims the group with the new size; changing a line's *content*
+ * is an ordinary write.
+ *
+ * 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 lines live in the batch, not the scene graph.
+ */
+export declare const TextInstance: import("react").MemoExoticComponent<(props: TextInstanceProps) => null>;
+//# sourceMappingURL=TextInstance.d.ts.map

package/dist/objects/text/TextInstance.js

@@ -0,0 +1,95 @@
+import { memo } from 'react';
+import { Color, LinearSRGBColorSpace, SRGBColorSpace } from 'three';
+import { normalizeColor } from '../../utils/colors';
+import { createLogger } from '../../utils/logging';
+import { useDefSync } from '../containers';
+import { applyPlacement, layoutText } from './text-layout';
+const logger = createLogger('text-instance');
+/**
+ * Keeps one text def's lines current: claims a group of members on mount, writes each line's
+ * content, placement and visibility on mount and after every `update(def)`, and releases the group
+ * on unmount.
+ *
+ * Renders no scene node — the batch belongs to the container. The claim keys on `def.lines.length`,
+ * so adding or removing a line re-claims the group with the new size; changing a line's *content*
+ * is an ordinary write.
+ *
+ * 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 lines live in the batch, not the scene graph.
+ */
+export const TextInstance = memo(function TextInstance(props) {
+    const { def, container } = props;
+    useDefSync(container, def, () => def.lines.length, (slot) => {
+        writeText(container, slot, def);
+    });
+    return null;
+});
+/**
+ * Writes a def's whole line stack into its group.
+ * @param container - The container holding the group.
+ * @param slot - The def's group.
+ * @param def - The text def supplying content and layout.
+ */
+function writeText(container, slot, def) {
+    const { texts, slots } = container.linesAt(slot);
+    const placements = layoutText(def);
+    for (let line = 0; line < texts.length; line++) {
+        writeLine(container.mesh, slots[line], texts[line], def.lines[line], placements[line], def);
+    }
+    // Content writes flag the batch as needing a sync; this is what actually runs one, coalesced
+    // across every instance that wrote in the same tick.
+    container.scheduleSync();
+}
+/**
+ * Writes one line's content and placement into its member.
+ * @param mesh - The batch, for the visibility write that also invalidates its bounds.
+ * @param lineSlot - The member's batch slot.
+ * @param text - The member.
+ * @param line - The line def.
+ * @param placed - The line's laid-out placement.
+ * @param def - The owning def, supplying the bounds the placement is relative to.
+ */
+function writeLine(mesh, lineSlot, text, line, placed, def) {
+    // A zero font size is the floorplan's "too small to read at this zoom" sentinel — its scale tables
+    // fall through to zero rather than carrying a separate hidden flag. Routed through the batch, not
+    // `text.visible`, so the bounds that enclose only visible members are invalidated with it.
+    mesh.setVisibleAt(lineSlot, line.fontSize > 0);
+    if (line.fontSize <= 0)
+        return;
+    // All syncable; troika's own setters skip an unchanged write, so an update that only moved a
+    // label re-lays-out nothing.
+    text.text = line.text;
+    text.font = line.fontUrl;
+    text.anchorX = placed.anchorX;
+    text.anchorY = placed.anchorY;
+    text.textAlign = placed.textAlign;
+    writeColorAndOpacity(text, line.color, 'fill');
+    // `stroke` is a halo drawn *around* the glyphs, so it maps to troika's outline rather than its
+    // stroke, which is drawn inside them.
+    //
+    // Divided by the font size, because the outline is measured in the member's own units and the
+    // member lays out at one em while the def's width is in the same units as its `fontSize`. Without
+    // the conversion a two-unit halo becomes two *ems* and swallows the glyphs entirely.
+    if (line.stroke) {
+        writeColorAndOpacity(text, line.stroke.color, 'outline');
+        text.outlineWidth = line.fontSize == 0 ? 0 : line.stroke.width / line.fontSize;
+    }
+    applyPlacement(text, placed, def.bounds, def.screenSpace === true);
+}
+function writeColorAndOpacity(text, color, field) {
+    const colorFieldName = field == 'fill' ? 'color' : 'outlineColor';
+    const opacityFieldName = `${field}Opacity`;
+    const rgb = normalizeColor(color);
+    if (!rgb) {
+        logger.warn(`Invalid color: ${color} %O`, text);
+        text[colorFieldName] = color;
+        return;
+    }
+    _color.setRGB(rgb.r / 255, rgb.g / 255, rgb.b / 255, SRGBColorSpace);
+    text[colorFieldName] = _color.getHex(LinearSRGBColorSpace);
+    text[opacityFieldName] = rgb.a;
+}
+const _color = new Color();

package/dist/objects/text/Texts.d.ts

@@ -0,0 +1,30 @@
+import { type TextDef } from '../../types/defs';
+import { type DefsProps } from '../containers';
+/** Props for {@link Texts}. */
+export type TextsProps = DefsProps<TextDef>;
+/**
+ * Draws a collection of texts as members of one `BatchedText`, so a layer of labels renders in a
+ * single draw call.
+ *
+ * Each def contributes one member per line, laid out as a block inside the def's bounds. 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.
+ *
+ * Two things differ from a shape layer, both because a text batch draws through packed glyph
+ * attributes rather than an indirect draw list:
+ *
+ * - **Paint order is the pack order**, so there is no `customSort`; the container hands the batch an
+ *   ordered member list and a change repacks. The order pass skips an unchanged order to keep an
+ *   `update()` that moved nothing from repacking.
+ * - **Syncing is asynchronous** — troika fetches and parses the font — so the container drives it
+ *   eagerly with R3F's `invalidate` as the completion callback, rather than leaving it to the next
+ *   `onBeforeRender`, which would have nothing to request the frame that shows the result.
+ *
+ * The material is an ordinary `<ColorMaterial>` child: troika derives its text material from
+ * whatever base it is given, and the base is what supplies the layer blending — which is also what
+ * keeps the batch out of three's transparent render list.
+ * @param props - The texts to draw.
+ * @returns The batch and one instance component per text.
+ */
+export declare function Texts(props: TextsProps): import("react").JSX.Element;
+//# sourceMappingURL=Texts.d.ts.map

package/dist/objects/text/Texts.js

@@ -0,0 +1,43 @@
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useThree } from '@react-three/fiber';
+import { BatchedText } from '../../core/text/BatchedText';
+import { defKey, useContainer } from '../containers';
+import { ColorMaterial } from '../materials/ColorMaterial';
+import { TextContainer } from './text-container';
+import { TextInstance } from './TextInstance';
+/**
+ * Draws a collection of texts as members of one `BatchedText`, so a layer of labels renders in a
+ * single draw call.
+ *
+ * Each def contributes one member per line, laid out as a block inside the def's bounds. 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.
+ *
+ * Two things differ from a shape layer, both because a text batch draws through packed glyph
+ * attributes rather than an indirect draw list:
+ *
+ * - **Paint order is the pack order**, so there is no `customSort`; the container hands the batch an
+ *   ordered member list and a change repacks. The order pass skips an unchanged order to keep an
+ *   `update()` that moved nothing from repacking.
+ * - **Syncing is asynchronous** — troika fetches and parses the font — so the container drives it
+ *   eagerly with R3F's `invalidate` as the completion callback, rather than leaving it to the next
+ *   `onBeforeRender`, which would have nothing to request the frame that shows the result.
+ *
+ * The material is an ordinary `<ColorMaterial>` child: troika derives its text material from
+ * whatever base it is given, and the base is what supplies the layer blending — which is also what
+ * keeps the batch out of three's transparent render list.
+ * @param props - The texts to draw.
+ * @returns The batch and one instance component per text.
+ */
+export function Texts(props) {
+    const { defs } = props;
+    // Only the instances are staged; the container is built and ordered from the whole membership.
+    const mounted = props.mounted ?? defs.length;
+    const invalidate = useThree((state) => state.invalidate);
+    // The container is bookkeeping only — the members and the mesh are created against R3F's object —
+    // so the copy StrictMode's double-invoked initializer discards is plain garbage.
+    const container = useContainer(() => new TextContainer(invalidate), defs);
+    // The `ref` arrow (not `ref={container.bind}`) keeps the React Compiler from inferring `container`
+    // itself as a ref and rejecting its render-time reads.
+    return (_jsxs(_Fragment, { children: [_jsx(BatchedText, { ref: (mesh) => container.bind(mesh), children: _jsx(ColorMaterial, {}) }), defs.slice(0, mounted).map((def) => (_jsx(TextInstance, { def: def, container: container }, defKey(def))))] }));
+}

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

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

package/dist/objects/text/index.js

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