@expofp/renderer 1.2.1 → 1.3.3

package/dist/index.d.ts

@@ -1,25 +1,123 @@
+import { Camera } from 'three';
 import { default as default_2 } from 'stats-gl';
 import { default as default_3 } from 'camera-controls';
 import { EventManager } from 'mjolnir.js';
+import { Intersection } from 'three';
+import { Object3D } from 'three';
+import { Object3DEventMap } from 'three';
+import { PerspectiveCamera } from 'three';
+import { Scene } from 'three';
 import { Vector2 } from 'three';
 import { Vector2Like } from 'three';
 import { Vector2Tuple } from 'three';
 import { WebGLRenderer } from 'three';
 
+/** Camera controller. Manages the camera, it's controls and smooth updates. */
+declare class CameraController extends default_3 {
+    private renderer;
+    /**
+     * @param camera {@link PerspectiveCamera} instance
+     * @param renderer {@link Renderer} instance
+     */
+    constructor(camera: PerspectiveCamera, renderer: Renderer);
+    update(delta: number): boolean;
+}
+
 export declare type ColorInput = string | number;
 
-/**
- * Options for the CameraControls class.
- */
-declare interface ControlsOptions {
-    /** Whether the camera controls are enabled */
-    enabled: boolean;
-    /** Time for zooming transitions (in seconds) */
+/** Options for the {@link ControlsAPI.configure} method. */
+export declare interface ConfigureOptions {
+    /** Smooth time for zoom operations in seconds.*/
     zoomTime: number;
-    /** Options for the camera roll controller - see {@link RollOptions} */
-    roll: RollOptions;
-    /** Options for the camera inertia - see {@link InertiaOptions} */
-    inertia: InertiaOptions;
+    /** Smooth time for pan operations in seconds. */
+    panTime: number;
+    /** Smooth time for roll operations in seconds. */
+    rollTime: number;
+    /** Smooth time for pitch operations in seconds. */
+    pitchTime: number;
+}
+
+/** Controls system public API. */
+export declare interface ControlsAPI {
+    /** Gesture handlers for camera controls. */
+    handlers: Readonly<Handlers>;
+    /**
+     * Zooms the camera by the given factor.
+     * @param zoom Zoom factor to apply (e.g., 1.5 for 50% zoom in, 0.5 for 50% zoom out)
+     * @param immediate If true, applies the change immediately without animation
+     * @returns Promise that resolves when the zoom animation completes
+     */
+    zoomBy(zoom: number, immediate?: boolean): Promise<void>;
+    /**
+     * Zooms the camera to fit the given rectangle.
+     * @param rect Rectangle to zoom to in SVG coordinates
+     * @param options Optional zoom configuration
+     * @param immediate If true, applies the change immediately without animation
+     * @returns Promise that resolves when the zoom animation completes
+     */
+    zoomTo(rect: Rect, options?: Partial<ZoomToOptions>, immediate?: boolean): Promise<void>;
+    /**
+     * Pans the camera by the given offset in SVG space.
+     * @param x X offset in SVG space
+     * @param y Y offset in SVG space
+     * @param immediate If true, applies the change immediately without animation
+     * @returns Promise that resolves when the pan animation completes
+     */
+    panBy(x: number, y: number, immediate?: boolean): Promise<void>;
+    /**
+     * Pans the camera to the given coordinates in SVG space.
+     * @param x X coordinate in SVG space
+     * @param y Y coordinate in SVG space
+     * @param immediate If true, applies the change immediately without animation
+     * @returns Promise that resolves when the pan animation completes
+     */
+    panTo(x: number, y: number, immediate?: boolean): Promise<void>;
+    /**
+     * Rolls the camera by the given angle in degrees.
+     * Note: This method won't work if {@link ControlsAPI.handlers | handlers.roll} is disabled.
+     * @param angle Angle in degrees to roll by
+     * @param immediate If true, applies the change immediately without animation
+     * @returns Promise that resolves when the roll animation completes
+     */
+    rollBy(angle: number, immediate?: boolean): Promise<void>;
+    /**
+     * Rolls the camera to the given angle in degrees.
+     * Note: This method won't work if {@link ControlsAPI.handlers | handlers.roll} is disabled.
+     * @param angle Target angle in degrees
+     * @param immediate If true, applies the change immediately without animation
+     * @returns Promise that resolves when the roll animation completes
+     */
+    rollTo(angle: number, immediate?: boolean): Promise<void>;
+    /**
+     * Pitches the camera by the given angle in degrees.
+     * Positive angles increase pitch, negative angles decrease pitch.
+     * Note: This method won't work if {@link ControlsAPI.handlers | handlers.pitch} is disabled.
+     * @param angle Angle in degrees to pitch by
+     * @param immediate If true, applies the change immediately without animation
+     * @returns Promise that resolves when the pitch animation completes
+     */
+    pitchBy(angle: number, immediate?: boolean): Promise<void>;
+    /**
+     * Pitches the camera to the given angle in degrees.
+     * The angle is clamped to the 0-90 degree range.
+     * Note: This method won't work if {@link ControlsAPI.handlers | handlers.pitch} is disabled.
+     * @param angle Target angle in degrees
+     * @param immediate If true, applies the change immediately without animation
+     * @returns Promise that resolves when the pitch animation completes
+     */
+    pitchTo(angle: number, immediate?: boolean): Promise<void>;
+    /**
+     * Resets the camera to the starting state.
+     * @param options Configuration for which handlers to reset
+     * @param immediate If true, applies the change immediately without animation
+     * @returns Promise that resolves when all reset animations complete
+     */
+    resetCamera(options?: Partial<ResetCameraOptions>, immediate?: boolean): Promise<void>;
+    /**
+     * Configures smooth time values for camera operations.
+     * @param options Partial configuration object with time values in seconds
+     */
+    configure(options: Partial<ConfigureOptions>): void;
 }
 
 /**
@@ -35,8 +133,6 @@ export declare function createVector2(vector2: IVector2): Vector2;
 export declare interface EngineEvents {
     /** Camera change */
     "navigation:change": void;
-    /** Camera stop */
-    "navigation:stop": void;
     /** Camera roll */
     "navigation:roll": number;
     /** Mouse move */
@@ -47,8 +143,6 @@ export declare interface EngineEvents {
     "pointer:click": MouseEventData;
     /** Viewport pixel to svg scale */
     "viewport:ptscale": number;
-    /** Camera update */
-    "camera:update": void;
 }
 
 export declare type EventHandler<Payload> = (payload: Payload) => void;
@@ -63,6 +157,41 @@ export declare interface EventsAPI {
     clear(): void;
 }
 
+/**
+ * System for managing engine-wide events
+ */
+declare class EventSystem implements EventsAPI {
+    private handlers;
+    /**
+     * Add an event listener for a specific event
+     * @param event - The event to listen for
+     * @param handler - The handler to call when the event is emitted
+     */
+    addEventListener<E extends keyof EngineEvents>(event: E, handler: EventHandler<EngineEvents[E]>): void;
+    /**
+     * Remove an event listener for a specific event
+     * @param event - The event to remove the listener for
+     * @param handler - The handler to remove
+     */
+    removeEventListener<E extends keyof EngineEvents>(event: E, handler: EventHandler<EngineEvents[E]>): void;
+    /**
+     * Check if there are any listeners for a specific event
+     * @param event - The event to check
+     * @returns true if there are listeners, false otherwise
+     */
+    hasListeners<E extends keyof EngineEvents>(event: E): boolean;
+    /**
+     * Emit an event with a specific payload
+     * @param event - The event to emit
+     * @param args - The payload to emit
+     */
+    emit<E extends keyof EngineEvents>(event: E, ...args: EngineEvents[E] extends void ? [] : [EngineEvents[E]]): void;
+    /**
+     * Clear all event listeners
+     */
+    clear(): void;
+}
+
 /**
  * Abstract base class for all interaction handlers.
  * Provides common lifecycle management and access to camera controller, DOM element, and event manager.
@@ -83,7 +212,7 @@ export declare interface EventsAPI {
  *     this.controller.mouseButtons.left = CameraController.ACTION.NONE;
  *   }
  *
- *   reset(): void {
+ *   reset(enableTransition = true): Promise<void> {
  *     // No custom state to reset
  *   }
  * }
@@ -104,24 +233,26 @@ export declare interface EventsAPI {
  *     this.rotating = false;
  *   }
  *
- *   reset(): void {
+ *   reset(enableTransition = true): Promise<void> {
  *     this.rotating = false;
  *   }
  * }
  * ```
  */
 declare abstract class Handler<T = undefined> implements HandlerAPI<T> {
-    protected controller: default_3;
+    protected viewportSystem: ViewportSystem;
     protected domElement: HTMLElement;
     protected eventManager: EventManager;
     /** Whether this handler is enabled */
     protected enabled: boolean;
+    /** The camera-controls instance for camera manipulation */
+    protected controller: CameraController;
     /**
-     * @param controller The camera-controls instance for camera manipulation
+     * @param viewportSystem The viewport system instance
      * @param domElement The DOM element to attach event listeners to
      * @param eventManager Shared Mjolnir EventManager for gesture recognition
      */
-    constructor(controller: default_3, domElement: HTMLElement, eventManager: EventManager);
+    constructor(viewportSystem: ViewportSystem, domElement: HTMLElement, eventManager: EventManager);
     /**
      * Per-frame update for this handler.
      * Called every frame in the render loop.
@@ -132,8 +263,10 @@ declare abstract class Handler<T = undefined> implements HandlerAPI<T> {
     update(delta: number): boolean;
     /**
      * Reset this handler to its initial state.
+     * @param enableTransition Whether to animate the transition (default: true)
+     * @returns Promise that resolves when the reset is complete
      */
-    abstract reset(): void;
+    abstract reset(enableTransition?: boolean): Promise<void>;
     /**
      * Configure this handler with handler-specific options.
      * Does NOT handle enabled state - use enable()/disable() for that.
@@ -148,7 +281,7 @@ declare abstract class Handler<T = undefined> implements HandlerAPI<T> {
     enable(): void;
     /**
      * Disable this handler.
-     * Calls onDisable() hook for subclass-specific disabling logic
+     * Resets to initial state without transition, then calls onDisable() hook for subclass-specific disabling logic
      */
     disable(): void;
     /**
@@ -179,7 +312,7 @@ declare abstract class Handler<T = undefined> implements HandlerAPI<T> {
  * Each handler implements this interface to provide consistent enable/disable/configure functionality.
  * @template T Handler-specific options type (can be undefined if handler has no options).
  */
-declare interface HandlerAPI<T = undefined> {
+export declare interface HandlerAPI<T = undefined> {
     /**
      * Enable this handler
      */
@@ -201,19 +334,25 @@ declare interface HandlerAPI<T = undefined> {
     configure(options: T extends undefined ? never : Partial<T>): void;
     /**
      * Reset this handler to its initial state.
+     * @param enableTransition Whether to animate the transition (default: true)
+     * @returns Promise that resolves when the reset is complete
      */
-    reset(): void;
+    reset(enableTransition?: boolean): Promise<void>;
 }
 
 /**
  * Gesture handlers - all fields are readonly to prevent reassignment
  */
-declare type Handlers = Readonly<{
+declare interface Handlers {
     /** Pan handler */
     pan: PanHandler;
+    /** Zoom handler */
+    zoom: ZoomHandler;
     /** Roll handler */
     roll: RollHandler;
-}>;
+    /** Pitch handler */
+    pitch: PitchHandler;
+}
 
 /** Image definition */
 export declare interface ImageDef extends SharedDef {
@@ -232,22 +371,6 @@ export declare type ImageSource = HTMLImageElement | HTMLCanvasElement | ImageBi
 
 export declare type Index = [number, number, number];
 
-/**
- * Options for the InertiaController class.
- */
-declare interface InertiaOptions {
-    /** Whether the inertia controller is enabled */
-    enabled?: boolean;
-    /** Minimum time in milliseconds to sample backwards to determine inertia */
-    minSampleMs?: number;
-    /** Inertial movement duration in milliseconds */
-    durationMs?: number;
-    /** Speed threshold after which inertia is stopped (in world units per ms) */
-    speedThreshold?: number;
-    /** Easing function for the inertia movement. Maps interval [0, 1] to [0, 1], default exp-in-ish */
-    ease?: (t: number) => number;
-}
-
 export declare function isImageDef(def: RenderableDef): def is ImageDef;
 
 export declare function isImageLayer(layer: LayerDef): layer is TypedLayerDef<ImageDef>;
@@ -302,25 +425,15 @@ export declare interface MouseEventData {
     defs: RenderableDef[];
 }
 
-/** Navigation system public API. */
-declare interface NavigationAPI {
-    /** Zooms the camera by the given factor. */
-    zoomBy(zoom: number): void;
-    /** Zooms the camera to the given rectangle. */
-    zoomTo(rect: Rect, options?: Partial<ZoomToOptions>): void;
-    /** Resets the camera to the starting state. */
-    resetCamera(options?: Partial<ResetCameraOptions>): void;
-    /** Configures the camera controls. */
-    configure(options: Partial<ControlsOptions>): void;
-}
-
 /**
  * Pan handler - wraps camera-controls TRUCK action.
  * Handles both mouse drag (left-click) and single-finger touch pan.
  * No custom event listeners needed - camera-controls handles everything
  */
 declare class PanHandler extends Handler {
-    reset(): void;
+    private inertia;
+    reset(enableTransition?: boolean): Promise<void>;
+    update(delta: number): boolean;
     /**
      * Enable pan gestures.
      * Configures camera-controls to handle left-click drag and single-touch drag
@@ -333,6 +446,66 @@ declare class PanHandler extends Handler {
     protected onDisable(): void;
 }
 
+/**
+ * Pitch handler - controls camera polar angle (vertical pitch).
+ * Configures camera-controls polar angle limits.
+ * No gesture recognition yet - only sets angle constraints.
+ */
+declare class PitchHandler extends Handler<PitchHandlerOptions> {
+    private minPitch;
+    private maxPitch;
+    private isValid?;
+    private firstMove?;
+    private lastPoints?;
+    private prevTwoFingerAction?;
+    /**
+     * @param viewportSystem {@link ViewportSystem} instance
+     * @param domElement {@link HTMLElement} instance
+     * @param eventManager {@link EventManager} instance
+     */
+    constructor(viewportSystem: ViewportSystem, domElement: HTMLElement, eventManager: EventManager);
+    reset(enableTransition?: boolean): Promise<void>;
+    /**
+     * Configure pitch handler options
+     * @param options Partial options to update
+     */
+    configure(options: Partial<PitchHandlerOptions>): void;
+    /**
+     * Enable pitch.
+     * Configures camera-controls to allow polar angle changes within configured range
+     */
+    protected onEnable(): void;
+    /**
+     * Disable pitch.
+     */
+    protected onDisable(): void;
+    /**
+     * Update controller polar angles based on current configuration
+     */
+    private updatePolarAngles;
+    private onPitchStart;
+    private onPitchEnd;
+    private onPitch;
+    private gestureBeginsVertically;
+    private isVertical;
+}
+
+/**
+ * Configuration options for PitchHandler
+ */
+declare interface PitchHandlerOptions {
+    /**
+     * Minimum pitch angle in degrees (0 = looking straight down at the map)
+     * @default 0
+     */
+    minPitch?: number;
+    /**
+     * Maximum pitch angle in degrees (90 = looking horizontally)
+     * @default 85
+     */
+    maxPitch?: number;
+}
+
 /** Polygon shape instance. */
 export declare class Polygon {
     /** Array of polygon vertices. */
@@ -414,28 +587,26 @@ export declare class Renderer {
     /** {@link HTMLCanvasElement} that this renderer is rendering to */
     readonly canvas: HTMLCanvasElement;
     private ui?;
-    private clock;
-    private renderer;
+    private gl?;
     private eventSystem;
     private layerSystem;
     private viewportSystem;
     private interactionsSystem;
-    private memoryInfoExtension;
-    private memoryInfo;
+    private controlsSystem;
+    private clock;
+    private renderer;
     private viewport?;
     private needsRedraw;
-    private isExternalMode;
+    private memoryInfoExtension;
+    private memoryInfo;
     /**
      * @param opts {@link RendererOptions}
      */
     constructor(opts: RendererOptions);
     /**
-     * {@link NavigationAPI} instance for controlling the viewport
+     * {@link ControlsAPI} instance for controlling the viewport
      */
-    get controls(): NavigationAPI & {
-        handlers: Handlers;
-        controller: default_3;
-    };
+    get controls(): ControlsAPI;
     /**
      * {@link EventsAPI} instance for subscribing to internal events
      */
@@ -457,12 +628,12 @@ export declare class Renderer {
      * Sets the renderer to external mode, where parts of rendering process are not managed by the renderer (e.g. Mapbox GL JS).
      * @param staticTransformMatrix static transform matrix to apply to the scene
      */
-    configureExternalMode(staticTransformMatrix: number[]): void;
+    setExternalTransform(staticTransformMatrix: number[]): void;
     /**
      * Update scene matrix from dynamic transform matrix.
      * @param dynamicTransformMatrix dynamic transform matrix (changes every frame)
      */
-    updateExternalTransformMatrix(dynamicTransformMatrix: number[]): void;
+    updateExternalCamera(dynamicTransformMatrix: number[]): void;
     /**
      * Initialize the scene and start the rendering loop
      * @param sceneDef {@link SceneDef} to render
@@ -476,7 +647,7 @@ export declare class Renderer {
     update(...defs: RenderableDef[]): void;
     /**
      * Converts coordinates from canvas space to SVG space.
-     * @param point point in canvas space (relative to the canvas's top left corner)
+     * @param point point in canvas space (relative to the canvas's top left corner), in css pixels
      * @returns point in SVG space
      */
     screenToSvg(point: Vector2Like): Vector2Like;
@@ -504,111 +675,89 @@ export declare interface RendererOptions {
     ui?: Partial<UI>;
 }
 
-/** Options for the {@link NavigationAPI.resetCamera} method. */
-declare interface ResetCameraOptions {
-    /** Whether to reset the camera roll. */
-    roll: boolean;
-    /** Whether to reset the camera zoom. */
-    zoom: boolean;
-}
+/** Options for the {@link ControlsAPI.resetCamera} method. */
+export declare type ResetCameraOptions = {
+    [Property in keyof Handlers]?: boolean;
+};
 
 /**
  * Roll handler - implements custom two-finger rotation around arbitrary pivot point.
  * Handles mouse drag (right-click) via camera-controls and custom touch rotation.
- *
- * Touch rotation keeps world points under both fingers fixed in screen space by:
- * 1. Unprojecting finger midpoint to world plane
- * 2. Rotating camera (azimuth)
- * 3. Panning camera to compensate for midpoint movement
+ * Uses Mapbox-style threshold to prevent accidental rotations.
  */
-declare class RollHandler extends Handler {
-    private rotating;
+declare class RollHandler extends Handler<RollHandlerOptions> {
+    private isRolling;
+    private rotationThreshold;
     private startVector?;
     private vector?;
     private minDiameter;
-    private startBearing;
-    private raycaster;
+    private prevAngle;
     private pivotWorld;
-    private tempVec2;
-    private tempVec3;
-    reset(): void;
+    private targetWorld;
+    private cameraPosition;
+    private cameraForward;
+    private rotationMatrix;
+    /**
+     * Get bearing angle between current camera orientation and true north (in radians).
+     * Angle is in range [0, 2π), going clockwise from north.
+     */
+    get bearing(): number;
+    reset(enableTransition?: boolean): Promise<void>;
+    /**
+     * Configure roll handler options
+     * @param options Partial options to update
+     */
+    configure(options: Partial<RollHandlerOptions>): void;
     /**
      * Enable roll gestures.
-     * - Mobile: custom two-finger rotation with pivot compensation
+     * Configures camera-controls to allow any azimuth angle and two-finger touch rotate
      */
     protected onEnable(): void;
     /**
      * Disable roll gestures.
-     * Restricts azimuth angle to zero and removes event listeners
      */
     protected onDisable(): void;
     private onRotateStart;
-    private onRotate;
     private onRotateEnd;
+    private onRotate;
+    private setPivot;
     /**
      * Check if rotation is below threshold (Mapbox-style).
-     * Threshold is in pixels along circumference, scaled by touch circle diameter.
+     * The threshold before a rotation actually happens is configured in
+     * pixels along the circumference of the circle formed by the two fingers.
+     * This makes the threshold in degrees larger when the fingers are close
+     * together and smaller when the fingers are far apart.
+     * Uses the smallest diameter from the whole gesture to reduce sensitivity
+     * when pinching in and out.
      * @param vector Current vector between fingers
      * @returns true if below threshold, false otherwise
      */
     private isBelowThreshold;
     /**
-     * Get signed angle between two vectors in degrees
+     * Get signed angle between two vectors in degrees (Mapbox pattern)
      * @param a First vector
      * @param b Second vector
      * @returns Angle difference in degrees
      */
     private getBearingDelta;
     /**
-     * Normalize screen pixel coordinates to NDC [-1, 1]
-     * @param screenPos Screen position in pixels
-     * @param out Output vector for NDC coordinates
-     * @returns NDC coordinates
-     */
-    private normalizeScreenCoords;
-    /**
-     * Denormalize NDC coordinates to screen pixels
-     * @param ndc NDC coordinates [-1, 1]
-     * @param out Output vector for screen pixel coordinates
-     * @returns Screen pixel coordinates
+     * Normalize angle to be between -π and π
+     * @param angle Angle in radians
+     * @returns Normalized angle in radians
      */
-    private denormalizeScreenCoords;
-    /**
-     * Unproject screen NDC coordinates to world plane (Z=0)
-     * @param ndc NDC coordinates [-1, 1]
-     * @param out Output vector for world coordinates
-     * @returns World coordinates on Z=0 plane
-     */
-    private unprojectToWorldPlane;
-    /**
-     * Project world point to screen NDC coordinates
-     * @param worldPos World position
-     * @param out Output vector for NDC coordinates
-     * @returns NDC coordinates
-     */
-    private projectWorldToScreen;
-    /**
-     * Convert screen-space pixel delta to world-space translation.
-     * For top-down view, this is a simple perspective calculation.
-     * @param deltaX Screen delta X in pixels
-     * @param deltaY Screen delta Y in pixels
-     * @returns World-space translation vector
-     */
-    private screenDeltaToWorldDelta;
+    private normalizeAngle;
 }
 
 /**
- * Options for the RollController class.
+ * Configuration options for RollHandler
  */
-declare interface RollOptions {
-    /** Whether the roll controller is enabled */
-    enabled?: boolean;
-    /** Speed in radians of arc length per pixel */
-    speed?: number;
-    /** Threshold in degrees for the roll gesture */
-    angleThreshold?: number;
-    /** Threshold in scale for the pinch gesture */
-    pinchThreshold?: number;
+declare interface RollHandlerOptions {
+    /**
+     * Rotation threshold in pixels along circumference of touch circle (Mapbox-style).
+     * Higher values require more movement before rotation starts.
+     * @default 25
+     */
+    rotationThreshold?: number;
 }
 
 /** Scene definition */
@@ -619,6 +768,8 @@ export declare interface SceneDef {
     background?: ColorInput;
     /** SVG viewbox */
     viewbox: Rect;
+    /** Scene's rectangle bounds in SVG coordinates. Essentially, the size of a largest layer */
+    bounds?: Rect;
     /** Textures memory limit in megabytes */
     memoryLimit?: number;
 }
@@ -641,6 +792,8 @@ export declare interface SharedDef {
     dim?: boolean;
 }
 
+declare type Space = "svg" | "world";
+
 /** Text alignment */
 export declare interface TextAlignment {
     /** Horizontal alignment */
@@ -695,8 +848,102 @@ export declare interface UI {
     memoryInfoPanel: HTMLDivElement;
 }
 
-/** Options for the {@link NavigationAPI.zoomTo} method. */
-declare interface ZoomToOptions {
+/** Viewport system. Manages the scene and camera. */
+declare class ViewportSystem {
+    private renderer;
+    private eventSystem;
+    private sceneSystem;
+    private cameraSystem;
+    private raycaster;
+    private intersectionPoint;
+    private viewboxPlane;
+    private pxToSvgScaleThreshold;
+    private prevPxToSvgScale?;
+    private externalStaticTransformMatrix;
+    /**
+     * @param renderer {@link Renderer} instance
+     * @param eventSystem {@link EventSystem} instance
+     */
+    constructor(renderer: Renderer, eventSystem: EventSystem);
+    /** {@link Scene} instance */
+    get scene(): Scene;
+    /** Current {@link Camera} instance */
+    get camera(): Camera;
+    /** {@link CameraController} instance */
+    get cameraController(): CameraController;
+    /** Current camera zoom factor. */
+    get zoomFactor(): number;
+    /** Scene scale factor (SVG to pixel) */
+    get scaleFactor(): number;
+    /**
+     * Initializes the viewport and zoom bounds with the given scene definition.
+     * @param sceneDef {@link SceneDef} scene definition
+     */
+    initViewport(sceneDef: SceneDef): void;
+    /** Updates the viewport when the renderer size changes. */
+    updateViewport(): void;
+    /**
+     * Recalculates the svg to pixel scale factor and emits the event if necessary.
+     */
+    updatePtScale(): void;
+    /**
+     * Gets the objects intersected by the raycaster.
+     * @param normalizedCoords raycast point in NDC (normalized device coordinates
+     * @returns Array of {@link Intersection} instances
+     */
+    getIntersectedObjects(normalizedCoords: Vector2): Intersection<Object3D<Object3DEventMap>>[];
+    /**
+     * Converts a point from SVG coordinates to world coordinates.
+     * @param svgCoords Point in SVG coordinates
+     * @returns Point in world coordinates
+     */
+    svgToWorld(svgCoords: Vector2): Vector2;
+    /**
+     * Converts a point from screen coordinates to the given coordinate space.
+     * @param space Space to convert to (either "svg" or "world")
+     * @param normalizedCoords Point in NDC (normalized device coordinates)
+     * @returns Point in the given space
+     */
+    screenTo(space: Space, normalizedCoords: Vector2): Vector2Like;
+    /**
+     * Calculates the camera distance from the scene's plane for a given zoom factor.
+     * @param zoomFactor Zoom factor
+     * @returns Corresponding camera distance on the Z axis
+     */
+    zoomFactorToDistance(zoomFactor: number): number;
+    /**
+     * Sets the external transform matrix.
+     * @param staticTransformMatrix static transform matrix to apply to the scene
+     */
+    setExternalTransform(staticTransformMatrix: number[]): void;
+    /**
+     * Updates the external camera.
+     * @param dynamicTransformMatrix dynamic transform matrix to apply to the scene
+     */
+    updateExternalCamera(dynamicTransformMatrix: number[]): void;
+}
+
+/**
+ * Zoom handler - wraps camera-controls DOLLY action.
+ * Handles both mouse wheel and two-finger pinch gestures.
+ * No custom event listeners needed - camera-controls handles everything
+ */
+declare class ZoomHandler extends Handler {
+    reset(enableTransition?: boolean): Promise<void>;
+    /**
+     * Enable zoom gestures.
+     * Configures camera-controls to handle mouse wheel and two-finger pinch
+     */
+    protected onEnable(): void;
+    /**
+     * Disable zoom gestures.
+     * Removes zoom actions from camera-controls
+     */
+    protected onDisable(): void;
+}
+
+/** Options for the {@link ControlsAPI.zoomTo} method. */
+export declare interface ZoomToOptions {
     /** Maximum zoom factor. */
     maxZoom: number;
     /** Percentage of padding to add to the target rectangle. */