@mappedin/mappedin-js 6.17.1 → 6.18.0

package/lib/esm/index.d.ts

@@ -1,13 +1,13 @@
-import * as _mappedin_mvf_v22 from "@mappedin/mvf-v2";
+import * as _mappedin_mvf_v28 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";
-import { AddLabelOptionsInternal, AddText3DOptions, AddText3DOptions as AddText3DOptions$1, AddText3DPointOptions, CameraSystemState, ColorString, EntityId, EnvMapOptions, EnvMapOptions as EnvMapOptions$1, GLTFExportOptions as GLTFExportOptions$1, GroupContainerState, ISystemPlugin, ISystemPlugin as ISystemPlugin$1, ImagePlacementOptions, InitializeModelState, InitializeModelState as InitializeModelState$1, InitializeText3DState, InsetPadding, InsetPadding as InsetPadding$1, InsetPaddingOption, InsetPaddingOption as InsetPaddingOption$1, InterpolateOn, Interpolation, Interpolation as Interpolation$1, LabelAppearance as LabelAppearance$1, LabelRenderedState, LabelTextPlacement as LabelTextPlacement$1, LineStyle, LineStyle as LineStyle$1, MapViewState, MarkerState, OutlinesOptions, PaintStyle, PaintStyle as PaintStyle$1, PathState, Position as Position$1, RendererCore, RendererCoreOptions, Shading, Text3DState, WatermarkUpdateOptions } from "@mappedin/renderer-three";
+import { AddLabelOptionsInternal, AddText3DOptions, AddText3DOptions as AddText3DOptions$1, AddText3DPointOptions, CameraSystemState, ColorString, DebugState, DebugState as DebugState$1, EntityId, EnvMapOptions, EnvMapOptions as EnvMapOptions$1, GLTFExportOptions as GLTFExportOptions$1, GroupContainerState, ISystemPlugin, ISystemPlugin as ISystemPlugin$1, ImagePlacementOptions, InitializeModelState, InitializeModelState as InitializeModelState$1, InitializeText3DState, InsetPadding, InsetPadding as InsetPadding$1, InsetPaddingOption, InsetPaddingOption as InsetPaddingOption$1, InterpolateOn, Interpolation, LabelAppearance as LabelAppearance$1, LabelRenderedState, LabelTextPlacement as LabelTextPlacement$1, LineStyle, LineStyle as LineStyle$1, MapViewState, MarkerState, OutlinesOptions, PaintStyle, PaintStyle as PaintStyle$1, PathState, PathWidth, PathWidth as PathWidth$1, PixelWidth, Position as Position$1, RendererCore, RendererCoreOptions, Shading, Text3DState, WatermarkUpdateOptions } from "@mappedin/renderer-three";
 import * as _tweenjs_tween_js0 from "@tweenjs/tween.js";
 import { Group, Tween } from "@tweenjs/tween.js";
 import { CustomLayerInterface, IControl, Map as Map$1, MapEventType } from "@mappedin/outdoor-context";
+import { ANIMATION_TWEENS, PathWidth as PathWidth$2, PathWidth as PathWidth$3, enableTestMode } from "@mappedin/renderer-shared";
 import { MatchInfo, SearchResult as SearchResult$1, Suggestion, Suggestion as Suggestion$1 } from "minisearch";
-import { ANIMATION_TWEENS, enableTestMode } from "@mappedin/renderer-shared";
 import * as three0 from "three";
 import { AmbientLight, BatchedMesh, BatchedMeshGeometryRange, Box3, BufferAttribute, BufferGeometry, Camera as Camera$1, Color, DirectionalLight, Group as Group$1, Intersection, LineSegments, Matrix4, Mesh, MeshLambertMaterial, MeshLambertMaterialParameters, Object3D, Object3DEventMap, PerspectiveCamera, Plane, PlaneGeometry, Raycaster, Scene, ShaderMaterial, Texture, TubeGeometry, Vector2, Vector3, WebGLRenderer } from "three";
 import { BatchedText, BatchedText as BatchedText$1, Text, Text as Text$1 } from "troika-three-text";
@@ -290,6 +290,12 @@ type TGetMapDataSharedOptions = {
      * @internal
      */
     version?: string;
+    /**
+     * The externalId parameter attaches a custom tracking identifier to every analytics event sent during the session.
+     * This is useful for correlating Mappedin analytics data with an external system — for example, linking a map session
+     * back to a specific marketing campaign, CRM record, or third-party tracking platform.
+     */
+    externalId?: string;
   };
   search?: TSearchOptions;
   /**
@@ -542,7 +548,7 @@ declare class AnalyticsInternal {
   sendGetDirectionsEvent: DebouncedFunction<(start: string, end: string, accessible?: boolean) => void | Promise<void> | Promise<Response>>;
   sendBlueDotEvents(event: BlueDotEvents): void | Promise<void> | Promise<Response>;
 }
-type UpdateStateParam = Partial<Pick<AnalyticState, 'geolocationMode' | 'context' | 'logEvents' | 'userPosition' | 'mapId' | 'sendEvents' | 'logEvents' | 'accessToken' | 'sessionId' | 'deviceId'>>;
+type UpdateStateParam = Partial<Pick<AnalyticState, 'geolocationMode' | 'context' | 'logEvents' | 'userPosition' | 'mapId' | 'sendEvents' | 'logEvents' | 'accessToken' | 'sessionId' | 'deviceId' | 'externalId'>>;
 /**
  * Maps reserved analytics event names to their payload structures.
  *
@@ -641,6 +647,12 @@ declare class Analytics {
     logEvents: boolean;
     /** Flag to enable sending of events. */
     sendEvents: boolean;
+    /**
+     * The externalId parameter attaches a custom tracking identifier to every analytics event sent during the session.
+     * This is useful for correlating Mappedin analytics data with an external system — for example, linking a map session
+     * back to a specific marketing campaign, CRM record, or third-party tracking platform.
+     */
+    externalId?: string;
     /** The API key for authentication. */
     key?: string;
     /** The API secret for authentication. */
@@ -693,6 +705,12 @@ type AnalyticState = {
   logEvents: boolean;
   /** Flag to enable sending of events. */
   sendEvents: boolean;
+  /**
+   * The externalId parameter attaches a custom tracking identifier to every analytics event sent during the session.
+   * This is useful for correlating Mappedin analytics data with an external system — for example, linking a map session
+   * back to a specific marketing campaign, CRM record, or third-party tracking platform.
+   */
+  externalId?: string;
 } & AnalyticsAuth;
 type AnalyticsOptions = Partial<Omit<AnalyticState, 'analyticsBaseUrl' | 'geolocationMode' | 'userPosition'>>;
 type AnalyticsUpdateOptions = Omit<AnalyticsOptions, keyof AnalyticsAuth> & ((Required<Pick<AnalyticsAuth, 'key' | 'secret'>> & Partial<Pick<AnalyticsAuth, 'accessToken'>>) | (Required<Pick<AnalyticsAuth, 'accessToken'>> & Partial<Pick<AnalyticsAuth, 'key' | 'secret'>>));
