@thatopen/components 3.4.1 → 3.4.3

package/dist/index.d.ts

@@ -1417,6 +1417,28 @@ export declare class Clipper extends Component implements Createable, Disposable
      * to the arrow gizmo as you zoom in/out. Default is true.
      */
     autoScalePlanes: boolean;
+    /**
+     * When true, planes created by this Clipper are flagged
+     * `isLocal: true` so they stay out of `renderer.three.clippingPlanes`
+     * (the WebGL-level global list). All clipping happens via per-
+     * material `material.clippingPlanes`, which `Clipper.updateMaterialsAndPlanes`
+     * already populates from the renderer's component-side array. The
+     * global list still works for non-Clipper code that pushes its own
+     * planes via `setPlane(active, plane, /*isLocal*\/ false)`.
+     *
+     * Why this matters: with planes only on materials (not global),
+     * consumers like {@link ClipStyler} can give their section fill /
+     * line meshes a *different* `material.clippingPlanes` list — one
+     * that excludes the section's own plane — so the cut geometry
+     * sits exactly on the cut without being discarded by it. The old
+     * 1cm world-space offset workaround is no longer needed and the
+     * fill stays aligned at every camera angle (issue #733).
+     *
+     * Default `false` to preserve existing behavior. Set this once
+     * before creating planes; toggling at runtime won't reclassify
+     * planes already on the renderer.
+     */
+    localClippingPlanes: boolean;
     /**
      * The type of clipping plane to be created.
      * Default is {@link SimplePlane}.
@@ -1434,7 +1456,7 @@ export declare class Clipper extends Component implements Createable, Disposable
     private _size;
     private _enabled;
     private _visible;
-    readonly onStateChanged: Event_2<("material" | "enabled" | "size" | "visibility")[]>;
+    readonly onStateChanged: Event_2<("enabled" | "size" | "visibility" | "material")[]>;
     /** {@link Component.enabled} */
     get enabled(): boolean;
     /** {@link Component.enabled} */
@@ -1453,6 +1475,21 @@ export declare class Clipper extends Component implements Createable, Disposable
     set size(size: number);
     constructor(components: Components);
     private setEvents;
+    private subscribeToFragmentMaterials;
+    /**
+     * Assign `material.clippingPlanes` to the renderer's component-
+     * side `clippingPlanes` array — the only place local planes live
+     * once `localClippingPlanes = true`. In legacy global-clipping
+     * mode this is a no-op: the renderer's global list handles
+     * fragments clipping and assigning per-material would just be
+     * redundant.
+     *
+     * Applied to every fragment material, including LOD line
+     * materials — they need the planes too, otherwise far-LOD line
+     * geometry stays visible past the cut while the shell geometry
+     * clips correctly.
+     */
+    private applyClippingToFragmentMaterial;
     /** {@link Disposable.dispose} */
     dispose(): void;
     /** {@link Createable.create} */
