@thatopen/components 3.4.8 → 3.4.9

package/dist/index.d.ts

@@ -1,6 +1,6 @@
-import CameraControls from 'camera-controls';
 import { DataMap as DataMap_2 } from '@thatopen/fragments';
 import { DataSet as DataSet_2 } from '@thatopen/fragments';
+import { default as default_2 } from 'camera-controls';
 import * as FRAGS from '@thatopen/fragments';
 import * as THREE from 'three';
 import { TransformControls } from 'three/examples/jsm/controls/TransformControls.js';
@@ -345,7 +345,7 @@ export declare abstract class BaseCamera extends BaseWorldItem {
      * Optional CameraControls instance for controlling the camera.
      * This property is only available if the camera is controllable.
      */
-    abstract controls?: CameraControls;
+    abstract controls?: default_2;
     /**
      * Checks whether the instance is {@link CameraControllable}.
      *
@@ -1170,7 +1170,7 @@ export declare interface CameraControllable {
      * An instance of CameraControls that provides camera control functionalities.
      * This instance is used to manipulate the camera.
      */
-    controls: CameraControls;
+    controls: default_2;
 }
 
 /**
@@ -1464,6 +1464,8 @@ export declare class Clipper extends Component implements Createable, Disposable
      * A list of all the clipping planes created by this component.
      */
     readonly list: FRAGS.DataMap<string, SimplePlane>;
+    /** Planes between the list's before-delete and item-deleted events. */
+    private _deleting;
     /** {@link Configurable.config} */
     config: ClipperConfigManager;
     protected _defaultConfig: ClipperConfig;
@@ -2785,10 +2787,23 @@ export declare class EdgeProjector extends Component implements Disposable_2 {
      */
     readonly generator: any;
     /**
-     * Resolution of the visibility culler in pixels per meter.
-     * Higher values = more accurate occlusion but slower culling.
+     * Size of one visibility-culling pixel, in meters (despite the name, the
+     * value is meters per pixel). LOWER values mean finer culling — fewer small
+     * meshes are discarded — at the cost of a larger render target, more tiles
+     * and more readback time. Higher values are coarser and faster. Default is
+     * 0.05 (one culling pixel covers 5 cm).
+     *
+     * Note: meshes without a single visible pixel are removed from BOTH the
+     * visible and the hidden line sets, so this value bounds how much small
+     * geometry a projection loses.
      */
     cullerPixelsPerMeter: number;
+    /**
+     * Alias of {@link EdgeProjector.cullerPixelsPerMeter} under a name that
+     * matches what the value actually is. Reads and writes the same setting.
+     */
+    get cullerMetersPerPixel(): number;
+    set cullerMetersPerPixel(value: number);
     /**
      * The direction the projector looks along. Meshes are projected onto the plane
      * perpendicular to this direction. Default is top-down (plan view).
@@ -2821,10 +2836,14 @@ export declare class EdgeProjector extends Component implements Disposable_2 {
      * @param world - The world whose renderer will be used for visibility culling.
      * @param config - Optional configuration.
      * @param config.onProgress - Optional progress callback receiving (message, progress?, collector?).
+     * @param config.signal - Optional AbortSignal. The generator pumps itself on
+     * requestAnimationFrame and checks it on every frame, so aborting rejects the
+     * returned promise and stops the pump instead of draining the whole task.
      * @returns Visible/hidden geometries with a `group` vertex attribute, and a groups mapping.
      */
     get(modelIdMap: ModelIdMap, world: World, config?: {
         onProgress?: (message: string, progress?: number) => void;
+        signal?: AbortSignal;
     }): Promise<EdgeProjectionResult>;
     dispose(): void;
 }