@@ -700,7 +718,7 @@ type AnalyticsUpdateOptions = Omit<AnalyticsOptions, keyof AnalyticsAuth> & ((Re
  * Options for updating the current state of analytics.
  * @interface
  */
-type TAnalyticsUpdateState = Pick<Partial<AnalyticState>, 'logEvents' | 'sendEvents' | 'baseUri' | 'accessToken'>;
+type TAnalyticsUpdateState = Pick<Partial<AnalyticState>, 'logEvents' | 'sendEvents' | 'baseUri' | 'accessToken' | 'externalId'>;
 //#endregion
 //#region ../packages/shave-text/shave-text.d.ts
 type TDrawFn = (ctx: CanvasRenderingContext2D | OffscreenCanvasRenderingContext2D, x: number, y: number) => void;
@@ -3041,7 +3059,7 @@ declare const LABEL_LOW_PRIORITY = "low-priority";
 type LabelTextPlacement = (typeof LABEL_TEXT_PLACEMENT)[keyof typeof LABEL_TEXT_PLACEMENT];
 type LabelTextPlacementInternal = LabelTextPlacement | typeof LABEL_LOW_PRIORITY;
 type EasingCurve$1 = string;
-type Interpolation$3<T$1 extends string, U$1 extends unknown[]> = {
+type Interpolation$2<T$1 extends string, U$1 extends unknown[]> = {
   on: T$1;
   input: number[];
   output: U$1;
@@ -3081,9 +3099,18 @@ declare const labelAppearanceSchemaBase: ZodObject<{
   }>>;
   iconVisible: ZodDefault<ZodUnion<readonly [ZodBoolean, ZodNumber]>>;
   opacity: ZodDefault<ZodNumber>;
+  __EXPERIMENTAL_wrapperBackgroundColor: ZodOptional<ZodString>;
+  __EXPERIMENTAL_wrapperPaddingX: ZodDefault<ZodNumber>;
+  __EXPERIMENTAL_wrapperPaddingY: ZodDefault<ZodNumber>;
+  __EXPERIMENTAL_wrapperBorderRadius: ZodDefault<ZodNumber>;
+  __EXPERIMENTAL_wrapperDotSize: ZodDefault<ZodNumber>;
+  __EXPERIMENTAL_wrapperShadowColor: ZodOptional<ZodString>;
+  __EXPERIMENTAL_wrapperShadowOffsetX: ZodDefault<ZodNumber>;
+  __EXPERIMENTAL_wrapperShadowOffsetY: ZodDefault<ZodNumber>;
+  __EXPERIMENTAL_wrapperShadowBlur: ZodDefault<ZodNumber>;
 }, $strip>;
 type LabelAppearance = Partial<input<typeof labelAppearanceSchemaBase>> & {
-  iconScale?: number | Interpolation$3<'zoom-level', number[]>;
+  iconScale?: number | Interpolation$2<'zoom-level', number[]>;
 };
 type LabelAppearanceWithDefaults = output<typeof labelAppearanceSchema>;
 declare const labelAppearanceSchema: ZodPipe<ZodObject<{
@@ -3120,6 +3147,15 @@ declare const labelAppearanceSchema: ZodPipe<ZodObject<{
   }>>;
   iconVisible: ZodDefault<ZodUnion<readonly [ZodBoolean, ZodNumber]>>;
   opacity: ZodDefault<ZodNumber>;
+  __EXPERIMENTAL_wrapperBackgroundColor: ZodOptional<ZodString>;
+  __EXPERIMENTAL_wrapperPaddingX: ZodDefault<ZodNumber>;
+  __EXPERIMENTAL_wrapperPaddingY: ZodDefault<ZodNumber>;
+  __EXPERIMENTAL_wrapperBorderRadius: ZodDefault<ZodNumber>;
+  __EXPERIMENTAL_wrapperDotSize: ZodDefault<ZodNumber>;
+  __EXPERIMENTAL_wrapperShadowColor: ZodOptional<ZodString>;
+  __EXPERIMENTAL_wrapperShadowOffsetX: ZodDefault<ZodNumber>;
+  __EXPERIMENTAL_wrapperShadowOffsetY: ZodDefault<ZodNumber>;
+  __EXPERIMENTAL_wrapperShadowBlur: ZodDefault<ZodNumber>;
 }, $strip>, ZodTransform<Required<LabelAppearance>, {
   margin: number;
   maxLines: number;
@@ -3140,6 +3176,13 @@ declare const labelAppearanceSchema: ZodPipe<ZodObject<{
   iconOverflow: "hidden" | "visible";
   iconVisible: number | boolean;
   opacity: number;
+  __EXPERIMENTAL_wrapperPaddingX: number;
+  __EXPERIMENTAL_wrapperPaddingY: number;
+  __EXPERIMENTAL_wrapperBorderRadius: number;
+  __EXPERIMENTAL_wrapperDotSize: number;
+  __EXPERIMENTAL_wrapperShadowOffsetX: number;
+  __EXPERIMENTAL_wrapperShadowOffsetY: number;
+  __EXPERIMENTAL_wrapperShadowBlur: number;
   textColor?: string | undefined;
   textOutlineColor?: string | undefined;
   pinColor?: string | undefined;
@@ -3147,6 +3190,8 @@ declare const labelAppearanceSchema: ZodPipe<ZodObject<{
   pinColorInactive?: string | undefined;
   pinOutlineColorInactive?: string | undefined;
   icon?: string | undefined;
+  __EXPERIMENTAL_wrapperBackgroundColor?: string | undefined;
+  __EXPERIMENTAL_wrapperShadowColor?: string | undefined;
 }>>;
 type AddLabelOptionsInternal$1 = {
   rank?: CollisionRankingTier;
@@ -3334,6 +3379,12 @@ type AddMarkerOptions = {
    * @default { size: 2, color: '#666' }
    */
   lowPriorityPin?: Partial<LowPriorityPinConfig>;
+  /**
+   * Whether the marker should animate visibility transitions.
+   * When false, opacity is set directly without transitions.
+   * @default true
+   */
+  animated?: boolean;
 };
 type MarkerStrategy = {
   name: MarkerPlacement;
@@ -3503,12 +3554,6 @@ declare class PubSub<EVENT_PAYLOAD, EVENT extends keyof EVENT_PAYLOAD = keyof EV
    * AbortController for managing lifecycle and cleanup
    */
   private _abortController;
-  /**
-   * @protected
-   * @internal
-   * Tracks all cleanup functions for subscriptions made via on()
-   */
-  protected _cleanupFunctions: Array<() => void>;
   /**
    * Returns the AbortSignal for this PubSub instance.
    * Use this signal with APIs that support cancellation (fetch, addEventListener, etc.)
@@ -3657,6 +3702,14 @@ declare class TwoDDrawSystem extends PubSub<{
     url: string;
   }>;
   pinCache: Record<string, [HTMLCanvasElement | OffscreenCanvas, HTMLCanvasElement | OffscreenCanvas]>;
+  /**
+   * Caches pre-rasterized experimental wrapper sprites (shape + baked shadow)
+   * keyed by geometry + color + shadow params. Blitting the sprite with
+   * `drawImage` sidesteps per-frame path construction and shadow
+   * rasterization — the hot cost in the wrapper render path. Cleared on
+   * full-redraw (`this.dirty`) to match `pinCache`/`textCache` invalidation.
+   */
+  wrapperCache: Record<string, OffscreenCanvas | HTMLCanvasElement>;
   /** Stores the loaded images ready to be drawn. */
   imageCache: Record<number, HTMLImageElement | ImageBitmap>;
   /** Stores the promises for each image fetch. */
@@ -3670,6 +3723,22 @@ declare class TwoDDrawSystem extends PubSub<{
     center?: OffscreenCanvas | HTMLCanvasElement;
     right?: OffscreenCanvas | HTMLCanvasElement;
   }>;
+  /** Number of labels that cleared the `canShow && visible` gate this frame. */
+  private drawCount;
+  /**
+   * Number of `project()` calls issued this frame. Owned and written by the
+   * pipeline (which performs the actual projection loop); read-only here.
+   */
+  projectionCount: number;
+  /**
+   * Number of labels currently in `visibilitySystem.animating`. Owned and
+   * written by the pipeline right before the draw pass; read-only here.
+   */
+  animatingCount: number;
+  /** Number of labels that reached `recomputeCurrentStrategy` this frame. */
+  private drawAttemptCount;
+  /** Lazily-mounted DOM overlay that renders per-frame stats. */
+  private statsElement?;
   /**
    * Runs the draw pass for all label entities.
    * @param zoomLevel - Current zoom level (for icon scale interpolation)
@@ -3684,6 +3753,72 @@ declare class TwoDDrawSystem extends PubSub<{
   cacheImage: (label: LabelComponent) => void;
   createPinCanvas: (label: LabelComponent, pinSize: number, backgroundColor: string, foregroundColor: string, maxIconScale?: number) => HTMLCanvasElement | OffscreenCanvas;
   prepare: (label: LabelComponent, labelCacheId: string, context: CanvasRenderingContext2D) => void;
+  /**
+   * Lazily mounts (and updates) a small DOM overlay reporting per-frame
+   * label-pipeline stats:
+   *
+   * - `projections` — raw count of `project()` calls issued by the pipeline
+   *   (every entity, regardless of whether it lands on-screen).
+   * - `draw-attempts` — labels that reached `recomputeCurrentStrategy`, i.e.
+   *   survived the `offscreen`/`visible` cull and had their layout/strategy
+   *   recomputed.
+   * - `draws` — labels that cleared the final `canShow && visible` gate in
+   *   `draw()` and issued canvas draw calls.
+   *
+   * Intended as a lightweight diagnostic for tuning visibility strategies
+   * and culling.
+   */
+  private updateStatsOverlay;
+  /**
+   * Creates an offscreen sprite containing a filled wrapper shape with its
+   * drop shadow pre-rasterized. The shape is drawn at `(marginX, marginY)`
+   * inside a canvas sized to fully contain the shadow spread.
+   *
+   * @param w - Shape width in canvas pixels (integer, excludes shadow margin).
+   * @param h - Shape height in canvas pixels (integer, excludes shadow margin).
+   * @param marginX - Horizontal padding added to the sprite to hold the shadow.
+   * @param marginY - Vertical padding added to the sprite to hold the shadow.
+   * @param drawShape - Callback that issues the path for the shape at the
+   *   provided top-left `(x, y)` with dimensions `(w, h)`. The caller already
+   *   set `fillStyle` + shadow properties; `beginPath` is the callback's
+   *   responsibility.
+   * @param bgColor - Fill color for the shape.
+   * @param shadowColor - Drop-shadow color; `''`/`undefined` disables shadow.
+   * @param shadowOffsetX - Drop-shadow X offset in canvas pixels.
+   * @param shadowOffsetY - Drop-shadow Y offset in canvas pixels.
+   * @param shadowBlur - Drop-shadow blur radius in canvas pixels.
+   * @returns An OffscreenCanvas (preferred) or HTMLCanvasElement fallback.
+   */
+  private createWrapperSprite;
+  /**
+   * Draws the experimental wrapper background shape behind the label.
+   *
+   * Shape varies with the active strategy:
+   * - Text visible → rounded rectangle union of pin + text, expanded by
+   *   `__EXPERIMENTAL_wrapperPaddingX` / `__EXPERIMENTAL_wrapperPaddingY`.
+   * - No text, pin ACTIVE (HIDDEN placement with visible icon) → filled
+   *   circle with radius `visiblePinRadius + max(paddingX, paddingY)` so the
+   *   icon sits inside a colored chip.
+   * - No text, pin INACTIVE (LOW_PRIORITY / HIDDEN without icon) → tiny
+   *   filled dot. Radius is half of `__EXPERIMENTAL_wrapperDotSize` (CSS
+   *   pixels) when set, otherwise the intrinsic inactive pin fill radius.
+   *
+   * The pin contribution to the rect / chip uses the *visible* pin radius
+   * (`(pinSize + PIN_STROKE_SIZE * pixelRatio) / 2`) rather than `drawSize`.
+   * `drawSize` reflects the pin's padded canvas extent (includes transparent
+   * margin for shadow / stroke headroom), which would otherwise inflate the
+   * wrapper to ~2× the visible pin — making small padding values read as
+   * much larger than requested.
+   *
+   * Hot-path optimization: the shape + shadow are rasterized once into an
+   * offscreen sprite keyed by geometry/color/shadow params (see
+   * `wrapperCache`) and blitted with `drawImage` on subsequent frames,
+   * avoiding per-frame path construction and shadow rasterization.
+   *
+   * No-op unless the appearance sets `__EXPERIMENTAL_wrapperBackgroundColor`.
+   * All coordinates are in canvas pixels (already multiplied by pixelRatio).
+   */
+  private drawWrapperBackground;
   /**
    * Draws a single label to the canvas.
    */
@@ -3744,6 +3879,8 @@ declare class TwoDPipeline {
   get drawSystem(): TwoDDrawSystem;
   /** Exposed for testing; DOM draw is internal to the pipeline */
   get domDrawSystem(): DOMDrawSystem;
+  /** @internal Canvas used for rendering 2D labels. */
+  get labelCanvas(): HTMLCanvasElement;
   constructor(container: HTMLElement, state: TwoDPipelineState, project: ProjectFn, options?: TwoDPipelineOptions);
   /**
    * Registers an entity in the lookup map without activating it.
@@ -4269,15 +4406,6 @@ type TNavigationPathOptions = TAddPathOptions & {
    * If not specified, connection paths use the main `color` property.
    */
   __EXPERIMENTAL__CONNECTION_COLOR?: string;
-  /**
-   * @experimental Controls billboarding for connection path geometry.
-   * - `boolean`: Enable/disable billboarding directly
-   * - `number`: Angle threshold in degrees (0-90). Billboard when path angle from horizontal >= threshold.
-   *   For example, 80 means billboard only when path is >=80 degrees from horizontal (nearly vertical).
-   *
-   * @defaultValue false
-   */
-  __EXPERIMENTAL__CONNECTION_BILLBOARDING?: boolean | number;
   /**
    * @experimental Amount in meters to shorten connection path from each end.
    * Prevents visual overlap with floor paths at junctions.
@@ -4297,6 +4425,13 @@ type TNavigationPathOptions = TAddPathOptions & {
    * If not specified, connection paths use the main `__EXPERIMENTAL_GEOMETRY` property.
    */
   __EXPERIMENTAL__CONNECTION_GEOMETRY?: 'tube' | 'ribbon';
+  /**
+   * @experimental
+   * @deprecated Use `__EXPERIMENTAL_BILLBOARDING` instead. With per-vertex angle gating in the shader,
+   * billboarding applies to all path segments but only affects vertices above the angle threshold.
+   * A numeric value (degrees) naturally billboards only steep connection segments while leaving floor paths flat.
+   */
+  __EXPERIMENTAL__CONNECTION_BILLBOARDING?: boolean | number;
 };
 /**
  * Options for navigation.
@@ -4335,7 +4470,7 @@ type TNavigationOptions = {
   /**
    * Path Options for the non-current path in multi-destination mode.
    */
-  inactivePathOptions?: Partial<TAddPathOptions>;
+  inactivePathOptions?: Partial<TNavigationPathOptions>;
   /**
    * Controls whether the path drawing is animated across floors.
    * @default true
@@ -4779,7 +4914,7 @@ declare class GeojsonApiMapObject extends PubSub<{
    * @param floorStackId - The floor stack ID
    * @returns The altitude map for the floor stack
    */
-  getFloorStackAltitudeData(floorStackId: string): Map<any, any>;
+  getFloorStackAltitudeData(floorStackId: string): Map<number, TFloorAltitudeData>;
   private cancelAnimation;
   Models: {
     add: (id: string, targets: Coordinate[], opts: TAddModelOptions & {
@@ -5029,9 +5164,9 @@ type InspectorOption = Partial<InspectorState>;
 //#region src/debug.d.ts
 declare class Debug {
   #private;
-  state: RendererCore['Debug']['state'];
+  state: DebugState$1;
   constructor(core: RendererCore);
-  update: RendererCore['Debug']['update'];
+  update: (updateState: Partial<DebugState$1>) => void;
   /**
    * Returns the current camera state as a JSON object that can be passed directly to `mapView.Camera.set()`.
    * @returns The current camera state including center, zoomLevel, bearing, and pitch.
@@ -6959,12 +7094,105 @@ declare class MapView {
    */
   set __INTERNAL__hidePathsNotOnCurrentFloor(value: boolean);
   /**
-   * @internal
+   * **Super experimental — this API may change or be removed in any release without notice.
+   * Do not depend on it in production.**
+   *
+   * Registers a plugin that runs every frame in the render loop.
+   *
+   * The plugin's {@link ISystemPlugin.update | update()} method receives the full
+   * {@link TRendererState} — including the Three.js scene, camera, renderer, lighting,
+   * and all ECS geometry entities — allowing you to inject custom Three.js objects,
+   * apply per-frame effects, or read scene state.
+   *
+   * Plugins execute during the finalization phase of the render loop (after camera,
+   * path, and 2D systems, but before `DrawSystem` and `paint()`).
+   *
+   * @param plugin - An object implementing {@link ISystemPlugin}. Must have an
+   *   `update(state: TRendererState)` method.
+   *
+   * @example
+   * ### Standalone mode — add a spinning cube
+   * ```ts
+   * import { type ISystemPlugin, type TRendererState } from '@mappedin/mappedin-js';
+   * import { BoxGeometry, Mesh, MeshStandardMaterial } from 'three';
+   *
+   * class CubePlugin implements ISystemPlugin {
+   *   private cube: Mesh | null = null;
+   *
+   *   update(state: TRendererState): void {
+   *     if (!this.cube) {
+   *       this.cube = new Mesh(
+   *         new BoxGeometry(5, 5, 5),
+   *         new MeshStandardMaterial({ color: 0x00ff88 }),
+   *       );
+   *       this.cube.position.set(0, 0, 10);
+   *       state.threeJSScene.add(this.cube);
+   *     }
+   *     this.cube.rotation.y += 0.01;
+   *   }
+   * }
+   *
+   * mapView.registerPlugin(new CubePlugin());
+   * ```
+   *
+   * @example
+   * ### MapLibre overlay mode — add a floating sphere
+   * ```ts
+   * import { type ISystemPlugin, type TRendererState } from '@mappedin/mappedin-js';
+   * import { Mesh, MeshStandardMaterial, SphereGeometry } from 'three';
+   *
+   * class SpherePlugin implements ISystemPlugin {
+   *   private sphere: Mesh | null = null;
+   *
+   *   update(state: TRendererState): void {
+   *     if (!this.sphere) {
+   *       this.sphere = new Mesh(
+   *         new SphereGeometry(3, 32, 32),
+   *         new MeshStandardMaterial({ color: 0xff4444 }),
+   *       );
+   *       // In overlay mode, add to geometryScene (not threeJSScene)
+   *       state.geometryScene.add(this.sphere);
+   *     }
+   *   }
+   * }
+   *
+   * // Inside the overlay's 'loaded' callback:
+   * overlay.on('loaded', ({ mapView }) => {
+   *   mapView.registerPlugin(new SpherePlugin());
+   * });
+   * ```
+   *
+   * @see {@link unregisterPlugin} to remove a plugin.
+   * @see {@link ISystemPlugin} for the plugin interface and lifecycle details.
+   *
    * @experimental
    */
   registerPlugin(plugin: ISystemPlugin$1): void;
   /**
-   * @internal
+   * **Super experimental — this API may change or be removed in any release without notice.
+   * Do not depend on it in production.**
+   *
+   * Removes a previously registered plugin from the render loop.
+   *
+   * After removal, the plugin's `update()` method will no longer be called.
+   * Any Three.js objects the plugin added to the scene are **not** automatically
+   * removed — the plugin is responsible for its own cleanup before or after
+   * unregistration.
+   *
+   * @param plugin - The same plugin instance that was passed to {@link registerPlugin}.
+   *
+   * @example
+   * ```ts
+   * const plugin = new CubePlugin();
+   *
+   * mapView.registerPlugin(plugin);
+   *
+   * // Later, when the plugin is no longer needed:
+   * mapView.unregisterPlugin(plugin);
+   * ```
+   *
+   * @see {@link registerPlugin} to add a plugin.
+   *
    * @experimental
    */
   unregisterPlugin(plugin: ISystemPlugin$1): void;
@@ -8480,7 +8708,7 @@ type TGeometryUpdateState = output<typeof geometryStateSchemaPartial>;
 declare const labelStateSchema: ZodObject<{
   type: ZodDefault<ZodLiteral<"label">>;
   text: ZodString;
-  rank: ZodCustom<"initial" | TCollisionRankingTier, "initial" | TCollisionRankingTier>;
+  rank: ZodCustom<TCollisionRankingTier | "initial", TCollisionRankingTier | "initial">;
   appearance: ZodCustom<LabelAppearance, LabelAppearance>;
   interactive: ZodDefault<ZodBoolean>;
   enabled: ZodDefault<ZodBoolean>;
@@ -8502,7 +8730,7 @@ declare const labelStateSchema: ZodObject<{
 declare const labelStateSchemaPartial: ZodObject<{
   type: ZodOptional<ZodDefault<ZodLiteral<"label">>>;
   text: ZodOptional<ZodString>;
-  rank: ZodOptional<ZodCustom<"initial" | TCollisionRankingTier, "initial" | TCollisionRankingTier>>;
+  rank: ZodOptional<ZodCustom<TCollisionRankingTier | "initial", TCollisionRankingTier | "initial">>;
   appearance: ZodOptional<ZodCustom<LabelAppearance, LabelAppearance>>;
   interactive: ZodOptional<ZodDefault<ZodBoolean>>;
   enabled: ZodOptional<ZodDefault<ZodBoolean>>;
@@ -8527,7 +8755,7 @@ type TLabelUpdateState = output<typeof labelStateSchemaPartial>;
 //#region src/states/marker-state.d.ts
 declare const markerStateSchema: ZodObject<{
   type: ZodDefault<ZodLiteral<"marker">>;
-  rank: ZodCustom<"initial" | TCollisionRankingTier, "initial" | TCollisionRankingTier>;
+  rank: ZodCustom<TCollisionRankingTier | "initial", TCollisionRankingTier | "initial">;
   placement: ZodOptional<ZodUnion<readonly [ZodEnum<{
     hidden: "hidden";
     top: "top";
@@ -8563,13 +8791,12 @@ declare const markerStateSchema: ZodObject<{
   element: ZodCustom<HTMLElement, HTMLElement>;
   contentHTML: ZodString;
   occlude: ZodDefault<ZodBoolean>;
+  animated: ZodDefault<ZodBoolean>;
 }, $strip>;
 declare const markerStateSchemaPartial: ZodObject<{
   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>>;
+  rank: ZodOptional<ZodCustom<TCollisionRankingTier | "initial", TCollisionRankingTier | "initial">>;
   placement: ZodOptional<ZodOptional<ZodUnion<readonly [ZodEnum<{
     hidden: "hidden";
     top: "top";
@@ -8593,6 +8820,7 @@ declare const markerStateSchemaPartial: ZodObject<{
     "bottom-left": "bottom-left";
     "bottom-right": "bottom-right";
   }>>]>>>;
+  interactive: ZodOptional<ZodDefault<ZodUnion<readonly [ZodBoolean, ZodLiteral<"pointer-events-auto">]>>>;
   dynamicResize: ZodOptional<ZodDefault<ZodBoolean>>;
   zIndex: ZodOptional<ZodOptional<ZodNumber>>;
   lowPriorityPin: ZodOptional<ZodOptional<ZodObject<{
@@ -8601,6 +8829,8 @@ declare const markerStateSchemaPartial: ZodObject<{
     color: ZodOptional<ZodString>;
   }, $strip>>>;
   contentHTML: ZodOptional<ZodString>;
+  occlude: ZodOptional<ZodDefault<ZodBoolean>>;
+  animated: ZodOptional<ZodDefault<ZodBoolean>>;
 }, $strip>;
 type TMarkerState = output<typeof markerStateSchema>;
 type TMarkerUpdateState = output<typeof markerStateSchemaPartial>;
@@ -8611,7 +8841,7 @@ type BorderColor = LiteralUnion<'darken', string>;
 declare const pathStateSchemaPartial: ZodObject<{
   type: ZodOptional<ZodDefault<ZodLiteral<"path">>>;
   color: ZodOptional<ZodDefault<ZodString>>;
-  width: ZodOptional<ZodType<number | Interpolation$1<"zoom-level", number[]>, unknown, $ZodTypeInternals<number | Interpolation$1<"zoom-level", number[]>, unknown>>>;
+  width: ZodOptional<ZodType<PathWidth$2, unknown, $ZodTypeInternals<PathWidth$2, unknown>>>;
   completeFraction: ZodOptional<ZodDefault<ZodNumber>>;
   visible: ZodOptional<ZodDefault<ZodBoolean>>;
   verticalOffset: ZodOptional<ZodDefault<ZodNumber>>;
@@ -8642,18 +8872,24 @@ declare const pathStateSchemaPartial: ZodObject<{
     ribbon: "ribbon";
   }>>>;
   __EXPERIMENTAL_ENDCAP_EXTENSION: ZodOptional<ZodDefault<ZodTuple<[ZodNumber, ZodNumber], null>>>;
-  __EXPERIMENTAL_BILLBOARDING: ZodOptional<ZodDefault<ZodBoolean>>;
+  __EXPERIMENTAL_BILLBOARDING: ZodOptional<ZodDefault<ZodUnion<readonly [ZodBoolean, ZodNumber]>>>;
   __EXPERIMENTAL_BORDER: ZodOptional<ZodOptional<ZodObject<{
     enabled: ZodBoolean;
     color: ZodCustom<BorderColor, BorderColor>;
     width: ZodOptional<ZodNumber>;
   }, $strip>>>;
   __EXPERIMENTAL_PREVENT_SELF_OVERLAP: ZodOptional<ZodDefault<ZodBoolean>>;
+  __EXPERIMENTAL_XRAY_STYLE: ZodOptional<ZodOptional<ZodObject<{
+    opacity: ZodOptional<ZodNumber>;
+    color: ZodOptional<ZodString>;
+    tint: ZodOptional<ZodNumber>;
+    dithering: ZodOptional<ZodNumber>;
+  }, $strip>>>;
 }, $strip>;
 declare const pathStateSchemaStrict: ZodObject<{
   type: ZodDefault<ZodLiteral<"path">>;
   color: ZodDefault<ZodString>;
-  width: ZodType<number | Interpolation$1<"zoom-level", number[]>>;
+  width: ZodType<PathWidth$2>;
   completeFraction: ZodDefault<ZodNumber>;
   visible: ZodDefault<ZodBoolean>;
   verticalOffset: ZodDefault<ZodNumber>;
@@ -8684,13 +8920,19 @@ declare const pathStateSchemaStrict: ZodObject<{
     ribbon: "ribbon";
   }>>;
   __EXPERIMENTAL_ENDCAP_EXTENSION: ZodDefault<ZodTuple<[ZodNumber, ZodNumber], null>>;
-  __EXPERIMENTAL_BILLBOARDING: ZodDefault<ZodBoolean>;
+  __EXPERIMENTAL_BILLBOARDING: ZodDefault<ZodUnion<readonly [ZodBoolean, ZodNumber]>>;
   __EXPERIMENTAL_BORDER: ZodOptional<ZodObject<{
     enabled: ZodBoolean;
     color: ZodCustom<BorderColor, BorderColor>;
     width: ZodOptional<ZodNumber>;
   }, $strip>>;
   __EXPERIMENTAL_PREVENT_SELF_OVERLAP: ZodDefault<ZodBoolean>;
+  __EXPERIMENTAL_XRAY_STYLE: ZodOptional<ZodObject<{
+    opacity: ZodOptional<ZodNumber>;
+    color: ZodOptional<ZodString>;
+    tint: ZodOptional<ZodNumber>;
+    dithering: ZodOptional<ZodNumber>;
+  }, $strip>>;
 }, $strict>;
 type TPathState = output<typeof pathStateSchemaStrict>;
 type TPathUpdateState = input<typeof pathStateSchemaPartial>;
@@ -8997,7 +9239,7 @@ declare class GeoJsonApi extends PubSub<TNavigationEvents> {
    * @param floorStackId - The floor stack ID
    * @returns A map of floor elevation to altitude and effective height data
    */
-  getFloorStackAltitudeData(floorStackId: string): Map<any, any>;
+  getFloorStackAltitudeData(floorStackId: string): Map<number, TFloorAltitudeData>;
   /**
    * Create a coordinate from a screen coordinate
    * @param x - The x coordinate of the screen
@@ -9922,6 +10164,10 @@ type TEvents = {
    * Emitted when the pan bounds of the camera changes.
    */
   'camera-bounds-change': CameraBounds;
+  /**
+   * Emitted when the camera's screen offsets change.
+   */
+  'camera-screen-offsets-change': InsetPadding$1;
   /**
    * Emitted when a floor change starts.
    */
@@ -10253,6 +10499,8 @@ type TFocusOnOptions = TCameraAnimationOptions & {
    * @default: true
    */
   interruptible?: boolean;
+  /** @internal @experimental Debug color override (CSS color string) for this point cloud. */
+  debugColor?: string;
 };
 /**
  * Defines the target for camera operations.
@@ -10382,11 +10630,15 @@ type TAddPathOptions = {
    */
   pulsePauseDuration?: number;
   /**
-   * The width of the path in meters. Can be a number or an {@link Interpolation}.
+   * The width of the path.
+   * - `number` — meters (e.g. `1.5`)
+   * - `'Npx'` — screen-space pixels (e.g. `'20px'`), ribbon geometry only
+   * - `Interpolation` — zoom-interpolated meters
+   * - `Interpolation<'zoom-level', PixelWidth[]>` — zoom-interpolated pixels (e.g. `output: ['10px', '20px']`), ribbon geometry only
    *
    * @defaultValue Interpolation { on: 'zoom-level', input: [17, 22], output: [0.8, 0.4] }
    */
-  width?: number | Interpolation$1<'zoom-level', number[]>;
+  width?: PathWidth$1;
   /**
    * Duration of path drawing in milliseconds.
    *
@@ -10458,9 +10710,26 @@ type TAddPathOptions = {
   /**
    * The opacity of the path when it's behind geometry (x-ray effect). Value from 0 to 1.
    *
+   * Prefer {@link __EXPERIMENTAL_XRAY_STYLE}.opacity instead.
+   * If both are set, `__EXPERIMENTAL_XRAY_STYLE.opacity` takes precedence.
+   *
    * @defaultValue 0.25
    */
   xrayOpacity?: number;
+  /**
+   * @experimental
+   * Consolidated x-ray appearance configuration. Controls how paths look when behind geometry.
+   */
+  __EXPERIMENTAL_XRAY_STYLE?: {
+    /** The opacity when behind geometry (0-1). @default 0.25 */
+    opacity?: number;
+    /** Explicit color override for the x-ray portion. Omit to auto-compute from path color. */
+    color?: string;
+    /** Tint strength (0-1). 0 = no muting, 1 = fully muted. @default 0.3 */
+    tint?: number;
+    /** Dithering cell size in screen pixels (e.g. 4 = 4x4px checkerboard). 0 or undefined = off. */
+    dithering?: number;
+  };
   /**
    * @experimental Controls the smoothness of path corners using CatmullRom curve tension. Higher values create smoother curves.
    * Values between 0.1-0.3 provide subtle smoothing suitable for most use cases.
@@ -10499,12 +10768,15 @@ type TAddPathOptions = {
    */
   __EXPERIMENTAL_ENDCAP_EXTENSION?: [number, number];
   /**
-   * @experimental When true and using ribbon geometry, the path will always face the camera (billboard effect).
-   * Most useful for vertical paths between floors.
+   * @experimental Controls billboarding for ribbon path geometry.
+   * - `true`: Every vertex faces the camera (unconditional billboard)
+   * - `false`: Flat world-space orientation
+   * - `number`: Angle threshold in degrees (0-90). Billboard only when path tangent
+   *   verticality >= threshold. E.g. 80 means billboard only nearly-vertical segments.
    *
-   * @defaultValue false
+   * @defaultValue 80
    */
-  __EXPERIMENTAL_BILLBOARDING?: boolean;
+  __EXPERIMENTAL_BILLBOARDING?: boolean | number;
   /**
    * @experimental Border configuration for ribbon path geometry.
    * Renders darkened edges along both sides of the ribbon.
@@ -10527,18 +10799,9 @@ type TAddPathOptions = {
 };
 /**
  * @experimental Options specific to connection paths (vertical paths between floors).
- * Extends TAddPathOptions but with enhanced billboarding that supports angle-threshold activation.
+ * Extends TAddPathOptions with junction inset control.
  */
-type TConnectionPathOptions = Omit<TAddPathOptions, '__EXPERIMENTAL_BILLBOARDING'> & {
-  /**
-   * @experimental Controls billboarding for connection path geometry.
-   * - `boolean`: Enable/disable billboarding directly
-   * - `number`: Angle threshold in degrees (0-90). Billboard when path angle from horizontal >= threshold.
-   *   For example, 80 means billboard only when path is >=80 degrees from horizontal (nearly vertical).
-   *
-   * @defaultValue false
-   */
-  __EXPERIMENTAL_BILLBOARDING?: boolean | number;
+type TConnectionPathOptions = TAddPathOptions & {
   /**
    * @experimental Amount in meters to shorten connection path from each end.
    * Prevents visual overlap with floor paths at junctions.
@@ -11087,7 +11350,7 @@ interface UpdateGlobalState {
 /**
  * A map element that can be focused on by the camera.
  */
-type TFocusTarget = Coordinate | Space | Area | MapObject | Floor | Shape;
+type TFocusTarget = Coordinate | Space | Area | MapObject | Floor | FloorStack | Shape;
 /**
  * Associates MapData type strings with their corresponding classes.
  */
@@ -12013,8 +12276,8 @@ declare class Area extends DetailedMapData<AreaCollection['features'][number]> i
    */
   get geoJSON(): {
     properties: null;
-    type: _mappedin_mvf_v22.FeatureType;
-    geometry: _mappedin_mvf_v22.Polygon;
+    type: _mappedin_mvf_v28.FeatureType;
+    geometry: _mappedin_mvf_v28.Polygon;
   };
   /** @internal */
   get focusTarget(): this;
@@ -12116,8 +12379,8 @@ declare class Door extends DetailedMapData<EntranceFeature> implements IGeoJSOND
    */
   get geoJSON(): {
     properties: null;
-    type: _mappedin_mvf_v22.FeatureType;
-    geometry: _mappedin_mvf_v22.LineString;
+    type: _mappedin_mvf_v28.FeatureType;
+    geometry: _mappedin_mvf_v28.LineString;
   };
   /** @internal */
   get focusTarget(): Coordinate;
@@ -12253,8 +12516,8 @@ declare class Space extends DetailedMapData<SpaceFeature> implements IGeoJSONDat
    */
   get geoJSON(): {
     properties: null;
-    type: _mappedin_mvf_v22.FeatureType;
-    geometry: _mappedin_mvf_v22.Point | _mappedin_mvf_v22.Polygon | _mappedin_mvf_v22.LineString;
+    type: _mappedin_mvf_v28.FeatureType;
+    geometry: _mappedin_mvf_v28.Point | _mappedin_mvf_v28.Polygon | _mappedin_mvf_v28.LineString;
   };
   /** @internal */
   get focusTarget(): this | Coordinate;
@@ -12340,7 +12603,7 @@ declare class PointOfInterest extends DetailedMapData<FeatureCollection$1<Point$
    */
   get geoJSON(): {
     properties: null;
-    type: _mappedin_mvf_v22.FeatureType;
+    type: _mappedin_mvf_v28.FeatureType;
     geometry: Point$1;
   };
   /**
@@ -12454,8 +12717,8 @@ declare class Annotation extends DetailedMapData<AnnotationCollection['features'
    */
   get geoJSON(): {
     properties: null;
-    type: _mappedin_mvf_v22.FeatureType;
-    geometry: _mappedin_mvf_v22.Point;
+    type: _mappedin_mvf_v28.FeatureType;
+    geometry: _mappedin_mvf_v28.Point;
   };
   /** @internal */
   get focusTarget(): Coordinate;
@@ -12671,8 +12934,8 @@ declare class MapObject extends DetailedMapData<ObstructionFeature> implements I
    */
   get geoJSON(): {
     properties: null;
-    type: _mappedin_mvf_v22.FeatureType;
-    geometry: _mappedin_mvf_v22.Polygon | _mappedin_mvf_v22.LineString;
+    type: _mappedin_mvf_v28.FeatureType;
+    geometry: _mappedin_mvf_v28.Polygon | _mappedin_mvf_v28.LineString;
   };
   /** @internal */
   get anchorTarget(): Coordinate;
@@ -12985,8 +13248,8 @@ declare class Node extends BaseMetaData implements IGeoJSONData, IFocusable, IAn
    */
   get geoJSON(): {
     properties: null;
-    type: _mappedin_mvf_v22.FeatureType;
-    geometry: _mappedin_mvf_v22.Point;
+    type: _mappedin_mvf_v28.FeatureType;
+    geometry: _mappedin_mvf_v28.Point;
   };
   /** @internal */
   get focusTarget(): Coordinate;
@@ -13026,7 +13289,7 @@ declare class Node extends BaseMetaData implements IGeoJSONData, IFocusable, IAn
  *
  * FloorStacks are used to represent a group of floors that are part of a single entity.
  */
-declare class FloorStack extends BaseMapData implements IGeoJSONData {
+declare class FloorStack extends BaseMapData implements IGeoJSONData, IFocusable {
   #private;
   /**
    * @internal
@@ -13084,6 +13347,10 @@ declare class FloorStack extends BaseMapData implements IGeoJSONData {
    * Gets the facade ({@link Facade}) representing this floor stack, if it exists.
    */
   get facade(): Facade | undefined;
+  /**
+   * Returns this FloorStack as the focus target for the camera.
+   */
+  get focusTarget(): FloorStack;
   /**
    * Gets the underlying GeoJSON Feature representation of this FloorStack.
    *
@@ -13424,7 +13691,7 @@ declare class EnterpriseLocation extends BaseMetaData implements Omit<Enterprise
     parentId?: string;
   });
   /** @internal */
-  get focusTarget(): Space[] | Coordinate[];
+  get focusTarget(): Coordinate[] | Space[];
   /** @internal */
   get navigationTarget(): Space[];
   /**
@@ -15018,7 +15285,7 @@ declare class MapData {
    * console.log(`Current language: ${language.name} (${language.code})`);
    * ```
    */
-  get currentLanguage(): _mappedin_mvf_v22.Language | undefined;
+  get currentLanguage(): _mappedin_mvf_v28.Language | undefined;
   /**
    * Gets the natural bearing of the map.
    *
@@ -15631,13 +15898,14 @@ declare class Mask {
   dirty: boolean;
 }
 //#endregion
-//#region ../renderer-three/src/entities/geometry-group.d.ts
+//#region ../renderer-three/src/entities/batched-geometry-group.d.ts
 /**
- * State representing a Geometry Group, which is a container for Geometries and Models.
+ * State representing a Batched Geometry Group, which is a container for Geometries and Models
+ * rendered via THREE.js BatchedMesh.
  */
-type GeometryGroupState = {
+type BatchedGeometryGroupState = {
   readonly id: string | number;
-  readonly type: 'geometry-group';
+  readonly type: 'batched-geometry-group';
   /**
    * The ids of the children of the geometry group
    */
@@ -15688,9 +15956,9 @@ type GeometryGroupState = {
    */
   position: Position$2;
 };
-declare class GeometryGroupObject3D extends Object3D {
+declare class BatchedGeometryGroupObject3D extends Object3D {
   visible: boolean;
-  readonly type: "geometry-group";
+  readonly type: "batched-geometry-group";
   components: [Mask?];
   getComponent(type: 'mask'): Mask | undefined;
   userData: {
@@ -15708,8 +15976,9 @@ declare class GeometryGroupObject3D extends Object3D {
   removeEntity(): void;
   constructor(id: string);
   /**
-   * Get first child entity of a group if it's a batched mesh
-   * We use this logic a lot for getting the material of the group. since group does not have material and batched mesh does
+   * Get first child entity of a group if it's a batched mesh.
+   * We use this logic a lot for getting the material of the group, since the group does not have
+   * a material and the batched mesh does.
    */
   getfirstChildEntityId(): string | number | undefined;
 }
@@ -15721,7 +15990,7 @@ declare class InteractionComponent {
   dirty: boolean;
 }
 //#endregion
-//#region ../renderer-three/src/systems/mesh-creation-and-optimization/batched-material.d.ts
+//#region ../renderer-three/src/systems/batched-mesh/batched-material.d.ts
 declare class BatchedStandardMaterial extends MeshLambertMaterial {
   private propertiesTexture;
   texturesVisible: boolean;
@@ -15908,7 +16177,7 @@ type GeometryState = {
   /**
    * The parent group of the geometry
    */
-  readonly parent: EntityId$1<GeometryGroupState>;
+  readonly parent: EntityId$1<BatchedGeometryGroupState>;
   /**
    * Whether the geometry is visible. This is independent of the visibility of the children, but will affect the visibility of the children if set to false.
    */
@@ -16070,7 +16339,7 @@ type ModelState = {
   /**
    * The parent container of the marker
    */
-  readonly parent?: EntityId$1<GeometryGroupState> | string | number;
+  readonly parent?: EntityId$1<BatchedGeometryGroupState> | string | number;
   /**
    * The position of the model in [lon, lat]
    */
@@ -16147,6 +16416,19 @@ type BorderConfig = {
   /** Border width as fraction of total ribbon width (0-0.5). @default 0.1 */
   width?: number;
 };
+/**
+ * @experimental
+ * Configuration for the x-ray appearance of paths behind geometry.
+ */
+type XrayStyleConfig = {
+  /** Explicit color override for the x-ray base color. When omitted, uses the path color. Tint is always applied on top. */
+  color?: string;
+  /** Tint strength (0-1) controlling how much the color is desaturated.
+   *  0 = no muting (same as base color), 1 = fully gray. @default 0.2 */
+  tint?: number;
+  /** Dithering cell size in screen pixels. 0 or undefined = off. */
+  dithering?: number;
+};
 type PathProperties = {
   /**
    * The parentId of the point. The point will be anchored to the altitude of this parent group container.
@@ -16207,9 +16489,10 @@ type PathState$1 = {
    */
   animateArrowsOnPath: boolean;
   /**
-   * The width of the path in meters. Can be a number or an {@link Interpolation}.
+   * The width of the path. Can be a number (meters), a pixel string like '20px',
+   * or an {@link Interpolation} (meters or pixels).
    */
-  width: number | Interpolation$2<'zoom-level', number[]>;
+  width: PathWidth$3;
   /**
    * The fraction of the path that should be highlighted. This can be used to animate the highlight.
    * @default 0
@@ -16224,6 +16507,11 @@ type PathState$1 = {
    * @default 0.25
    */
   xrayOpacity: number;
+  /**
+   * @experimental
+   * Configuration for x-ray appearance when path is behind geometry.
+   */
+  xrayStyle?: XrayStyleConfig;
   /**
    * Controls the smoothness of path corners using CatmullRom curve tension. Higher values create smoother curves.
    * Values between 0.1-0.3 provide subtle smoothing suitable for most use cases.
@@ -16292,7 +16580,7 @@ type PathState$1 = {
    * Most useful for vertical paths between floors.
    * @default false
    */
-  __EXPERIMENTAL_BILLBOARDING: boolean;
+  __EXPERIMENTAL_BILLBOARDING: boolean | number;
   /**
    * @experimental
    * Border configuration for ribbon path geometry.
@@ -16319,10 +16607,14 @@ type AddPathOptions = {
   id?: string | number;
   /**
    * The width of the path.
+   * - `number` — meters (e.g. `1.5`)
+   * - `'Npx'` — screen-space pixels (e.g. `'20px'`)
+   * - `Interpolation` — zoom-interpolated meters
+   * - `Interpolation<'zoom-level', PixelWidth[]>` — zoom-interpolated pixels (e.g. `output: ['10px', '20px']`)
    *
    * @default Interpolation { on: 'zoom-level', input: [17, 22], output: [0.8, 0.4] }
    */
-  width?: number | Interpolation$2<'zoom-level', number[]>;
+  width?: PathWidth$3;
   /**
    * The color of the path.
    */
@@ -16365,6 +16657,11 @@ type AddPathOptions = {
    * @default 0.25
    */
   xrayOpacity?: number;
+  /**
+   * @experimental
+   * Configuration for x-ray appearance when path is behind geometry.
+   */
+  xrayStyle?: XrayStyleConfig;
   /**
    * Controls the smoothness of path corners using CatmullRom curve tension. Higher values create smoother curves.
    * Values between 0.1-0.3 provide subtle smoothing suitable for most use cases.
@@ -16439,7 +16736,7 @@ type AddPathOptions = {
    * Most useful for vertical paths between floors.
    * @default false
    */
-  __EXPERIMENTAL_BILLBOARDING?: boolean;
+  __EXPERIMENTAL_BILLBOARDING?: boolean | number;
   /**
    * @experimental
    * Border configuration for ribbon path geometry.
@@ -16463,8 +16760,12 @@ declare class PathComponent {
   outline?: LineSegments;
   feature: FeatureCollection<Point, PathProperties>;
   options: AddPathOptions;
-  width: number | Interpolation$2<'zoom-level', number[]>;
+  width: PathWidth$3;
   breakpoint: number;
+  /** Whether width is in screen-space pixels (derived from width value). */
+  screenSpace: boolean;
+  /** Pre-parsed numeric output values for interpolated widths. Avoids parseFloat on every frame. */
+  parsedOutputValues: number[];
   altitudeBreakpoints?: number[];
   accentColor: string;
   completeFraction: number;
@@ -16478,6 +16779,7 @@ declare class PathComponent {
   highlightWidthMultiplier: number;
   highlightColor: string;
   xrayOpacity: number;
+  xrayStyle?: XrayStyleConfig;
   dashed: boolean;
   smoothingTension: number;
   smoothingCornerRadius: number;
@@ -16491,7 +16793,7 @@ declare class PathComponent {
   gapMeters: number;
   __EXPERIMENTAL_GEOMETRY: 'tube' | 'ribbon';
   __EXPERIMENTAL_ENDCAP_EXTENSION: [number, number];
-  __EXPERIMENTAL_BILLBOARDING: boolean;
+  __EXPERIMENTAL_BILLBOARDING: boolean | number;
   __EXPERIMENTAL_BORDER?: BorderConfig;
   __EXPERIMENTAL_PREVENT_SELF_OVERLAP: boolean;
   /**
@@ -16501,6 +16803,7 @@ declare class PathComponent {
   dirty: boolean;
   materialDirty: boolean;
   constructor(feature: FeatureCollection<Point, PathProperties>, options?: AddPathOptions);
+  updateScreenSpaceState(): void;
   setColor(): void;
   setOpacity(): void;
   set visible(visible: boolean);
@@ -16845,7 +17148,7 @@ declare class Geometry3D<M$1 extends MeshComponentTypes = MeshComponent, S exten
    */
   parentId?: string | number;
   get object3d(): M$1["mesh"];
-  get parentObject3D(): GroupContainerObject3D | GeometryGroupObject3D | null;
+  get parentObject3D(): GroupContainerObject3D | BatchedGeometryGroupObject3D | null;
   type: T$1;
   entities2D: Map<string | number, Geometry2D>;
   constructor(meshComponent: M$1, styleComponent: S);
@@ -16942,6 +17245,10 @@ interface PathUniforms {
     type: 'b';
     value: boolean;
   };
+  xrayDithering: {
+    type: 'f';
+    value: number;
+  };
   highlightStartFraction: {
     type: 'f';
     value: number;
@@ -16998,9 +17305,9 @@ interface PathUniforms {
     type: 'b';
     value: boolean;
   };
-  billboarded: {
-    type: 'b';
-    value: boolean;
+  billboardThreshold: {
+    type: 'f';
+    value: number;
   };
   borderEnabled: {
     type: 'b';
@@ -17026,6 +17333,14 @@ interface PathUniforms {
     type: 'm4';
     value: Matrix4;
   };
+  screenSpace: {
+    type: 'b';
+    value: boolean;
+  };
+  metersPerPixel: {
+    type: 'f';
+    value: number;
+  };
 }
 //#endregion
 //#region ../renderer-three/src/services/renderer.d.ts
@@ -17242,8 +17557,8 @@ declare class ExporterSystem {
   destroy(): void;
 }
 //#endregion
-//#region ../renderer-three/src/systems/mesh-creation-and-optimization/system.d.ts
-declare class MeshCreationAndOptimizationSystem extends PubSub<{
+//#region ../renderer-three/src/systems/batched-mesh/system.d.ts
+declare class BatchedMeshSystem extends PubSub<{
   'geometry-2d-added': void;
   'geometry-group-added': void;
 }> {
@@ -17904,6 +18219,17 @@ declare class CameraSystem extends PubSub<CameraEvents> {
   getCurrentMetersPerPixel(): number;
 }
 //#endregion
+//#region ../renderer-three/src/camera-debug.d.ts
+type FocusOnDebugConfig = {
+  pointCloud?: {
+    size?: number;
+    color?: string;
+  } | false;
+  boundingBox?: {
+    color?: string;
+  } | false;
+} | false;
+//#endregion
 //#region ../renderer-three/src/camera.d.ts
 type AnimationOptions = {
   duration?: number;
@@ -17920,6 +18246,10 @@ type FocusOnOptions = AnimationOptions & {
   maxZoomLevel?: number;
   interruptible?: boolean;
   verticalPadding?: number;
+  /** Debug key — the target object used as a Map key so multiple debug visualizations coexist. */
+  debugKey?: object;
+  /** Debug color override (CSS color string) for this point cloud. */
+  debugColor?: string;
 };
 type AnimateToOptions = AnimationOptions & {
   center?: Position$2;
@@ -18097,6 +18427,16 @@ declare class Camera$2 extends PubSub<{
    * @internal
    */
   hideCameraTargetsDebug(): void;
+  /**
+   * Enable 3D debug visualization of the focusOn point cloud and bounding boxes.
+   * @internal
+   */
+  showFocusOnDebug(cfg: FocusOnDebugConfig): void;
+  /**
+   * Disable 3D debug visualization of the focusOn point cloud and bounding boxes.
+   * @internal
+   */
+  hideFocusOnDebug(): void;
   /**
    * Enable debug visualization of screen offsets.
    * Shows colored overlays for each padding area.
@@ -18364,7 +18704,7 @@ declare class OutlineInterpolationSystem extends PubSub<{
    * @param options - Optional configuration for outline rendering
    */
   constructor(rendererState: RendererState, options?: OutlinesOptions$1);
-  buildOutlines(geometryGroupEntity: GeometryGroupObject3D): void;
+  buildOutlines(geometryGroupEntity: BatchedGeometryGroupObject3D): void;
   /**
    * Update the outline color of all entities with an outline component.
    * @param zoomLevel - The current zoom level.
@@ -18526,7 +18866,7 @@ declare class PathSystem extends PubSub<{
   getParentContainer: Core['getParentContainer'];
   convertZoomLevelToAltitude: CameraSystem['convertZoomLevelToAltitude'];
   constructor(rendererState: RendererState, convertTo3DMapPosition: Core['convertTo3DMapPosition'], getParentContainer: Core['getParentContainer'], convertZoomLevelToAltitude: CameraSystem['convertZoomLevelToAltitude']);
-  update(minZoomAltitude: number, maxZoomAltitude: number, currentZoomAltitude: number): void;
+  update(minZoomAltitude: number, maxZoomAltitude: number, currentZoomAltitude: number, metersPerPixel: number): void;
 }
 //#endregion
 //#region ../renderer-three/src/systems/mesh-detachment/system.d.ts
@@ -18633,12 +18973,17 @@ declare const DEFAULT_DEBUG_STATE: {
    * - Cyan box: getFocusOnTransform bounding area
    */
   showCameraTargets: boolean;
+  /**
+   * Shows focusOn 3D debug visualization (point cloud spheres and/or wireframe bounding boxes).
+   * Pass `{ pointCloud?: { size?, color? } | false, boundingBox?: { color? } | false }` to configure.
+   */
+  focusOn: FocusOnDebugConfig;
 };
 /**
  * Type definition for the debug state configuration.
  * Represents all available debug options that can be toggled.
  */
-type DebugState = typeof DEFAULT_DEBUG_STATE;
+type DebugState$2 = typeof DEFAULT_DEBUG_STATE;
 /**
  * Debug utility class for toggling various debug visualization features.
  *
@@ -18697,6 +19042,11 @@ declare class Debug$1 {
      * - Cyan box: getFocusOnTransform bounding area
      */
     showCameraTargets: boolean;
+    /**
+     * Shows focusOn 3D debug visualization (point cloud spheres and/or wireframe bounding boxes).
+     * Pass `{ pointCloud?: { size?, color? } | false, boundingBox?: { color? } | false }` to configure.
+     */
+    focusOn: FocusOnDebugConfig;
   };
   /** Reference to the core renderer instance */
   core: Core;
@@ -18724,7 +19074,7 @@ declare class Debug$1 {
    * });
    * ```
    */
-  update(updateState: Partial<DebugState>): void;
+  update(updateState: Partial<DebugState$2>): void;
   /**
    * Handles the actual system updates based on changed debug state values.
    * This method applies the debug state changes to the appropriate renderer systems.
@@ -18888,17 +19238,118 @@ declare class ClippingPlaneSystem {
 }
 //#endregion
 //#region ../renderer-three/src/systems/system-plugins/system.d.ts
+/**
+ * **Super experimental — this API may change or be removed in any release without notice.
+ * Do not depend on it in production.**
+ *
+ * Interface for plugins that hook into the Mappedin render loop.
+ *
+ * Plugins receive the full renderer state every frame, providing direct access
+ * to the Three.js scene, camera, renderer, lighting, and all ECS geometry entities.
+ * Use this to inject custom Three.js objects, apply per-frame effects, or read scene state.
+ *
+ * ## Lifecycle
+ *
+ * - `update()` is called **every frame** during the finalization phase of the render loop
+ *   (after camera, path, and 2D systems have run, but before `DrawSystem` applies
+ *   style changes and before `paint()` draws the frame).
+ * - Plugins are called in registration order.
+ *
+ * ## Standalone vs. Overlay Mode
+ *
+ * | Concern | Standalone | MapLibre Overlay |
+ * |---|---|---|
+ * | Add meshes to | `state.threeJSScene` | `state.geometryScene` |
+ * | Camera position | Reflects actual viewer position | **Not reliable** — MapLibre overwrites the projection matrix each frame |
+ * | Coordinate space | Scene units (meters from map center) | Scene units (meters from map center) |
+ *
+ * ## Performance
+ *
+ * `update()` runs on the main thread every frame. Avoid heavy computation, allocations,
+ * or GPU-blocking operations. Gate one-time work behind an initialization flag.
+ *
+ * @example
+ * ### Adding a custom Three.js mesh
+ * ```ts
+ * import { type ISystemPlugin, type TRendererState } from '@mappedin/mappedin-js';
+ * import { Mesh, MeshStandardMaterial, SphereGeometry } from 'three';
+ *
+ * class SpherePlugin implements ISystemPlugin {
+ *   private sphere: Mesh | null = null;
+ *
+ *   update(state: TRendererState): void {
+ *     // One-time setup — add a sphere to the scene
+ *     if (!this.sphere) {
+ *       const geo = new SphereGeometry(3, 32, 32);
+ *       const mat = new MeshStandardMaterial({ color: 0xff4444 });
+ *       this.sphere = new Mesh(geo, mat);
+ *       // Use geometryScene for overlay mode, threeJSScene for standalone
+ *       state.geometryScene.add(this.sphere);
+ *     }
+ *     this.sphere.rotation.y += 0.01;
+ *   }
+ * }
+ *
+ * mapView.registerPlugin(new SpherePlugin());
+ * ```
+ *
+ * @example
+ * ### Reading ECS component data
+ * ```ts
+ * class InspectorPlugin implements ISystemPlugin {
+ *   update(state: TRendererState): void {
+ *     for (const geometry of state.geometry3DsInScene) {
+ *       const style = geometry.getComponent('style');
+ *       if (style) {
+ *         console.log(geometry.id, style.color, style.opacity);
+ *       }
+ *     }
+ *   }
+ * }
+ * ```
+ *
+ * @example
+ * ### Mutating ECS styles (mark dirty to apply)
+ * ```ts
+ * class HighlightPlugin implements ISystemPlugin {
+ *   update(state: TRendererState): void {
+ *     for (const geometry of state.geometry3DMap.values()) {
+ *       const style = geometry.getComponent('style');
+ *       if (style) {
+ *         style.color = 'red';
+ *         style.dirty = true; // Required — triggers DrawSystem to apply the change
+ *       }
+ *     }
+ *   }
+ * }
+ * ```
+ *
+ * @experimental
+ */
 interface ISystemPlugin$2 {
   /**
+   * Called every frame with the current renderer state.
    *
-   * @param state - The current state of the renderer.
+   * @param state - The renderer state snapshot for this frame. Contains Three.js objects
+   *   (`threeJSScene`, `renderer`, `cameraObject`, `directionalLight`, `ambientLight`),
+   *   the geometry scene graph (`geometryScene`), and all ECS entity maps
+   *   (`geometry3DMap`, `geometry3DsInScene`, `geometry2DMap`, `geometry2DsInScene`).
    */
   update(state: RendererState): void;
 }
+/**
+ * Manages registered {@link ISystemPlugin} instances and invokes them each frame.
+ *
+ * @internal — Not part of the public API. Use {@link MapView.registerPlugin} and
+ * {@link MapView.unregisterPlugin} instead.
+ */
 declare class PluginSystem {
   private plugins;
+  /** @internal */
   registerPlugin(plugin: ISystemPlugin$2): void;
+  /** @internal */
   unregisterPlugin(plugin: ISystemPlugin$2): void;
+  /** @internal */
   update(state: RendererState): void;
 }
 //#endregion
@@ -19213,7 +19664,7 @@ declare class ModelSystem extends PubSub<{
    * @param tree - The geometry group container
    * @returns The created Object3D containing the model instances
    */
-  populateModelGroup(entities: Set<string | number>, url: string, tree: GeometryGroupObject3D): Promise<Geometry3DObject3D>;
+  populateModelGroup(entities: Set<string | number>, url: string, tree: BatchedGeometryGroupObject3D): Promise<Geometry3DObject3D>;
   /**
    * Updates the model system, processing any pending model loads and style updates
    * @returns A promise that resolves when all model loading is complete
@@ -19298,6 +19749,8 @@ declare class TwoDEntitySystem {
   constructor(container: HTMLElement, state: RendererState, pipelineState: TwoDPipelineState, projectFn: (out: Vector2, v3: Vector3) => void, options?: TwoDPipelineOptions);
   /** Returns the internal pipeline for direct access (test use only). */
   get pipeline(): TwoDPipeline;
+  /** @internal Canvas used for rendering 2D labels. */
+  get labelCanvas(): HTMLCanvasElement;
   /** Quad tree of interactive colliders for hit testing. */
   get interactiveCollidersQTree(): QuadTree<{
     entityId: string | number;
@@ -19387,7 +19840,7 @@ type Systems = {
   panBoundsSystem: PanBoundsSystem;
   twoDEntitySystem: TwoDEntitySystem;
   interactionSystem: InteractionSystem;
-  meshOptimizationSystem: MeshCreationAndOptimizationSystem;
+  batchedMeshSystem: BatchedMeshSystem;
   modelSystem: ModelSystem;
   drawSystem: DrawSystem;
   renderSystem: RenderSystem;
@@ -19488,9 +19941,10 @@ declare class Core extends PubSub<MapEvent> {
   registerPlugin(plugin: ISystemPlugin$2): void;
   unregisterPlugin(plugin: ISystemPlugin$2): void;
   /**
-   * Add a geometry group from GeoJSON data
+   * Add a batched geometry group from GeoJSON data.
+   * Features are batched into a single BatchedMesh per material group for efficient rendering.
    */
-  addGeometryGroup<T$1 extends FeatureCollection<Polygon | MultiPolygon | LineString, any>>(id: string, geometry: T$1, style?: (T$1 extends FeatureCollection<LineString, any> ? LineStyle$2 : PaintStyle$2) | ((feature: Feature<Polygon | MultiPolygon | LineString, any>) => T$1 extends FeatureCollection<LineString, any> ? LineStyle$2 : PaintStyle$2), parent?: EntityId$1<GroupContainerState$1> | string | number | null): EntityId$1<GeometryGroupState>;
+  addBatchedGeometryGroup<T$1 extends FeatureCollection<Polygon | MultiPolygon | LineString, any>>(id: string, geometry: T$1, style?: (T$1 extends FeatureCollection<LineString, any> ? LineStyle$2 : PaintStyle$2) | ((feature: Feature<Polygon | MultiPolygon | LineString, any>) => T$1 extends FeatureCollection<LineString, any> ? LineStyle$2 : PaintStyle$2), parent?: EntityId$1<GroupContainerState$1> | string | number | null): EntityId$1<BatchedGeometryGroupState>;
   addOccluder<T$1 extends Feature<Polygon | MultiPolygon, any>>(feature: T$1, parent?: EntityId$1<GroupContainerState$1> | string | number | null): number;
   addImage(id: string, geometry: Feature<Point, ImageProperties>, style: ImageStyle, parent?: EntityId$1<GroupContainerState$1> | string | null): EntityId$1<ImageState> | undefined;
   /**
@@ -19502,7 +19956,7 @@ declare class Core extends PubSub<MapEvent> {
   }?: {
     parent?: EntityId$1<GroupContainerState$1> | string | null;
     onComplete?: () => void;
-  }): EntityId$1<GeometryGroupState> | undefined;
+  }): EntityId$1<BatchedGeometryGroupState> | undefined;
   /**
    * Add an HTML Marker at a GeoJSON coordinate.
    */
@@ -19584,9 +20038,9 @@ declare class Core extends PubSub<MapEvent> {
    * Get the current state of the map view, or any entity that was added, regardless of whether it is visible in the scene
    */
   getState(): MapViewState$1;
-  getState<T$1 extends EntityId$1<EntityState>>(geometryOrGeometryId: T$1): T$1 extends EntityId$1<LabelState> ? LabelState : T$1 extends EntityId$1<GeometryState> ? GeometryState : T$1 extends EntityId$1<MarkerState$1> ? MarkerState$1 : T$1 extends EntityId$1<GeometryGroupState> ? GeometryGroupState : T$1 extends EntityId$1<GroupContainerState$1> ? GroupContainerState$1 : T$1 extends EntityId$1<ModelState> ? ModelState : T$1 extends EntityId$1<PathState$1> ? PathState$1 : T$1 extends EntityId$1<ShapeState> ? ShapeState : T$1 extends EntityId$1<ImageState> ? ImageState : T$1 extends EntityId$1<Text3DState$1> ? Text3DState$1 : EntityState;
+  getState<T$1 extends EntityId$1<EntityState>>(geometryOrGeometryId: T$1): T$1 extends EntityId$1<LabelState> ? LabelState : T$1 extends EntityId$1<GeometryState> ? GeometryState : T$1 extends EntityId$1<MarkerState$1> ? MarkerState$1 : T$1 extends EntityId$1<BatchedGeometryGroupState> ? BatchedGeometryGroupState : T$1 extends EntityId$1<GroupContainerState$1> ? GroupContainerState$1 : T$1 extends EntityId$1<ModelState> ? ModelState : T$1 extends EntityId$1<PathState$1> ? PathState$1 : T$1 extends EntityId$1<ShapeState> ? ShapeState : T$1 extends EntityId$1<ImageState> ? ImageState : T$1 extends EntityId$1<Text3DState$1> ? Text3DState$1 : EntityState;
   getState(geometryOrGeometryId?: Record<string | number, any> | string | number): EntityState;
-  getState<T$1 extends EntityState>(geometryOrGeometryId: T$1['id']): T$1 extends LabelState ? LabelState : T$1 extends GeometryState ? GeometryState : T$1 extends MarkerState$1 ? MarkerState$1 : T$1 extends GeometryGroupState ? GeometryGroupState : T$1 extends GroupContainerState$1 ? GroupContainerState$1 : T$1 extends ModelState ? ModelState : T$1 extends PathState$1 ? PathState$1 : T$1 extends ShapeState ? ShapeState : T$1 extends ImageState ? ImageState : EntityState;
+  getState<T$1 extends EntityState>(geometryOrGeometryId: T$1['id']): T$1 extends LabelState ? LabelState : T$1 extends GeometryState ? GeometryState : T$1 extends MarkerState$1 ? MarkerState$1 : T$1 extends BatchedGeometryGroupState ? BatchedGeometryGroupState : T$1 extends GroupContainerState$1 ? GroupContainerState$1 : T$1 extends ModelState ? ModelState : T$1 extends PathState$1 ? PathState$1 : T$1 extends ShapeState ? ShapeState : T$1 extends ImageState ? ImageState : EntityState;
   /**
    * Get rendered state for an entity (e.g., runtime rendering state that changes frequently)
    * @param entity The entity to get rendered state for
@@ -19599,7 +20053,7 @@ declare class Core extends PubSub<MapEvent> {
   setState(object: Partial<Omit<MapViewState$1, 'type'>>): void;
   setState<T$1 extends EntityId$1<LabelState>>(object: T$1 | T$1['id'], state: Partial<LabelState>): void;
   setState<T$1 extends EntityId$1<MarkerState$1>>(object: T$1 | T$1['id'], state: Partial<MarkerStateUpdate>): void;
-  setState<T$1 extends EntityId$1<GeometryGroupState>>(object: T$1 | T$1['id'], state: Partial<GeometryGroupState>): void;
+  setState<T$1 extends EntityId$1<BatchedGeometryGroupState>>(object: T$1 | T$1['id'], state: Partial<BatchedGeometryGroupState>): void;
   setState<T$1 extends EntityId$1<GroupContainerState$1>>(object: T$1 | T$1['id'], state: Partial<GroupContainerState$1>): void;
   setState<T$1 extends EntityId$1<GeometryState>>(object: T$1 | T$1['id'], state: Partial<GeometryState>): void;
   setState<T$1 extends EntityId$1<ShapeState>>(object: T$1 | T$1['id'], state: Partial<ShapeState>): void;
@@ -19785,7 +20239,7 @@ type GroupContainerState$1 = {
   /**
    * The states of the children of the group container
    */
-  readonly children: (PathState$1 | MarkerState$1 | LabelState | GroupContainerState$1 | GeometryGroupState)[];
+  readonly children: (PathState$1 | MarkerState$1 | LabelState | GroupContainerState$1 | BatchedGeometryGroupState)[];
   /**
    * Whether the group container is visible
    */
@@ -19807,7 +20261,7 @@ type GroupContainerState$1 = {
 };
 declare class GroupContainerObject3D extends Object3D {
   childrenIds: Set<string | number>;
-  children: (GroupContainerObject3D | GeometryGroupObject3D | BatchedText$1 | Geometry2D['object3d'] | NonNullable<Geometry3D['object3d']>)[];
+  children: (GroupContainerObject3D | BatchedGeometryGroupObject3D | BatchedText$1 | Geometry2D['object3d'] | NonNullable<Geometry3D['object3d']>)[];
   getComponent(): void;
   readonly type: "group-container";
   userData: {
@@ -19828,7 +20282,7 @@ declare class GroupContainerObject3D extends Object3D {
   components: [InteractionComponent?, FocusableComponent?];
   constructor(id: string);
   addOccluderFeature(feature: Feature<Polygon | MultiPolygon, any>, occluderId: number): void;
-  addEntity(entityGroupOrContainer: GroupContainerObject3D | GeometryGroupObject3D | Geometry2D | Geometry3DTypes): void;
+  addEntity(entityGroupOrContainer: GroupContainerObject3D | BatchedGeometryGroupObject3D | Geometry2D | Geometry3DTypes): void;
   removeEntity(entityGroupOrContainer: EntityTypes): void;
   setVisible(visible: boolean): void;
   setAltitude(altitude: number): void;
@@ -19869,7 +20323,7 @@ declare class Geometry2D {
   type: 'label' | 'marker';
   /** Lightweight entity for the 2D pipeline */
   entity2D: Entity2D;
-  get parentObject3D(): GroupContainerObject3D | GeometryGroupObject3D | null;
+  get parentObject3D(): GroupContainerObject3D | BatchedGeometryGroupObject3D | null;
   /** The geometry3D that this 2D entity is attached to */
   get attachedTo(): string | number | undefined;
   verticalOffset: number;
@@ -19879,6 +20333,12 @@ declare class Geometry2D {
   disposed: boolean;
   constructor(ui: MarkerComponent | LabelComponent, position: Vector3, verticalOffset?: number);
   private worldPosition;
+  /**
+   * Recomputes the cached world position from the Object3D scene graph.
+   * matrixAutoUpdate must be temporarily enabled so updateWorldMatrix
+   * (called internally by getWorldPosition) incorporates parent transforms.
+   */
+  private computeWorldPosition;
   get position(): Vector3;
   /**
    * When the position of the entity changes, this should be set to true, so that systems like pan bounds can update
@@ -19887,8 +20347,16 @@ declare class Geometry2D {
   set positionDirty(value: boolean);
   updatePosition(position: Vector3): void;
   setAltitude(z: number): void;
-  /** Copies the ThreeJS world position to the lightweight Entity2D */
+  /**
+   * Copies the ThreeJS world position to the lightweight Entity2D.
+   * Uses the position getter which clears positionDirty.
+   */
   syncPosition(): void;
+  /**
+   * Syncs the Entity2D world position without clearing positionDirty,
+   * so that downstream systems (e.g. pan bounds) still see the dirty flag.
+   */
+  private syncEntity2DWorldPosition;
 }
 //#endregion
 //#region ../renderer-three/src/types/geometry.d.ts
@@ -20052,53 +20520,11 @@ type ShadowsOptions = {
   visibleAtZoomLevel?: number;
 };
 //#endregion
-//#region ../renderer-three/src/types/interpolation.d.ts
-/**
- * Different properties that can be interpolated on, and what input values are expected.
- */
-type InterpolateOn$1 = {
-  'zoom-level': number[];
-};
-/**
- * Define interpolation behavior for a value.
- * @example
- * ```ts
- * // Interpolate a value from 1 to 2 between zoom levels 17 and 18 with easing
- * const value: Interpolation<'zoom-level', [number, number]> = {
- *  on: 'zoom-level',
- * 	input: [17, 18],
- * 	output: [1, 2],
- * 	easing: 'ease-in',
- * };
- */
-type Interpolation$2<T$1 extends keyof InterpolateOn$1, U$1 extends unknown[]> = {
-  /**
-   * The property to observe when interpolating.
-   *
-   * @defaultValue 'zoom-level'
-   */
-  on: T$1;
-  /**
-   * Breakpoints in the observed property.
-   */
-  input: [InterpolateOn$1[T$1][number], ...InterpolateOn$1[T$1]];
-  /**
-   * Output values corresponding to the input breakpoints.
-   */
-  output: [U$1[number], ...U$1];
-  /**
-   * The easing function to use for the interpolation.
-   *
-   * @defaultValue 'linear'
-   */
-  easing?: EasingCurve;
-};
-//#endregion
 //#region ../renderer-three/src/types/index.d.ts
 /**
  * The state of an entity, which can be a geometry, geometry group, group container, path, model, label, or marker.
  */
-type EntityState = GeometryState | GeometryGroupState | GroupContainerState$1 | PathState$1 | ModelState | LabelState | MarkerState$1 | ImageState | Text3DState$1 | ShapeState;
+type EntityState = GeometryState | BatchedGeometryGroupState | GroupContainerState$1 | PathState$1 | ModelState | LabelState | MarkerState$1 | ImageState | Text3DState$1 | ShapeState;
 /**
  * A wrapper object that contains the ID and type of an entity. This is returned when adding entities to the scene, and can be used
  * to `getState` and `setState` of the entity.
@@ -20379,7 +20805,7 @@ type MapEvent = {
 /**
  * All entities in 3D
  */
-type All3DTypes = Geometry3DTypes | GeometryGroupObject3D | GroupContainerObject3D;
+type All3DTypes = Geometry3DTypes | BatchedGeometryGroupObject3D | GroupContainerObject3D;
 type RendererState = {
   /**
    * A map of all 3D geometries in the world.
@@ -20410,7 +20836,7 @@ type RendererState = {
   /**
    * IDs of geometry groups that need to be loaded, including preloaded geometry groups that are not in the scene yet
    */
-  readonly geometryGroupIdsToLoad: Set<GeometryGroupObject3D['userData']['entityId']>;
+  readonly geometryGroupIdsToLoad: Set<BatchedGeometryGroupObject3D['userData']['entityId']>;
   readonly geometryScene: GroupContainerObject3D;
   hoverColor: string;
   text3dHoverColor: string;
@@ -20450,7 +20876,7 @@ type RendererState = {
 /**
  * All of the entities in the scene
  */
-type EntityTypes = Geometry3DTypes | Geometry2D | GeometryGroupObject3D | GroupContainerObject3D;
+type EntityTypes = Geometry3DTypes | Geometry2D | BatchedGeometryGroupObject3D | GroupContainerObject3D;
 /** @internal */
 type TransformImageRequest = (url: string) => Promise<{
   url: string;
@@ -21090,4 +21516,4 @@ declare const getVersion: () => string | undefined;
  */
 declare const show3dMapGeojson: (el: HTMLElement, mapData: MapData, options?: TShow3DMapOptions) => Promise<MapView>;
 //#endregion
-export { ACTION_TYPE, ANIMATION_TWEENS, type AddText3DOptions, type Analytics, Annotation, Area, type AutoElements, BBox, BEARING_TYPE, CONNECTION_TYPE, type Camera, type CameraBounds, type CameraTransform, type CaptureEventsPayloadMap, type ColorString, Connection, Coordinate, DOORS, type Debug, DetailedMapData, Directions, Door, E_SDK_LOG_LEVEL, EnterpriseCategory, EnterpriseLocation, EnterpriseVenue, type EnvMapOptions, type Environment, type Exporter, Facade, Feature, FeatureCollection, Floor, FloorStack, type FootprintConfig, GeoJSON$1 as GeoJSON, GeoJsonGeometryTypes, GeoJsonObject, GeoJsonProperties, GeoJsonTypes, Geometry, GeometryCollection, GeometryObject, type GlobalState, Hyperlink, type IAnchorable, type IFocusable, type IGeoJSONData, type INavigatable, type ISystemPlugin, type Image3D, type Image3DView, ImageMetaData, type InitializeModelState, type InitializeText3DState, type InsetPadding, type InsetPaddingOption, type InterpolateOn, type Interpolation, type Label, type LabelAppearance, type LabelTextPlacement, type Labels, LineString, type LineStyle, LocationCategory, LocationProfile, type LocationSocial, type LocationState, MAPPEDIN_COLORS, type MapData, type MapDataElements, type MapElementToGetRenderedState, type MapElementToGetState, type MapElementToUpdateState, type MapElementsWithState, type MapFeatureOfType, MapObject, MapView, type MapViewElements, type MapViewState, type MappedinError, type MappedinRenderError, type Marker, type Markers, type MatchInfo, type Model, type Models, type MultiFloorViewEffectState, MultiLineString, MultiPoint, MultiPolygon, type Navigation, type NavigationState, Node, type OpeningHours, type OperationHours, type Outdoor, type OutlinesOptions, type PaintStyle, type Path, type PathSegment$1 as PathSegment, type Paths, type Places, Point, PointOfInterest, Polygon, type Position, type PubSub, type Query, type RendererCoreOptions, type Search, type SearchOptions, type SearchResult, type SearchResultEnterpriseCategory, type SearchResultEnterpriseLocations, type SearchResultItem, type SearchResultPlaces, type Shading, type Shape, type Shapes, type SiblingGroup, Space, type Style, type Suggestion, type TActionType, type TAddImageOptions, type TAddLabelOptions, type TAddMarkerOptions, type TAddModel, type TAddModelOptions, type TAddPathOptions, type TAddText3DAnchorableOptions, type TAddText3DOptions, type TAnalyticsUpdateState, type TAnimateStateResult, type TAnimationOptions, type TAntialiasingOptions, type TBearingType, type TCameraAnimationOptions, type TCameraInteractionsSetOptions, type TCameraTarget, type TCancellablePromise, type TClickPayload, type TCollisionRankingTier, type TConnectionPathOptions, type TConnectionType, type TCoordinateParams, type TCreateMarker, type TDirectionInstruction, type TDirectionInstructionAction, type TDirectionZone, type TDoorsState, type TDoorsUpdateState, type TEasingFunction, type TEventPayload, type TEvents, type TFacadeState, type TFacadeUpdateState, type TFindNearestOptions, type TFindNearestResult, type TFindPreferredLanguageInVenueOptions, type TFloorAltitudeData, type TFloorChangePayload, type TFloorChangeReason, type TFloorState, type TFloorUpdateState, type TFocusOnOptions, type TFocusTarget, type TGeometryState, type TGeometryUpdateState, type TGetDirectionsOptions, type TGetMapDataOptions, type TGetMapDataSharedOptions, type TGetMapDataWithAccessTokenOptions, type TGetMapDataWithCredentialsOptions, type TGetState, type THoverPayload, type THydrateMapDataBundle, type TImage3DState as TImageState, type TImage3DUpdateState as TImageUpdateState, type TLabelState, type TLabelUpdateState, type TMVF, type TMVFLineStringStyle, type TMVFPointStyle, type TMVFPolygonStyle, type TMVFStyle, type TMVFStyleCollection, type TMapDataEvents, type TMapDataObjectTypes, type TMapFeatureTypes, type TMapViewObjectTypes, type TMarkerPlacement, type TMarkerState, type TMarkerUpdateState, type TModelState, type TModelUpdateState, type TMultiFloorViewOptions, type TNavigationOptions, type TNavigationPathOptions, type TNavigationTarget, type TPathSectionHighlightOptions, type TPathState, type TPathUpdateState, type TQueriables, type TQueryAtResult, type RendererState as TRendererState, type TSearchOptions, type TSetFloorOptions, type TShapeState, type TShapeUpdateState, type TShow3DMapOptions, type TSpaceType, type TStateChangedInternalPayload, type TTakeScreenshotOptions, type TText3DState, type TText3DUpdateState, type TUpdateState, type TWallsState, type TWallsUpdateState, TWatermarkOptions, type Text3D, type Text3DView, type UpdateGlobalState, type VisibilityState, WALLS, type WithState, MapLibreOverlay as __INTERNAL__MapLibreOverlay, __setWatermarkOnClickFn, checkWorkerUrls, disableText3DWorker, enableTestMode, findPreferredLanguageInVenue, forceEnterpriseLocations, getMapData, getMapDataEnterprise, getMultiFloorState, getVersion, hydrateMapData, hydrateMapDataFromMVF, parseMVFv2 as parseMVF, preloadFont, setLoggerLevel, setUseEnterpriseAPI, setWorkersUrl, shouldForceEnterpriseLocations, show3dMap, show3dMapGeojson, unzipAndParseMVFv2, unzipMVFv2 as unzipMVF };
+export { ACTION_TYPE, ANIMATION_TWEENS, type AddText3DOptions, type Analytics, Annotation, Area, type AutoElements, BBox, BEARING_TYPE, CONNECTION_TYPE, type Camera, type CameraBounds, type CameraTransform, type CaptureEventsPayloadMap, type ColorString, Connection, Coordinate, DOORS, type Debug, type DebugState, DetailedMapData, Directions, Door, E_SDK_LOG_LEVEL, EnterpriseCategory, EnterpriseLocation, EnterpriseVenue, type EnvMapOptions, type Environment, type Exporter, Facade, Feature, FeatureCollection, Floor, FloorStack, type FootprintConfig, GeoJSON$1 as GeoJSON, GeoJsonGeometryTypes, GeoJsonObject, GeoJsonProperties, GeoJsonTypes, Geometry, GeometryCollection, GeometryObject, type GlobalState, Hyperlink, type IAnchorable, type IFocusable, type IGeoJSONData, type INavigatable, type ISystemPlugin, type Image3D, type Image3DView, ImageMetaData, type InitializeModelState, type InitializeText3DState, type InsetPadding, type InsetPaddingOption, type InterpolateOn, type Interpolation, type Label, type LabelAppearance, type LabelTextPlacement, type Labels, LineString, type LineStyle, LocationCategory, LocationProfile, type LocationSocial, type LocationState, MAPPEDIN_COLORS, type MapData, type MapDataElements, type MapElementToGetRenderedState, type MapElementToGetState, type MapElementToUpdateState, type MapElementsWithState, type MapFeatureOfType, MapObject, MapView, type MapViewElements, type MapViewState, type MappedinError, type MappedinRenderError, type Marker, type Markers, type MatchInfo, type Model, type Models, type MultiFloorViewEffectState, MultiLineString, MultiPoint, MultiPolygon, type Navigation, type NavigationState, Node, type OpeningHours, type OperationHours, type Outdoor, type OutlinesOptions, type PaintStyle, type Path, type PathSegment$1 as PathSegment, type PathWidth, type Paths, type PixelWidth, type Places, Point, PointOfInterest, Polygon, type Position, type PubSub, type Query, type RendererCoreOptions, type Search, type SearchOptions, type SearchResult, type SearchResultEnterpriseCategory, type SearchResultEnterpriseLocations, type SearchResultItem, type SearchResultPlaces, type Shading, type Shape, type Shapes, type SiblingGroup, Space, type Style, type Suggestion, type TActionType, type TAddImageOptions, type TAddLabelOptions, type TAddMarkerOptions, type TAddModel, type TAddModelOptions, type TAddPathOptions, type TAddText3DAnchorableOptions, type TAddText3DOptions, type TAnalyticsUpdateState, type TAnimateStateResult, type TAnimationOptions, type TAntialiasingOptions, type TBearingType, type TCameraAnimationOptions, type TCameraInteractionsSetOptions, type TCameraTarget, type TCancellablePromise, type TClickPayload, type TCollisionRankingTier, type TConnectionPathOptions, type TConnectionType, type TCoordinateParams, type TCreateMarker, type TDirectionInstruction, type TDirectionInstructionAction, type TDirectionZone, type TDoorsState, type TDoorsUpdateState, type TEasingFunction, type TEventPayload, type TEvents, type TFacadeState, type TFacadeUpdateState, type TFindNearestOptions, type TFindNearestResult, type TFindPreferredLanguageInVenueOptions, type TFloorAltitudeData, type TFloorChangePayload, type TFloorChangeReason, type TFloorState, type TFloorUpdateState, type TFocusOnOptions, type TFocusTarget, type TGeometryState, type TGeometryUpdateState, type TGetDirectionsOptions, type TGetMapDataOptions, type TGetMapDataSharedOptions, type TGetMapDataWithAccessTokenOptions, type TGetMapDataWithCredentialsOptions, type TGetState, type THoverPayload, type THydrateMapDataBundle, type TImage3DState as TImageState, type TImage3DUpdateState as TImageUpdateState, type TLabelState, type TLabelUpdateState, type TMVF, type TMVFLineStringStyle, type TMVFPointStyle, type TMVFPolygonStyle, type TMVFStyle, type TMVFStyleCollection, type TMapDataEvents, type TMapDataObjectTypes, type TMapFeatureTypes, type TMapViewObjectTypes, type TMarkerPlacement, type TMarkerState, type TMarkerUpdateState, type TModelState, type TModelUpdateState, type TMultiFloorViewOptions, type TNavigationOptions, type TNavigationPathOptions, type TNavigationTarget, type TPathSectionHighlightOptions, type TPathState, type TPathUpdateState, type TQueriables, type TQueryAtResult, type RendererState as TRendererState, type TSearchOptions, type TSetFloorOptions, type TShapeState, type TShapeUpdateState, type TShow3DMapOptions, type TSpaceType, type TStateChangedInternalPayload, type TTakeScreenshotOptions, type TText3DState, type TText3DUpdateState, type TUpdateState, type TWallsState, type TWallsUpdateState, TWatermarkOptions, type Text3D, type Text3DView, type UpdateGlobalState, type VisibilityState, WALLS, type WithState, MapLibreOverlay as __INTERNAL__MapLibreOverlay, __setWatermarkOnClickFn, checkWorkerUrls, disableText3DWorker, enableTestMode, findPreferredLanguageInVenue, forceEnterpriseLocations, getMapData, getMapDataEnterprise, getMultiFloorState, getVersion, hydrateMapData, hydrateMapDataFromMVF, parseMVFv2 as parseMVF, preloadFont, setLoggerLevel, setUseEnterpriseAPI, setWorkersUrl, shouldForceEnterpriseLocations, show3dMap, show3dMapGeojson, unzipAndParseMVFv2, unzipMVFv2 as unzipMVF };