@mappedin/mappedin-js 6.20.0 → 6.21.1

package/lib/esm/index.d.ts

@@ -1,4 +1,4 @@
-import * as _mappedin_mvf_v25 from "@mappedin/mvf-v2";
+import * as _mappedin_mvf_v22 from "@mappedin/mvf-v2";
 import { AnnotationCollection, AnnotationSymbol, AreaCollection, AreaId, BaseTextAreaProperties, Category, CategoryId, Connection as Connection$1, Details, EnterpriseCategory as EnterpriseCategory$1, EnterpriseCategoryId, EnterpriseLocation as EnterpriseLocation$1, EnterpriseLocationId, EnterpriseLocationInstance, EnterpriseTexture, EnterpriseVenue as EnterpriseVenue$1, EnterpriseVenueType, EntranceCollection, EntranceFeature, Facade as Facade$1, Feature as Feature$1, FeatureCollection as FeatureCollection$1, FloatingFloorTextProperties, FloorCollection, FloorId, FloorProperties, FloorStack as FloorStack$1, FloorTextCommonProperties, Geometry as Geometry$1, Hyperlink as Hyperlink$1, Image, Language, LineStringStyle, LineStringStyle as TMVFLineStringStyle, Location, LocationId, LocationLink, LocationSocial, LocationSocial as LocationSocial$1, LocationState, LocationState as LocationState$1, MVFv2_STANDARD_MVFv3, MultiPolygon as MultiPolygon$1, NavigationFlagDeclarations, NodeCollection, NodeId, ObstructionCollection, ObstructionCollection as ObstructionCollection$1, ObstructionFeature, ObstructionId, OpeningHoursSpecification, OperationHours, OperationHours as OperationHours$1, ParsedMVF, ParsedMVF as TMVF, ParsedMVFLocalePack, Point as Point$1, PointStyle, PointStyle as TMVFPointStyle, Polygon as Polygon$1, PolygonStyle, PolygonStyle as TMVFPolygonStyle, SiblingGroup, SiblingGroup as SiblingGroup$1, SpaceCollection, SpaceCollection as SpaceCollection$1, SpaceFeature, SpaceId, SpaceProperties, Style as TMVFStyle, StyleCollection, StyleCollection as TMVFStyleCollection, TilesetStyle } from "@mappedin/mvf-v2";
 import { MVFv2_STANDARD_MVFv3 as MVFv2_STANDARD_MVFv3$1, ParsedMVF as ParsedMVF$1, RawMVF } from "@mappedin/mvf-v2/no-validator-lite";
 import * as _mappedin_renderer_three0 from "@mappedin/renderer-three";
