@expofp/renderer 0.0.0-experimental.2d6c681

package/dist/objects/text/text-container.d.ts

@@ -0,0 +1,121 @@
+import { type BatchedTextImpl } from '../../core/text/BatchedText';
+import { TextImpl } from '../../core/text/Text';
+import { type RenderableDef, type TextDef } from '../../types/defs';
+import { SlotContainer } from '../containers';
+/** One def's members: a `TextImpl` per line, and the batch slot each of them occupies. */
+export interface LineGroup {
+    /** The members, in the def's line order. */
+    readonly texts: readonly TextImpl[];
+    /** Each member's batch slot, index-parallel to {@link texts}. */
+    readonly slots: readonly number[];
+}
+/**
+ * One text layer's bookkeeping: a group of members per def, and the paint order across them.
+ *
+ * The slot a def claims here is a **group**, not a batch member — a `TextDef` holds an array of
+ * lines and each line is its own `TextImpl`. That is the one place this differs from the shape and
+ * image containers, and it falls out of the def type rather than being a choice: the lines of one
+ * def are laid out together (a centered block needs every line's height before it can place the
+ * first), so they cannot be independent instances.
+ *
+ * Group size is the slot's resource, so a def that gains or loses a line re-claims automatically —
+ * which is what makes `TextDef.lines` updatable here, where the imperative renderer required it to
+ * be fixed.
+ *
+ * Ordering differs too: a text batch draws through packed glyph attributes rather than a sortable
+ * draw list, so {@link applyOrder} hands the batch a rebuilt member list instead of labeling slots,
+ * and the inherited `customSort` goes unused.
+ */
+export declare class TextContainer extends SlotContainer<number, BatchedTextImpl, TextDef> {
+    /** Groups by slot, with holes for released ones. */
+    private readonly groups;
+    private readonly freeGroups;
+    /**
+     * Batch member to the group holding it, so a hit — which names a member — resolves to a def. The
+     * batch reuses a released member's slot, so entries are dropped with the group that owned them.
+     */
+    private readonly groupByMember;
+    private groupCount;
+    /** The last order applied to the batch, kept so an unchanged one can skip the repack. */
+    private appliedOrder;
+    private syncScheduled;
+    private readonly invalidate;
+    /**
+     * Builds a text layer's bookkeeping. The batch itself is R3F's — the component renders
+     * `<BatchedText>` and hands it over through {@link SlotContainer.bind} — so R3F disposes it on
+     * unmount.
+     * @param invalidate - R3F's frame request, called when an asynchronous sync completes. Stable for
+     *   the lifetime of a canvas, so capturing it here is safe.
+     */
+    constructor(invalidate: () => void);
+    /**
+     * Binds the batch, and asks for a frame each time it finishes a sync.
+     *
+     * {@link scheduleSync}'s callback closes the loop only for a sync it starts. A write made inside a
+     * frame callback — a layout rule's, or a placement report's drained before the render — flags the
+     * batch before that frame renders, so the batch's own render hook starts the sync, with no
+     * callback, and the coalesced one that follows finds nothing left to do. Its glyphs then land
+     * after the last frame anyone asked for, and the old text stays on screen until something else
+     * happens to draw. A repack that runs inside the render hook is a frame late for the same reason:
+     * three has uploaded the batch's attributes by then. The batch's own completion is the one signal
+     * both paths share.
+     * @param mesh - The mounted batch, or the ref-cleanup `null`.
+     */
+    bind(mesh: BatchedTextImpl | null): void;
+    /**
+     * The members backing one def.
+     * @param slot - The def's group.
+     * @returns Its members and their batch slots.
+     */
+    linesAt(slot: number): LineGroup;
+    /**
+     * Requests one batch sync, coalescing every request made in the same tick.
+     *
+     * Eager rather than waiting for `onBeforeRender`, because syncing is asynchronous — troika loads
+     * and parses the font — and under on-demand rendering a sync started during a frame has nothing to
+     * request the *next* frame when it completes. The callback carries R3F's `invalidate`, which is
+     * what closes that loop; without it new text appears only when something else happens to
+     * invalidate. A sync this did not start is covered by the batch's own completion, which
+     * {@link bind} listens for.
+     */
+    scheduleSync(): void;
+    claim(def: RenderableDef, lineCount: number): number;
+    setVisibleAt(slot: number, visible: boolean): void;
+    /**
+     * Sets the draw order for the whole layer, then syncs.
+     *
+     * The sync rides along so one structural change costs exactly one sync — a mount writes content
+     * through its instances in the same effect flush, and every request in the tick coalesces.
+     * @param defs - The layer's texts, in paint order.
+     * @param layerDimmed - Whether the layer is dimmed, inherited by defs without a `dim` of their own.
+     */
+    setPaintOrder(defs: readonly TextDef[], layerDimmed: boolean): void;
+    /**
+     * The batch reports the member it was hit on, and a def owns one member per line — so unlike every
+     * other container's, this one's slots are not its mesh's instances, and a member resolves to a def
+     * only through the group holding it.
+     * @param member - The member the batch reported.
+     * @returns The def, or `undefined` when no claimed group holds that member.
+     */
+    defAt(member: number | undefined): RenderableDef | undefined;
+    /**
+     * Rebuilds the flat member order from the current defs and hands it to the batch, unless nothing
+     * moved.
+     *
+     * Skipping an unchanged order matters more here than for the other containers: a text batch has no
+     * `customSort`, so reordering means repacking the glyph attributes, and `useStagedChildren` hands out
+     * a fresh snapshot on *every* layer update — including ones that moved nothing.
+     */
+    protected applyOrder(): void;
+    /**
+     * Per member, not per def: a def's lines are separate batch members, and the uniform row is
+     * addressed by member. One `dim` on the def therefore writes each of its lines, exactly as
+     * visibility does.
+     * @param slot - The def's group.
+     * @param amount - The encoded amount.
+     */
+    protected writeDim(slot: number, amount: number): void;
+    protected addInstance(lineCount: number): number;
+    protected removeInstance(slot: number): void;
+}
+//# sourceMappingURL=text-container.d.ts.map

