@expofp/renderer 1.2.1

package/dist/index.d.ts

@@ -0,0 +1,706 @@
+import { default as default_2 } from 'stats-gl';
+import { default as default_3 } from 'camera-controls';
+import { EventManager } from 'mjolnir.js';
+import { Vector2 } from 'three';
+import { Vector2Like } from 'three';
+import { Vector2Tuple } from 'three';
+import { WebGLRenderer } from 'three';
+
+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) */
+    zoomTime: number;
+    /** Options for the camera roll controller - see {@link RollOptions} */
+    roll: RollOptions;
+    /** Options for the camera inertia - see {@link InertiaOptions} */
+    inertia: InertiaOptions;
+}
+
+/**
+ * Converts multiple vector2 representations to a {@link Vector2} instance.
+ * @param vector2 Vector2 representation as a tuple/POJO
+ * @returns Vector2 instance
+ */
+export declare function createVector2(vector2: IVector2): Vector2;
+
+/**
+ * Mapping of engine-wide events to their payloads
+ */
+export declare interface EngineEvents {
+    /** Camera change */
+    "navigation:change": void;
+    /** Camera stop */
+    "navigation:stop": void;
+    /** Camera roll */
+    "navigation:roll": number;
+    /** Mouse move */
+    "pointer:move": MouseEventData;
+    /** Mouse out */
+    "pointer:out": MouseEventData;
+    /** Mouse click */
+    "pointer:click": MouseEventData;
+    /** Viewport pixel to svg scale */
+    "viewport:ptscale": number;
+    /** Camera update */
+    "camera:update": void;
+}
+
+export declare type EventHandler<Payload> = (payload: Payload) => void;
+
+/**
+ * Public API for interacting with the event system
+ */
+export declare interface EventsAPI {
+    addEventListener<E extends keyof EngineEvents>(event: E, handler: EventHandler<EngineEvents[E]>): void;
+    removeEventListener<E extends keyof EngineEvents>(event: E, handler: EventHandler<EngineEvents[E]>): void;
+    hasListeners<E extends keyof EngineEvents>(event: E): boolean;
+    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(): 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(): void {
+ *     this.rotating = false;
+ *   }
+ * }
+ * ```
+ */
+declare abstract class Handler<T = undefined> implements HandlerAPI<T> {
+    protected controller: default_3;
+    protected domElement: HTMLElement;
+    protected eventManager: EventManager;
+    /** Whether this handler is enabled */
+    protected enabled: boolean;
+    /**
+     * @param controller The camera-controls instance for camera manipulation
+     * @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);
+    /**
+     * 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.
+     */
+    abstract reset(): 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.
+     * 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.
+ * @template T Handler-specific options type (can be undefined if handler has no options).
+ */
+declare interface HandlerAPI<T = undefined> {
+    /**
+     * Enable this handler
+     */
+    enable(): void;
+    /**
+     * Disable this handler
+     */
+    disable(): void;
+    /**
+     * Check if this handler is currently enabled
+     * @returns true if enabled, false otherwise
+     */
+    isEnabled(): boolean;
+    /**
+     * Configure this handler with new options.
+     * Only available if handler has options (T is not undefined)
+     * @param options Partial options to update
+     */
+    configure(options: T extends undefined ? never : Partial<T>): void;
+    /**
+     * Reset this handler to its initial state.
+     */
+    reset(): void;
+}
+
+/**
+ * Gesture handlers - all fields are readonly to prevent reassignment
+ */
+declare type Handlers = Readonly<{
+    /** Pan handler */
+    pan: PanHandler;
+    /** Roll handler */
+    roll: RollHandler;
+}>;
+
+/** Image definition */
+export declare interface ImageDef extends SharedDef {
+    /** Image source. Not updatable. */
+    source: ImageSource;
+    /** Image's bounds */
+    bounds: Rect;
+    /**
+     * Image's anchor point. Defines the point on the image that is used as an origin point for transformations.
+     * [0, 0] is the top-left corner, [0.5, 0.5] is the center (default), [1, 1] is the bottom-right corner.
+     */
+    origin?: [number, number];
+}
+
+export declare type ImageSource = HTMLImageElement | HTMLCanvasElement | ImageBitmap | OffscreenCanvas;
+
+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>;
+
+export declare function isLayerDef(def: RenderableDef): def is LayerDef;
+
+export declare function isLayerLayer(layer: LayerDef): layer is TypedLayerDef<LayerDef>;
+
+export declare function isLineDef(def: RenderableDef): def is LineDef;
+
+export declare function isLineLayer(layer: LayerDef): layer is TypedLayerDef<LineDef>;
+
+export declare function isShapeDef(def: RenderableDef): def is ShapeDef;
+
+export declare function isShapeLayer(layer: LayerDef): layer is TypedLayerDef<ShapeDef>;
+
+export declare function isTextDef(def: RenderableDef): def is TextDef;
+
+export declare function isTextLayer(layer: LayerDef): layer is TypedLayerDef<TextDef>;
+
+export declare type IVector2 = Vector2 | Vector2Like | Vector2Tuple;
+
+/** Layer definition */
+export declare interface LayerDef extends SharedDef {
+    /** Layer's name */
+    readonly name: string;
+    /** Whether to enable interaction with the layer (raycasting). */
+    interactive?: boolean;
+    /** Collection of layer's children. Mixing different types of children is not supported. */
+    children: RenderableDefCollection;
+}
+
+/** Line definition */
+export declare interface LineDef extends SharedDef {
+    /** Line's points. Not updatable. */
+    points: [Vector2Like, Vector2Like];
+    /** Line's color in css format */
+    color: ColorInput;
+    /** Line's width in screen-space units (pixels). */
+    width: number;
+}
+
+/**
+ * Data for mouse events
+ */
+export declare interface MouseEventData {
+    /** Original mouse event */
+    event: MouseEvent;
+    /** Point in svg coordinates */
+    point: Vector2Like;
+    /** Intersected defs */
+    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;
+    /**
+     * 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;
+}
+
+/** Polygon shape instance. */
+export declare class Polygon {
+    /** Array of polygon vertices. */
+    readonly vertices: Vector2[];
+    /** Array of polygon indices. Each index is a triplet of vertex indices forming a triangle. */
+    readonly indices: Index[];
+    /**
+     * @param vertices Array of polygon vertices.
+     * @param indices Array of polygon indices. Each index is a triplet of vertex indices forming a triangle.
+     */
+    constructor(vertices: IVector2[], indices: Index[]);
+    /**
+     * Converts a {@link Rect} to a {@link Polygon}.
+     * @param rect {@link Rect} instance
+     * @returns new {@link Polygon} instance
+     */
+    static fromRect(rect: Rect): Polygon;
+    /**
+     * Merges multiple polygons into a single one.
+     * @param polygons Array of {@link Polygon} instances
+     * @returns new {@link Polygon} instance
+     */
+    static merge(...polygons: Polygon[]): Polygon;
+    /**
+     * Rotates all vertices of the polygon around the given center.
+     * @param rotation Rotation angle in radians. Positive values rotate clockwise.
+     * @param center Center of the rotation.
+     * @returns this {@link Polygon} instance
+     */
+    rotate(rotation: number, center: Vector2Like): Polygon;
+}
+
+/** Rectangle shape instance. */
+export declare class Rect {
+    /** Top left corner of the rectangle. */
+    readonly min: Vector2;
+    /** Bottom right corner of the rectangle. */
+    readonly max: Vector2;
+    /** Optional rotation of the rectangle. In radians, around center. Positive values rotate clockwise. */
+    rotation: number;
+    private _center?;
+    private _size?;
+    /**
+     * @param min Top left corner of the rectangle.
+     * @param max Bottom right corner of the rectangle.
+     * @param rotation Optional rotation of the rectangle. In radians, around center. Positive values rotate clockwise.
+     */
+    constructor(min: IVector2, max: IVector2, rotation?: number);
+    /** Center of the rectangle. Read-only, calculated on demand. */
+    get center(): Vector2;
+    /** Size of the rectangle. Read-only, calculated on demand. */
+    get size(): Vector2;
+    /**
+     * Creates a rectangle from an SVG rectangle element.
+     * @param rect {@link SVGRectElement} or {@link SVGImageElement}
+     * @param rotation Optional rotation of the rectangle. In radians, around center. Positive values rotate clockwise.
+     * @returns new {@link Rect} instance
+     */
+    static fromSvg(rect: SVGRectElement | SVGImageElement, rotation?: number): Rect;
+    /**
+     * Increases the size of the rectangle by the given amount. Padding is added to both sides of the rectangle.
+     * @param x Horizontal padding.
+     * @param y Vertical padding. If omitted, defaults to the same value as `x`.
+     * @returns this {@link Rect} instance
+     */
+    addPadding(x: number, y?: number): this;
+}
+
+export declare type RenderableDef = LayerDef | ShapeDef | ImageDef | TextDef | LineDef;
+
+export declare type RenderableDefCollection<T = RenderableDef> = T extends RenderableDef ? T[] : never;
+
+/**
+ * Main class for rendering the content of a {@link SceneDef}
+ */
+export declare class Renderer {
+    /** Whether to log debug information */
+    readonly debugLog: boolean;
+    /** {@link HTMLCanvasElement} that this renderer is rendering to */
+    readonly canvas: HTMLCanvasElement;
+    private ui?;
+    private clock;
+    private renderer;
+    private eventSystem;
+    private layerSystem;
+    private viewportSystem;
+    private interactionsSystem;
+    private memoryInfoExtension;
+    private memoryInfo;
+    private viewport?;
+    private needsRedraw;
+    private isExternalMode;
+    /**
+     * @param opts {@link RendererOptions}
+     */
+    constructor(opts: RendererOptions);
+    /**
+     * {@link NavigationAPI} instance for controlling the viewport
+     */
+    get controls(): NavigationAPI & {
+        handlers: Handlers;
+        controller: default_3;
+    };
+    /**
+     * {@link EventsAPI} instance for subscribing to internal events
+     */
+    get events(): EventsAPI;
+    /**
+     * Optional sub-rectangle of the viewport that is used for positioning scene's viewbox
+     */
+    get visibleRect(): Rect | undefined;
+    /**
+     * Optional sub-rectangle of the viewport that is used for positioning scene's viewbox
+     */
+    set visibleRect(rect: Rect);
+    /**
+     * Underlying {@link WebGLRenderer} instance
+     */
+    get context(): WebGLRenderer;
+    /* Excluded from this release type: size */
+    /**
+     * 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;
+    /**
+     * Update scene matrix from dynamic transform matrix.
+     * @param dynamicTransformMatrix dynamic transform matrix (changes every frame)
+     */
+    updateExternalTransformMatrix(dynamicTransformMatrix: number[]): void;
+    /**
+     * Initialize the scene and start the rendering loop
+     * @param sceneDef {@link SceneDef} to render
+     * @param startLoop whether to start the rendering loop
+     */
+    start(sceneDef: SceneDef, startLoop?: boolean): void;
+    /**
+     * Update the given defs to make them reflect the current state
+     * @param defs {@link RenderableDef} array to update
+     */
+    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)
+     * @returns point in SVG space
+     */
+    screenToSvg(point: Vector2Like): Vector2Like;
+    /**
+     * Main rendering loop
+     */
+    render(): void;
+    private resizeCanvasToDisplaySize;
+    private updateMemoryInfo;
+    private onContextLost;
+    private onContextRestored;
+}
+
+/**
+ * Options for initializing the {@link Renderer}
+ */
+export declare interface RendererOptions {
+    /** {@link HTMLCanvasElement} to render to */
+    canvas: HTMLCanvasElement;
+    /** Optional {@link WebGLRenderingContext} to use (e.g. for Mapbox GL JS) */
+    gl?: WebGLRenderingContext;
+    /** Whether to log debug information */
+    debugLog?: boolean;
+    /** Optional partial {@link UI} configuration */
+    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;
+}
+
+/**
+ * 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
+ */
+declare class RollHandler extends Handler {
+    private rotating;
+    private startVector?;
+    private vector?;
+    private minDiameter;
+    private startBearing;
+    private raycaster;
+    private pivotWorld;
+    private tempVec2;
+    private tempVec3;
+    reset(): void;
+    /**
+     * Enable roll gestures.
+     * - Mobile: custom two-finger rotation with pivot compensation
+     */
+    protected onEnable(): void;
+    /**
+     * Disable roll gestures.
+     * Restricts azimuth angle to zero and removes event listeners
+     */
+    protected onDisable(): void;
+    private onRotateStart;
+    private onRotate;
+    private onRotateEnd;
+    /**
+     * Check if rotation is below threshold (Mapbox-style).
+     * Threshold is in pixels along circumference, scaled by touch circle diameter.
+     * @param vector Current vector between fingers
+     * @returns true if below threshold, false otherwise
+     */
+    private isBelowThreshold;
+    /**
+     * Get signed angle between two vectors in degrees
+     * @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
+     */
+    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;
+}
+
+/**
+ * Options for the RollController class.
+ */
+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;
+}
+
+/** Scene definition */
+export declare interface SceneDef {
+    /** Root layer of the scene tree */
+    rootLayer: LayerDef;
+    /** Background color in css format */
+    background?: ColorInput;
+    /** SVG viewbox */
+    viewbox: Rect;
+    /** Textures memory limit in megabytes */
+    memoryLimit?: number;
+}
+
+export declare type Shape = Rect | Polygon;
+
+/** Shape definition. */
+export declare interface ShapeDef extends SharedDef {
+    /** Shape to render. Not updatable. */
+    shape: Shape;
+    /** Shape's color in css format */
+    color: ColorInput;
+}
+
+/** Shared properties for all renderable defs */
+export declare interface SharedDef {
+    /** Whether the def is hidden */
+    hidden?: boolean;
+    /** Def's dim state. `true` to dim, `false` to skip dim, `undefined` to reset to ancestor's value. */
+    dim?: boolean;
+}
+
+/** Text alignment */
+export declare interface TextAlignment {
+    /** Horizontal alignment */
+    horizontal: "left" | "center" | "right";
+    /** Vertical alignment */
+    vertical: "top" | "center" | "bottom";
+    /** Text alignment within the line. Optional. */
+    text?: "left" | "center" | "right";
+}
+
+/** Text definition */
+export declare interface TextDef extends SharedDef {
+    /** Array of text lines. Not updatable, but each line is updatable. */
+    lines: TextLineDef[];
+    /** Text's bounds */
+    bounds: Rect;
+    /** Text's padding [horizontal, vertical] */
+    padding: [number, number];
+    /** {@link TextAlignment} object describing text's alignment */
+    alignment: TextAlignment;
+}
+
+/** Single text line definition */
+export declare interface TextLineDef {
+    /** Line's text */
+    text: string;
+    /** Line's color in css format */
+    color: ColorInput;
+    /** Line's font URL. Not updatable. Supported formats: .ttf, .otf, .woff (.woff2 is not supported). */
+    fontUrl: string;
+    /** Line's font size */
+    fontSize: number;
+    /** Line's stroke color & width. Optional. */
+    stroke?: {
+        color: ColorInput;
+        width: number;
+    };
+}
+
+/** Typed layer definition. Useful for type-checking and type-casting. */
+export declare interface TypedLayerDef<T extends RenderableDef> extends LayerDef {
+    children: RenderableDefCollection<T>;
+}
+
+/**
+ * Type describing debug UI elements
+ */
+export declare interface UI {
+    /** {@link Stats} instance for tracking performance metrics */
+    stats: default_2;
+    /** HTML element for displaying WebGL memory information */
+    memoryInfoPanel: HTMLDivElement;
+}
+
+/** Options for the {@link NavigationAPI.zoomTo} method. */
+declare interface ZoomToOptions {
+    /** Maximum zoom factor. */
+    maxZoom: number;
+    /** Percentage of padding to add to the target rectangle. */
+    paddingPercent: number;
+}
+
+export { }