@expofp/renderer 1.3.2 → 1.4.0

package/dist/index.d.ts

@@ -1,26 +1,21 @@
-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;
+/** Camera state returned by {@link ControlsAPI.getCameraState}. */
+export declare interface CameraState {
+    /** Camera target position in SVG coordinates */
+    center: Vector2Like;
+    /** Current zoom factor */
+    zoom: number;
+    /** Roll angle in degrees */
+    roll: number;
+    /** Pitch angle in degrees */
+    pitch: number;
+    /** Pixel to SVG scale factor */
+    ptScale: number;
 }
 
 export declare type ColorInput = string | number;
@@ -39,7 +34,10 @@ export declare interface ConfigureOptions {
 
 /** Controls system public API. */
 export declare interface ControlsAPI {
-    /** Gesture handlers for camera controls. */
+    /**
+     * Gesture handlers for camera controls.
+     * @inlineType Handlers
+     */
     handlers: Readonly<Handlers>;
     /**
      * Zooms the camera by the given factor.
@@ -118,6 +116,17 @@ export declare interface ControlsAPI {
      * @param options Partial configuration object with time values in seconds
      */
     configure(options: Partial<ConfigureOptions>): void;
+    /**
+     * Sets the camera bounds to restrict camera movement.
+     * Note: This method must be called after the viewport is initialized by `renderer.start()`.
+     * @param rect Rectangle in SVG coordinates defining the camera boundary or `undefined` to remove the boundary
+     */
+    setCameraBounds(rect?: Rect): void;
+    /**
+     * Gets the current camera state.
+     * @returns Camera state object with center, zoom, roll, pitch, and ptScale
+     */
+    getCameraState(): CameraState;
 }
 
 /**
@@ -157,156 +166,6 @@ 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.
- * Subclasses can:
- * - Configure camera-controls in onEnable/onDisable (e.g., set mouseButtons, limits)
- * - Subscribe to DOM events or Mjolnir gestures in onEnable/onDisable
- * - Or do both
- * @template T Handler-specific options type (undefined if no options)
- * @example
- * ```typescript
- * // Simple handler that just configures camera-controls
- * class PanHandler extends Handler {
- *   protected onEnable(): void {
- *     this.controller.mouseButtons.left = CameraController.ACTION.TRUCK;
- *   }
- *
- *   protected onDisable(): void {
- *     this.controller.mouseButtons.left = CameraController.ACTION.NONE;
- *   }
- *
- *   reset(enableTransition = true): Promise<void> {
- *     // No custom state to reset
- *   }
- * }
- *
- * // Handler with custom gesture recognition
- * class RotateHandler extends Handler {
- *   private rotating = false;
- *
- *   protected onEnable(): void {
- *     this.controller.touches.two = CameraController.ACTION.NONE; // Disable built-in
- *     this.eventManager.on('rotate', this.onRotate);
- *     this.domElement.addEventListener('pointerdown', this.onPointerDown);
- *   }
- *
- *   protected onDisable(): void {
- *     this.eventManager.off('rotate', this.onRotate);
- *     this.domElement.removeEventListener('pointerdown', this.onPointerDown);
- *     this.rotating = false;
- *   }
- *
- *   reset(enableTransition = true): Promise<void> {
- *     this.rotating = false;
- *   }
- * }
- * ```
- */
-declare abstract class Handler<T = undefined> implements HandlerAPI<T> {
-    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 viewportSystem The viewport system instance
-     * @param domElement The DOM element to attach event listeners to
-     * @param eventManager Shared Mjolnir EventManager for gesture recognition
-     */
-    constructor(viewportSystem: ViewportSystem, domElement: HTMLElement, eventManager: EventManager);
-    /**
-     * Per-frame update for this handler.
-     * Called every frame in the render loop.
-     * Override if handler needs per-frame logic (e.g., smooth interpolation).
-     * @param delta Time elapsed since last frame in seconds
-     * @returns true if the handler made changes that require re-rendering
-     */
-    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(enableTransition?: boolean): Promise<void>;
-    /**
-     * Configure this handler with handler-specific options.
-     * Does NOT handle enabled state - use enable()/disable() for that.
-     * Subclasses should override to handle their specific options
-     * @param options Partial options to update (handler-specific, not including enabled flag)
-     */
-    configure(options: T extends undefined ? never : Partial<T>): void;
-    /**
-     * Enable this handler.
-     * Calls onEnable() hook for subclass-specific enabling logic
-     */
-    enable(): void;
-    /**
-     * Disable this handler.
-     * Resets to initial state without transition, then calls onDisable() hook for subclass-specific disabling logic
-     */
-    disable(): void;
-    /**
-     * Check if this handler is currently enabled
-     * @returns true if enabled, false otherwise
-     */
-    isEnabled(): boolean;
-    /**
-     * Hook called when the handler is enabled.
-     * Subclasses override this to:
-     * - Configure camera-controls (set mouseButtons, touches, limits, etc.)
-     * - Subscribe to DOM events (addEventListener)
-     * - Subscribe to Mjolnir gestures (eventManager.on)
-     */
-    protected abstract onEnable(): void;
-    /**
-     * Hook called when the handler is disabled.
-     * Subclasses override this to:
-     * - Reset camera-controls configuration
-     * - Unsubscribe from DOM events (removeEventListener)
-     * - Unsubscribe from Mjolnir gestures (eventManager.off)
-     */
-    protected abstract onDisable(): void;
-}
-
 /**
  * Public API interface exposed through renderer.controls.handlers.
  * Each handler implements this interface to provide consistent enable/disable/configure functionality.
@@ -341,17 +200,17 @@ export declare interface HandlerAPI<T = undefined> {
 }
 
 /**
- * Gesture handlers - all fields are readonly to prevent reassignment
+ * Gesture handlers
  */
 declare interface Handlers {
     /** Pan handler */
-    pan: PanHandler;
+    pan: HandlerAPI;
     /** Zoom handler */
-    zoom: ZoomHandler;
+    zoom: HandlerAPI;
     /** Roll handler */
-    roll: RollHandler;
+    roll: HandlerAPI<RollHandlerOptions>;
     /** Pitch handler */
-    pitch: PitchHandler;
+    pitch: HandlerAPI<PitchHandlerOptions>;
 }
 
 /** Image definition */
@@ -425,75 +284,10 @@ export declare interface MouseEventData {
     defs: RenderableDef[];
 }
 
-/**
- * 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 {
-    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
-     */
-    protected onEnable(): void;
-    /**
-     * Disable pan gestures.
-     * Removes pan actions from camera-controls
-     */
-    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 {
+export declare interface PitchHandlerOptions {
     /**
      * Minimum pitch angle in degrees (0 = looking straight down at the map)
      * @default 0
@@ -675,83 +469,18 @@ export declare interface RendererOptions {
     ui?: Partial<UI>;
 }
 
-/** Options for the {@link ControlsAPI.resetCamera} method. */
+/**
+ * Options for the {@link ControlsAPI.resetCamera} method.
+ * @inline
+ */
 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.
- * Uses Mapbox-style threshold to prevent accidental rotations.
- */
-declare class RollHandler extends Handler<RollHandlerOptions> {
-    private isRolling;
-    private rotationThreshold;
-    private startVector?;
-    private vector?;
-    private minDiameter;
-    private prevAngle;
-    private pivotWorld;
-    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.
-     * Configures camera-controls to allow any azimuth angle and two-finger touch rotate
-     */
-    protected onEnable(): void;
-    /**
-     * Disable roll gestures.
-     */
-    protected onDisable(): void;
-    private onRotateStart;
-    private onRotateEnd;
-    private onRotate;
-    private setPivot;
-    /**
-     * Check if rotation is below threshold (Mapbox-style).
-     * 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 (Mapbox pattern)
-     * @param a First vector
-     * @param b Second vector
-     * @returns Angle difference in degrees
-     */
-    private getBearingDelta;
-    /**
-     * Normalize angle to be between -π and π
-     * @param angle Angle in radians
-     * @returns Normalized angle in radians
-     */
-    private normalizeAngle;
-}
-
 /**
  * Configuration options for RollHandler
  */
-declare interface RollHandlerOptions {
+export declare interface RollHandlerOptions {
     /**
      * Rotation threshold in pixels along circumference of touch circle (Mapbox-style).
      * Higher values require more movement before rotation starts.
@@ -768,8 +497,6 @@ 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;
 }
@@ -792,8 +519,6 @@ export declare interface SharedDef {
     dim?: boolean;
 }
 
-declare type Space = "svg" | "world";
-
 /** Text alignment */
 export declare interface TextAlignment {
     /** Horizontal alignment */
@@ -848,100 +573,6 @@ export declare interface UI {
     memoryInfoPanel: HTMLDivElement;
 }
 
-/** 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. */