package/dist/objects/text/text-container.js

@@ -0,0 +1,229 @@
+import { TextImpl } from '../../core/text/Text';
+import { sameSequence } from '../../utils/arrays';
+import { SlotContainer } from '../containers';
+import { isDimmed } from '../materials/effects/color-dim';
+import { LAYOUT_FONT_SIZE, LINE_HEIGHT } from './text-layout';
+/**
+ * One text layer's bookkeeping: a group of members per def, and the paint order across them.
+ *
+ * The slot a def claims here is a **group**, not a batch member — a `TextDef` holds an array of
+ * lines and each line is its own `TextImpl`. That is the one place this differs from the shape and
+ * image containers, and it falls out of the def type rather than being a choice: the lines of one
+ * def are laid out together (a centered block needs every line's height before it can place the
+ * first), so they cannot be independent instances.
+ *
+ * Group size is the slot's resource, so a def that gains or loses a line re-claims automatically —
+ * which is what makes `TextDef.lines` updatable here, where the imperative renderer required it to
+ * be fixed.
+ *
+ * Ordering differs too: a text batch draws through packed glyph attributes rather than a sortable
+ * draw list, so {@link applyOrder} hands the batch a rebuilt member list instead of labeling slots,
+ * and the inherited `customSort` goes unused.
+ */
+export class TextContainer extends SlotContainer {
+    /** Groups by slot, with holes for released ones. */
+    groups = [];
+    freeGroups = [];
+    /**
+     * Batch member to the group holding it, so a hit — which names a member — resolves to a def. The
+     * batch reuses a released member's slot, so entries are dropped with the group that owned them.
+     */
+    groupByMember = new Map();
+    groupCount = 0;
+    /** The last order applied to the batch, kept so an unchanged one can skip the repack. */
+    appliedOrder = [];
+    syncScheduled = false;
+    invalidate;
+    /**
+     * Builds a text layer's bookkeeping. The batch itself is R3F's — the component renders
+     * `<BatchedText>` and hands it over through {@link SlotContainer.bind} — so R3F disposes it on
+     * unmount.
+     * @param invalidate - R3F's frame request, called when an asynchronous sync completes. Stable for
+     *   the lifetime of a canvas, so capturing it here is safe.
+     */
+    constructor(invalidate) {
+        super();
+        this.invalidate = invalidate;
+    }
+    /**
+     * Binds the batch, and asks for a frame each time it finishes a sync.
+     *
+     * {@link scheduleSync}'s callback closes the loop only for a sync it starts. A write made inside a
+     * frame callback — a layout rule's, or a placement report's drained before the render — flags the
+     * batch before that frame renders, so the batch's own render hook starts the sync, with no
+     * callback, and the coalesced one that follows finds nothing left to do. Its glyphs then land
+     * after the last frame anyone asked for, and the old text stays on screen until something else
+     * happens to draw. A repack that runs inside the render hook is a frame late for the same reason:
+     * three has uploaded the batch's attributes by then. The batch's own completion is the one signal
+     * both paths share.
+     * @param mesh - The mounted batch, or the ref-cleanup `null`.
+     */
+    bind(mesh) {
+        // `mesh` reads the bound batch, which is undefined until the first bind; the base ignores a
+        // re-bind, so the listener is added once too.
+        const first = mesh !== null && this.mesh === undefined;
+        super.bind(mesh);
+        if (first)
+            mesh.addEventListener('synccomplete', () => this.invalidate());
+    }
+    /**
+     * The members backing one def.
+     * @param slot - The def's group.
+     * @returns Its members and their batch slots.
+     */
+    linesAt(slot) {
+        return this.groups[slot] ?? EMPTY_GROUP;
+    }
+    /**
+     * Requests one batch sync, coalescing every request made in the same tick.
+     *
+     * Eager rather than waiting for `onBeforeRender`, because syncing is asynchronous — troika loads
+     * and parses the font — and under on-demand rendering a sync started during a frame has nothing to
+     * request the *next* frame when it completes. The callback carries R3F's `invalidate`, which is
+     * what closes that loop; without it new text appears only when something else happens to
+     * invalidate. A sync this did not start is covered by the batch's own completion, which
+     * {@link bind} listens for.
+     */
+    scheduleSync() {
+        if (this.syncScheduled)
+            return;
+        this.syncScheduled = true;
+        // `Promise.resolve().then`, not `queueMicrotask`: the SDK targets Android WebViews as old as
+        // Chrome 66, which predates it. Same microtask timing.
+        void Promise.resolve().then(() => {
+            this.syncScheduled = false;
+            // Unmounted between the request and the microtask; the batch is R3F's and already disposed.
+            if (!this.mesh)
+                return;
+            this.mesh.sync(this.invalidate);
+        });
+    }
+    claim(def, lineCount) {
+        const slot = super.claim(def, lineCount);
+        // `addText` appends to the batch's order, so a first mount draws in claim order and the layer's
+        // own pass relabels it in the same effect flush. A *re*-claim after that pass has to re-run it,
+        // or the new members would stay stuck at the end of the paint order.
+        if (this.layerDefs.length)
+            this.applyOrder();
+        return slot;
+    }
+    setVisibleAt(slot, visible) {
+        const group = this.groups[slot];
+        if (!group)
+            return;
+        for (const member of group.slots) {
+            this.mesh.setVisibleAt(member, visible);
+        }
+    }
+    /**
+     * Sets the draw order for the whole layer, then syncs.
+     *
+     * The sync rides along so one structural change costs exactly one sync — a mount writes content
+     * through its instances in the same effect flush, and every request in the tick coalesces.
+     * @param defs - The layer's texts, in paint order.
+     * @param layerDimmed - Whether the layer is dimmed, inherited by defs without a `dim` of their own.
+     */
+    setPaintOrder(defs, layerDimmed) {
+        super.setPaintOrder(defs, layerDimmed);
+        this.scheduleSync();
+    }
+    /**
+     * The batch reports the member it was hit on, and a def owns one member per line — so unlike every
+     * other container's, this one's slots are not its mesh's instances, and a member resolves to a def
+     * only through the group holding it.
+     * @param member - The member the batch reported.
+     * @returns The def, or `undefined` when no claimed group holds that member.
+     */
+    defAt(member) {
+        return super.defAt(member === undefined ? undefined : this.groupByMember.get(member));
+    }
+    /**
+     * Rebuilds the flat member order from the current defs and hands it to the batch, unless nothing
+     * moved.
+     *
+     * Skipping an unchanged order matters more here than for the other containers: a text batch has no
+     * `customSort`, so reordering means repacking the glyph attributes, and `useStagedChildren` hands out
+     * a fresh snapshot on *every* layer update — including ones that moved nothing.
+     */
+    applyOrder() {
+        const order = [];
+        for (const def of this.orderedDefs()) {
+            const slot = this.slotOf(def);
+            if (slot === undefined)
+                continue;
+            const group = this.groups[slot];
+            if (!group)
+                continue;
+            order.push(...group.texts);
+            this.dimmedBySlot[slot] = isDimmed(def.dim, this.layerDimmed);
+        }
+        if (sameSequence(order, this.appliedOrder))
+            return;
+        this.appliedOrder = order;
+        this.mesh.setOrder(order);
+    }
+    /**
+     * Per member, not per def: a def's lines are separate batch members, and the uniform row is
+     * addressed by member. One `dim` on the def therefore writes each of its lines, exactly as
+     * visibility does.
+     * @param slot - The def's group.
+     * @param amount - The encoded amount.
+     */
+    writeDim(slot, amount) {
+        const group = this.groups[slot];
+        if (!group)
+            return;
+        for (const member of group.slots) {
+            super.writeDim(member, amount);
+        }
+    }
+    addInstance(lineCount) {
+        const slot = this.freeGroups.pop() ?? this.groupCount++;
+        const texts = [];
+        const slots = [];
+        for (let line = 0; line < lineCount; line++) {
+            const text = makeMember();
+            texts.push(text);
+            slots.push(this.mesh.addText(text));
+        }
+        this.groups[slot] = { texts, slots };
+        for (const member of slots)
+            this.groupByMember.set(member, slot);
+        return slot;
+    }
+    removeInstance(slot) {
+        const group = this.groups[slot];
+        if (!group)
+            return;
+        for (const member of group.slots)
+            this.groupByMember.delete(member);
+        for (const text of group.texts) {
+            this.mesh.removeText(text);
+            // The member's own `GlyphsGeometry`, which only ever held its bounds — the batch draws from
+            // its own. Nothing was uploaded, so this is bookkeeping, not a GPU free.
+            text.dispose();
+        }
+        this.groups[slot] = undefined;
+        this.freeGroups.push(slot);
+        // Members left the batch's order with them; drop the stale copy so the next pass reapplies.
+        this.appliedOrder = [];
+    }
+}
+/**
+ * Builds a batch member with the properties that never change for its lifetime.
+ *
+ * All three are syncable, so writing them once here — rather than per update — is what keeps a
+ * layout change from re-running troika's async layout and repacking the batch.
+ * @returns The member.
+ */
+function makeMember() {
+    const text = new TextImpl();
+    text.fontSize = LAYOUT_FONT_SIZE;
+    text.lineHeight = LINE_HEIGHT;
+    // Wrapping is the floorplan's job: it measures and breaks lines itself, then hands over the
+    // result with explicit newlines. Letting troika re-wrap on top would fight that.
+    text.whiteSpace = 'nowrap';
+    return text;
+}
+/** Returned for an unclaimed slot, so a caller reading one iterates nothing rather than throwing. */
+const EMPTY_GROUP = { texts: [], slots: [] };