@@ -2922,29 +2941,35 @@ export declare interface ExternalDocumentReference extends DocumentReference {
 
 /**
  * GPU-readback picker that identifies what's under a screen position
- * without going through the worker raycast. Two granularities, same
- * render pass:
+ * without going through the worker raycast.
  *
  * - {@link getModelAt} returns the model id under the cursor.
  * - {@link getItemAt} returns the item itself (`modelId` + `localId`).
+ * - {@link getPointAt} / {@link getNormalAt} return the surface point and normal.
+ * - {@link getFullPick} returns all of the above from the same pick.
  *
- * The fragments tile geometry already carries a per-vertex `id`
- * attribute (the internal item id). We render the BIM scene to an
- * offscreen target with a shader that packs `(modelByte, itemId)` into
- * RGBA, then `readPixels` at the cursor and decode. One render plus
- * one 4-byte readback per call. No worker round-trip for the model
- * lookup; the first time we resolve a given `itemId` to a `localId`
- * we ask the worker, and afterwards that lookup is cached.
+ * Every query goes through {@link renderPick}: one render of the BIM scene
+ * into a 1×1 multiple-render-target, through a camera whose frustum covers
+ * only the pixel under the cursor. The pick shader writes the item id,
+ * depth and normal of that pixel into one attachment each, so they always
+ * describe the same fragment; each query reads back only the attachments
+ * it needs.
  *
- * Encoding (one pixel):
+ * What can be picked is what is drawn. An item that fragments currently draws
+ * at a reduced LOD — a line mesh carrying no `id` attribute — is not pickable,
+ * and the pick resolves to whatever is behind it; the worker raycast tests the
+ * authored geometry instead, so the two can disagree on small or distant
+ * items, see {@link collectPickables}.
+ *
+ * Item id encoding (one pixel). The id is written as `itemId + 1` so that
+ * an unwritten pixel (all zeroes) decodes as "no item" rather than item 0:
  *   R = modelByte (1..254, 0 = void / unwritten)
- *   G = (itemId >> 16) & 0xff
- *   B = (itemId >> 8)  & 0xff
- *   A = (itemId)       & 0xff
+ *   G = ((itemId + 1) >> 16) & 0xff
+ *   B = ((itemId + 1) >> 8)  & 0xff
+ *   A = (itemId + 1)         & 0xff
  *
- * `modelByte` is assigned per-pick from a `byteToModelId` map; the
- * picker re-allocates bytes each call so the assignment is stable for
- * the duration of the pick but doesn't grow over the session.
+ * `modelByte` is assigned per-pick, so the assignment is stable for the
+ * duration of the pick but doesn't grow over the session.
  */
 export declare class FastModelPicker implements Disposable_2 {
     /** {@link Component.enabled} */
@@ -2958,10 +2983,10 @@ export declare class FastModelPicker implements Disposable_2 {
     /** World this picker renders against. */
     world: World;
     /**
-     * When `true`, mirrors the id render to a debug canvas pinned in the
-     * top-right corner. Each model shows up as a near-uniform red band
-     * (the model byte) modulated by varying greens / blues from the
-     * per-item id encoding.
+     * When `true`, mirrors the id output of the whole viewport to a debug
+     * canvas pinned in the top-right corner. Each model shows up as a
+     * near-uniform red band (the model byte) modulated by varying greens /
+     * blues from the per-item id encoding.
      */
     debugMode: boolean;
     /**
@@ -2969,68 +2994,50 @@ export declare class FastModelPicker implements Disposable_2 {
      * by the 8-bit `modelByte`. In practice we never approach this.
      */
     static readonly MAX_MODELS = 254;
-    private _renderTarget?;
-    private _renderTargetSize;
+    /** The 1×1 target every pick renders into. */
+    private _pickTarget?;
+    /** Viewport-sized target for the debug overlay, created on demand. */
+    private _debugTarget?;
+    private _pickBuffers;
     private _debugCanvas?;
     private _debugContainer?;
     /**
-     * Single shared shader for the id pass. The same program runs across
-     * every model; we flip the `modelByte` uniform between per-model
-     * render passes inside one pick to disambiguate which model owns a
-     * pixel.
-     */
-    private _idMaterial;
-    /**
-     * Depth-encoding shader used by {@link getPointAt}. Written via
-     * `scene.overrideMaterial` for one render of the BIM scene, packs
-     * `gl_FragCoord.z` into the four bytes of the color attachment using
-     * three's `packing` chunk. The packed value is robust to round-trip
-     * through an `UNSIGNED_BYTE` target.
-     */
-    private _depthMaterial;
-    /**
-     * World-space normal-encoding shader used by {@link getNormalAt}.
-     * Writes `(normal * 0.5 + 0.5)` into RGB, alpha = 1. Decode side maps
-     * `(rgb * 2 - 1)` and renormalizes. Naive packing wastes alpha and
-     * gives ~1° precision per axis, which is plenty for surface
-     * alignment, orbit-around-clicked-point, and snapping. Octahedral
-     * packing would buy us another bit per axis but isn't worth the
-     * complexity until a consumer actually needs sub-degree accuracy.
-     */
-    private _normalMaterial;
-    /**
-     * Cached original materials for the swap-render-restore pass.
-     * Populated in {@link applyIdMaterial}, drained in
-     * {@link restoreOriginalMaterials} after the render.
-     */
-    private _originalMaterials;
-    /**
-     * LOD line meshes don't carry the per-vertex `id` attribute and would
-     * write whatever color their normal shader produces into the id
-     * buffer, faking hits. Hidden for the duration of the id render and
-     * restored after.
-     */
-    private _hiddenLods;
-    /**
-     * The meshes each model owns, i.e. excluding those belonging to a
-     * model nested inside it. A delta model's object is parented under
-     * its parent model's object (see the fragments EditHelper), while
-     * both are listed as separate models, so subtree membership alone
-     * does not determine ownership.
-     *
-     * Populated in {@link applyIdMaterial}, consumed by
-     * {@link renderPickPass} to isolate one model per render without
-     * relying on root visibility. A nested model can't be isolated by
-     * its root, since hiding the parent's root culls the child too.
-     */
-    private _ownMeshes;
+     * Writes every {@link PickOutput} on each draw. Set as the scene's
+     * `overrideMaterial` for the pick render, so fragments' materials are
+     * never swapped.
+     */
+    private _pickMaterial;
+    /** Snapshot of the world camera with a narrowed projection. */
+    private _pickCamera;
+    private _pickMatrix;
+    private _pickNdc;
+    private _viewportSize;
+    private _clearColor;
+    /** The pick camera's world position, for measuring distance to a hit. */
+    private _cameraPosition;
+    /**
+     * Per-pick state filled by {@link collectPickables}. `_meshBytes` is read
+     * by the pick material while drawing; `_byteToModel` outlives the render
+     * so the caller can decode the id output.
+     */
+    private _meshBytes;
+    private _byteToModel;
+    private _modelBytes;
+    private _modelRoots;
+    /** Undo log for {@link collectPickables}, drained by {@link restorePickables}. */
+    private _hidden;
+    private _forcedOverrides;
+    private _walkNodes;
+    private _walkOwners;
+    /** The pick material's `clippingPlanes`, refilled by {@link collectLocalPlanes}. */
+    private _localPlanes;
     constructor(components: Components, world: World);
     /**
      * Returns the model id under the given screen position, or `null` if
      * the cursor is over empty space.
      *
      * Cheaper than {@link getItemAt} because we don't resolve the
-     * `localId`; we just read the model byte from the same render.
+     * `localId`; we just read the model byte.
      *
      * @param position - Normalized device coords. Defaults to the
      *   picker's last known mouse position.
@@ -3040,10 +3047,12 @@ export declare class FastModelPicker implements Disposable_2 {
      * Returns `{ modelId, localId }` for the item under the given screen
      * position, or `null` if the cursor is over empty space.
      *
-     * Pure main-thread resolution: fragments now stores the user-facing
-     * `localId` directly in each tile's per-vertex `id` attribute, so
-     * the encoded RGBA pixel decodes straight to the localId. No worker
-     * round-trip, no cache.
+     * The vertex `id` attribute encodes the internal **itemId** (the
+     * FlatBuffer `sample.item()` index, key for `boxes.sampleOf`) rather
+     * than the user-facing localId, which unblocks the snap path's O(1)
+     * sample lookup. The trade-off: resolving `localId` takes one worker
+     * round-trip. Internal consumers that only need itemId (e.g. snap) can
+     * read it from the result directly.
      *
      * @param position - Normalized device coords. Defaults to the
      *   picker's last known mouse position.
@@ -3057,16 +3066,9 @@ export declare class FastModelPicker implements Disposable_2 {
      * Returns the world-space point under the given screen position, or
      * `null` if the cursor is over empty space.
      *
-     * Renders the BIM scene with a depth-encoding override material that
-     * packs `gl_FragCoord.z` into the color buffer, reads four bytes at
-     * the cursor pixel, and unprojects through the camera matrices to a
-     * world point. One render pass, one 4-byte readback, no worker
-     * round-trip. Useful for things like "set camera orbit center to
-     * what the user just clicked on".
-     *
-     * Cheaper than {@link getItemAt} because we don't differentiate
-     * models — one render covers the whole BIM scene at once. We don't
-     * resolve any item id either.
+     * Reads the packed `gl_FragCoord.z` of the picked pixel and unprojects
+     * it through the pick camera. Useful for things like "set camera orbit
+     * center to what the user just clicked on".
      *
      * @param position - Normalized device coords. Defaults to the
      *   picker's last known mouse position.
@@ -3076,18 +3078,16 @@ export declare class FastModelPicker implements Disposable_2 {
      * Returns the world-space surface normal under the cursor, or `null`
      * if the cursor is over empty space.
      *
-     * Mirrors {@link getPointAt}'s structure: one `scene.overrideMaterial`
-     * render with the normal-encoding shader, one 4-byte readback,
-     * decode and renormalize.
+     * @param position - Normalized device coords. Defaults to the
+     *   picker's last known mouse position.
      */
     getNormalAt(position?: THREE.Vector2): Promise<THREE.Vector3 | null>;
     /**
      * One-shot pick that produces the full result shape consumers need:
-     * `{ modelId, localId, point, normal, distance }`. Routes through the
-     * three GPU passes (id, depth, normal) and composes the output. No
-     * worker round-trip.
+     * `{ modelId, localId, point, normal, distance }`, all from the same
+     * render.
      *
-     * Returns `null` if the cursor is over empty space, the id pass
+     * Returns `null` if the cursor is over empty space, the id output
      * decodes to the void sentinel, or the depth round-trip yields the
      * far plane.
      */
@@ -3106,142 +3106,126 @@ export declare class FastModelPicker implements Disposable_2 {
         distance: number;
     } | null>;
     /**
-     * Toggle the debug overlay. When enabled the picker mirrors its id
-     * render to a small canvas pinned in the top-right corner so you can
-     * see what the readback sees.
+     * Toggle the debug overlay. When enabled the picker mirrors the id
+     * output of the whole viewport to a small canvas pinned in the
+     * top-right corner so you can see what the picks see.
      */
     setDebugMode(enabled: boolean): void;
     /** {@link Disposable.dispose} */
     dispose(): void;
     /**
-     * Runs the id renders and returns the raw decoded
-     * `(modelId, itemId)` for the cursor pixel. Two render passes:
-     *
-     *   - Pass 1 (`_renderTarget`): writes the model byte into R via
-     *     the `_idMaterial`. Used solely to disambiguate which model
-     *     owns the picked pixel.
-     *   - Pass 2 (`_localIdRenderTarget`): writes the full 32-bit
-     *     localId across all four bytes via the same `_idMaterial`
-     *     with `mode = 1`.
-     *
-     * Two single-attachment targets instead of MRT keeps the code
-     * portable and the diff small. Both passes use the same scene,
-     * camera and visibility toggling so depth tests resolve to the
-     * same front-most fragment per pixel.
-     *
-     * Both public entry points lean on this.
-     */
-    private runIdPass;
-    /**
-     * Walks every fragments model. For each shell mesh that carries the
-     * per-vertex `id` attribute, stashes the original material and swaps
-     * in the shared id-encoding shader. Hides LOD line meshes (which
-     * lack `id`) so they don't pollute the id buffer. Returns the
-     * temporary `byte → modelId` map the render pass uses to
-     * disambiguate models.
-     */
-    private applyIdMaterial;
-    /**
-     * The object roots of every loaded model.
-     */
-    private getModelRoots;
-    /**
-     * Like `Object3D.traverse`, but prunes the subtree of any nested model
-     * root, so each mesh is visited exactly once, by the model that owns
-     * it. A delta model's object hangs under its parent model's object
-     * while being a model in its own right; a plain `traverse` from the
-     * parent would walk into it.
-     */
-    private traverseOwn;
-    /**
-     * Renders the world scene to the id target one model at a time,
-     * flipping the `modelByte` uniform between renders. The depth buffer
-     * is shared across the per-model passes so the front-most item still
-     * wins each pixel regardless of which model it belongs to.
-     *
-     * Non-BIM meshes in the world scene (the user's own helpers, ground
-     * planes, hover proxies, anything else) are hidden for the duration
-     * of the render. Without this, their normal materials write whatever
-     * colour they happen to produce into the id target, which decodes as
-     * a bogus `(modelByte, itemId)` pair when the cursor lands on one.
-     */
-    /**
-     * Single id render. Iterates models in byte order, flipping the
-     * `modelByte` uniform between renders so each model's pixels carry
-     * its assigned byte in R while the lower 3 bytes of GBA carry
-     * `itemId + 1`. Depth buffer shared across the per-model passes so
-     * the front-most item still wins each pixel regardless of which
-     * model it belongs to.
-     */
-    private renderIdPass;
-    /**
-     * Renders the BIM scene model-by-model into `target` with `material`,
-     * scissor-clipped to a small box around the cursor. Iterates models
-     * in byte order so depth tests resolve to the same front-most
-     * fragment per pixel. Per-model loop sets `material.uniforms.modelByte`
-     * before each render so the picked pixel carries the model byte.
-     */
-    private renderPickPass;
-    /**
-     * Renders the picker's color target with the BIM tile shells using
-     * the given override-style material, swapped in **per-mesh** rather
-     * than via `scene.overrideMaterial`.
-     *
-     * Why per-mesh swap and not `scene.overrideMaterial`: fragments runs
-     * its own LOD/visibility logic on tile shells (`mesh.visible`
-     * toggled internally based on current LOD stage and frustum). At
-     * the moment we render, most tile shells are flagged invisible —
-     * `overrideMaterial` then renders nothing and we read back a
-     * cleared pixel. Per-mesh swap mirrors what {@link renderIdPass}
-     * does; we also force each shell visible for the duration of the
-     * render so fragments' culling decisions don't blank our output.
-     *
-     * Honours the renderer's clipping planes so picked depth/normal
-     * match what's actually rendered on screen.
-     */
-    private renderWithTileMaterial;
-    private renderDepthPass;
-    private renderNormalPass;
-    private restoreOriginalMaterials;
-    private readPixelAt;
-    /**
-     * Single id shader, single render pass. Reads:
-     *   - `id`: per-vertex `vec4` — the four bytes of `itemId + 1`
-     *     (big-endian) supplied as a non-normalised `Uint8Array`
-     *     attribute by fragments. Each component is 0–255 as a float.
-     *   - `modelByte` uniform — the byte assigned to the currently-
-     *     rendered model.
-     *
-     * Output packs `(modelByte, idMid, idLo1, idLo0)` into one RGBA8
-     * pixel: model byte in R, the lower three bytes of `itemId + 1` in
-     * GBA. Capping the encoded id at 24 bits is fine because `itemId`
-     * is the FlatBuffer item index — bounded by item count per model
-     * (16M is plenty for any practical BIM model). The high byte of
-     * the vertex attribute (`vId.x`) is therefore always 0 and we
-     * discard it; that frees R for the model byte. One render → one
-     * readback per pick (the previous two-target layout cost two
-     * sync-stalling readPixels calls).
-     */
-    private buildIdMaterial;
-    /**
-     * Builds the depth-encoding override material used by
-     * {@link renderDepthPass}. Includes three's `packing` chunk to reuse
-     * the standard `packDepthToRGBA` helper, which is robust to the
-     * round-trip through an `UNSIGNED_BYTE` color attachment (the chunk
-     * pre-multiplies by `256/255` so `depth = 1.0` decodes back exactly
-     * to `1.0`). Decode side mirrors this with the same scaling factors;
-     * see {@link unpackDepthFromRGBA} below.
-     */
-    private buildDepthMaterial;
-    /**
-     * World-space normal in RGB. Handles backfaces by flipping the
-     * encoded normal so consumers always get the surface they're looking
-     * at. Decode side: `(rgb * 2 - 1)` → renormalize.
-     */
-    private buildNormalMaterial;
-    private setupRenderTarget;
+     * Renders one pick and decodes the outputs named in `request` into values
+     * the caller owns. Synchronous by design: everything that depends on the
+     * picker's reused state is resolved here, so nothing an entry point does
+     * afterwards can race the next pick.
+     */
+    private pick;
+    /**
+     * Renders every {@link PickOutput} for the region around `ndc` in a single
+     * render, then reads the outputs named in `request` from the centre pixel of
+     * `target` into `out`.
+     *
+     * `target` needs one attachment per output. Its size is the size of the
+     * rendered region in viewport pixels: 1×1 for a pick, the whole viewport
+     * centred on the origin for the debug overlay.
+     *
+     * The scene is left exactly as found, even if rendering throws.
+     */
+    private renderPick;
+    /**
+     * Copies the world camera into the pick camera and narrows its projection
+     * to a `target`-sized region of the viewport centred on `ndc`, the
+     * classic pick matrix: `P' = M · P`.
+     *
+     * - Frustum culling then skips every mesh whose bounds miss that region,
+     *   so only meshes under the cursor are drawn at all.
+     * - `M` leaves the depth row alone, so depth decodes as usual.
+     * - The centre of a 1×1 target is exactly `ndc`: no NDC → pixel rounding,
+     *   no scissor, no device pixel ratio to account for.
+     * - The world camera is never modified, and custom projections work.
+     */
+    private snapshotCamera;
+    /**
+     * The planes the pick material clips by, so picks match what is on screen.
+     *
+     * - Global planes (`three.clippingPlanes`) are applied by three to every
+     *   material on its own. Listing them here too would clip by each twice.
+     * - Local planes (`isLocal`, see `Clipper.localClippingPlanes`) stay out of
+     *   that list and reach only the tile materials, so the pick material has
+     *   to carry them itself.
+     */
+    private collectLocalPlanes;
+    /**
+     * Walks the scene once and decides what the pick render draws:
+     *
+     * - Shells owned by a model, i.e. meshes carrying the per-vertex `id`
+     *   attribute, are drawn and tagged with their model's byte. Ownership
+     *   is the nearest model root above the mesh: a delta model's object is
+     *   parented under its parent model's object (see the fragments
+     *   EditHelper) but keeps its own byte.
+     * - Every other renderable is hidden:
+     *   - LOD line meshes, which fragments draws in place of small or distant
+     *     items, carry no `id`. Drawn, the missing attribute would read as
+     *     `(0, 0, 0, 1)` and write `itemId + 1 = 1`, i.e. a false hit on item 0,
+     *     while occluding the real shell behind it. Hidden, the item they stand
+     *     for simply isn't pickable, though the worker raycast still reports it.
+     *   - Non-BIM objects (helpers, grids, annotation lines, sprites) would
+     *     write their own colors into the pick outputs.
+     *
+     * Invisible subtrees are skipped: three won't draw them, and it leaves
+     * fragments' own tile visibility (stale LOD stages, hidden items) as is.
+     */
+    private collectPickables;
+    /**
+     * The byte to draw `node` with, or 0 if it isn't a pickable shell of
+     * `modelId`. Bytes are handed out on a model's first shell, so models with
+     * nothing on screen don't use one up.
+     */
+    private pickableByte;
+    /**
+     * Three skips `scene.overrideMaterial` for materials with
+     * `allowOverride === false`, which would draw a shell with its own shader
+     * into the pick outputs.
+     */
+    private allowOverride;
+    private restorePickables;
+    /**
+     * The pick shader. Writes one output per {@link PickOutput} attachment:
+     *
+     * - `id`: `(modelByte, idMid, idLo1, idLo0)`. The vertex `id` attribute
+     *   holds the four bytes of `itemId + 1` (big-endian, non-normalized
+     *   `Uint8Array`, so each component is 0–255 as a float). `itemId` is
+     *   bounded by the item count per model, so its high byte is always 0
+     *   and R is free for the model byte, set per draw from
+     *   {@link collectPickables}.
+     * - `depth`: `gl_FragCoord.z` packed into four bytes, inverse of
+     *   {@link unpackDepthFromRGBA}:
+     *     r = fract(v * 256^3)  (least significant)
+     *     g = fract(v * 256^2)
+     *     b = fract(v * 256)
+     *     a = v                 (most significant)
+     *   `r.yzw -= r.xyz / 256` shaves the residual from each higher component
+     *   so the encoded value is exact, and the final `* 256/255` upscale lands
+     *   `v = 1.0` at all-255 bytes rather than rolling over to 0. Packed by
+     *   hand: `ShaderMaterial` doesn't reliably resolve three's `packing`
+     *   chunk for custom shaders.
+     * - `normal`: world-space normal as `normal * 0.5 + 0.5` in RGB, alpha 1.
+     *   Flipped on backfaces so consumers get the surface they're looking at.
+     *   ~1° precision per axis, plenty for surface alignment, orbiting and
+     *   snapping.
+     *
+     * Every output is written on every draw: rasterizing one pixel, the only
+     * per-output cost worth saving is the readback, which
+     * {@link renderPick} skips for outputs it wasn't asked for. Per-request
+     * shader variants would each cost a program compile instead.
+     */
+    private buildPickMaterial;
     private setupDebugCanvas;
     private removeDebugCanvas;
+    /**
+     * Renders the pick for the whole viewport into {@link _debugTarget} and
+     * mirrors its id output to the debug canvas.
+     */
     private updateDebugCanvas;
 }
 
@@ -3367,7 +3351,7 @@ export declare class FirstPersonMode implements NavigationMode {
     readonly id = "FirstPerson";
     constructor(camera: OrthoPerspectiveCamera);
     /** {@link NavigationMode.set} */
-    set(active: boolean): void;
+    set(active: boolean, options?: NavigationModeOptions): void;
     private setupFirstPersonCamera;
 }
 
@@ -3791,6 +3775,16 @@ export declare class IDSProperty extends IDSFacet {
     constructor(components: Components, propertySet: IDSFacetParameter, baseName: IDSFacetParameter);
     serialize(type: "applicability" | "requirement"): string;
     getEntities(modelIds: RegExp[], collector: ModelIdMap): Promise<void>;
+    /**
+     * Appends the elements that inherit one of `matchedSets` from their type,
+     * as `test()` does through {@link getTypePsets} (issue #708), so a set that
+     * only lives on a type selects the type's instances (issue #798).
+     *
+     * An element's own set of the same name overrides the inherited value of
+     * any property it also defines: if it defines every matched property
+     * itself, whether it applies was already decided from that set above.
+     */
+    private appendTypeInstances;
     test(items: ModelIdMap, collector: ModelIdDataMap<IDSItemCheckResult>, config?: {
         skipIfFails: boolean;
     }): Promise<void>;
@@ -4641,11 +4635,26 @@ export declare interface NavigationMode {
      * @param active - whether to enable or disable this mode.
      * @param options - any additional data required to enable or disable it.
      * */
-    set: (active: boolean, options?: any) => void;
+    set: (active: boolean, options?: NavigationModeOptions) => void;
     /** Whether this navigation mode is active or not. */
     enabled: boolean;
 }
 
+/**
+ * Optional data passed to {@link NavigationMode.set} when enabling or
+ * disabling a navigation mode.
+ */
+export declare interface NavigationModeOptions {
+    /**
+     * If `true`, the mode must not readjust the camera controls target when
+     * it activates (i.e. it must skip any `moveTo` re-framing). Used by the
+     * {@link OrthoPerspectiveCamera} on world assignment, where the initial
+     * mode setup has already framed the camera and a second adjustment would
+     * move the target again.
+     */
+    preventTargetAdjustment?: boolean;
+}
+
 /**
  * The extensible list of supported navigation modes.
  */
@@ -4683,7 +4692,7 @@ export declare class OrbitMode implements NavigationMode {
     readonly id = "Orbit";
     constructor(camera: OrthoPerspectiveCamera);
     /** {@link NavigationMode.set} */
-    set(active: boolean): void;
+    set(active: boolean, options?: NavigationModeOptions): void;
     private activateOrbitControls;
 }
 
@@ -4719,6 +4728,13 @@ export declare class OrthoPerspectiveCamera extends SimpleCamera {
      * @throws {Error} Throws an error if the mode is not found or the camera is not initialized.
      */
     get mode(): NavigationMode;
+    /**
+     * Whether the camera has a {@link NavigationMode} set. Navigation modes
+     * are created when the camera is assigned to a world, so this is `false`
+     * before that assignment (when {@link OrthoPerspectiveCamera.mode} would
+     * throw). Useful to guard code that may run before initialization.
+     */
+    get hasMode(): boolean;
     constructor(components: Components);
     /** {@link Disposable.dispose} */
     dispose(): void;
@@ -4769,8 +4785,12 @@ export declare class PlanMode implements NavigationMode {
     private readonly defaultAzimuthSpeed;
     private readonly defaultPolarSpeed;
     constructor(camera: OrthoPerspectiveCamera);
-    /** {@link NavigationMode.set} */
-    set(active: boolean): void;
+    /**
+     * {@link NavigationMode.set}. This mode never adjusts the camera target,
+     * so {@link NavigationModeOptions.preventTargetAdjustment} is trivially
+     * honored: there is nothing to skip.
+     */
+    set(active: boolean, _options?: NavigationModeOptions): void;
 }
 
 /** Basic type to describe the progress of any kind of process. */
@@ -5033,6 +5053,27 @@ export declare interface SerializedQueryParameters {
     };
 }
 
+/**
+ * Move the orbit point to an anchored surface without letting the camera
+ * jump or the zoom decay.
+ *
+ * `CameraControls.setOrbitPoint` internally calls `dollyTo(distance)`, which
+ * clamps the orbit radius to `[minDistance, maxDistance]`. If the anchored
+ * surface sits closer than `minDistance`, that clamp would snap the camera
+ * backwards, so the anchor has to be placed with a near-zero `minDistance`.
+ *
+ * But `minDistance` is also what stops the zoom from decaying: with
+ * `dollyToCursor` + `infinityDolly` the wheel step is proportional to the
+ * orbit radius, and the constant-speed "infinity" push only kicks in once the
+ * radius reaches `minDistance`. Leaving `minDistance` near zero (as dynamic
+ * anchoring used to, globally) let the radius shrink toward zero on every
+ * zoom-in, so each notch moved exponentially less — the zoom felt like it was
+ * grinding to a halt until a press re-anchored it. So we drop `minDistance`
+ * only for the placement itself and restore it immediately, keeping the real
+ * `minDistance` in force for the wheel.
+ */
+export declare function setOrbitPoint(controls: default_2, point: THREE.Vector3): void;
+
 /**
  * A scene that supports efficient cast shadows. 📕 [Tutorial](https://docs.thatopen.com/Tutorials/Components/Core/ShadowedScene). 📘 [API](https://docs.thatopen.com/api/@thatopen/components/classes/ShadowedScene).
  */
@@ -5117,7 +5158,7 @@ export declare class SimpleCamera extends BaseCamera implements Updateable, Disp
      * Transforming the camera directly will have no effect: you need to use this
      * object to move, rotate, look at objects, etc.
      */
-    get controls(): CameraControls;
+    get controls(): default_2;
     /**
      * Getter for the enabled state of the camera controls.
      * If the current world is null, it returns false.