🎩 You're Invited:Meet the Socket team at Black Hat in Las Vegas, August 3-6.RSVP
Sign In

@expofp/renderer

Package Overview
Dependencies
Maintainers
5
Versions
33
Alerts
File Explorer

Advanced tools

Socket logo

Install Socket

Detect and block malicious and high-risk dependencies

Install

@expofp/renderer - npm Package Compare versions

Comparing version
1.2.1
to
1.3.2
+385
-138
dist/index.d.ts

@@ -0,4 +1,10 @@

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';

@@ -9,18 +15,110 @@ import { Vector2Like } 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;
}
/**

@@ -39,4 +137,2 @@ * Converts multiple vector2 representations to a {@link Vector2} instance.

"navigation:change": void;
/** Camera stop */
"navigation:stop": void;
/** Camera roll */

@@ -52,4 +148,2 @@ "navigation:roll": number;

"viewport:ptscale": number;
/** Camera update */
"camera:update": void;
}

@@ -70,2 +164,37 @@

/**
* 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.

@@ -90,3 +219,3 @@ * Provides common lifecycle management and access to camera controller, DOM element, and event manager.

*
* reset(): void {
* reset(enableTransition = true): Promise<void> {
* // No custom state to reset

@@ -112,3 +241,3 @@ * }

*
* reset(): void {
* reset(enableTransition = true): Promise<void> {
* this.rotating = false;

@@ -120,3 +249,3 @@ * }

declare abstract class Handler<T = undefined> implements HandlerAPI<T> {
protected controller: default_3;
protected viewportSystem: ViewportSystem;
protected domElement: HTMLElement;

@@ -126,8 +255,10 @@ protected eventManager: EventManager;

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);
/**

@@ -143,4 +274,6 @@ * Per-frame update for this handler.

* 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>;
/**

@@ -160,3 +293,3 @@ * Configure this handler with handler-specific options.

* 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
*/

@@ -192,3 +325,3 @@ disable(): void;

*/
declare interface HandlerAPI<T = undefined> {
export declare interface HandlerAPI<T = undefined> {
/**

@@ -215,4 +348,6 @@ * Enable this handler

* 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>;
}

@@ -223,8 +358,12 @@

*/
declare type Handlers = Readonly<{
declare interface Handlers {
/** Pan handler */
pan: PanHandler;
/** Zoom handler */
zoom: ZoomHandler;
/** Roll handler */
roll: RollHandler;
}>;
/** Pitch handler */
pitch: PitchHandler;
}

@@ -248,18 +387,2 @@ /** Image definition */

/**
* 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;

@@ -319,14 +442,2 @@

/** 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;
}
/**

@@ -338,3 +449,5 @@ * Pan handler - wraps camera-controls TRUCK action.

declare class PanHandler extends Handler {
reset(): void;
private inertia;
reset(enableTransition?: boolean): Promise<void>;
update(delta: number): boolean;
/**

@@ -352,2 +465,62 @@ * Enable pan gestures.

/**
* 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. */

@@ -434,4 +607,3 @@ export declare class Polygon {

private ui?;
private clock;
private renderer;
private gl?;
private eventSystem;

@@ -441,7 +613,9 @@ private layerSystem;

private interactionsSystem;
private controlsSystem;
private clock;
private renderer;
private viewport?;
private needsRedraw;
private memoryInfoExtension;
private memoryInfo;
private viewport?;
private needsRedraw;
private isExternalMode;
/**

@@ -452,8 +626,5 @@ * @param opts {@link 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;
/**

@@ -480,3 +651,3 @@ * {@link EventsAPI} instance for subscribing to internal events

*/
configureExternalMode(staticTransformMatrix: number[]): void;
setExternalTransform(staticTransformMatrix: number[]): void;
/**

@@ -486,3 +657,3 @@ * Update scene matrix from dynamic transform matrix.

*/
updateExternalTransformMatrix(dynamicTransformMatrix: number[]): void;
updateExternalCamera(dynamicTransformMatrix: number[]): void;
/**

@@ -501,3 +672,3 @@ * Initialize the scene and start the rendering loop

* 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

@@ -530,9 +701,6 @@ */

/** 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;
};

@@ -542,22 +710,30 @@ /**

* 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
*/

@@ -567,11 +743,16 @@ protected onEnable(): void;

* Disable roll gestures.
* Restricts azimuth angle to zero and removes event listeners
*/
protected onDisable(): void;
private onRotateStart;
private onRotateEnd;
private onRotate;
private onRotateEnd;
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

@@ -582,3 +763,3 @@ * @returns true if below threshold, false otherwise

/**
* Get signed angle between two vectors in degrees
* Get signed angle between two vectors in degrees (Mapbox pattern)
* @param a First vector

@@ -590,51 +771,19 @@ * @param b Second vector

/**
* Normalize screen pixel coordinates to NDC [-1, 1]
* @param screenPos Screen position in pixels
* @param out Output vector for NDC coordinates
* @returns NDC coordinates
* Normalize angle to be between -π and π
* @param angle Angle in radians
* @returns Normalized angle in radians
*/
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;
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;
}

@@ -650,2 +799,4 @@

viewbox: Rect;
/** Scene's rectangle bounds in SVG coordinates. Essentially, the size of a largest layer */
bounds?: Rect;
/** Textures memory limit in megabytes */

@@ -673,2 +824,4 @@ memoryLimit?: number;

declare type Space = "svg" | "world";
/** Text alignment */

@@ -728,4 +881,98 @@ export declare interface TextAlignment {

/** 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. */

@@ -732,0 +979,0 @@ maxZoom: number;

{
"name": "@expofp/renderer",
"version": "1.2.1",
"version": "1.3.2",
"type": "module",

@@ -8,2 +8,5 @@ "files": [

],
"publishConfig": {
"access": "public"
},
"exports": "./dist/index.js",

@@ -23,3 +26,2 @@ "devDependencies": {

"culori": "^4.0.1",
"hold-event": "^1.1.0",
"maxrects-packer": "^2.7.3",

@@ -26,0 +28,0 @@ "mjolnir.js": "^3.0.0",

Sorry, the diff of this file is too big to display