@canvas-tile-engine/core 0.2.0 → 0.3.0

package/dist/index.d.mts

@@ -1,43 +1,223 @@
 /**
- * Simple image loader with in-memory caching to avoid duplicate network requests.
+ * Normalizes and stores grid engine configuration with safe defaults.
  */
-declare class ImageLoader {
-    private cache;
-    private inflight;
-    private listeners;
+declare class Config {
+    private config;
     /**
-     * Register a callback fired when a new image finishes loading.
+     * Create a config store with defaults merged from the provided partial config.
+     * @param config Incoming configuration values.
+     * @throws {ConfigValidationError} If any config value is invalid.
      */
-    onLoad(cb: () => void): () => boolean;
-    private notifyLoaded;
+    constructor(config: CanvasTileEngineConfig);
     /**
-     * Load an image, reusing cache when possible.
-     * @param src Image URL.
-     * @param retry How many times to retry on error (default: 1).
-     * @returns Promise resolving to the loaded image element.
+     * Get a defensive copy of the current configuration.
+     * @returns Normalized configuration snapshot e.g. `{ scale: 1, size: { width: 800, height: 600 }, ... }`.
      */
-    load(src: string, retry?: number): Promise<HTMLImageElement>;
+    get(): Readonly<Required<CanvasTileEngineConfig>>;
     /**
-     * Get a cached image without loading.
-     * @param src Image URL key.
+     * Update event handlers at runtime.
+     * @param handlers Partial event handlers to update.
      */
-    get(src: string): HTMLImageElement | undefined;
+    updateEventHandlers(handlers: Partial<EventHandlers>): void;
     /**
-     * Check if an image is already cached.
-     * @param src Image URL key.
+     * Update map bounds at runtime.
+     * @param bounds New boundary limits. Use Infinity/-Infinity to remove limits on specific axes.
+     * @throws {ConfigValidationError} If bounds are invalid.
      */
-    has(src: string): boolean;
+    updateBounds(bounds: {
+        minX: number;
+        maxX: number;
+        minY: number;
+        maxY: number;
+    }): void;
+}
+
+/**
+ * Camera contract used by rendering and coordinate transforms.
+ */
+interface ICamera$1 {
+    /** Current top-left world x coordinate. */
+    readonly x: number;
+    /** Current top-left world y coordinate. */
+    readonly y: number;
+    /** Current zoom scale. */
+    readonly scale: number;
     /**
-     * Clear all cached and inflight images/listeners to free memory.
+     * Pan the camera by screen-space deltas.
+     * @param deltaScreenX X delta in pixels.
+     * @param deltaScreenY Y delta in pixels.
      */
-    clear(): void;
+    pan(deltaScreenX: number, deltaScreenY: number): void;
+    /**
+     * Zoom around a mouse position.
+     * @param mouseX Mouse X relative to viewport.
+     * @param mouseY Mouse Y relative to viewport.
+     * @param deltaY Wheel delta (positive scroll down).
+     * @param canvasRect Canvas bounding rect for mouse offset.
+     */
+    zoom(mouseX: number, mouseY: number, deltaY: number, canvasRect: DOMRect): void;
+    /**
+     * Canvas center coordinates in world space.
+     * @param canvasWidth Canvas width in pixels.
+     * @param canvasHeight Canvas height in pixels.
+     * @returns Center point in world coordinates.
+     */
+    getCenter(canvasWidth: number, canvasHeight: number): Coords;
+    /**
+     * Set top-left coordinates based on a target center.
+     * @param center Desired center in world space.
+     * @param canvasWidth Canvas width in pixels.
+     * @param canvasHeight Canvas height in pixels.
+     */
+    setCenter(center: Coords, canvasWidth: number, canvasHeight: number): void;
+    /**
+     * Adjust view so center stays stable on resize.
+     * @param deltaWidthPx Change in canvas width (pixels).
+     * @param deltaHeightPx Change in canvas height (pixels).
+     */
+    adjustForResize(deltaWidthPx: number, deltaHeightPx: number): void;
+    /**
+     * Zoom by a scale factor around a specific point (for pinch-to-zoom).
+     * @param factor Scale multiplier (>1 zooms in, <1 zooms out).
+     * @param centerX Center X in screen coordinates.
+     * @param centerY Center Y in screen coordinates.
+     */
+    zoomByFactor(factor: number, centerX: number, centerY: number): void;
+    /**
+     * Set the camera scale directly, clamped to min/max bounds.
+     * @param newScale The desired scale value.
+     */
+    setScale(newScale: number): void;
+    /**
+     * Get the visible world coordinate bounds of the viewport.
+     * @param canvasWidth Canvas width in pixels.
+     * @param canvasHeight Canvas height in pixels.
+     * @returns Visible bounds with min/max coordinates (floored/ceiled to cell boundaries).
+     */
+    getVisibleBounds(canvasWidth: number, canvasHeight: number): {
+        minX: number;
+        maxX: number;
+        minY: number;
+        maxY: number;
+    };
 }
 
-interface LayerHandle {
-    layer: number;
-    id: symbol;
+/**
+ * Transforms coordinates between world space and screen space using the active camera.
+ */
+declare class CoordinateTransformer {
+    private camera;
+    /**
+     * @param camera Camera providing origin and scaling for transformations.
+     */
+    constructor(camera: ICamera$1);
+    /**
+     * Convert a world grid coordinate to screen pixels, accounting for camera offset and scale.
+     * @param worldX Grid X in world space (tile index).
+     * @param worldY Grid Y in world space (tile index).
+     * @returns Screen-space coordinates in pixels. e.g., (e.g. `{ x: 100.5, y: 200.5 }`).
+     */
+    worldToScreen(worldX: number, worldY: number): Coords;
+    /**
+     * Convert screen pixel coordinates back to world space grid coordinates.
+     * @param screenX X coordinate in screen space (pixels).
+     * @param screenY Y coordinate in screen space (pixels).
+     * @returns World-space grid coordinates. (e.g. `{ x: 10, y: 20 }`).
+     */
+    screenToWorld(screenX: number, screenY: number): Coords;
+}
+
+/**
+ * Holds mutable viewport size for runtime changes (resize, layout).
+ * Also tracks device pixel ratio for HiDPI/Retina display support.
+ */
+declare class ViewportState {
+    private width;
+    private height;
+    private _dpr;
+    constructor(width: number, height: number);
+    getSize(): {
+        width: number;
+        height: number;
+    };
+    setSize(width: number, height: number): void;
+    /**
+     * Get the current device pixel ratio.
+     * Used for HiDPI/Retina display rendering.
+     */
+    get dpr(): number;
+    /**
+     * Update DPR (useful when window moves between displays).
+     */
+    updateDpr(): void;
 }
 
+type onDrawCallback = (ctx: unknown, info: {
+    scale: number;
+    width: number;
+    height: number;
+    coords: Coords;
+}) => void;
+type MouseEventCallback = (coords: {
+    raw: Coords;
+    snapped: Coords;
+}, mouse: {
+    raw: Coords;
+    snapped: Coords;
+}, client: {
+    raw: Coords;
+    snapped: Coords;
+}) => void;
+type onClickCallback = MouseEventCallback;
+type onHoverCallback = MouseEventCallback;
+type onMouseDownCallback = MouseEventCallback;
+type onMouseUpCallback = MouseEventCallback;
+type onMouseLeaveCallback = MouseEventCallback;
+type onRightClickCallback = MouseEventCallback;
+type onZoomCallback = (scale: number) => void;
+
+type DrawObject = {
+    x: number;
+    y: number;
+    size?: number;
+    origin?: {
+        mode?: "cell" | "self";
+        x?: number;
+        y?: number;
+    };
+    style?: {
+        fillStyle?: string;
+        strokeStyle?: string;
+        lineWidth?: number;
+    };
+    /** Rotation angle in degrees (0 = no rotation, positive = clockwise) */
+    rotate?: number;
+    /** Border radius in pixels. Single value for all corners, or array for [topLeft, topRight, bottomRight, bottomLeft] */
+    radius?: number | number[];
+};
+type Rect = DrawObject;
+type Circle = Omit<DrawObject, "rotate" | "radius">;
+type ImageItem = Omit<DrawObject, "style"> & {
+    img: HTMLImageElement;
+};
+type Text = Omit<DrawObject, "radius" | "size"> & {
+    text: string;
+    /** Font size in world units (scales with zoom). Default: 1 */
+    size?: number;
+    style?: {
+        fillStyle?: string;
+        /** Font family (default: "sans-serif") */
+        fontFamily?: string;
+        textAlign?: CanvasTextAlign;
+        textBaseline?: CanvasTextBaseline;
+    };
+};
+type Line = {
+    from: Coords;
+    to: Coords;
+};
+type Path = Coords[];
+
 type CanvasTileEngineConfig = {
     renderer?: "canvas";
     scale: number;
@@ -100,74 +280,121 @@ type EventHandlers = {
     zoom?: boolean;
     resize?: boolean;
 };
+
 type Coords = {
     x: number;
     y: number;
 };
-type onDrawCallback = (ctx: CanvasRenderingContext2D, info: {
-    scale: number;
+interface LineStyle {
+    strokeStyle?: string;
+    lineWidth?: number;
+}
+interface Bounds {
+    minX: number;
+    maxX: number;
+    minY: number;
+    maxY: number;
+}
+interface ViewportBounds {
+    left: number;
+    top: number;
     width: number;
     height: number;
-    coords: Coords;
-}) => void;
-type MouseEventCallback = (coords: {
-    raw: Coords;
-    snapped: Coords;
-}, mouse: {
-    raw: Coords;
-    snapped: Coords;
-}, client: {
-    raw: Coords;
-    snapped: Coords;
-}) => void;
-type onClickCallback = MouseEventCallback;
-type onHoverCallback = MouseEventCallback;
-type onMouseDownCallback = MouseEventCallback;
-type onMouseUpCallback = MouseEventCallback;
-type onMouseLeaveCallback = MouseEventCallback;
-type onRightClickCallback = MouseEventCallback;
-type onZoomCallback = (scale: number) => void;
-type DrawObject = {
-    x: number;
-    y: number;
-    size?: number;
-    origin?: {
-        mode?: "cell" | "self";
-        x?: number;
-        y?: number;
-    };
-    style?: {
-        fillStyle?: string;
-        strokeStyle?: string;
-        lineWidth?: number;
-    };
-    /** Rotation angle in degrees (0 = no rotation, positive = clockwise) */
-    rotate?: number;
-    /** Border radius in pixels. Single value for all corners, or array for [topLeft, topRight, bottomRight, bottomLeft] */
-    radius?: number | number[];
-};
-type Rect = DrawObject;
-type Circle = Omit<DrawObject, "rotate" | "radius">;
-type ImageItem = Omit<DrawObject, "style"> & {
-    img: HTMLImageElement;
-};
-type Text = Omit<DrawObject, "radius" | "size"> & {
-    text: string;
-    /** Font size in world units (scales with zoom). Default: 1 */
-    size?: number;
-    style?: {
-        fillStyle?: string;
-        /** Font family (default: "sans-serif") */
-        fontFamily?: string;
-        textAlign?: CanvasTextAlign;
-        textBaseline?: CanvasTextBaseline;
-    };
-};
-type Line = {
-    from: Coords;
-    to: Coords;
-};
-type Path = Coords[];
+}
+interface RendererDependencies {
+    wrapper: HTMLDivElement;
+    camera: ICamera;
+    viewport: ViewportState;
+    config: Config;
+    transformer: CoordinateTransformer;
+}
+interface IRenderer {
+    init(deps: RendererDependencies): void;
+    render(): void;
+    resize(width: number, height: number): void;
+    resizeWithAnimation(width: number, height: number, durationMs: number, onComplete?: () => void): void;
+    destroy(): void;
+    getDrawAPI(): IDrawAPI;
+    getImageLoader(): IImageLoader;
+    setupEvents(): void;
+    onClick?: onClickCallback;
+    onRightClick?: onRightClickCallback;
+    onHover?: onHoverCallback;
+    onMouseDown?: onMouseDownCallback;
+    onMouseUp?: onMouseUpCallback;
+    onMouseLeave?: onMouseLeaveCallback;
+    onZoom?: onZoomCallback;
+    onResize?: () => void;
+    onCameraChange?: () => void;
+    onDraw?: onDrawCallback;
+}
+interface IDrawAPI {
+    addDrawFunction(fn: (ctx: unknown, coords: Coords, config: Required<CanvasTileEngineConfig>) => void, layer?: number): DrawHandle;
+    drawRect(items: Rect | Rect[], layer?: number): DrawHandle;
+    drawCircle(items: Circle | Circle[], layer?: number): DrawHandle;
+    drawLine(items: Line | Line[], style?: LineStyle, layer?: number): DrawHandle;
+    drawText(items: Text | Text[], layer?: number): DrawHandle;
+    drawImage(items: ImageItem | ImageItem[], layer?: number): DrawHandle;
+    drawPath(items: Path | Path[], style?: LineStyle, layer?: number): DrawHandle;
+    drawGridLines(cellSize: number, style: {
+        lineWidth: number;
+        strokeStyle: string;
+    }, layer?: number): DrawHandle;
+    drawStaticRect(items: Rect[], cacheKey: string, layer?: number): DrawHandle;
+    drawStaticCircle(items: Circle[], cacheKey: string, layer?: number): DrawHandle;
+    drawStaticImage(items: ImageItem[], cacheKey: string, layer?: number): DrawHandle;
+    removeDrawHandle(handle: DrawHandle): void;
+    clearLayer(layer: number): void;
+    clearAll(): void;
+    clearStaticCache(cacheKey?: string): void;
+}
+interface DrawHandle {
+    readonly id: symbol;
+    readonly layer: number;
+}
+/**
+ * Platform-agnostic image loader interface.
+ * Each renderer implements this with platform-specific image handling.
+ */
+interface IImageLoader<TImage = unknown> {
+    /**
+     * Load an image from URL, with caching.
+     * @param src Image URL.
+     * @param retry Retry count on failure.
+     */
+    load(src: string, retry?: number): Promise<TImage>;
+    /**
+     * Get a cached image without loading.
+     */
+    get(src: string): TImage | undefined;
+    /**
+     * Check if an image is already cached.
+     */
+    has(src: string): boolean;
+    /**
+     * Clear all cached images.
+     */
+    clear(): void;
+    /**
+     * Register a callback fired when a new image finishes loading.
+     * @returns Unsubscribe function.
+     */
+    onLoad(cb: () => void): () => void;
+}
+interface ICamera {
+    readonly x: number;
+    readonly y: number;
+    readonly scale: number;
+    pan(dx: number, dy: number): void;
+    zoom(screenX: number, screenY: number, deltaY: number, bounds: ViewportBounds): void;
+    zoomByFactor(factor: number, centerX: number, centerY: number): void;
+    setScale(scale: number): void;
+    setCenter(center: Coords, viewportWidth: number, viewportHeight: number): void;
+    getCenter(viewportWidth: number, viewportHeight: number): Coords;
+    getVisibleBounds(viewportWidth: number, viewportHeight: number): Bounds;
+    setBounds(bounds: Bounds): void;
+    adjustForResize(dw: number, dh: number): void;
+}
 
 /**
  * Core engine wiring camera, config, renderer, events, and draw helpers.
@@ -177,16 +404,15 @@ declare class CanvasTileEngine {
     private camera;
     private viewport;
     private coordinateTransformer;
-    private layers?;
     private renderer;
-    private events;
-    private draw?;
-    images: ImageLoader;
-    private sizeController;
     private animationController;
-    private responsiveWatcher?;
     canvasWrapper: HTMLDivElement;
     canvas: HTMLCanvasElement;
+    /**
+     * Image loader for loading and caching images.
+     * Uses the renderer's platform-specific implementation.
+     */
+    get images(): IImageLoader;
     /**
      * Callback when center coordinates change (pan or zoom).
      * @param coords - Center world coordinates: `{ x, y }`
@@ -329,11 +555,12 @@ declare class CanvasTileEngine {
     get onZoom(): ((scale: number) => void) | undefined;
     set onZoom(cb: ((scale: number) => void) | undefined);
     /**
-     * @param canvas Target canvas element.
+     * @param canvasWrapper Canvas wrapper element containing a canvas child.
      * @param config Initial engine configuration.
+     * @param renderer The renderer implementation to use (e.g., RendererCanvas).
      * @param center Initial center in world space.
      */
-    constructor(canvasWrapper: HTMLDivElement, config: CanvasTileEngineConfig, center?: Coords);
+    constructor(canvasWrapper: HTMLDivElement, config: CanvasTileEngineConfig, renderer: IRenderer, center?: Coords);
     /** Tear down listeners and observers. */
     destroy(): void;
     /** Render a frame using the active renderer. */
@@ -452,20 +679,14 @@ declare class CanvasTileEngine {
         maxY: number;
     }): void;
     /**
-     * Register a generic draw callback (canvas renderer only).
-     * @param fn Callback invoked with context, top-left coords, and config.
-     * @param layer Layer order (lower draws first).
-     */
-    addDrawFunction(fn: (ctx: CanvasRenderingContext2D, coords: Coords, config: Required<CanvasTileEngineConfig>) => void, layer?: number): LayerHandle;
-    /**
-     * Draw one or many rectangles in world space (canvas renderer only).
+     * Draw one or many rectangles in world space.
      * Supports rotation via the `rotate` property (degrees, positive = clockwise).
      * @param items Rectangle definitions.
      * @param layer Layer order (lower draws first).
      */
-    drawRect(items: Rect | Array<Rect>, layer?: number): LayerHandle;
+    drawRect(items: Rect | Array<Rect>, layer?: number): DrawHandle;
     /**
-     * Draw rectangles with pre-rendering cache (canvas renderer only).
+     * Draw rectangles with pre-rendering cache.
      * Renders all items once to an offscreen canvas, then blits the visible portion each frame.
      * Ideal for large static datasets like mini-maps where items don't change.
      * Supports rotation via the `rotate` property (degrees, positive = clockwise).
@@ -473,18 +694,18 @@ declare class CanvasTileEngine {
      * @param cacheKey Unique key for this cache (e.g., "minimap-items").
      * @param layer Layer order (lower draws first).
      */
-    drawStaticRect(items: Array<Rect>, cacheKey: string, layer?: number): LayerHandle;
+    drawStaticRect(items: Array<Rect>, cacheKey: string, layer?: number): DrawHandle;
     /**
-     * Draw circles with pre-rendering cache (canvas renderer only).
+     * Draw circles with pre-rendering cache.
      * Renders all items once to an offscreen canvas, then blits the visible portion each frame.
      * Ideal for large static datasets like mini-maps where items don't change.
      * @param items Array of circle definitions.
      * @param cacheKey Unique key for this cache (e.g., "minimap-circles").
      * @param layer Layer order (lower draws first).
      */
-    drawStaticCircle(items: Array<Circle>, cacheKey: string, layer?: number): LayerHandle;
+    drawStaticCircle(items: Array<Circle>, cacheKey: string, layer?: number): DrawHandle;
     /**
-     * Draw images with pre-rendering cache (canvas renderer only).
+     * Draw images with pre-rendering cache.
      * Renders all items once to an offscreen canvas, then blits the visible portion each frame.
      * Ideal for large static datasets like terrain tiles or static decorations.
      * Supports rotation via the `rotate` property (degrees, positive = clockwise).
@@ -492,14 +713,14 @@ declare class CanvasTileEngine {
      * @param cacheKey Unique key for this cache (e.g., "terrain-cache").
      * @param layer Layer order (lower draws first).
      */
-    drawStaticImage(items: Array<ImageItem>, cacheKey: string, layer?: number): LayerHandle;
+    drawStaticImage(items: Array<ImageItem>, cacheKey: string, layer?: number): DrawHandle;
     /**
      * Clear a static rendering cache.
      * @param cacheKey The cache key to clear, or undefined to clear all caches.
      */
     clearStaticCache(cacheKey?: string): void;
     /**
-     * Draw one or many lines between world points (canvas renderer only).
+     * Draw one or many lines between world points.
      * @param items Line segments.
      * @param style Line style overrides.
      * @param layer Layer order.
@@ -507,15 +728,15 @@ declare class CanvasTileEngine {
     drawLine(items: Array<Line> | Line, style?: {
         strokeStyle?: string;
         lineWidth?: number;
-    }, layer?: number): LayerHandle;
+    }, layer?: number): DrawHandle;
     /**
-     * Draw one or many circles sized in world units (canvas renderer only).
+     * Draw one or many circles sized in world units.
      * @param items Circle definitions.
      * @param layer Layer order.
      */
-    drawCircle(items: Circle | Array<Circle>, layer?: number): LayerHandle;
+    drawCircle(items: Circle | Array<Circle>, layer?: number): DrawHandle;
     /**
-     * Draw one or many texts at world positions (canvas renderer only).
+     * Draw one or many texts at world positions.
      * @param items Text definitions with position, text, size, and style.
      * @param layer Layer order.
      * @example
@@ -535,9 +756,9 @@ declare class CanvasTileEngine {
      * ]);
      * ```
      */
-    drawText(items: Array<Text> | Text, layer?: number): LayerHandle;
+    drawText(items: Array<Text> | Text, layer?: number): DrawHandle;
     /**
-     * Draw one or many polylines through world points (canvas renderer only).
+     * Draw one or many polylines through world points.
      * @param items Polyline point collections.
      * @param style Stroke style overrides.
      * @param layer Layer order.
@@ -545,30 +766,38 @@ declare class CanvasTileEngine {
     drawPath(items: Array<Path> | Path, style?: {
         strokeStyle?: string;
         lineWidth?: number;
-    }, layer?: number): LayerHandle;
+    }, layer?: number): DrawHandle;
     /**
-     * Draw one or many images scaled in world units (canvas renderer only).
+     * Draw one or many images scaled in world units.
      * Supports rotation via the `rotate` property (degrees, positive = clockwise).
      * @param items Image definitions.
      * @param layer Layer order.
      */
-    drawImage(items: Array<ImageItem> | ImageItem, layer?: number): LayerHandle;
+    drawImage(items: Array<ImageItem> | ImageItem, layer?: number): DrawHandle;
     /**
-     *  Draw grid lines at specified cell size (canvas renderer only).
+     * Draw grid lines at specified cell size.
      * @param cellSize Size of each grid cell in world units.
      * @example
      * ```ts
      * engine.drawGridLines(50);
      * ```
      */
-    drawGridLines(cellSize: number, lineWidth?: number, strokeStyle?: string, layer?: number): LayerHandle;
+    drawGridLines(cellSize: number, lineWidth?: number, strokeStyle?: string, layer?: number): DrawHandle;
+    /**
+     * Register a custom draw function for complete rendering control.
+     * Useful for complex or one-off drawing operations.
+     * @param fn Function receiving canvas context, top-left coords, and config.
+     * @param layer Layer index (default 1).
+     * @returns DrawHandle for removal.
+     */
+    addDrawFunction(fn: (ctx: unknown, coords: Coords, config: Required<CanvasTileEngineConfig>) => void, layer?: number): DrawHandle;
     /**
-     * Remove a specific draw callback by handle (canvas renderer only).
+     * Remove a specific draw callback by handle.
      * Does not clear other callbacks on the same layer.
      */
-    removeLayerHandle(handle: LayerHandle): void;
+    removeDrawHandle(handle: DrawHandle): void;
     /**
-     * Clear all draw callbacks from a specific layer (canvas renderer only).
+     * Clear all draw callbacks from a specific layer.
      * Use this before redrawing dynamic content to prevent accumulation.
      * @param layer Layer index to clear.
      * @example
@@ -580,7 +809,7 @@ declare class CanvasTileEngine {
      */
     clearLayer(layer: number): void;
     /**
-     * Clear all draw callbacks from all layers (canvas renderer only).
+     * Clear all draw callbacks from all layers.
      * Useful for complete scene reset.
      * @example
      * ```ts
@@ -589,13 +818,6 @@ declare class CanvasTileEngine {
      * ```
      */
     clearAll(): void;
-    /**
-     * Build the active renderer based on config.
-     * @param type Renderer type requested.
-     */
-    private createRenderer;
-    private ensureCanvasDraw;
-    private getCanvasRenderer;
     private handleCameraChange;
 }
 
@@ -686,4 +908,187 @@ declare function gridToSize(options: {
     cellSize: number;
 }): Pick<CanvasTileEngineConfig, "size" | "scale">;
 
-export { COORDINATE_OVERLAY, CanvasTileEngine, type CanvasTileEngineConfig, type Circle, type Coords, DEBUG_HUD, DEFAULT_VALUES, type DrawObject, type EventHandlers, type ImageItem, type LayerHandle, type Line, type Path, RENDER_DEFAULTS, type Rect, SCALE_LIMITS, SIZE_LIMITS, type Text, VISIBILITY_BUFFER, gridToSize, type onClickCallback, type onDrawCallback, type onHoverCallback, type onMouseDownCallback, type onMouseLeaveCallback, type onMouseUpCallback, type onRightClickCallback, type onZoomCallback };
+/**
+ * Spatial indexing wrapper using RBush (R-Tree) for fast viewport queries
+ * @internal
+ */
+interface SpatialItem {
+    x: number;
+    y: number;
+    /**
+     * Optional world-space size (width/height). Defaults to 0 for point-like items.
+     */
+    size?: number;
+}
+declare class SpatialIndex<T extends SpatialItem> {
+    private tree;
+    constructor();
+    /**
+     * Bulk load items into the R-Tree (much faster than individual inserts)
+     */
+    load(items: T[]): void;
+    /**
+     * Query all items within a rectangular range
+     */
+    query(minX: number, minY: number, maxX: number, maxY: number): T[];
+    /**
+     * Clear all items
+     */
+    clear(): void;
+    /**
+     * Create SpatialIndex from array of items
+     */
+    static fromArray<T extends SpatialItem>(items: T[]): SpatialIndex<T>;
+}
+
+/**
+ * Normalized pointer input - renderer-agnostic format.
+ * All coordinates should be canvas-relative.
+ */
+interface NormalizedPointer {
+    /** X position relative to canvas */
+    x: number;
+    /** Y position relative to canvas */
+    y: number;
+    /** X position relative to viewport (for callbacks) */
+    clientX: number;
+    /** Y position relative to viewport (for callbacks) */
+    clientY: number;
+}
+/**
+ * Normalized multi-pointer input for pinch gestures.
+ */
+interface NormalizedPinch {
+    /** First pointer */
+    pointer1: NormalizedPointer;
+    /** Second pointer */
+    pointer2: NormalizedPointer;
+}
+/**
+ * Processed coordinate result for callbacks.
+ */
+interface ProcessedCoords {
+    coords: {
+        raw: Coords;
+        snapped: Coords;
+    };
+    mouse: {
+        raw: Coords;
+        snapped: Coords;
+    };
+    client: {
+        raw: Coords;
+        snapped: Coords;
+    };
+}
+/**
+ * Canvas bounds for zoom calculation.
+ * Compatible with DOMRect subset needed by Camera.zoom
+ */
+interface CanvasBounds {
+    left: number;
+    top: number;
+    width: number;
+    height: number;
+    x: number;
+    y: number;
+    bottom: number;
+    right: number;
+}
+/**
+ * Handles gesture logic (click, hover, drag, zoom) independent of DOM/platform.
+ * Receives normalized input from renderer and performs calculations.
+ */
+declare class GestureProcessor {
+    private camera;
+    private config;
+    private transformer;
+    private canvasBoundsGetter;
+    private onCameraChange;
+    private isDragging;
+    private shouldPreventClick;
+    private lastPos;
+    private isPinching;
+    private lastPinchDistance;
+    private lastPinchCenter;
+    onClick?: onClickCallback;
+    onRightClick?: onRightClickCallback;
+    onHover?: onHoverCallback;
+    onMouseDown?: onMouseDownCallback;
+    onMouseUp?: onMouseUpCallback;
+    onMouseLeave?: onMouseLeaveCallback;
+    onZoom?: onZoomCallback;
+    constructor(camera: ICamera$1, config: Config, transformer: CoordinateTransformer, canvasBoundsGetter: () => CanvasBounds, onCameraChange: () => void);
+    /**
+     * Process pointer coordinates into world/screen coords for callbacks.
+     */
+    private processCoords;
+    /**
+     * Calculate distance between two pointers.
+     */
+    private getPointerDistance;
+    /**
+     * Calculate center point between two pointers (in client coords).
+     */
+    private getPointerCenter;
+    handleClick: (pointer: NormalizedPointer) => void;
+    handleRightClick: (pointer: NormalizedPointer) => void;
+    handlePointerDown: (pointer: NormalizedPointer) => void;
+    handlePointerMove: (pointer: NormalizedPointer) => void;
+    handlePointerUp: (pointer: NormalizedPointer) => void;
+    handlePointerLeave: (pointer: NormalizedPointer) => void;
+    handleTouchStart: (pointers: NormalizedPointer[]) => void;
+    handleTouchMove: (pointers: NormalizedPointer[]) => void;
+    handleTouchEnd: (remainingPointers: NormalizedPointer[], changedPointer?: NormalizedPointer) => void;
+    handleWheel: (pointer: NormalizedPointer, deltaY: number) => void;
+    get dragging(): boolean;
+    get pinching(): boolean;
+}
+
+/**
+ * Manages smooth animations for camera movements and canvas resizing.
+ * Handles animation frame scheduling and cleanup.
+ */
+declare class AnimationController {
+    private camera;
+    private viewport;
+    private onAnimationFrame;
+    private moveAnimationId?;
+    private resizeAnimationId?;
+    constructor(camera: ICamera$1, viewport: ViewportState, onAnimationFrame: () => void);
+    /**
+     * Smoothly animate camera movement to target coordinates.
+     * @param targetX Target world x coordinate.
+     * @param targetY Target world y coordinate.
+     * @param durationMs Animation duration in milliseconds (default: 500ms). Set to 0 for instant move.
+     * @param onComplete Optional callback fired when animation completes.
+     */
+    animateMoveTo(targetX: number, targetY: number, durationMs?: number, onComplete?: () => void): void;
+    /**
+     * Smoothly animate canvas size change while keeping view centered.
+     * @param targetWidth New canvas width in pixels.
+     * @param targetHeight New canvas height in pixels.
+     * @param durationMs Animation duration in milliseconds (default: 500ms). Set to 0 for instant resize.
+     * @param onApplySize Callback to apply the new size (updates wrapper, canvas, renderer).
+     * @param onComplete Optional callback fired when animation completes.
+     */
+    animateResize(targetWidth: number, targetHeight: number, durationMs: number | undefined, onApplySize: (width: number, height: number, center: Coords) => void, onComplete?: () => void): void;
+    /**
+     * Cancel the current move animation if running.
+     */
+    cancelMove(): void;
+    /**
+     * Cancel the current resize animation if running.
+     */
+    cancelResize(): void;
+    /**
+     * Cancel all running animations.
+     */
+    cancelAll(): void;
+    /**
+     * Check if any animation is currently running.
+     */
+    isAnimating(): boolean;
+}
+
+export { AnimationController, type Bounds, COORDINATE_OVERLAY, type CanvasBounds, CanvasTileEngine, type CanvasTileEngineConfig, type Circle, Config, CoordinateTransformer, type Coords, DEBUG_HUD, DEFAULT_VALUES, type DrawHandle, type DrawObject, type EventHandlers, GestureProcessor, type ICamera, type IDrawAPI, type IImageLoader, type IRenderer, type ImageItem, type Line, type LineStyle, type NormalizedPinch, type NormalizedPointer, type Path, type ProcessedCoords, RENDER_DEFAULTS, type Rect, type RendererDependencies, SCALE_LIMITS, SIZE_LIMITS, SpatialIndex, type Text, VISIBILITY_BUFFER, type ViewportBounds, ViewportState, gridToSize, type onClickCallback, type onDrawCallback, type onHoverCallback, type onMouseDownCallback, type onMouseLeaveCallback, type onMouseUpCallback, type onRightClickCallback, type onZoomCallback };