@@ -4916,6 +4916,10 @@ declare class Navigation {
   get travelledFraction(): number | null;
   /**
    * Highlights path section between two coordinates. This can be used to highlight any section of the path or indicated the currently traveled path.
+   *
+   * In multi-destination mode the highlight is scoped to the active path so
+   * that a `from`/`to` pair on the active route doesn't accidentally pull in
+   * (or get matched to) segments from other destinations.
    */
   highlightPathSection(from: Coordinate, to: Coordinate, options?: TPathSectionHighlightOptions): {
     animation: Promise<unknown>;
@@ -5080,6 +5084,12 @@ declare class FloorObject implements FloorProperties {
   shortName?: string | undefined;
   subtitle?: string | undefined;
   occluderId?: number;
+  /**
+   * Entity id of the per-floor geometry group container created in {@link load}.
+   * Used to parent ancillary content (e.g. the focusable footprint) so visibility
+   * is driven by the same container as the rest of the floor geometry.
+   */
+  geometryContainer?: EntityId<GroupContainerState>;
   private loaded;
   private styleMap;
   private obstructions?;
@@ -5128,6 +5138,14 @@ declare class FloorObject implements FloorProperties {
    * Add an occluder to the floor if it has a footprint.
    */
   addOccluder(): void;
+  /**
+   * Adds an invisible extruded footprint geometry to the floor that participates
+   * in dynamic focus. Using a single merged feature gives the geometry-in-focus
+   * system a stable bounding volume per floor without scanning every interior
+   * space, and the resulting entity id `${FOCUSABLE_FOOTPRINT_PREFIX}${floorId}-merged`
+   * is the canonical id resolved back to the floor by `getFacadeFromEntityId`.
+   */
+  addFocusFootprint(): void;
   /**
    * Whether the floor contains facade geometry.
    */
@@ -7633,7 +7651,7 @@ declare class Camera {
   /**
    * The camera's current pan mode.
    */
-  get panMode(): "default" | "elevation";
+  get panMode(): "elevation" | "default";
   /**
    * Set the camera's pan mode. 'elevation' moves the camera up and down, while 'default' allows the camera to pan in all directions.
    * @experimental
@@ -9077,7 +9095,7 @@ declare const geometryStateSchemaPartial: ZodObject<{
   color: ZodOptional<ZodDefault<ZodUnion<readonly [ZodString, ZodLiteral<"initial">]>>>;
   topColor: ZodOptional<ZodOptional<ZodUnion<readonly [ZodString, ZodLiteral<"initial">]>>>;
   hoverColor: ZodOptional<ZodOptional<ZodUnion<readonly [ZodString, ZodLiteral<"initial">]>>>;
-  interactive: ZodOptional<ZodDefault<ZodBoolean>>;
+  interactive: ZodOptional<ZodDefault<ZodUnion<readonly [ZodBoolean, ZodLiteral<"pass-through">]>>>;
   opacity: ZodOptional<ZodDefault<ZodNumber>>;
   height: ZodOptional<ZodDefault<ZodNumber>>;
   altitude: ZodOptional<ZodDefault<ZodNumber>>;
@@ -9100,7 +9118,7 @@ declare const geometryStateSchemaStrict: ZodObject<{
   color: ZodDefault<ZodUnion<readonly [ZodString, ZodLiteral<"initial">]>>;
   topColor: ZodOptional<ZodUnion<readonly [ZodString, ZodLiteral<"initial">]>>;
   hoverColor: ZodOptional<ZodUnion<readonly [ZodString, ZodLiteral<"initial">]>>;
-  interactive: ZodDefault<ZodBoolean>;
+  interactive: ZodDefault<ZodUnion<readonly [ZodBoolean, ZodLiteral<"pass-through">]>>;
   opacity: ZodDefault<ZodNumber>;
   height: ZodDefault<ZodNumber>;
   altitude: ZodDefault<ZodNumber>;
@@ -9227,8 +9245,8 @@ declare const markerStateSchema: ZodObject<{
 }, $strip>;
 /** @internal */
 declare const markerStateSchemaPartial: ZodObject<{
-  enabled: ZodOptional<ZodDefault<ZodBoolean>>;
   type: ZodOptional<ZodDefault<ZodLiteral<"marker">>>;
+  enabled: ZodOptional<ZodDefault<ZodBoolean>>;
   interactive: ZodOptional<ZodDefault<ZodUnion<readonly [ZodBoolean, ZodLiteral<"pointer-events-auto">]>>>;
   rank: ZodOptional<ZodCustom<"initial" | TCollisionRankingTier, "initial" | TCollisionRankingTier>>;
   occlude: ZodOptional<ZodDefault<ZodBoolean>>;
@@ -9294,6 +9312,7 @@ declare const pathStateSchemaPartial: ZodObject<{
   highlightColor: ZodOptional<ZodDefault<ZodString>>;
   highlightWidthMultiplier: ZodOptional<ZodDefault<ZodNumber>>;
   highlightCompleteFraction: ZodOptional<ZodDefault<ZodNumber>>;
+  highlightDisplayArrowsOnPath: ZodOptional<ZodDefault<ZodBoolean>>;
   xrayOpacity: ZodOptional<ZodDefault<ZodNumber>>;
   travelledEndFraction: ZodOptional<ZodDefault<ZodNumber>>;
   travelledColor: ZodOptional<ZodDefault<ZodString>>;
@@ -9345,6 +9364,7 @@ declare const pathStateSchemaStrict: ZodObject<{
   highlightColor: ZodDefault<ZodString>;
   highlightWidthMultiplier: ZodDefault<ZodNumber>;
   highlightCompleteFraction: ZodDefault<ZodNumber>;
+  highlightDisplayArrowsOnPath: ZodDefault<ZodBoolean>;
   xrayOpacity: ZodDefault<ZodNumber>;
   travelledEndFraction: ZodDefault<ZodNumber>;
   travelledColor: ZodDefault<ZodString>;
@@ -9403,7 +9423,7 @@ declare const shapeStateSchemaPartial: ZodObject<{
   hoverColor: ZodOptional<ZodOptional<ZodString>>;
   height: ZodOptional<ZodDefault<ZodNumber>>;
   opacity: ZodOptional<ZodDefault<ZodNumber>>;
-  interactive: ZodOptional<ZodDefault<ZodBoolean>>;
+  interactive: ZodOptional<ZodDefault<ZodUnion<readonly [ZodBoolean, ZodLiteral<"pass-through">]>>>;
   bevel: ZodOptional<ZodOptional<ZodObject<{
     enabled: ZodOptional<ZodBoolean>;
     thickness: ZodOptional<ZodNumber>;
@@ -9422,7 +9442,7 @@ declare const shapeStateSchemaStrict: ZodObject<{
   hoverColor: ZodOptional<ZodString>;
   height: ZodDefault<ZodNumber>;
   opacity: ZodDefault<ZodNumber>;
-  interactive: ZodDefault<ZodBoolean>;
+  interactive: ZodDefault<ZodUnion<readonly [ZodBoolean, ZodLiteral<"pass-through">]>>;
   bevel: ZodOptional<ZodObject<{
     enabled: ZodOptional<ZodBoolean>;
     thickness: ZodOptional<ZodNumber>;
@@ -12192,6 +12212,16 @@ type TPathSectionHighlightOptions = {
    * @default 1500
    */
   animationDuration?: number;
+  /**
+   * Independently controls whether direction arrows are drawn inside the
+   * highlighted section, regardless of the path-level `displayArrowsOnPath`.
+   * If omitted, the highlighted section inherits the path-level setting.
+   *
+   * Animation still follows the path-level `animateArrowsOnPath`, so the
+   * highlighted arrows will animate when the path was created with
+   * `animateArrowsOnPath: true`.
+   */
+  displayArrowsOnPath?: boolean;
 };
 /**
  * Altitude and visual height data for a single floor elevation.
@@ -12845,8 +12875,8 @@ declare class Area extends DetailedMapData<AreaCollection['features'][number]> i
    */
   get geoJSON(): {
     properties: null;
-    type: _mappedin_mvf_v25.FeatureType;
-    geometry: _mappedin_mvf_v25.Polygon;
+    type: _mappedin_mvf_v22.FeatureType;
+    geometry: _mappedin_mvf_v22.Polygon;
   };
   /** @internal */
   get focusTarget(): this;
@@ -12948,8 +12978,8 @@ declare class Door extends DetailedMapData<EntranceFeature> implements IGeoJSOND
    */
   get geoJSON(): {
     properties: null;
-    type: _mappedin_mvf_v25.FeatureType;
-    geometry: _mappedin_mvf_v25.LineString;
+    type: _mappedin_mvf_v22.FeatureType;
+    geometry: _mappedin_mvf_v22.LineString;
   };
   /** @internal */
   get focusTarget(): Coordinate;
@@ -13085,8 +13115,8 @@ declare class Space extends DetailedMapData<SpaceFeature> implements IGeoJSONDat
    */
   get geoJSON(): {
     properties: null;
-    type: _mappedin_mvf_v25.FeatureType;
-    geometry: _mappedin_mvf_v25.Point | _mappedin_mvf_v25.Polygon | _mappedin_mvf_v25.LineString;
+    type: _mappedin_mvf_v22.FeatureType;
+    geometry: _mappedin_mvf_v22.Point | _mappedin_mvf_v22.Polygon | _mappedin_mvf_v22.LineString;
   };
   /** @internal */
   get focusTarget(): this | Coordinate;
@@ -13172,7 +13202,7 @@ declare class PointOfInterest extends DetailedMapData<FeatureCollection$1<Point$
    */
   get geoJSON(): {
     properties: null;
-    type: _mappedin_mvf_v25.FeatureType;
+    type: _mappedin_mvf_v22.FeatureType;
     geometry: Point$1;
   };
   /**
@@ -13286,8 +13316,8 @@ declare class Annotation extends DetailedMapData<AnnotationCollection['features'
    */
   get geoJSON(): {
     properties: null;
-    type: _mappedin_mvf_v25.FeatureType;
-    geometry: _mappedin_mvf_v25.Point;
+    type: _mappedin_mvf_v22.FeatureType;
+    geometry: _mappedin_mvf_v22.Point;
   };
   /** @internal */
   get focusTarget(): Coordinate;
@@ -13503,8 +13533,8 @@ declare class MapObject extends DetailedMapData<ObstructionFeature> implements I
    */
   get geoJSON(): {
     properties: null;
-    type: _mappedin_mvf_v25.FeatureType;
-    geometry: _mappedin_mvf_v25.Polygon | _mappedin_mvf_v25.LineString;
+    type: _mappedin_mvf_v22.FeatureType;
+    geometry: _mappedin_mvf_v22.Polygon | _mappedin_mvf_v22.LineString;
   };
   /** @internal */
   get anchorTarget(): Coordinate;
@@ -13817,8 +13847,8 @@ declare class Node extends BaseMetaData implements IGeoJSONData, IFocusable, IAn
    */
   get geoJSON(): {
     properties: null;
-    type: _mappedin_mvf_v25.FeatureType;
-    geometry: _mappedin_mvf_v25.Point;
+    type: _mappedin_mvf_v22.FeatureType;
+    geometry: _mappedin_mvf_v22.Point;
   };
   /** @internal */
   get focusTarget(): Coordinate;
@@ -13909,9 +13939,15 @@ declare class FloorStack extends BaseMapData implements IGeoJSONData, IFocusable
    */
   get floors(): [Floor, ...Floor[]];
   /**
-   * Get the default floor for this floor stack
+   * Gets the default floor for this floor stack.
+   *
+   * Resolution order:
+   * 1. The explicitly configured default floor, when it resolves to a known {@link Floor}.
+   * 2. Otherwise, the floor whose elevation is nearest to ground level (zero).
+   *
+   * @returns The default {@link Floor}, or `undefined` when this floor stack has no floors.
    */
-  get defaultFloor(): Floor;
+  get defaultFloor(): Floor | undefined;
   /**
    * Gets the facade ({@link Facade}) representing this floor stack, if it exists.
    */
@@ -14260,7 +14296,7 @@ declare class EnterpriseLocation extends BaseMetaData implements Omit<Enterprise
     parentId?: string;
   });
   /** @internal */
-  get focusTarget(): Coordinate[] | Space[];
+  get focusTarget(): Space[] | Coordinate[];
   /** @internal */
   get navigationTarget(): Space[];
   /**
@@ -15868,7 +15904,7 @@ declare class MapData {
    * console.log(`Current language: ${language.name} (${language.code})`);
    * ```
    */
-  get currentLanguage(): _mappedin_mvf_v25.Language | undefined;
+  get currentLanguage(): _mappedin_mvf_v22.Language | undefined;
   /**
    * Gets the natural bearing of the map.
    *
@@ -16148,6 +16184,11 @@ declare class StyleComponent implements Style$1 {
   opacity: number;
   width: number;
   height: number;
+  /**
+   * The height the geometry's vertices were baked at; the divisor for instance
+   * height scaling (`height / initialHeight`). Provisional until the deferred bake:
+   * re-anchored to the actual baked height in `BatchedMeshSystem.populateEntityMesh`.
+   */
   initialHeight: number;
   altitude: number;
   join: LineStyle$2['join'];
@@ -16551,10 +16592,18 @@ type FeatureCollectionState = {
    */
   side?: MaterialSide;
   /**
-   * @deprecated Per-feature property; read-through to the first child is
-   * preserved for now.
+   * Controls how the feature collection participates in pointer-event raycasting.
+   * Setting this cascades to every child geometry.
+   *
+   * - `true`: hover and click handlers fire on the child geometries.
+   * - `false` (default): each child geometry captures the raycast — clicks
+   *   land on whichever feature is in front and stop there — but no hover or
+   *   click handler fires. Children still shield anything rendered behind
+   *   them from receiving events.
+   * - `'pass-through'`: raycasts skip every feature in the collection so
+   *   pointer events fall through to whatever is rendered behind.
    */
-  interactive?: boolean;
+  interactive?: InteractiveMode;
   /**
    * Collection-level visibility. Maps directly to `Object3D.visible` on the
    * wrapping `FeatureCollectionObject3D`; toggling cascades to children via
@@ -16761,10 +16810,18 @@ declare class SimpleGeometryMaterial extends MeshLambertMaterial {
 }
 //#endregion
 //#region ../renderer-three/src/components/image.d.ts
-declare class EntityMesh$1 extends Mesh {
-  userData: {
-    entityId: string | number;
-  };
+/** userData carried by an {@link ImageMesh}: the entity id plus per-asset metadata hoisted once at
+ * creation so the per-frame update loop never recomputes it. */
+interface ImageMeshUserData {
+  entityId: string | number;
+  /** Cache key into the LOD controller; hoisted once in createImageMesh, read each frame. */
+  cacheKey: string;
+  /** Whether the asset URL supports server-side resizing; hoisted to avoid per-frame recompute. */
+  isResizable: boolean;
+}
+/** Per-image Three.js mesh. Image-only — distinct from the generic `EntityMesh<T>` in `types/index.ts`. */
+declare class ImageMesh extends Mesh {
+  userData: ImageMeshUserData;
 }
 type ImageStyle = {
   /**
@@ -16829,7 +16886,7 @@ type ImageState = {
 };
 declare class ImageComponent {
   mesh: Geometry3DObject3D;
-  imageMesh?: EntityMesh$1;
+  imageMesh?: ImageMesh;
   outline?: LineSegments;
   readonly type = "image";
   instanceIndex: number;
@@ -16906,14 +16963,21 @@ type GeometryState = {
    */
   hoverColor?: string;
   /**
-   * Whether the geometry is interactive, which means it can be hovered over and clicked on.
+   * Controls how the geometry participates in pointer-event raycasting.
+   *
+   * - `true`: hover and click handlers fire on this geometry.
+   * - `false` (default): the geometry captures the raycast — clicks land on
+   *   it and stop there — but no hover or click handler fires. The geometry
+   *   still shields anything rendered behind it from receiving events.
+   * - `'pass-through'`: raycasts skip this geometry entirely so pointer
+   *   events fall through to whatever is rendered behind it.
    *
    * @example
    * ```javascript
    * 	renderer.on('click', ({ geometry }) => {});
    * ```
    */
-  interactive: boolean;
+  interactive: InteractiveMode;
   /**
    * Whether the geometry is outlined with a 30% darkened color. This effect adds lines around the geometry to make it stand out.
    */
@@ -17001,6 +17065,15 @@ declare class MeshComponent {
   textEntityId?: string;
   readonly type = "geometry";
   dirty: boolean;
+  /**
+   * Single source of truth for `interactive: 'pass-through'`. When true, the
+   * interaction system excludes this mesh from `_hitBoxes` so the raycast
+   * never hits it and pointer events fall through to whatever is rendered
+   * behind. Set via `setState({ interactive: 'pass-through' })`. Distinct
+   * from the presence of `InteractionComponent`, which represents
+   * `interactive: true`.
+   */
+  pointerEventsPassThrough: boolean;
   shouldDetach: boolean;
   detached: boolean;
   instanceIndex: number;
@@ -17205,6 +17278,12 @@ type PathState$1 = {
   highlightColor: string;
   highlightWidthMultiplier: number;
   highlightCompleteFraction: number;
+  /**
+   * Independently controls whether arrows are drawn inside the highlighted
+   * section of the path. When omitted on `addPath` it inherits from
+   * `displayArrowsOnPath`. Animation still follows `animateArrowsOnPath`.
+   */
+  highlightDisplayArrowsOnPath: boolean;
   /**
    * The opacity of the path when it's behind geometry (x-ray effect). Value from 0 to 1.
    * @default 0.25
@@ -17366,6 +17445,12 @@ type AddPathOptions = {
   highlightColor?: string;
   highlightWidthMultiplier?: number;
   highlightCompleteFraction?: number;
+  /**
+   * Independently controls whether arrows are drawn inside the highlighted
+   * section of the path. When omitted, it inherits from `displayArrowsOnPath`.
+   * Animation still follows `animateArrowsOnPath`.
+   */
+  highlightDisplayArrowsOnPath?: boolean;
   /**
    * The opacity of the path when it's behind geometry (x-ray effect). Value from 0 to 1.
    * @default 0.25
@@ -17503,6 +17588,7 @@ declare class PathComponent {
   highlightCompleteFraction: number;
   highlightWidthMultiplier: number;
   highlightColor: string;
+  highlightDisplayArrowsOnPath: boolean;
   xrayOpacity: number;
   xrayStyle?: XrayStyleConfig;
   travelledEndFraction: number;
@@ -18021,6 +18107,10 @@ interface PathUniforms {
     type: 'f';
     value: number;
   };
+  highlightDisplayArrowsOnPath: {
+    type: 'b';
+    value: boolean;
+  };
   travelledEndFraction: {
     type: 'f';
     value: number;
@@ -18941,6 +19031,18 @@ declare class CameraSystem extends PubSub<CameraEvents> {
   private createCameraPlane;
   private addEventListeners;
   private addMouseEventListeners;
+  /**
+   * Ends an in-progress drag only when the pointer actually leaves the browser
+   * window. `mouseout` bubbles, so it also fires when the pointer merely moves
+   * from the canvas onto another in-page element rendered above it — for
+   * example an interactive HTML marker or a developer-owned overlay. Treating
+   * those in-page transitions as drag-end froze pan/rotate gestures until the
+   * mouse button was released and pressed again. When the pointer leaves the
+   * window, `relatedTarget` is `null`; in-page transitions always carry a
+   * non-null `relatedTarget`.
+   * @param event - The `mouseout` event from the window listener.
+   */
+  private onWindowMouseOut;
   private addMouseMoveEventListeners;
   private removeMouseMoveEventListeners;
   private removeMouseUpEventListeners;
@@ -19531,49 +19633,24 @@ declare class ImageSystem extends PubSub<{
   private naturalBearing;
   private imagePlacementOptions;
   private cameraFrustum;
-  private transformImageRequest?;
   private cameraWorldPosition;
   private debug;
   get debugLOD(): boolean;
   set debugLOD(value: boolean);
   /**
-   * Cache for tracking image LOD state. Stores the original image element
-   * and textures at each LOD level for memory-efficient switching.
+   * The overlay LOD controller: owns all per-asset texture state and the download→promote upgrade
+   * pipeline. ImageSystem holds only ECS/mesh/material/visibility and calls this seam
+   * (register / get / requestUpgrade / drainPromotions / effectiveLOD / dispose). Not to be confused
+   * with `TextureSystem`, which paints fixed-resolution surface textures onto polygon materials.
    */
-  private cache;
+  private lod;
   constructor(rendererState: RendererState, convertTo3DMapPosition: Core['convertTo3DMapPosition'], projectToScreen: Core['project'], initialBearing?: number, naturalBearing?: number, imagePlacementOptions?: ImagePlacementOptions$1, transformImageRequest?: TransformImageRequest);
   private createImageMesh;
-  /**
-   * Gets or downloads an image texture. Cache entry must exist before calling.
-   * For resizable URLs (Mappedin CDN): uses server-side resizing with LOD levels.
-   * For non-resizable URLs: caps to the specified size once at load.
-   * @param cacheKey - Cache key (URL or URL|size for non-resizable images)
-   * @param url - The image URL for loading
-   * @param targetSize - Texture dimension in pixels
-   * @returns Promise that resolves to the texture
-   */
-  private getOrDownloadImage;
-  /**
-   * Returns the texture capped to maxSize. Only scales if the image exceeds maxSize.
-   * Used for external images to prevent VRAM exhaustion on mobile.
-   * @param sourceTexture - The loaded texture from TextureLoader
-   * @param maxSize - Maximum dimension in pixels
-   * @returns The original texture if within limits, or a new CanvasTexture if scaled
-   */
-  private createCappedTexture;
-  /**
-   * Updates the LOD for an image mesh based on camera distance.
-   * Only applies to resizable URLs (Mappedin CDN) - server handles the scaling.
-   * Non-resizable URLs use a fixed image size set at load time.
-   * @param url - The image URL
-   * @param imageMesh - The mesh to update
-   * @param position - The world position of the image
-   * @param maxImageSize - Maximum image size for non-resizable images (used for cache key)
-   */
-  private updateLODIfNeeded;
   /**
    * Applies debug LOD colors to all image materials when debug mode is enabled.
-   * Calculates LOD based on current camera position and applies appropriate color tinting.
+   * Colors reflect the ACTUAL decoded resolution of the resident texture (`hi ?? base`), bucketed to
+   * the ladder — not the requested tier (`hiLod`) and not the distance target. So a raster source
+   * smaller than its requested tier (e.g. 666px requested at 2048) tints by what the GPU truly holds.
    */
   private applyDebugLODColors;
   /**
@@ -19584,10 +19661,19 @@ declare class ImageSystem extends PubSub<{
   currentImageScreenBBoxes: Rectangle[];
   private viewProjectionMatrix;
   private lastLODUpdateTime;
+  /**
+   * Reconciles a material's map to the effective resident texture (`hi ?? base`) for an asset.
+   * This is the single per-frame resync point: it swaps in a deferred upgrade once it lands and
+   * keeps materials sharing an asset consistent. Hot path — no allocation. Returns whether a
+   * texture is resident.
+   * @param material - The mesh material to reconcile
+   * @param cacheKey - The asset cache key
+   * @returns True if an effective texture is resident (mesh can be shown)
+   */
+  private reconcileMaterialTexture;
   update(cameraRotationRadians: number, isCameraMoving: boolean, cameraStoppedTime: number): void;
   /**
-   * Disposes all cached textures and clears the cache.
-   * Called when the renderer is destroyed to prevent GPU memory leaks.
+   * Disposes all cached textures and clears state. Called on renderer destroy to prevent GPU leaks.
    */
   destroy(): void;
   updateImageScreenBBoxes(meshComponent: MeshComponent | ImageComponent): void;
@@ -20715,6 +20801,16 @@ type MapViewState$1 = {
   hoverColor: string;
   text3dHoverColor: string;
 };
+/**
+ * Style accepted by {@link Core.addFeatureCollection}: the GeoJSON-shape-specific
+ * paint/line style plus `focusable`, which enrolls the resulting mesh in the
+ * dynamic-focus system. To set `interactive` (including `'pass-through'`), cascade
+ * it via `setState` on the FC id after creation; that path already handles all
+ * the per-leaf bookkeeping.
+ */
+type FCFeatureStyle<T$1 extends FeatureCollection<Polygon | MultiPolygon | LineString, any>> = (T$1 extends FeatureCollection<LineString, any> ? LineStyle$2 : PaintStyle$2) & {
+  focusable?: boolean;
+};
 declare class Core extends PubSub<MapEvent> {
   #private;
   options: Omit<RendererCoreOptions$2, 'outdoorView'>;
@@ -20768,6 +20864,11 @@ declare class Core extends PubSub<MapEvent> {
   addGroupContainer(id: string, options?: {
     visible?: boolean;
     altitude?: number;
+    /**
+     * Group containers do not accept `'pass-through'` (they have no mesh
+     * of their own to skip). Mark individual descendants as
+     * `interactive: 'pass-through'` instead.
+     */
     interactive?: boolean;
     focusable?: boolean;
     preloadGeometry?: boolean;
@@ -20799,7 +20900,7 @@ declare class Core extends PubSub<MapEvent> {
    * The only collection-level concern honored at creation time is the optional
    * mask — read from `style(features[0])`.
    */
-  addFeatureCollection<T$1 extends FeatureCollection<Polygon | MultiPolygon | LineString, any>>(id: string, geometry: T$1, style?: ((feature: Feature<Polygon | MultiPolygon | LineString, any>) => T$1 extends FeatureCollection<LineString, any> ? LineStyle$2 : PaintStyle$2) | (T$1 extends FeatureCollection<LineString, any> ? LineStyle$2 : PaintStyle$2), fcState?: {
+  addFeatureCollection<T$1 extends FeatureCollection<Polygon | MultiPolygon | LineString, any>>(id: string, geometry: T$1, style?: ((feature: Feature<Polygon | MultiPolygon | LineString, any>) => FCFeatureStyle<T$1>) | FCFeatureStyle<T$1>, fcState?: {
     altitude?: number;
     visible?: boolean;
   }, parent?: EntityId$1<GroupContainerState$1> | string | number | null): EntityId$1<FeatureCollectionState>;
@@ -21106,6 +21207,21 @@ type GroupContainerState$1 = {
    * The altitude of the group container above the ground in meters
    */
   altitude: number;
+  /**
+   * Controls whether the group container itself fires hover and click events.
+   *
+   * - `true`: container-level hover and click handlers fire when the user
+   *   interacts with any descendant. The container appears in the
+   *   `groupContainers` array of the event payload.
+   * - `false` (default): no container-level handler fires. Descendants still
+   *   capture the raycast independently based on their own `interactive`
+   *   state.
+   *
+   * `'pass-through'` is intentionally not supported on group containers —
+   * group containers have no mesh of their own to skip. Mark individual
+   * descendant geometries / shapes / feature collections as
+   * `interactive: 'pass-through'` instead.
+   */
   interactive: boolean;
   /**
    * The opacity of the group container, which sets the opacity of all its children
@@ -21276,6 +21392,13 @@ type RendererCoreOptions$2 = Partial<{
   transformImageRequest?: TransformImageRequest;
   useWorkers?: boolean;
   useCollisionWorker?: boolean;
+  /**
+   * When true, skips zod validation of label/marker inputs on add and update.
+   * Map-global perf escape hatch for bulk operations where inputs are already
+   * known-good. Mirrors the `disableUpdateStateValidation` map option.
+   * @default false
+   */
+  disableUpdateStateValidation?: boolean;
   /**
    * Shadow rendering configuration
    * @experimental
@@ -21406,6 +21529,25 @@ declare class EntityMesh<T$1> extends Mesh<any> {
     entity: T$1;
   };
 }
+/**
+ * Controls how an entity participates in pointer-event raycasting.
+ *
+ * In all three modes the geometry is rendered identically — the difference is
+ * purely about how pointer events are routed.
+ *
+ * - `true`: the entity opts in to events. Hover and click handlers registered
+ *   on the map view fire when the user interacts with this entity.
+ * - `false` (default): the entity captures the raycast — pointer events land
+ *   on it and stop there — but no hover or click handler fires. This is the
+ *   right choice for static, non-clickable decoration that should still
+ *   shield whatever is rendered behind it (for example a wall in front of an
+ *   interactive space). Anything behind the entity will not receive events.
+ * - `'pass-through'`: raycasts skip the entity entirely, so pointer events
+ *   fall through to whatever is rendered behind it. Useful for invisible
+ *   helper geometry that must never block clicks on the real content beneath
+ *   it (for example a per-floor focus footprint).
+ */
+type InteractiveMode = boolean | 'pass-through';
 /**
  * Options for configuring bevel effects on extruded geometry.
  */
@@ -21736,6 +21878,8 @@ type RendererState = {
   readonly geometryScene: GroupContainerObject3D;
   hoverColor: string;
   text3dHoverColor: string;
+  /** When true, label/marker input validation is skipped (perf escape hatch). */
+  disableUpdateStateValidation: boolean;
   center?: Position$2;
   insetsPadding: InsetPadding$2;
   shouldMeasureCanvas: boolean;

package/lib/esm/index.js

@@ -1 +1 @@
-import{A as C,B as D,C as E,D as F,E as M,F as N,I as O,J as P,K as Q,L as R,M as S,N as T,O as U,P as V,Q as W,R as X,S as Y,T as Z,U as _,V as $,W as aa,X as ba,a as c,b as d,c as e,d as f,e as g,f as h,g as i,h as j,i as k,j as l,k as m,l as n,m as o,n as p,o as q,p as r,q as s,r as t,s as u,t as v,u as w,v as x,w as y,x as z,y as A,z as B}from"./chunk-QISNVXXC.js";import{v as K,x as L}from"./chunk-JTQDGBFM.js";import{Ca as I,P as G,Y as H,a,c as b,mb as J}from"./chunk-344UV3KW.js";import"./chunk-PCLZGYNN.js";import"./chunk-S5CGAT7I.js";import"./chunk-PWEV3AFA.js";export{y as ACTION_TYPE,G as ANIMATION_TWEENS,p as Annotation,i as Area,z as BEARING_TYPE,A as CONNECTION_TYPE,m as Connection,c as Coordinate,C as DOORS,g as DetailedMapData,D as Directions,j as Door,a as E_SDK_LOG_LEVEL,t as EnterpriseCategory,s as EnterpriseLocation,u as EnterpriseVenue,r as Facade,l as Floor,q as FloorStack,e as Hyperlink,f as ImageMetaData,F as LocationCategory,E as LocationProfile,h as MAPPEDIN_COLORS,n as MapObject,P as MapView,d as Node,o as PointOfInterest,k as Space,B as WALLS,I as __INTERNAL__MAPPEDIN_LAYER_ID,L as __INTERNAL__MapLibreOverlay,K as __INTERNAL__RendererCore,R as __INTERNAL__convertToRendererCoreOptions,T as __setWatermarkOnClickFn,_ as checkWorkerUrls,N as disableText3DWorker,H as enableTestMode,S as findPreferredLanguageInVenue,W as forceEnterpriseLocations,Y as getMapData,Z as getMapDataEnterprise,M as getMultiFloorState,aa as getVersion,Q as hydrateMapData,U as hydrateMapDataFromMVF,v as parseMVF,J as preloadFont,b as setLoggerLevel,V as setUseEnterpriseAPI,O as setWorkersUrl,X as shouldForceEnterpriseLocations,$ as show3dMap,ba as show3dMapGeojson,x as unzipAndParseMVFv2,w as unzipMVF};
+import{A as C,B as D,C as E,D as F,E as M,F as N,I as O,J as P,K as Q,L as R,M as S,N as T,O as U,P as V,Q as W,R as X,S as Y,T as Z,U as _,V as $,W as aa,X as ba,a as c,b as d,c as e,d as f,e as g,f as h,g as i,h as j,i as k,j as l,k as m,l as n,m as o,n as p,o as q,p as r,q as s,r as t,s as u,t as v,u as w,v as x,w as y,x as z,y as A,z as B}from"./chunk-HQ5BIBGU.js";import{v as K,x as L}from"./chunk-B5PVUD5J.js";import{Da as I,P as G,Y as H,a,c as b,nb as J}from"./chunk-23SDKQLF.js";import"./chunk-DEPTGCUS.js";import"./chunk-73NFNZ3A.js";import"./chunk-PWEV3AFA.js";export{y as ACTION_TYPE,G as ANIMATION_TWEENS,p as Annotation,i as Area,z as BEARING_TYPE,A as CONNECTION_TYPE,m as Connection,c as Coordinate,C as DOORS,g as DetailedMapData,D as Directions,j as Door,a as E_SDK_LOG_LEVEL,t as EnterpriseCategory,s as EnterpriseLocation,u as EnterpriseVenue,r as Facade,l as Floor,q as FloorStack,e as Hyperlink,f as ImageMetaData,F as LocationCategory,E as LocationProfile,h as MAPPEDIN_COLORS,n as MapObject,P as MapView,d as Node,o as PointOfInterest,k as Space,B as WALLS,I as __INTERNAL__MAPPEDIN_LAYER_ID,L as __INTERNAL__MapLibreOverlay,K as __INTERNAL__RendererCore,R as __INTERNAL__convertToRendererCoreOptions,T as __setWatermarkOnClickFn,_ as checkWorkerUrls,N as disableText3DWorker,H as enableTestMode,S as findPreferredLanguageInVenue,W as forceEnterpriseLocations,Y as getMapData,Z as getMapDataEnterprise,M as getMultiFloorState,aa as getVersion,Q as hydrateMapData,U as hydrateMapDataFromMVF,v as parseMVF,J as preloadFont,b as setLoggerLevel,V as setUseEnterpriseAPI,O as setWorkersUrl,X as shouldForceEnterpriseLocations,$ as show3dMap,ba as show3dMapGeojson,x as unzipAndParseMVFv2,w as unzipMVF};