@@ -1598,7 +1635,7 @@ export declare class Components implements Disposable_2 {
      * Default value is false.
      */
     enabled: boolean;
-    private _clock;
+    private _timer;
     /**
      * Event that triggers the Components instance is initialized.
      *
@@ -2074,7 +2111,7 @@ declare class DistanceRenderer {
     /**
      * The scene where the distance is computed.
      */
-    scene: THREE.Scene;
+    scene: THREE.Scene<THREE.Object3DEventMap>;
     /**
      * The camera used to compute the distance.
      */
@@ -2868,125 +2905,303 @@ export declare interface ExternalDocumentReference extends DocumentReference {
 }
 
 /**
- * A fast model picker that uses color coding to identify fragment models under the mouse cursor. This is much faster than raycasting for simple model identification.
+ * GPU-readback picker that identifies what's under a screen position
+ * without going through the worker raycast. Two granularities, same
+ * render pass:
+ *
+ * - {@link getModelAt} returns the model id under the cursor.
+ * - {@link getItemAt} returns the item itself (`modelId` + `localId`).
+ *
+ * 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.
+ *
+ * Encoding (one pixel):
+ *   R = modelByte (1..254, 0 = void / unwritten)
+ *   G = (itemId >> 16) & 0xff
+ *   B = (itemId >> 8)  & 0xff
+ *   A = (itemId)       & 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.
  */
 export declare class FastModelPicker implements Disposable_2 {
     /** {@link Component.enabled} */
     enabled: boolean;
-    /** The components instance to which this FastModelPicker belongs. */
+    /** Components instance this picker belongs to. */
     components: Components;
     /** {@link Disposable.onDisposed} */
     readonly onDisposed: Event_2<unknown>;
-    /** The position of the mouse in the screen. */
+    /** Position helper bound to the world's canvas. */
     readonly mouse: Mouse;
-    /**
-     * A reference to the world instance to which this FastModelPicker belongs.
-     * This is used to access the camera and scene.
-     */
+    /** World this picker renders against. */
     world: World;
     /**
-     * Whether debug mode is enabled. When enabled, shows the color-coded canvas.
+     * 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.
      */
     debugMode: boolean;
     /**
-     * Map from color (as RGB number) to model ID.
-     * Color is encoded as: (r << 16) | (g << 8) | b
-     */
-    private colorToModelId;
-    /**
-     * Map from model ID to color.
-     */
-    private modelIdToColor;
-    /**
-     * Render target for the color-coded scene.
+     * Maximum models the picker can disambiguate in a single pick. Capped
+     * by the 8-bit `modelByte`. In practice we never approach this.
      */
-    private renderTarget?;
+    static readonly MAX_MODELS = 254;
+    private _renderTarget?;
+    private _renderTargetSize;
+    private _debugCanvas?;
+    private _debugContainer?;
     /**
-     * Size of the render target (stored separately since getSize doesn't exist).
+     * 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 renderTargetSize;
+    private _idMaterial;
     /**
-     * Debug canvas element (shown when debugMode is true).
+     * 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 debugCanvas?;
+    private _depthMaterial;
     /**
-     * Debug container element.
+     * 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 debugContainer?;
+    private _normalMaterial;
     /**
-     * Material used for color-coding models.
+     * Cached original materials for the swap-render-restore pass.
+     * Populated in {@link applyIdMaterial}, drained in
+     * {@link restoreOriginalMaterials} after the render.
      */
-    private colorMaterials;
+    private _originalMaterials;
     /**
-     * Original materials cache (to restore after picking).
+     * 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 originalMaterials;
-    private originalLodColors;
-    /**
-     * Whether colors need to be reassigned (when models change).
-     */
-    private colorsNeedUpdate;
+    private _hiddenLods;
     constructor(components: Components, world: World);
     /**
-     * Sets up listeners for fragment model changes.
-     */
-    private setupFragmentListeners;
-    /**
-     * Sets up the render target for color-coded picking.
-     */
-    private setupRenderTarget;
-    /**
-     * Sets up the debug canvas for visualization.
-     */
-    private setupDebugCanvas;
-    /**
-     * Generates a deterministic color for a model based on its ID.
-     * This ensures the same model always gets the same color.
-     */
-    private generateColorForModel;
-    /**
-     * Converts a color to a numeric ID.
-     */
-    private colorToId;
-    /**
-     * Assigns unique colors to all fragment models.
-     * Colors are deterministic based on model ID, so the same model always gets the same color.
-     */
-    private assignColors;
-    /**
-     * Applies color materials to fragment models.
+     * 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.
+     *
+     * @param position - Normalized device coords. Defaults to the
+     *   picker's last known mouse position.
      */
-    private applyColorMaterials;
+    getModelAt(position?: THREE.Vector2): Promise<string | null>;
     /**
-     * Restores original materials to fragment models.
+     * 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.
+     *
+     * @param position - Normalized device coords. Defaults to the
+     *   picker's last known mouse position.
      */
-    private restoreOriginalMaterials;
+    getItemAt(position?: THREE.Vector2): Promise<{
+        modelId: string;
+        localId: number;
+        itemId: number;
+    } | null>;
     /**
-     * Renders the scene with color-coded models.
+     * 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.
+     *
+     * @param position - Normalized device coords. Defaults to the
+     *   picker's last known mouse position.
      */
-    private renderColorCoded;
+    getPointAt(position?: THREE.Vector2): Promise<THREE.Vector3 | null>;
     /**
-     * Updates the debug canvas with the color-coded render.
+     * 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.
      */
-    private updateDebugCanvas;
+    getNormalAt(position?: THREE.Vector2): Promise<THREE.Vector3 | null>;
     /**
-     * Gets the model ID at the given screen position.
+     * 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.
      *
-     * @param position - Optional screen position. If not provided, uses current mouse position.
-     * @returns The model ID at the position, or null if no model is found.
+     * Returns `null` if the cursor is over empty space, the id pass
+     * decodes to the void sentinel, or the depth round-trip yields the
+     * far plane.
      */
-    getModelAt(position?: THREE.Vector2): Promise<string | null>;
+    getFullPick(position?: THREE.Vector2): Promise<{
+        modelId: string;
+        localId: number;
+        /**
+         * Internal item index (FlatBuffer `sample.item()`). Exposed so
+         * SnapResolver and other internal consumers can hit fragments'
+         * itemId-keyed fast paths (`boxes.sampleOf`) without paying a
+         * second worker round-trip to translate back from localId.
+         */
+        itemId: number;
+        point: THREE.Vector3;
+        normal: THREE.Vector3 | null;
+        distance: number;
+    } | null>;
     /**
-     * Enables or disables debug mode.
-     * When enabled, shows a canvas with the color-coded render.
+     * 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.
      */
     setDebugMode(enabled: boolean): void;
-    /**
-     * Removes the debug canvas.
-     */
-    private removeDebugCanvas;
     /** {@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;
+    /**
+     * 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;
+    private setupDebugCanvas;
+    private removeDebugCanvas;
+    private updateDebugCanvas;
 }
 
 /**
@@ -3125,9 +3340,21 @@ export declare class FirstPersonMode implements NavigationMode {
 export declare function formatSlope(slope: number, format: SlopeFormat): string;
 
 /**
- * Component to load, delete and manage [fragments](https://github.com/ThatOpen/engine_fragment) efficiently. 📕 [Tutorial](https://docs.thatopen.com/Tutorials/Components/Core/FragmentsManager). 📘 [API](https://docs.thatopen.com/api/@thatopen/components/classes/FragmentsManager).
+ * Component to load, delete and manage [fragments](https://github.com/ThatOpen/engine_fragment) efficiently. 📕 [Tutorial](https://docs.thatopen.com/Tutorials/Components/Core/FragmentsManager). 📘 [API](https://docs.thatopen.com/api/@thatopen/components/classes/FragmentsManager). Before calling {@link FragmentsManager.init}, you need a URL for the fragments worker. The recommended way to get it is {@link FragmentsManager.getWorker}, which fetches the version-matched worker from unpkg.
  */
 export declare class FragmentsManager extends Component implements Disposable_2 {
+    /**
+     * Returns a blob URL for the fragments worker matching the installed
+     * `@thatopen/fragments` version. Delegates to {@link FRAGS.FragmentsModels.getWorker}.
+     * This is the recommended way to obtain the URL passed to {@link FragmentsManager.init}.
+     *
+     * @example
+     * ```ts
+     * const fragments = components.get(OBC.FragmentsManager);
+     * fragments.init(await OBC.FragmentsManager.getWorker());
+     * ```
+     */
+    static getWorker(): Promise<string>;
     /**
      * A unique identifier for the component.
      * This UUID is used to register the component within the Components system.
@@ -3156,6 +3383,13 @@ export declare class FragmentsManager extends Component implements Disposable_2
     constructor(components: Components);
     /** {@link Disposable.dispose} */
     dispose(): void;
+    /**
+     * Initializes the fragments core with the given worker URL.
+     * The recommended way to obtain the URL is {@link FragmentsManager.getWorker}:
+     * ```ts
+     * fragments.init(await OBC.FragmentsManager.getWorker());
+     * ```
+     */
     init(workerURL: string, options?: {
         classicWorker?: boolean;
     }): void;
@@ -5136,13 +5370,6 @@ export declare class SimpleRaycaster implements Disposable_2 {
      * This is used to access the camera and meshes.
      */
     world: World;
-    /**
-     * Whether to use fast model picking to optimize raycasting.
-     * When enabled, the raycaster will first use FastModelPicker to identify
-     * which model is under the mouse, then only raycast that specific model.
-     * This can significantly improve performance when there are many models.
-     */
-    useFastModelPicking: boolean;
     constructor(components: Components, world: World);
     /** {@link Disposable.dispose} */
     dispose(): void;
@@ -5172,7 +5399,7 @@ export declare class SimpleRaycaster implements Disposable_2 {
      * @param items - The meshes to query. If not provided, it will query all the meshes stored in {@link World.meshes}.
      * @returns The first intersection found or `null` if no intersection was found.
      */
-    castRayFromVector(origin: THREE.Vector3, direction: THREE.Vector3, items?: THREE.Mesh<THREE.BufferGeometry<THREE.NormalBufferAttributes, THREE.BufferGeometryEventMap>, THREE.Material | THREE.Material[], THREE.Object3DEventMap>[]): THREE.Intersection<THREE.Object3D<THREE.Object3DEventMap>> | null;
+    castRayFromVector(origin: THREE.Vector3, direction: THREE.Vector3, items?: THREE.Mesh<THREE.BufferGeometry<THREE.NormalBufferAttributes, THREE.BufferGeometryEventMap>, THREE.Material<THREE.MaterialEventMap> | THREE.Material<THREE.MaterialEventMap>[], THREE.Object3DEventMap>[]): THREE.Intersection<THREE.Object3D<THREE.Object3DEventMap>> | null;
     private intersect;
     private filterClippingPlanes;
 }
@@ -5207,6 +5434,48 @@ export declare class SimpleRenderer extends BaseRenderer {
     protected _resizeObserver: ResizeObserver | null;
     protected onContainerUpdated: Event_2<unknown>;
     private _resizing;
+    private _logo;
+    private _showLogo;
+    /**
+     * Whether the That Open Company logo is shown as a small overlay in the
+     * bottom-left corner of the renderer container. Defaults to `true`.
+     *
+     * The logo is how people discover that the libraries powering this app
+     * come from That Open Company, the team that keeps
+     * `@thatopen/components`, `@thatopen/fragments`, and the rest of the stack
+     * free and open source. If the logo fits your design, please consider
+     * leaving it on; every visible mark helps us reach more developers and
+     * keep investing in the libraries you're building on. Thank you.
+     *
+     * If your app needs a clean viewport (full-bleed print view, white-label
+     * embed, customer-branded surface), set it to `false`:
+     * ```ts
+     * world.renderer.showLogo = false;
+     * ```
+     */
+    get showLogo(): boolean;
+    set showLogo(value: boolean);
+    /**
+     * The DOM element rendering the That Open Company wordmark, or `null`
+     * before the renderer is set up. Mutate its `style` to restyle or move
+     * the overlay without forking the source. Common adjustments:
+     *
+     * ```ts
+     * const logo = world.renderer.logo;
+     * if (logo) {
+     *   logo.style.left = "auto";
+     *   logo.style.right = "0.75rem";   // move to bottom-right
+     *   logo.style.bottom = "auto";
+     *   logo.style.top = "0.75rem";     // or to the top edge
+     * }
+     * ```
+     *
+     * The element also carries a `data-thatopen-logo` attribute, so app-wide
+     * CSS can target it (`[data-thatopen-logo] { ... }`). External rules
+     * need `!important` (or higher specificity) to win against the inline
+     * defaults.
+     */
+    get logo(): HTMLElement | null;
     /**
      * Constructor for the SimpleRenderer class.
      *
@@ -5233,6 +5502,7 @@ export declare class SimpleRenderer extends BaseRenderer {
     setupEvents(active: boolean): void;
     private resizeEvent;
     private setupRenderer;
+    private setupLogo;
     private onContextLost;
     private onContextBack;
 }
@@ -5308,7 +5578,7 @@ export declare class SimpleWorld<T extends BaseScene = BaseScene, U extends Base
     /**
      * All the loaded [meshes](https://threejs.org/docs/#api/en/objects/Mesh). These meshes will be taken into account in operations like raycasting.
      */
-    readonly meshes: Set<THREE.Mesh<THREE.BufferGeometry<THREE.NormalBufferAttributes, THREE.BufferGeometryEventMap>, THREE.Material | THREE.Material[], THREE.Object3DEventMap>>;
+    readonly meshes: Set<THREE.Mesh<THREE.BufferGeometry<THREE.NormalBufferAttributes, THREE.BufferGeometryEventMap>, THREE.Material<THREE.MaterialEventMap> | THREE.Material<THREE.MaterialEventMap>[], THREE.Object3DEventMap>>;
     /** {@link Updateable.onAfterUpdate} */
     readonly onAfterUpdate: Event_2<unknown>;
     /** {@link Updateable.onBeforeUpdate} */
@@ -5451,6 +5721,146 @@ declare interface SlopeAnnotationSystem {
 /** How the slope value is displayed in the text label. */
 export declare type SlopeFormat = "percentage" | "ratio" | "degrees";
 
+/**
+ * Snap classes the resolver supports. Mirrors fragments' `SnappingClass`.
+ */
+export declare enum SnapClass {
+    POINT = 0,
+    LINE = 1,
+    FACE = 2
+}
+
+/**
+ * Main-thread snap resolver: takes a world-space pick point + the
+ * picked item, returns the closest face / line / point of that item
+ * for any requested snap classes. The heavy work (fetching the item's
+ * shell geometry through the fragments edit API and composing
+ * world-space polygons) runs once per item; subsequent calls for the
+ * same item are pure CPU geometry against the LRU-bounded cache.
+ * Call {@link invalidate} when an item changes (e.g. via the
+ * fragments edit API) so the cached snap data gets refreshed on the
+ * next request.
+ */
+export declare class SnapResolver implements Disposable_2 {
+    /** {@link Disposable.onDisposed} */
+    readonly onDisposed: Event_2<unknown>;
+    /**
+     * Maximum world-space distance for a snap candidate to be
+     * considered valid. Vertices, edges or face planes beyond this
+     * range are rejected. Set this in the same units as your model
+     * (typical BIM scenes are metres, so the default of 1 means
+     * "snap only when within 1 m of the cursor"). Tools that want a
+     * different feel can override per-instance.
+     */
+    maxDistance: number;
+    /**
+     * Maximum number of items to keep in the snap cache. Beyond this,
+     * the least-recently-used item is dropped on the next insertion.
+     * Each cached item is on the order of a few KB (per-shell faces +
+     * deduped edges + deduped vertices), so the default of 1000 caps
+     * memory at a few MB even on huge models. Bump it for workflows
+     * that revisit thousands of distinct items in a single session.
+     */
+    maxCacheSize: number;
+    private readonly components;
+    private readonly cache;
+    constructor(components: Components);
+    /** {@link Disposable.dispose} */
+    dispose(): void;
+    /**
+     * Returns the best snap candidate among the requested classes for a
+     * pre-picked surface point on a known item, or `null` if the item
+     * has no shell geometry. When multiple classes are requested, the
+     * winner is whichever produces the smallest distance to the input
+     * `point`.
+     *
+     * @param point - Pick point in world space (typically from the GPU
+     *   picker's `getFullPick`).
+     * @param modelId - Model the picked item belongs to.
+     * @param localId - The picked item's localId.
+     * @param classes - Subset of {@link SnapClass} the caller cares about.
+     */
+    resolve(point: THREE.Vector3, modelId: string, 
+    /**
+     * Internal **itemId** (the FlatBuffer `sample.item()` index, key
+     * for `boxes.sampleOf`), not the user-facing localId. The picker
+     * exposes this on its full-pick result; passing it through here
+     * lets us hit the O(1) item→samples reverse index on the worker
+     * via `_getItemSnapData(itemId)`. Keying by localId would force a
+     * full sample-table scan (~1 s on big models).
+     */
+    itemId: number, classes: Iterable<SnapClass>): Promise<SnapResult | null>;
+    /**
+     * Fire-and-forget prefetch of an item's snap geometry. Hoverer calls
+     * this on lock-onto-new-item so by the time the user clicks, the
+     * worker round-trip is already paid and `resolve` resolves
+     * synchronously off the cache.
+     *
+     * Returns a Promise so callers who *do* want to await can; most
+     * won't.
+     */
+    prefetch(modelId: string, itemId: number): Promise<void>;
+    /** Drop a specific item from the cache (e.g. after an edit). */
+    invalidate(modelId: string, itemId: number): void;
+    /** Drop the entire cache. Useful when many items have changed. */
+    clear(): void;
+    private static keyOf;
+    private storeWithLRU;
+    private fetchItemSnapData;
+    private collectPolygonsFromShell;
+    private snap;
+    private snapToPoint;
+    private snapToLine;
+    private snapToFace;
+}
+
+/**
+ * Singleton component that owns one shared {@link SnapResolver} for
+ * the {@link Components} instance. Snap caches are keyed by
+ * `(modelId, localId)` so a single resolver across all worlds is
+ * fine — there's no per-world state.
+ */
+export declare class SnapResolvers extends Component implements Disposable_2 {
+    /** Components-system UUID. */
+    static readonly uuid: "be9b8e6c-7f5b-4a36-8e7e-3a1f5e2a6c9d";
+    /** {@link Component.enabled} */
+    enabled: boolean;
+    /** {@link Disposable.onDisposed} */
+    readonly onDisposed: Event_2<unknown>;
+    private readonly _resolver;
+    constructor(components: Components);
+    /** The shared {@link SnapResolver}. */
+    get(): SnapResolver;
+    /** {@link Disposable.dispose} */
+    dispose(): void;
+}
+
+/**
+ * One result of a {@link SnapResolver.resolve} call. Fields match what
+ * the worker raycast snap path historically produces, so consumers
+ * (length / area measurements, drawing tools) keep working unchanged
+ * when their input switches from worker raycast to GPU pick + this.
+ */
+export declare type SnapResult = {
+    /** Snapped world-space position (vertex / segment closest point /
+     *  point projected onto the snapped face). */
+    point: THREE.Vector3;
+    /** World-space surface normal where applicable (always set for FACE,
+     *  unset for POINT, derived from the picked surface for LINE). */
+    normal?: THREE.Vector3;
+    /** Which snap class this result represents. */
+    snappingClass: SnapClass;
+    /** Polygon vertices of the snapped face (FACE only). Flat array of
+     *  `[x, y, z, x, y, z, ...]`. */
+    facePoints?: Float32Array;
+    /** Triangulation indices into `facePoints` (FACE only). For convex
+     *  polygons we emit a fan; for concave the consumer can re-tessellate. */
+    faceIndices?: Uint32Array;
+    /** Endpoints of the snapped edge (LINE only). */
+    snappedEdgeP1?: THREE.Vector3;
+    snappedEdgeP2?: THREE.Vector3;
+};
+
 /** A single technical drawing — the core spatial aggregate. */
 export declare class TechnicalDrawing {
     /** Unique identifier for this drawing instance. */
@@ -6796,6 +7206,17 @@ export declare class Views extends Component {
      */
     world: World | null;
     private _fragmentsUpdateEvent;
+    /**
+     * When true, opening a view snapshots the active camera's controls state
+     * (via `controls.toJSON()`) and closing the view restores that snapshot
+     * (via `controls.fromJSON(json, true)`), so exiting a view returns the
+     * camera to the same pose the user had before entering it. Default true.
+     *
+     * Set to `false` to keep the legacy behavior, where the default camera
+     * lands at whatever pose its controls drifted to during the view session.
+     */
+    restoreCameraOnClose: boolean;
+    private _restoreState;
     /**
      * Determines whether there are any open views in this component's list.
      */
@@ -6866,6 +7287,14 @@ export declare class Views extends Component {
      * @remarks This method resets the world to use its default camera.
      */
     close(id?: string): void;
+    /**
+     * Routes input to a single camera by toggling `controls.enabled`. Every
+     * camera in the world owns its own CameraControls instance bound to the
+     * renderer's DOM element; without this, all of them would react to the
+     * same wheel/pointer events in parallel, so navigating one view would
+     * drift every other camera at the same time.
+     */
+    private setOnlyEnabledControls;
 }
 
 /**