@expofp/renderer 3.44.8 → 3.45.1

package/dist/types/defs.d.ts

@@ -1,224 +1,234 @@
 import { type Box, type LineLike, type Rect, type Shape } from '@expofp/geometry';
-import { type LayoutHandlers, type PointerHandlers } from './events';
-/** A color as a css string or a packed numeric value. */
+import { type LayoutHandlers, type LayoutView, type PointerHandlers } from './events';
+/** A color as a CSS string or a packed number. */
 export type ColorInput = string | number;
 /**
- * Any image-like source that the renderer can upload as a texture.
- *
- * A `Blob` is how anything fetched over the network arrives. It is a handle to an immutable byte
- * store that the browser reference-counts. `postMessage` clones the handle, not the bytes. That is
- * what lets atlas packing move to a worker. The renderer decodes the `Blob` itself, off the main
- * thread wherever the environment allows it.
- *
- * `HTMLImageElement` is deliberately absent. Decoding one costs the main thread more than the
- * packing it feeds: at a thousand logos on a throttled CPU, it stalled the page for two seconds.
- * Leaving the member in the union would keep that slow path reachable. Pass a `Blob` instead.
- *
- * There is no `string` member either. The caller keeps all networking, so the renderer never
- * learns about URLs, retries, or CORS.
+ * An image the renderer can upload as a texture. Pass fetched images as a `Blob`: the renderer
+ * decodes it off the main thread. `HTMLImageElement` and URL strings are not accepted.
  */
 export type ImageSource = HTMLCanvasElement | ImageBitmap | OffscreenCanvas | Blob;
-/** Scene definition */
+/** Scene definition. */
 export interface SceneDef {
-    /** Root layer of the scene tree */
+    /** The root layer of the scene tree. */
     rootLayer: LayerDef;
-    /** Background color in css format */
+    /** The background color. */
     background?: ColorInput;
-    /** SVG viewbox */
+    /** The SVG viewbox. */
     viewbox: Box;
     /**
-     * Static transform matrix: plan → the host's world, in place of the viewbox fit and in the host's
-     * own coordinates. Assumed to share plan space's handedness — see `HANDEDNESS_FLIP` in Space.ts, which the
-     * renderer adds on top to reach three's.
+     * A plan-to-world matrix that replaces the viewbox fit, in the host's coordinates. It must keep
+     * plan space's handedness.
      */
     staticTransform?: number[];
 }
-/** Shared properties for all renderable defs */
+/** Fields every renderable def shares. */
 export interface SharedDef extends LayoutHandlers {
-    /** Whether the def is hidden */
+    /** Whether the def is hidden. */
     hidden?: boolean;
     /**
-     * How strongly the def is dimmed — desaturated toward gray and darkened — from `0` (undimmed) to
-     * `1` (fully dimmed), interpolating in between.
-     *
-     * `undefined` inherits from the nearest ancestor that sets one, and only `undefined` inherits: a
-     * def's own `0` un-dims it inside a dimmed layer, and its own `1` dims it inside an undimmed one.
-     * A layer and a single def carry the same field with the same meaning, so dimming a whole floor
-     * and un-dimming one booth on it are the same operation at two levels. The root defaults to `0`.
-     *
-     * Values outside `[0, 1]` are clamped. Being a number rather than a flag is what lets a dim be
-     * animated — easing a layer's value from `0` to `1` costs one uniform per layer per frame,
-     * whatever the layer holds.
+     * How much the def is dimmed, from `0` (none) to `1` (full). `undefined` inherits from the
+     * nearest ancestor, so a def can set `0` to stay undimmed inside a dimmed layer. Animate it
+     * freely: a change costs one uniform write per layer.
      */
     dim?: number;
 }
 /** Any def that can be rendered into a scene. */
 export type RenderableDef = LayerDef | ShapeDef | ImageDef | TextDef | LineDef | ModelDef;
