@expofp/renderer 3.44.7 → 3.45.0

package/dist/events/layout-targets.js

@@ -1,8 +1,9 @@
 import { createContext, use, useEffect } from 'react';
-import { isLayerDef } from '../types/guards';
-import { writeChanged } from '../update';
+import { isImageDef, isLayerDef, isPlacementTarget } from '../types/guards';
+import { subscribeDef, writeChanged } from '../update';
 import { createLogger } from '../utils/logging';
 import { culledBy } from './def-culling';
+import { createPlacement } from './placement';
 const logger = createLogger('layout');
 /**
  * The renderer's re-layout registry. Absent outside a renderer, where a layer simply registers
@@ -11,7 +12,8 @@ const logger = createLogger('layout');
 export const LayoutTargetsContext = createContext(undefined);
 /**
  * Registers a layer's re-layout targets for as long as the layer is mounted: the defs it holds that
- * declare an `onScale`, and the layer itself when it declares one.
+ * declare an `onScale`, an `onRoll` or a `placement`, and the layer itself when it declares a
+ * layout rule.
  *
  * A child *layer* is never registered here even when it declares a handler — it registers itself, and
  * it has to: a handler assigned to a layer after mount re-renders that layer alone, so a registration
@@ -34,12 +36,13 @@ export function useLayoutTargets(layer, children) {
     useEffect(() => {
         if (!targets)
             return undefined;
-        const defs = children.filter((def) => (def.onScale !== undefined || def.onRoll !== undefined) && !isLayerDef(def));
+        const defs = children.filter((def) => (def.onScale !== undefined || def.onRoll !== undefined || declaresPlacement(def)) &&
+            !isLayerDef(def));
         if (layer.onScale || layer.onRoll)
             defs.push(layer);
         if (!defs.length)
             return undefined;
-        return targets.register(defs);
+        return targets.register(layer, defs);
     }, [targets, layer, children]);
 }
 /**
@@ -50,7 +53,16 @@ export function useLayoutTargets(layer, children) {
  * @returns The registry.
  */
 export function createLayoutTargets(invalidate, pixelSize, roll = 0) {
-    const groups = new Set();
+    /**
+     * Every registered def array, with the layer that registered it. Map entries are exactly what
+     * the placement pass takes, so a pass is handed the registry itself.
+     */
+    const groups = new Map();
+    const placement = createPlacement();
+    /** Whether a participant registered since the last pass, so one is owed. */
+    let placementDirty = false;
+    /** Whether a participant's box moved since the last pass, so one is owed. */
+    let placementDrifted = false;
     /**
      * The pixel size each def was last laid out at — the registry's layout state, because the rule
      * that lays a def out is the def's own. Keyed by def rather than by group, so a membership change
@@ -160,7 +172,7 @@ export function createLayoutTargets(invalidate, pixelSize, roll = 0) {
         const start = performance.now();
         const before = flipped.size + queued.size + deferred.size;
         let ran = 0;
-        for (const defs of groups) {
+        for (const defs of groups.keys()) {
             for (const def of defs) {
                 if (!def[handler])
                     continue;
@@ -186,8 +198,14 @@ export function createLayoutTargets(invalidate, pixelSize, roll = 0) {
         get hasWork() {
             return flipped.size > 0 || queued.size > 0 || deferred.size > 0;
         },
-        register(defs) {
-            groups.add(defs);
+        get needsPlacement() {
+            return placementDirty;
+        },
+        get placementDrifted() {
+            return placementDrifted;
+        },
+        register(layer, defs) {
+            groups.set(defs, layer);
             let wrote = false;
             for (const def of defs) {
                 if (!drawnHidden.has(def))
@@ -200,18 +218,54 @@ export function createLayoutTargets(invalidate, pixelSize, roll = 0) {
                     wrote = true;
                 });
             }
+            // A verdict cannot be computed for one def alone, because it depends on every other box, and
+            // the registry holds no camera. So registration only marks a pass owed; the frame the
+            // `invalidate` below asks for is what runs it, and it runs before that frame draws.
+            //
+            // Owed on any `placement`, not only on a participant: a flat def that carries one is exactly
+            // the mistake the pass's development warning exists to catch, and the pass has to run to say so.
+            if (defs.some(declaresPlacement)) {
+                placementDirty = true;
+                wrote = true;
+            }
             // Registration happens in an effect rather than inside the frame loop, so anything written here
             // needs a frame asking for it.
             if (wrote)
                 invalidate();
+            // A participant that moves owes a pass as one that joins does: its verdict, and those of the
+            // defs it used to block or be blocked by, were earned at the old position. Only participants
+            // are watched, so a write to anything else costs nothing, and only a change to what the pass
+            // measures owes one: an `update()` that moved no box, such as a fade writing `opacity` on every
+            // animation frame, would otherwise run the pass at frame rate on a still camera, past the rate
+            // gate that is there for the camera. The registry's own writes (`onPlace` returns, which go
+            // through `syncNow`) never notify, so a verdict flip cannot owe the pass that would flip it
+            // again.
+            const unsubscribes = defs.filter(isPlacementTarget).map((def) => {
+                const seen = measuredBy(def);
+                return subscribeDef(def, () => {
+                    if (!remeasure(def, seen))
+                        return;
+                    placementDrifted = true;
+                    invalidate();
+                });
+            });
             return () => {
+                for (const unsubscribe of unsubscribes)
+                    unsubscribe();
                 groups.delete(defs);
+                // A participant that leaves frees its room, so the defs it beat may now fit: owe a pass, and
+                // ask for the frame that runs it, as registration does.
+                if (defs.some(isPlacementTarget)) {
+                    placementDirty = true;
+                    invalidate();
+                }
                 // A queued def whose layer is gone must not be written from the backlog: its instances are
                 // unmounting.
                 for (const def of defs) {
                     flipped.delete(def);
                     queued.delete(def);
                     deferred.delete(def);
+                    placement.forget(def);
                 }
             };
         },
@@ -225,6 +279,23 @@ export function createLayoutTargets(invalidate, pixelSize, roll = 0) {
             view.roll = nextRoll;
             runHandlers(`roll ${+nextRoll.toFixed(3)}`, 'onRoll');
         },
+        applyPlacement(context) {
+            placementDirty = false;
+            placementDrifted = false;
+            // Flips and clusters are reported in one synchronous call, flips first, so one drain writes
+            // a seed's hiding and the cluster standing for it together.
+            placement.run(groups, context, (def, placed) => {
+                const changed = def.placement?.onPlace(placed, view);
+                if (changed?.length)
+                    enqueue(changed);
+            }, (_layer, clusters, clustering) => {
+                // The options the pass hands over, not the layer's current ones: a layer that dropped
+                // `clustering` is still owed the empty set through the handler that drew its clusters.
+                const changed = clustering.onCluster(clusters, view);
+                if (changed?.length)
+                    enqueue(changed);
+            });
+        },
         drain(frustum, budgetMs = -1) {
             if (flipped.size === 0 && queued.size === 0 && deferred.size === 0)
                 return false;
@@ -275,3 +346,52 @@ export function createLayoutTargets(invalidate, pixelSize, roll = 0) {
         },
     };
 }
+/**
+ * Whether a def declares a placement, participating in the pass or not.
+ * @param def - The def to test.
+ * @returns Whether it carries `placement`.
+ */
+function declaresPlacement(def) {
+    return def.placement !== undefined;
+}
+/**
+ * Reads what the pass measures of a participant: the box its bounds, origin and padding describe.
+ * @param def - The participant.
+ * @returns The reading.
+ */
+function measuredBy(def) {
+    const measured = { numbers: new Float64Array(9), padding: undefined };
+    remeasure(def, measured);
+    // The first reading is the baseline, not a change.
+    return measured;
+}
+/**
+ * Re-reads a participant into an earlier reading and says whether anything the pass measures moved.
+ * @param def - The participant.
+ * @param into - The reading to compare against and overwrite.
+ * @returns Whether the reading changed.
+ */
+function remeasure(def, into) {
+    const { bounds } = def;
+    const origin = isImageDef(def) ? def.origin : undefined;
+    const padding = def.placement?.padding;
+    const next = _measure;
+    next[0] = bounds.center.x;
+    next[1] = bounds.center.y;
+    next[2] = bounds.size.x;
+    next[3] = bounds.size.y;
+    next[4] = bounds.rotation;
+    next[5] = bounds.elevation;
+    next[6] = origin?.[0] ?? 0.5;
+    next[7] = origin?.[1] ?? 0.5;
+    let changed = padding !== into.padding;
+    for (let i = 0; i < 8; i++) {
+        if (next[i] !== into.numbers[i])
+            changed = true;
+        into.numbers[i] = next[i];
+    }
+    into.padding = padding;
+    return changed;
+}
+// Scratch for the reading, filled and compared within one call.
+const _measure = new Float64Array(9);

package/dist/events/placement/box.d.ts

@@ -0,0 +1,59 @@
+import { type Camera } from 'three';
+import { type Space } from '../../space/Space';
+import { type ImageDef, type TextDef } from '../../types/defs';
+import { type PlacementBox } from './grid';
+/**
+ * The screen rectangle one def occupies, in CSS pixels from the canvas's top-left corner.
+ *
+ * There is one path, because only a screen-space def is ever tested. Its anchor projects through
+ * the camera, and its extent comes from the pixel size rather than from the projection: constant
+ * pixel size means a sprite is the same number of pixels across at every depth, so the only
+ * camera-dependent term is where the anchor lands.
+ *
+ * `origin` shifts the rectangle relative to the anchor exactly as it shifts the quad, in the
+ * plan's y-down sense, which is also the canvas's. A bottom-center origin therefore puts the
+ * anchor on the rectangle's bottom edge and the rectangle above it.
+ *
+ * This is the def's own extent, without its `placement.padding`: that is what the grid stores, and
+ * {@link paddedBox} grows it into the box that is tested. Storing the grown box as well would make
+ * two padded defs keep twice the padding apart.
+ * @param def - The def to measure.
+ * @param space - The scene's space, for the projection.
+ * @param camera - The camera in use.
+ * @param pixelSize - Plan units per CSS pixel.
+ * @param out - The box to write into, reused across a pass.
+ * @returns The box, or nothing when the def has no extent or its anchor does not project.
+ */
+export declare function screenBoxOf(def: ImageDef | TextDef, space: Space, camera: Camera, pixelSize: number, out: PlacementBox): PlacementBox | undefined;
+/**
+ * The screen rectangle a constant-pixel-size sprite occupies when its anchor stands at a plan
+ * point, in CSS pixels from the canvas's top-left corner.
+ *
+ * What {@link screenBoxOf} measures a def with, taken apart so that a box can stand at an anchor
+ * that is not a def's own: a cluster's marker stands at the mean of its units' anchors.
+ * @param x - The anchor's plan x.
+ * @param y - The anchor's plan y.
+ * @param elevation - The anchor's elevation, in plan units.
+ * @param width - The sprite's width in CSS pixels.
+ * @param height - The sprite's height in CSS pixels.
+ * @param origin - Which point of the sprite stands on the anchor, centered when omitted.
+ * @param rotation - Its spin about the screen normal, in radians.
+ * @param space - The scene's space, for the projection.
+ * @param camera - The camera in use.
+ * @param out - The box to write into.
+ * @returns The box, or nothing when the sprite has no extent or its anchor does not project.
+ */
+export declare function spriteBoxAt(x: number, y: number, elevation: number, width: number, height: number, origin: readonly [number, number] | undefined, rotation: number, space: Space, camera: Camera, out: PlacementBox): PlacementBox | undefined;
+/**
+ * The box a def is tested with: its extent grown by `placement.padding`, by one number on all four
+ * sides or by a `[horizontal, vertical]` pair.
+ *
+ * The grid stores the extent and tests this, so each def's padding applies once, on the side that is
+ * testing. A def with no padding gets a copy of its extent.
+ * @param def - The def whose padding grows the box.
+ * @param box - The def's extent, from {@link screenBoxOf}.
+ * @param out - The box to write into, which may be `box` itself.
+ * @returns `out`.
+ */
+export declare function paddedBox(def: ImageDef | TextDef, box: PlacementBox, out: PlacementBox): PlacementBox;
+//# sourceMappingURL=box.d.ts.map

package/dist/events/placement/box.js

@@ -0,0 +1,96 @@
+import { Box, Point, pointRotate, Rect, rectBounds } from '@expofp/geometry';
+import { isImageDef } from '../../types/guards';
+/**
+ * The screen rectangle one def occupies, in CSS pixels from the canvas's top-left corner.
+ *
+ * There is one path, because only a screen-space def is ever tested. Its anchor projects through
+ * the camera, and its extent comes from the pixel size rather than from the projection: constant
+ * pixel size means a sprite is the same number of pixels across at every depth, so the only
+ * camera-dependent term is where the anchor lands.
+ *
+ * `origin` shifts the rectangle relative to the anchor exactly as it shifts the quad, in the
+ * plan's y-down sense, which is also the canvas's. A bottom-center origin therefore puts the
+ * anchor on the rectangle's bottom edge and the rectangle above it.
+ *
+ * This is the def's own extent, without its `placement.padding`: that is what the grid stores, and
+ * {@link paddedBox} grows it into the box that is tested. Storing the grown box as well would make
+ * two padded defs keep twice the padding apart.
+ * @param def - The def to measure.
+ * @param space - The scene's space, for the projection.
+ * @param camera - The camera in use.
+ * @param pixelSize - Plan units per CSS pixel.
+ * @param out - The box to write into, reused across a pass.
+ * @returns The box, or nothing when the def has no extent or its anchor does not project.
+ */
+export function screenBoxOf(def, space, camera, pixelSize, out) {
+    const scale = pixelSize;
+    if (!Number.isFinite(scale) || scale <= 0)
+        return undefined;
+    const bounds = def.bounds;
+    const origin = isImageDef(def) ? def.origin : undefined;
+    return spriteBoxAt(bounds.center.x, bounds.center.y, bounds.elevation, bounds.size.x / scale, bounds.size.y / scale, origin, bounds.rotation, space, camera, out);
+}
+/**
+ * The screen rectangle a constant-pixel-size sprite occupies when its anchor stands at a plan
+ * point, in CSS pixels from the canvas's top-left corner.
+ *
+ * What {@link screenBoxOf} measures a def with, taken apart so that a box can stand at an anchor
+ * that is not a def's own: a cluster's marker stands at the mean of its units' anchors.
+ * @param x - The anchor's plan x.
+ * @param y - The anchor's plan y.
+ * @param elevation - The anchor's elevation, in plan units.
+ * @param width - The sprite's width in CSS pixels.
+ * @param height - The sprite's height in CSS pixels.
+ * @param origin - Which point of the sprite stands on the anchor, centered when omitted.
+ * @param rotation - Its spin about the screen normal, in radians.
+ * @param space - The scene's space, for the projection.
+ * @param camera - The camera in use.
+ * @param out - The box to write into.
+ * @returns The box, or nothing when the sprite has no extent or its anchor does not project.
+ */
+export function spriteBoxAt(x, y, elevation, width, height, origin, rotation, space, camera, out) {
+    if (!(width > 0) || !(height > 0))
+        return undefined;
+    const screen = space.planToCanvas(_anchor.set(x, y, elevation), camera, _screen);
+    if (!screen || !Number.isFinite(screen.x) || !Number.isFinite(screen.y))
+        return undefined;
+    // The sprite's center sits off the anchor by `origin`, and turns with the sprite about it.
+    _offset.set((0.5 - (origin?.[0] ?? 0.5)) * width, (0.5 - (origin?.[1] ?? 0.5)) * height);
+    pointRotate(_offset, rotation, ZERO, _offset);
+    _rect.set(screen.x + _offset.x, screen.y + _offset.y, width, height, rotation, 0);
+    const { min, max } = rectBounds(_rect, _bounds);
+    out.minX = min.x;
+    out.maxX = max.x;
+    out.minY = min.y;
+    out.maxY = max.y;
+    return out;
+}
+/**
+ * The box a def is tested with: its extent grown by `placement.padding`, by one number on all four
+ * sides or by a `[horizontal, vertical]` pair.
+ *
+ * The grid stores the extent and tests this, so each def's padding applies once, on the side that is
+ * testing. A def with no padding gets a copy of its extent.
+ * @param def - The def whose padding grows the box.
+ * @param box - The def's extent, from {@link screenBoxOf}.
+ * @param out - The box to write into, which may be `box` itself.
+ * @returns `out`.
+ */
+export function paddedBox(def, box, out) {
+    const padding = def.placement?.padding ?? 0;
+    const padX = typeof padding === 'number' ? padding : padding[0];
+    const padY = typeof padding === 'number' ? padding : padding[1];
+    out.minX = box.minX - padX;
+    out.maxX = box.maxX + padX;
+    out.minY = box.minY - padY;
+    out.maxY = box.maxY + padY;
+    return out;
+}
+/** The point a sprite's center offset turns about. */
+const ZERO = { x: 0, y: 0 };
+// Scratch, each filled and consumed within one synchronous call.
+const _anchor = new Point();
+const _screen = new Point();
+const _offset = new Point();
+const _rect = new Rect({ x: 0, y: 0 }, { x: 0, y: 0 });
+const _bounds = new Box();

package/dist/events/placement/grid.d.ts

@@ -0,0 +1,161 @@
+import { type OverlapMode } from '../../types/defs';
+/** A rectangle in CSS pixels from the canvas's top-left corner, as the placement pass tests it. */
+export interface PlacementBox {
+    /** The left edge. */
+    minX: number;
+    /** The top edge. */
+    minY: number;
+    /** The right edge. */
+    maxX: number;
+    /** The bottom edge. */
+    maxY: number;
+}
+/**
+ * Whether a def in mode `a` is allowed to cover one already placed in mode `b`.
+ *
+ * Ported from maplibre's `overlapAllowed` in `src/symbol/grid_index.ts`. With two modes the rule
+ * reduces to `a === 'always'`, and this stays as the one place it is written.
+ *
+ * The `_b` parameter is unused: an `always` entry is never inserted into the grid, so the mode of
+ * the def already there is always `never`. Re-adding a third mode brings it back.
+ * @param a - The mode of the def being tested.
+ * @param _b - The mode of the def already in the grid. Unused, see above.
+ * @returns Whether the overlap is allowed.
+ */
+export declare function overlapAllowed(a: OverlapMode, _b: OverlapMode): boolean;
+/**
+ * Whether two boxes overlap, by the rule {@link PlacementGrid.blockerOf} applies: edge contact is
+ * clear, so two boxes sharing a border do not overlap.
+ * @param a - One box.
+ * @param b - The other.
+ * @returns Whether they overlap.
+ */
+export declare function overlaps(a: PlacementBox, b: PlacementBox): boolean;
+/**
+ * A uniform-cell index of screen rectangles, which answers which rectangle already in it, if any,
+ * blocks a new one.
+ *
+ * Modeled on maplibre's `GridIndex`, without the circle half. Circles exist there for labels that
+ * follow a curved line, which this renderer does not draw. Entries live in flat arrays that a reset
+ * keeps at their length and refills from the front under a count cursor: setting `length = 0`
+ * instead lets V8 trim the backing store, so every pass would grow it again through its doublings.
+ * The per-cell id lists are short and are still cleared with `length = 0`, but only the cells an
+ * entry was filed under: a pass resets the grid once per collision scope, and every registered
+ * layer is a scope, most of them with no participant at all. Clearing all 1820 cells of a 1440 by
+ * 900 canvas for each of imexamerica25-3d's 21 scopes was 0.9–1.2 ms of a 1.1–1.4 ms pass.
+ *
+ * The index covers the canvas plus {@link GRID_MARGIN_PX} on every side, so a def crossing the
+ * edge of the screen decides off screen, where the churn is invisible.
+ */
+export declare class PlacementGrid {
+    /** Each cell's entry ids. Index is `y * xCells + x`. */
+    private cells;
+    /** The index of every cell that holds an entry since the last reset, which is all it clears. */
+    private readonly filled;
+    /**
+     * Four numbers per entry: `minX`, `minY`, `maxX`, `maxY`. Only the first `count * 4` are live; the
+     * rest are the last pass's, kept so the next pass overwrites them in place.
+     */
+    private readonly boxes;
+    /** One mode per entry, parallel to {@link boxes} and live up to `count` in the same way. */
+    private readonly modes;
+    private count;
+    private xCells;
+    private yCells;
+    /** The canvas width the cells were built for. `-1` until the first `reset`, so it always rebuilds. */
+    private width;
+    /** The canvas height the cells were built for. `-1` until the first `reset`, so it always rebuilds. */
+    private height;
+    /**
+     * @param width - The canvas width in CSS pixels.
+     * @param height - The canvas height in CSS pixels.
+     */
+    constructor(width: number, height: number);
+    /**
+     * Empties the index and sizes it for a canvas, which is what every pass starts with.
+     *
+     * The cell array is rebuilt only when the canvas size changed, so an unresized canvas pays only
+     * for clearing the cells the last fill used.
+     * @param width - The canvas width in CSS pixels.
+     * @param height - The canvas height in CSS pixels.
+     */
+    reset(width: number, height: number): void;
+    /**
+     * Whether the box intersects the indexed area, which is the canvas plus its margin. A box that
+     * only partly overlaps it passes; only one wholly outside fails.
+     *
+     * A box wholly outside it is not placed and not inserted. That is a correctness rule rather than a
+     * priority one: the index cannot hold it, so it cannot be tested against later defs either.
+     * @param box - The box to test.
+     * @returns Whether the index covers it.
+     */
+    intersects(box: PlacementBox): boolean;
+    /**
+     * The earliest-inserted entry that blocks this box, or nothing when it is clear.
+     *
+     * **Earliest, not first found.** The cell walk reaches a box filed under a later cell before one
+     * filed under an earlier cell, so returning the first match would make the answer depend on cell
+     * iteration order — and the answer is load-bearing: in a clustering scope the blocker is the
+     * cluster's seed, and first come, first served means the earliest. Scanning every cell the box
+     * touches costs the early exit a boolean test could take, against a few hundred entries in a
+     * handful of cells.
+     *
+     * Edge contact does not block: two boxes sharing a border are treated as clear, so a row of
+     * abutting labels is placeable.
+     *
+     * Test {@link intersects} first: a box wholly outside the indexed area is clamped into an edge cell,
+     * which is safe only because stored coordinates are then compared exactly.
+     * @param box - The box to test.
+     * @param overlap - How the def being tested competes.
+     * @returns The blocking entry's id, as {@link insert} returned it, or `undefined` when clear.
+     */
+    blockerOf(box: PlacementBox, overlap: OverlapMode): number | undefined;
+    /**
+     * Adds a box, so that later tests see it.
+     *
+     * Separate from {@link blockerOf} because asking whether a box is blocked and claiming its room are
+     * different questions: a group tests its padded union and inserts its plain one, and maplibre
+     * separates `placeCollisionBox` from `insertCollisionBox` for the same reason.
+     *
+     * Only insert a box that {@link intersects} accepted: one wholly outside the indexed area would be
+     * clamped into an edge cell, and relies on the exact comparison in {@link blockerOf} to stay
+     * harmless.
+     * @param box - The box to add.
+     * @param overlap - How the def competes.
+     * @returns The entry's id: the number of entries inserted before it since the last reset.
+     */
+    insert(box: PlacementBox, overlap: OverlapMode): number;
+    /**
+     * Reads back the box an entry was inserted with.
+     * @param id - The entry's id, as {@link insert} returned it since the last reset.
+     * @param out - The box to write into.
+     * @returns `out`.
+     */
+    boxOf(id: number, out: PlacementBox): PlacementBox;
+    /**
+     * Which cell column a CSS x lands in, clamped into the index.
+     * @param x - The coordinate.
+     * @returns The column.
+     */
+    private cellX;
+    /**
+     * Which cell row a CSS y lands in, clamped into the index.
+     * @param y - The coordinate.
+     * @returns The row.
+     */
+    private cellY;
+}
+/**
+ * How wide one cell is, in CSS pixels. More cells means fewer boxes to compare per cell, and more
+ * cells for one box to be filed under. Maplibre uses 25 against symbols a few pixels across; our
+ * pins are 32, so one pin usually touches one cell.
+ */
+export declare const GRID_CELL_PX = 32;
+/**
+ * How far past the canvas the index reaches, in CSS pixels.
+ *
+ * Maplibre's `viewportPadding`, for its reason: a def crossing the edge of the screen decides off
+ * screen, so the flicker that a crossing causes happens where nobody sees it.
+ */
+export declare const GRID_MARGIN_PX = 100;
+//# sourceMappingURL=grid.d.ts.map