package/dist/objects/text/text-layout.d.ts

@@ -0,0 +1,92 @@
+import { type Rect } from '@expofp/geometry';
+import { type TextImpl } from '../../core/text/Text';
+import { type TextDef, type TextLineDef } from '../../types/defs';
+/**
+ * The em size every member lays out at, fixed for its lifetime.
+ *
+ * `fontSize` is a syncable property: changing it re-runs troika's async layout and repacks the whole
+ * batch. A label's size changes on every zoom step, so paying that would make zooming a sequence of
+ * repacks. Laying out at a constant 1 em and carrying the real size in the member's `scale` costs a
+ * matrix write instead — the scale is not syncable, so nothing re-lays-out.
+ *
+ * One, not zero: troika reads `this.fontSize || 0.1`, so a member left at zero lays out at a tenth of
+ * an em and every scale below would have to carry a compensating factor of ten.
+ */
+export declare const LAYOUT_FONT_SIZE = 1;
+/** Line box height as a multiple of the font size, matching the `lineHeight` members are given. */
+export declare const LINE_HEIGHT = 1.1;
+/**
+ * A line's placement **in its def's own unrotated frame**, as an offset from the bounds' center.
+ *
+ * Layout stops here on purpose: where the bounds sit in the plan, and how they are turned, is a
+ * separate step ({@link applyPlacement}). Keeping the two apart is what lets the stacking be
+ * asserted as plain numbers, with no trigonometry in the test.
+ */
+export interface LaidOutLine {
+    /** Which horizontal point of the line's box sits at its origin. */
+    anchorX: 'left' | 'center' | 'right';
+    /** Which vertical point of the line's box sits at its origin; only the outer edges are used. */
+    anchorY: 'top' | 'bottom';
+    /** How wrapped rows align against each other within this line. */
+    textAlign: 'left' | 'center' | 'right';
+    /** Offset from the bounds' center along the bounds' own x axis. */
+    offsetX: number;
+    /** Offset from the bounds' center along the bounds' own y axis. */
+    offsetY: number;
+    /** Horizontal scale: the line's font size, which is its em height in plan units. */
+    scaleX: number;
+    /** Vertical scale: negative, because plan space runs y-down and text lays out y-up. */
+    scaleY: number;
+    /** `[minX, minY, maxX, maxY]` in the line's own em space, clipping it to the def's bounds. */
+    clipRect: [number, number, number, number];
+}
+/**
+ * Stacks a text def's lines inside its bounds, aligned as the def asks.
+ *
+ * Works entirely in the bounds' unrotated frame, so a rotated def lays out identically to an
+ * unrotated one — the rotation is applied afterwards, to the whole stack at once. That is also what
+ * lets the clip rect be a plain offset from the center: the member carries the same rotation, so the
+ * rect turns with it.
+ *
+ * **The y flip lives in `scaleY`.** Plan space runs y-down; troika lays text out y-up. Rather than
+ * troika's `orientation` — a `lookAt` rotation, which would leave the clip rect to be flipped
+ * separately — the flip rides on the scale the lines need anyway for their font size, so the clip
+ * rect, which divides by that scale, inherits it for free.
+ *
+ * **Plan units throughout**, font sizes included. A plan that wants a label to hold an on-screen size
+ * converts for itself, against the pixel size the renderer publishes — the same way it sizes every
+ * other pixel-authored thing it draws.
+ * @param def - The text to lay out.
+ * @returns One placement per line, in the def's line order.
+ */
+export declare function layoutText(def: TextDef): LaidOutLine[];
+/**
+ * Writes a laid-out line onto its member: the bounds rotation and position applied to the local
+ * offset, the line's scale, and its clip rect.
+ *
+ * The post-transform half of `layoutText`. `updateMatrix` is what reports the move to the batch,
+ * because members are not in the scene graph and nothing else would.
+ *
+ * A screen-space def also gets its sprite anchor. That is the def's bounds center, shared by every
+ * line: each line's member sits at its own plan position, and pivoting each about itself would
+ * compress the stack under tilt. The anchor carries no elevation, because every line already sits at
+ * the def's own elevation on `position`, and `MemberTexture` reads it from there instead.
+ * `MemberTexture` then composes the member per draw, so `matrixAutoUpdate` goes off and the
+ * position, rotation and scale written here become the inputs that compose reads rather than the
+ * matrix itself.
+ * @param text - The member to place.
+ * @param line - The line's local placement.
+ * @param bounds - The def's bounds, supplying the rotation, center and elevation.
+ * @param screenSpace - Whether the def faces the camera.
+ */
+export declare function applyPlacement(text: TextImpl, line: LaidOutLine, bounds: Rect, screenSpace: boolean): void;
+/**
+ * The height one line's box occupies.
+ *
+ * A single `TextLineDef` can hold embedded newlines — the floorplan joins an exhibitor's name rows
+ * into one def — so its box is as many line boxes tall as it has rows.
+ * @param line - The line to measure.
+ * @returns The height, in plan units.
+ */
+export declare function lineHeight(line: TextLineDef): number;
+//# sourceMappingURL=text-layout.d.ts.map