-/**
- * An array of a single {@link RenderableDef} kind (never a mixed union). The conditional
- * distributes over {@link RenderableDef}, so even the default is a union of single-kind arrays —
- * a mixed array is unrepresentable, which is what lets a first-element guard speak for the whole
- * collection. `Readonly<RenderableDefCollection<T>>` distributes the same way, into readonly
- * single-kind arrays.
- */
+/** An array of one {@link RenderableDef} kind. Mixed arrays do not type-check. */
 export type RenderableDefCollection<T = RenderableDef> = T extends RenderableDef ? T[] : never;
 /**
- * Layer definition.
- *
- * A layer is also where interaction lives: the handlers it inherits from {@link PointerHandlers} are
- * what make its subtree pickable, and each event names the def it hit. Layout is the other way round
- * — a layer carries its own {@link LayoutHandlers} through {@link SharedDef}, like any other def, and
- * that is how a layer whose contents depend on the camera re-derives them.
+ * Layer definition. Its {@link PointerHandlers} make its subtree pickable, and its
+ * {@link LayoutHandlers} run like any other def's.
  */
 export interface LayerDef<T extends RenderableDef = RenderableDef> extends SharedDef, PointerHandlers<T> {
-    /** Layer's name */
+    /** The layer's name. */
     readonly name: string;
-    /** Collection of layer's children. Mixing different types of children is not supported. */
+    /** The layer's children, all of one kind. */
     children: RenderableDefCollection<T>;
     /**
-     * Draws this layer and its subtree above 3D content. Depth testing goes off, and the layer is
-     * ordered by the overlay tier rather than by the plan tier.
+     * Draws the subtree above 3D content, with depth testing off. For flat content only: solid
+     * shapes and models ignore it. Descendants cannot opt out.
+     */
+    overlay?: boolean;
+    /**
+     * Placement defs compete only with defs in layers that share this key. Without it, the layer
+     * competes only with itself. Prefix the key with its owner.
+     */
+    collisionGroup?: string;
+    /**
+     * Turns collisions in this layer's collision scope into clusters. Both colliding defs are hidden
+     * through their own `onPlace`, and the cluster is reported to {@link ClusterOptions.onCluster}.
+     */
+    clustering?: ClusterOptions;
+}
+/** Clustering options of a layer. */
+export interface ClusterOptions {
+    /**
+     * The size of the marker you draw for a cluster. Any def or cluster that this marker would
+     * cover joins the cluster. Without it, the marker takes the size of the cluster's first member.
+     * When several clustering layers share a scope, the first layer's marker is used.
+     */
+    marker?: ClusterMarker;
+    /**
+     * Receives the full current set of clusters whenever it changes. A layer that loses all its
+     * clusters receives an empty array once.
      *
-     * A layer property, and a forced one. Depth mode is per material and render order is per group, so
-     * no implementation can vary either per instance. A def-level override could not be honored even
-     * if a caller wrote one.
+     * Changes are held while the plan moves on screen and are reported once it has stood still for a
+     * moment. A registration, an unregistration or a def whose bounds you update is reported at once.
+     * `onPlace` calls arrive first, in the same synchronous call.
      *
-     * **This is for planar content.** A volume that stops depth testing loses its own self occlusion,
-     * because its far faces then paint over its near ones in pack order. So a solid shape batch and a
-     * model batch ignore this flag. A solid batch also warns once that it did.
+     * Return the defs that changed. Never call `update()` here. Keep the options object stable: a
+     * new object is not noticed while the set stays the same.
+     * @param clusters - A new array on each call, in placement order.
+     * @param view - The current camera view.
+     * @returns The defs that changed, or nothing.
+     */
+    onCluster(this: void, clusters: readonly Cluster[], view: LayoutView): readonly RenderableDef[] | void;
+}
+/** The screen box of a cluster's marker. */
+export interface ClusterMarker {
+    /** The width in CSS pixels. */
+    width: number;
+    /** The height in CSS pixels. */
+    height: number;
+    /** The point that stands on the cluster's anchor, as in {@link ImageDef.origin}. */
+    origin?: [number, number];
+}
+/** One cluster of colliding defs. */
+export interface Cluster {
+    /** How many units it holds, at least two. A `placement.group` counts as one unit. */
+    readonly unitCount: number;
+    /** The mean x of the units' anchors, in plan units. */
+    readonly x: number;
+    /** The mean y of the units' anchors, in plan units. */
+    readonly y: number;
+    /** The greatest elevation of its members, in plan units. */
+    readonly elevation: number;
+}
+/**
+ * How a def competes for room on screen.
+ *
+ * - `never` (default): it is placed only where nothing placed before covers it, and then it
+ *   blocks the defs after it.
+ * - `always`: it is always placed, blocks nothing and never clusters. In a group, it takes the
+ *   group's verdict.
+ */
+export type OverlapMode = 'never' | 'always';
+/** Placement options of a screen-space def. */
+export interface PlacementOptions {
+    /**
+     * Receives the placement verdict: on the first pass after the def registers, then each time the
+     * verdict changes. Changes are reported when the camera stops, as for
+     * {@link ClusterOptions.onCluster}.
      *
-     * **A descendant cannot opt back out**: three propagates a group's render order to its whole
-     * subtree, so a descendant left in the plan tier would invert the nesting.
+     * Return the defs that changed. Never call `update()` here.
+     * @param placed - Whether the def got room on screen.
+     * @param view - The current camera view.
+     * @returns The defs that changed, or nothing.
      */
-    overlay?: boolean;
+    onPlace(this: void, placed: boolean, view: LayoutView): readonly RenderableDef[] | void;
+    /**
+     * Defs that share this key compete and cluster as one unit, with the union of their boxes. All
+     * members get the same verdict. The first member in order sets the unit's priority. Keys apply
+     * per collision scope. Prefix the key with its owner, and unregister old defs before you reuse
+     * their key.
+     */
+    group?: string;
+    /** CSS pixels added around the tested box: one value, or `[horizontal, vertical]`. */
+    padding?: number | [number, number];
+    /** How the def competes. Defaults to `never`. */
+    overlap?: OverlapMode;
+}
+/** Fields of the def kinds that can face the camera: {@link ImageDef} and {@link TextDef}. */
+export interface ScreenSpaceDef extends SharedDef {
+    /**
+     * Faces the def toward the camera. It pivots about `bounds.center` at `bounds.elevation`, sized
+     * by `bounds.size` in plan units. `bounds.rotation` spins it in the screen plane. Use an
+     * `onScale` rule to keep a constant pixel size.
+     */
+    screenSpace?: boolean;
+    /**
+     * Enters the def into the placement pass, which hides it where a def earlier in order already
+     * covers the screen. Works only when {@link screenSpace} is true.
+     */
+    placement?: PlacementOptions;
 }
 /** Shape definition. */
 export interface ShapeDef extends SharedDef {
     /**
-     * Shape to render. To change it, **replace** this with a new `Shape` and call `update(def)`: the
-     * new object re-claims the instance against fresh geometry, so even the shape *type* may change
-     * (rect ↔ polygon). Mutating the existing shape in place is more limited — a rect's or box's
-     * transform (center, size, rotation) is re-read every update, but a polygon's vertices and indices
-     * are cached by shape identity and will not rebuild in place.
+     * The shape to render. To change it, assign a new `Shape` and call `update(def)`. A polygon
+     * changed in place does not rebuild.
      */
     shape: Shape;
-    /** Shape's color in css format */
+    /** The shape's color. */
     color: ColorInput;
 }