package/dist/objects/text/text-layout.js

@@ -0,0 +1,180 @@
+import { Vector2 } from 'three';
+/**
+ * The em size every member lays out at, fixed for its lifetime.
+ *
+ * `fontSize` is a syncable property: changing it re-runs troika's async layout and repacks the whole
+ * batch. A label's size changes on every zoom step, so paying that would make zooming a sequence of
+ * repacks. Laying out at a constant 1 em and carrying the real size in the member's `scale` costs a
+ * matrix write instead — the scale is not syncable, so nothing re-lays-out.
+ *
+ * One, not zero: troika reads `this.fontSize || 0.1`, so a member left at zero lays out at a tenth of
+ * an em and every scale below would have to carry a compensating factor of ten.
+ */
+export const LAYOUT_FONT_SIZE = 1;
+/** Line box height as a multiple of the font size, matching the `lineHeight` members are given. */
+export const LINE_HEIGHT = 1.1;
+/**
+ * Stacks a text def's lines inside its bounds, aligned as the def asks.
+ *
+ * Works entirely in the bounds' unrotated frame, so a rotated def lays out identically to an
+ * unrotated one — the rotation is applied afterwards, to the whole stack at once. That is also what
+ * lets the clip rect be a plain offset from the center: the member carries the same rotation, so the
+ * rect turns with it.
+ *
+ * **The y flip lives in `scaleY`.** Plan space runs y-down; troika lays text out y-up. Rather than
+ * troika's `orientation` — a `lookAt` rotation, which would leave the clip rect to be flipped
+ * separately — the flip rides on the scale the lines need anyway for their font size, so the clip
+ * rect, which divides by that scale, inherits it for free.
+ *
+ * **Plan units throughout**, font sizes included. A plan that wants a label to hold an on-screen size
+ * converts for itself, against the pixel size the renderer publishes — the same way it sizes every
+ * other pixel-authored thing it draws.
+ * @param def - The text to lay out.
+ * @returns One placement per line, in the def's line order.
+ */
+export function layoutText(def) {
+    const { bounds, lines, alignment, padding } = def;
+    const half = _half.set(bounds.size.x, bounds.size.y).multiplyScalar(0.5);
+    // Where the first line's anchor sits. A centered block starts half the leftover space in from the
+    // top edge, so the stack ends up centered as a whole; every other alignment starts at the padded
+    // edge itself.
+    const offset = _offset.copy(half);
+    if (alignment.vertical === 'center') {
+        let stackHeight = 0;
+        for (const line of lines)
+            stackHeight += lineHeight(line);
+        offset.y -= (bounds.size.y - stackHeight) / 2;
+    }
+    else {
+        offset.sub(_padding.fromArray(padding));
+    }
+    offset.multiply(alignmentFactors(alignment));
+    const placed = [];
+    for (const line of lines) {
+        const scaleX = line.fontSize;
+        // Negative: the y flip. Also why the clip rect below comes out correctly ordered — dividing by a
+        // negative scale swaps its min and max back.
+        //
+        // `TextImpl.orientation` looks like the right tool for this flip, but it only reaches the shader
+        // as a uniform. `BatchedTextImpl.raycast` and `isDrawn` pick and cull through `text.matrix` and
+        // its geometry's bounds on the CPU, which never read it, so using `orientation` here draws
+        // correctly and picks the wrong region.
+        const scaleY = -scaleX;
+        placed.push({
+            anchorX: alignment.horizontal,
+            // Only the outer edges: a middle-anchored line would stack against its own center, so the
+            // block's vertical alignment is carried by the starting offset above instead.
+            anchorY: alignment.vertical === 'bottom' ? 'bottom' : 'top',
+            textAlign: alignment.text ?? alignment.horizontal,
+            offsetX: offset.x,
+            offsetY: offset.y,
+            scaleX,
+            scaleY,
+            // The bounds' corners relative to this line's origin, converted from plan units into the
+            // line's em space. A zero-size line would divide by zero, but those are hidden before they
+            // draw (see `TextInstance`), so the clip rect is never read.
+            clipRect: [
+                (-half.x - offset.x) / scaleX,
+                (half.y - offset.y) / scaleY,
+                (half.x - offset.x) / scaleX,
+                (-half.y - offset.y) / scaleY,
+            ],
+        });
+        offset.y += lineHeight(line);
+    }
+    return placed;
+}
+/**
+ * Writes a laid-out line onto its member: the bounds rotation and position applied to the local
+ * offset, the line's scale, and its clip rect.
+ *
+ * The post-transform half of `layoutText`. `updateMatrix` is what reports the move to the batch,
+ * because members are not in the scene graph and nothing else would.
+ *
+ * A screen-space def also gets its sprite anchor. That is the def's bounds center, shared by every
+ * line: each line's member sits at its own plan position, and pivoting each about itself would
+ * compress the stack under tilt. The anchor carries no elevation, because every line already sits at
+ * the def's own elevation on `position`, and `MemberTexture` reads it from there instead.
+ * `MemberTexture` then composes the member per draw, so `matrixAutoUpdate` goes off and the
+ * position, rotation and scale written here become the inputs that compose reads rather than the
+ * matrix itself.
+ * @param text - The member to place.
+ * @param line - The line's local placement.
+ * @param bounds - The def's bounds, supplying the rotation, center and elevation.
+ * @param screenSpace - Whether the def faces the camera.
+ */
+export function applyPlacement(text, line, bounds, screenSpace) {
+    const { rotation } = bounds;
+    const position = _position
+        .set(line.offsetX, line.offsetY)
+        .rotateAround(ORIGIN, rotation)
+        .add(bounds.center);
+    text.position.set(position.x, position.y, bounds.elevation);
+    text.rotation.set(0, 0, rotation);
+    text.scale.set(line.scaleX, line.scaleY, 1);
+    if (screenSpace) {
+        // Mutated in place rather than replaced, so a per-update write allocates nothing.
+        const anchor = text.spriteAnchor ?? new Vector2();
+        anchor.set(bounds.center.x, bounds.center.y);
+        text.spriteAnchor = anchor;
+        // The compose owns the matrix from here. Nothing may recompose it from the three fields above.
+        text.matrixAutoUpdate = false;
+    }
+    else {
+        text.spriteAnchor = null;
+        text.matrixAutoUpdate = true;
+    }
+    text.updateMatrix();
+    // Held as one array for the member's life: `clipRect` is not a syncable property, so this is a
+    // plain per-frame read and mutating it in place avoids a per-update allocation.
+    const clipRect = (text.clipRect ??= [0, 0, 0, 0]);
+    clipRect[0] = line.clipRect[0];
+    clipRect[1] = line.clipRect[1];
+    clipRect[2] = line.clipRect[2];
+    clipRect[3] = line.clipRect[3];
+}
+/**
+ * The height one line's box occupies.
+ *
+ * A single `TextLineDef` can hold embedded newlines — the floorplan joins an exhibitor's name rows
+ * into one def — so its box is as many line boxes tall as it has rows.
+ * @param line - The line to measure.
+ * @returns The height, in plan units.
+ */
+export function lineHeight(line) {
+    return line.fontSize * LINE_HEIGHT * line.text.split('\n').length;
+}
+/**
+ * Which way each axis is offset from the bounds' center for a given alignment.
+ *
+ * Vertical `center` shares `top`'s factor deliberately: a centered block still stacks downward from
+ * a start position, and it is that start position the caller moves.
+ * @param alignment - The def's alignment.
+ * @returns The scratch factors, valid until the next call.
+ */
+function alignmentFactors(alignment) {
+    return _factors.set(HORIZONTAL_FACTORS[alignment.horizontal], VERTICAL_FACTORS[alignment.vertical]);
+}
+/** Which edge a horizontal alignment offsets toward: `-1` left, `0` centered, `1` right. */
+const HORIZONTAL_FACTORS = {
+    left: -1,
+    center: 0,
+    right: 1,
+};
+/** Which edge a vertical alignment offsets toward; `center` shares `top`'s sign (see above). */
+const VERTICAL_FACTORS = {
+    top: -1,
+    center: -1,
+    bottom: 1,
+};
+/**
+ * Scratch reused across calls: layout runs once per def per update and never escapes a synchronous
+ * block, so it allocates nothing.
+ */
+const _half = new Vector2();
+const _offset = new Vector2();
+const _padding = new Vector2();
+const _factors = new Vector2();
+const _position = new Vector2();
+/** The point a rotated block turns about — its own bounds center, which the offsets are relative to. */
+const ORIGIN = new Vector2(0, 0);