-/** Image definition */
-export interface ImageDef extends SharedDef {
-    /**
-     * Image source. Write-once — a def's pixels are fixed for its lifetime: the atlas packs and
-     * uploads them at claim time and never re-reads the source, so a new image is a new def, not a
-     * reassignment. `readonly` makes that the type's guarantee (see {@link SceneDef.memoryLimit},
-     * which relies on a pack's byte totals staying stable until a repack).
-     */
+/** Image definition. */
+export interface ImageDef extends ScreenSpaceDef {
+    /** The image source. Fixed for the def's life: use a new def for a new image. */
     readonly source: ImageSource;
-    /** Image's bounds */
+    /** The image's bounds. */
     bounds: Rect;
     /**
-     * Image's anchor point. Defines the point on the image that is used as an origin point for transformations.
-     * [0, 0] is the top-left corner, [0.5, 0.5] is the center (default), [1, 1] is the bottom-right corner.
+     * The point of the image that `bounds.center` names. `[0, 0]` is the top-left corner,
+     * `[0.5, 0.5]` the center (default), `[1, 1]` the bottom-right corner.
      */
     origin?: [number, number];
-    /**
-     * Faces the camera, pivoting about `bounds.center` at `bounds.elevation`, at the size `bounds.size`
-     * gives in **plan units**. That is the same meaning `bounds.size` has for a flat def. A caller that
-     * wants a constant on-screen size keeps doing what markers do today, which is an `onScale` rule
-     * that rebuilds the bounds from the pixel size.
-     *
-     * `bounds.rotation` keeps its meaning, which is a spin about the content plane's normal. For a
-     * screen-space def that plane is the screen, so there is no separate spin field. An `onRoll` rule
-     * still runs, so keep this off where the rotation carries a plan bearing. Such a def would point
-     * at one screen direction however the plan is turned.
-     *
-     * Changing this at runtime is supported. The def moves between the layer's flat mesh and its
-     * camera-facing mesh, which never touches the atlas packing.
-     */
-    screenSpace?: boolean;
+    /** How opaque the image is, from `0` to `1`. Defaults to `1`. It blends as alpha does. */
+    opacity?: number;
 }
-/** Text definition */
-export interface TextDef extends SharedDef {
-    /**
-     * Array of text lines, drawn as a block stacked inside {@link bounds}.
-     *
-     * Updatable in both directions: a line's own fields are re-read on every `update(def)`, and
-     * changing the array's *length* re-claims the def's batch members against the new count. (The
-     * imperative renderer allocated members once and so required this to be fixed; React reconciles
-     * it instead.) A line whose `fontSize` is `0` is not drawn.
-     */
+/** Text definition. */
+export interface TextDef extends ScreenSpaceDef {
+    /** The text lines, stacked inside {@link bounds}. A line with `fontSize` `0` is not drawn. */
     lines: TextLineDef[];
-    /** Text's bounds */
+    /** The text's bounds. */
     bounds: Rect;
-    /** Text's padding [horizontal, vertical] */
+    /** The text's padding, `[horizontal, vertical]`. */
     padding: [number, number];
-    /** {@link TextAlignment} object describing text's alignment */
+    /** How the text is aligned. */
     alignment: TextAlignment;
-    /**
-     * As `ImageDef.screenSpace`. The block faces the camera and keeps its plan anchor and its
-     * plan-unit font sizes. The whole block pivots about `bounds.center`, on one anchor shared by
-     * every line, which is what keeps a stack from splaying under tilt.
-     */
-    screenSpace?: boolean;
 }
-/** Single text line definition */
+/** One line of a text def. */
 export interface TextLineDef {
-    /** Line's text */
+    /** The line's text. */
     text: string;
-    /** Line's color in css format */
+    /** The line's color. */
     color: ColorInput;
-    /** Line's font URL. Not updatable. Supported formats: .ttf, .otf, .woff (.woff2 is not supported). */
+    /** The font URL. Not updatable. Supports .ttf, .otf and .woff, not .woff2. */
     fontUrl: string;
-    /**
-     * Line's font size: its em height in plan units, the same units as the def's `bounds` and
-     * `padding`.
-     *
-     * Nothing here converts from pixels. A plan sizing a line to hold an on-screen size does that
-     * itself, against the pixel size the renderer publishes — as it does for every other
-     * pixel-authored thing it draws. `0` means the line is not drawn.
-     */
+    /** The em height in plan units. `0` hides the line. */
     fontSize: number;
-    /** Line's stroke color & width, the width in the same units as {@link fontSize}. Optional. */
+    /** The stroke color, and its width in the same units as {@link fontSize}. */
     stroke?: {
         color: ColorInput;
         width: number;
     };
 }
-/** Text alignment */
+/** Text alignment. */
 export interface TextAlignment {
-    /** Horizontal alignment */
+    /** The horizontal alignment. */
     horizontal: 'left' | 'center' | 'right';
-    /** Vertical alignment */
+    /** The vertical alignment. */
     vertical: 'top' | 'center' | 'bottom';
-    /** Text alignment within the line. Optional. */
+    /** The alignment of text inside a line. */
     text?: 'left' | 'center' | 'right';
 }
-/** Line definition */
+/** Line definition. */
 export interface LineDef extends SharedDef {
-    /**
-     * The segment's endpoints, with an optional `elevation` placing it on its layer's plane.
-     *
-     * Updatable: both ends are re-read on every `update(def)` and written only when they moved,
-     * so a line can be animated in place rather than replaced. A `LineLike` exposes readonly coordinates,
-     * so an update means replacing this with a new one — or moving the `Line` behind it,
-     * whose own setters do the same job.
-     */
+    /** The endpoints, with an optional elevation. Assign a new value and call `update(def)`. */
     points: LineLike;
-    /** Line's color in css format */
+    /** The line's color. */
     color: ColorInput;
-    /**
-     * Line's width in screen-space units (pixels), so it holds its thickness as the plan zooms.
-     * `0` draws nothing.
-     */
+    /** The width in screen pixels, constant at every zoom. `0` draws nothing. */
     width: number;
 }
-/** External 3D model definition */
+/** External 3D model definition. */
 export interface ModelDef extends SharedDef {
-    /** Model's URL. Not updatable. */
+    /** The model URL. Not updatable. */
     url: string;
-    /** Model's bounds */
+    /** The model's bounds. */
     bounds: Rect;
-    /** Model's opacity. Optional. */
+    /** The model's opacity, from `0` to `1`. */
     opacity?: number;
 }
 //# sourceMappingURL=defs.d.ts.map

package/dist/types/events.d.ts

@@ -119,8 +119,12 @@ export type RollHandler = NonNullable<LayoutHandlers['onRoll']>;
  */
 export interface LayoutView {
     /**
-     * How much of the plan one device pixel spans, in plan units — the factor anything sized in
+     * How much of the plan one CSS pixel spans, in plan units — the factor anything sized in
      * pixels is laid out against, and the quantity the imperative renderer published as `ptScale`.
+     *
+     * CSS pixels, so a size authored in them comes out the same at every screen density. The device
+     * ratio never reaches a rule because a rule never needs it: the ratio sets how crisp a def is
+     * drawn, not how big.
      */
     readonly pixelSize: number;
     /**

package/dist/types/guards.d.ts

@@ -5,6 +5,13 @@ export declare function isTextDef(def: RenderableDef): def is TextDef;
 export declare function isLineDef(def: RenderableDef): def is LineDef;
 export declare function isModelDef(def: RenderableDef): def is ModelDef;
 export declare function isLayerDef(def: RenderableDef): def is LayerDef;
+/**
+ * Whether a def takes part in the placement pass: it declares placement options, and it faces the
+ * camera. A flat def carrying options is not a target, which is what the pass warns about.
+ * @param def - The def to test.
+ * @returns Whether the pass tests it.
+ */
+export declare function isPlacementTarget(def: RenderableDef): def is ImageDef | TextDef;
 export declare function isLayerDefs(defs: Readonly<RenderableDefCollection>): defs is readonly LayerDef[];
 export declare function isShapeDefs(defs: Readonly<RenderableDefCollection>): defs is readonly ShapeDef[];
 export declare function isImageDefs(defs: Readonly<RenderableDefCollection>): defs is readonly ImageDef[];

package/dist/types/guards.js

@@ -16,6 +16,16 @@ export function isModelDef(def) {
 export function isLayerDef(def) {
     return def.children !== undefined;
 }
+/**
+ * Whether a def takes part in the placement pass: it declares placement options, and it faces the
+ * camera. A flat def carrying options is not a target, which is what the pass warns about.
+ * @param def - The def to test.
+ * @returns Whether the pass tests it.
+ */
+export function isPlacementTarget(def) {
+    const target = def;
+    return target.placement !== undefined && target.screenSpace === true;
+}
 // The array guards below take the collection type, not `readonly RenderableDef[]`: the collection
 // is a union of single-kind arrays, so a first-element check is sound for the whole array. A plain
 // `RenderableDef[]` parameter would admit mixed arrays the check cannot speak for. The `Readonly`

package/dist/utils/math.d.ts

@@ -1,4 +1,4 @@
-import { type Matrix4 } from 'three';
+import { type Camera, type Matrix4 } from 'three';
 /**
  * Holds a value inside an inclusive range.
  *
@@ -32,4 +32,21 @@ export declare function euclideanModulo(value: number, modulus: number): number;
  * @returns The transformed axis's length.
  */
 export declare function axisLength(matrix: Matrix4, axis: number): number;
+/**
+ * How far the camera's own axis travels before it meets a batch's own plane, in world units.
+ *
+ * That is the depth a plan-unit size is exact at, so it is what the shader cancels the perspective
+ * divide against. It has to agree with the depth `measurePixelSize` in `space/layout-measure.ts`
+ * works at, because a caller's `onScale` rule sizes a def in plan units from the pixel size that
+ * function reports. Without controls mounted that function reads this same crossing point. With
+ * them it reads their distance to their target, and the two agree while the target sits on the
+ * plan, which is what orbiting a floor plan keeps true.
+ *
+ * The plane is the batch's own, taken from its world matrix, because a sprite batch draws at plan
+ * `z = 0` and whatever places the plan places the mesh with it.
+ * @param camera - The camera this draw uses.
+ * @param planToWorld - The batch's world matrix.
+ * @returns The distance in world units, or `0` for a camera that never meets the plane ahead of it.
+ */
+export declare function aimDepth(camera: Camera, planToWorld: Matrix4): number;
 //# sourceMappingURL=math.d.ts.map

package/dist/utils/math.js

@@ -1,3 +1,4 @@
+import { Vector3 } from 'three';
 /**
  * Holds a value inside an inclusive range.
  *
@@ -39,3 +40,37 @@ export function axisLength(matrix, axis) {
     const at = axis * 4;
     return Math.hypot(elements[at], elements[at + 1], elements[at + 2]);
 }
+/**
+ * How far the camera's own axis travels before it meets a batch's own plane, in world units.
+ *
+ * That is the depth a plan-unit size is exact at, so it is what the shader cancels the perspective
+ * divide against. It has to agree with the depth `measurePixelSize` in `space/layout-measure.ts`
+ * works at, because a caller's `onScale` rule sizes a def in plan units from the pixel size that
+ * function reports. Without controls mounted that function reads this same crossing point. With
+ * them it reads their distance to their target, and the two agree while the target sits on the
+ * plan, which is what orbiting a floor plan keeps true.
+ *
+ * The plane is the batch's own, taken from its world matrix, because a sprite batch draws at plan
+ * `z = 0` and whatever places the plan places the mesh with it.
+ * @param camera - The camera this draw uses.
+ * @param planToWorld - The batch's world matrix.
+ * @returns The distance in world units, or `0` for a camera that never meets the plane ahead of it.
+ */
+export function aimDepth(camera, planToWorld) {
+    // A camera looks down its own negative z.
+    const direction = _direction.setFromMatrixColumn(camera.matrixWorld, 2).normalize().negate();
+    const normal = _normal.setFromMatrixColumn(planToWorld, 2).normalize();
+    const facing = direction.dot(normal);
+    // The camera looks along the plane and never meets it.
+    if (facing === 0)
+        return 0;
+    const eye = _eye.setFromMatrixPosition(camera.matrixWorld);
+    const depth = _origin.setFromMatrixPosition(planToWorld).sub(eye).dot(normal) / facing;
+    // Behind the camera is no measurement, so the shader keeps its plan-unit sizing instead.
+    return depth > 0 ? depth : 0;
+}
+// Scratch for aimDepth, filled and consumed within one call.
+const _direction = new Vector3();
+const _normal = new Vector3();
+const _eye = new Vector3();
+const _origin = new Vector3();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@expofp/renderer",
-  "version": "3.44.8",
+  "version": "3.45.1",
   "repository": {
     "type": "git",
     "url": "https://github.com/expofp/efp-app.git",
@@ -42,7 +42,7 @@
     "troika-three-text": "^0.52.5",
     "tslib": "^2.3.0",
     "webgl-memory": "^1.1.3",
-    "@expofp/geometry": "3.44.8"
+    "@expofp/geometry": "3.45.1"
   },
   "devDependencies": {
     "@react-three/test-renderer": "^9.1.0",