@canvas-tile-engine/core 0.1.0 → 0.3.0

package/dist/index.d.ts

@@ -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;
+    };
+}
+
+/**
+ * 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;
 }
 
-interface LayerHandle {
-    layer: number;
-    id: symbol;
+/**
+ * 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,70 +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 Line = {
-    from: Coords;
-    to: Coords;
-    style: {
-        strokeStyle?: string;
-        lineWidth?: number;
-    };
-};
-type Circle = Omit<DrawObject, "rotate" | "radius">;
-type Text = {
-    coords: Coords;
-    text: string;
-};
-type Path = Coords[];
-type ImageItem = Omit<DrawObject, "style"> & {
-    img: HTMLImageElement;
-};
+}
+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.
@@ -173,52 +404,163 @@ 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;
-    /** Callback: center coordinates change */
+    /**
+     * 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 }`
+     * @example
+     * ```ts
+     * engine.onCoordsChange = (coords) => {
+     *     console.log(`Center: ${coords.x}, ${coords.y}`);
+     * };
+     * ```
+     */
     onCoordsChange?: (coords: Coords) => void;
     private _onClick?;
+    /**
+     * Callback when a tile is clicked (mouse or touch tap).
+     * @param coords - World coordinates: `raw` (exact), `snapped` (floored to tile)
+     * @param mouse - Canvas-relative position: `raw` (exact), `snapped` (tile-aligned)
+     * @param client - Viewport position: `raw` (exact), `snapped` (tile-aligned)
+     * @example
+     * ```ts
+     * engine.onClick = (coords, mouse, client) => {
+     *     console.log(`Clicked tile: ${coords.snapped.x}, ${coords.snapped.y}`);
+     * };
+     * ```
+     */
     get onClick(): onClickCallback | undefined;
     set onClick(cb: onClickCallback | undefined);
     private _onRightClick?;
+    /**
+     * Callback when a tile is right-clicked.
+     * @param coords - World coordinates: `raw` (exact), `snapped` (floored to tile)
+     * @param mouse - Canvas-relative position: `raw` (exact), `snapped` (tile-aligned)
+     * @param client - Viewport position: `raw` (exact), `snapped` (tile-aligned)
+     * @example
+     * ```ts
+     * engine.onRightClick = (coords) => {
+     *     showContextMenu(coords.snapped.x, coords.snapped.y);
+     * };
+     * ```
+     */
     get onRightClick(): onRightClickCallback | undefined;
     set onRightClick(cb: onRightClickCallback | undefined);
     private _onHover?;
+    /**
+     * Callback when hovering over tiles.
+     * @param coords - World coordinates: `raw` (exact), `snapped` (floored to tile)
+     * @param mouse - Canvas-relative position: `raw` (exact), `snapped` (tile-aligned)
+     * @param client - Viewport position: `raw` (exact), `snapped` (tile-aligned)
+     * @example
+     * ```ts
+     * engine.onHover = (coords) => {
+     *     setHoveredTile({ x: coords.snapped.x, y: coords.snapped.y });
+     * };
+     * ```
+     */
     get onHover(): onHoverCallback | undefined;
     set onHover(cb: onHoverCallback | undefined);
     private _onMouseDown?;
+    /**
+     * Callback on mouse/touch down.
+     * @param coords - World coordinates: `raw` (exact), `snapped` (floored to tile)
+     * @param mouse - Canvas-relative position: `raw` (exact), `snapped` (tile-aligned)
+     * @param client - Viewport position: `raw` (exact), `snapped` (tile-aligned)
+     * @example
+     * ```ts
+     * engine.onMouseDown = (coords) => {
+     *     startPainting(coords.snapped.x, coords.snapped.y);
+     * };
+     * ```
+     */
     get onMouseDown(): onMouseDownCallback | undefined;
     set onMouseDown(cb: onMouseDownCallback | undefined);
     private _onMouseUp?;
+    /**
+     * Callback on mouse/touch up.
+     * @param coords - World coordinates: `raw` (exact), `snapped` (floored to tile)
+     * @param mouse - Canvas-relative position: `raw` (exact), `snapped` (tile-aligned)
+     * @param client - Viewport position: `raw` (exact), `snapped` (tile-aligned)
+     * @example
+     * ```ts
+     * engine.onMouseUp = (coords) => {
+     *     stopPainting();
+     * };
+     * ```
+     */
     get onMouseUp(): onMouseUpCallback | undefined;
     set onMouseUp(cb: onMouseUpCallback | undefined);
     private _onMouseLeave?;
+    /**
+     * Callback when mouse/touch leaves the canvas.
+     * @param coords - World coordinates: `raw` (exact), `snapped` (floored to tile)
+     * @param mouse - Canvas-relative position: `raw` (exact), `snapped` (tile-aligned)
+     * @param client - Viewport position: `raw` (exact), `snapped` (tile-aligned)
+     * @example
+     * ```ts
+     * engine.onMouseLeave = () => {
+     *     clearHoveredTile();
+     * };
+     * ```
+     */
     get onMouseLeave(): onMouseLeaveCallback | undefined;
     set onMouseLeave(cb: onMouseLeaveCallback | undefined);
     private _onDraw?;
+    /**
+     * Callback after each draw frame. Use for custom canvas drawing.
+     * @param ctx - The canvas 2D rendering context
+     * @param info - Frame info: `scale`, `width`, `height`, `coords` (center)
+     * @example
+     * ```ts
+     * engine.onDraw = (ctx, info) => {
+     *     ctx.fillStyle = "red";
+     *     ctx.fillText(`Scale: ${info.scale}`, 10, 20);
+     * };
+     * ```
+     */
     get onDraw(): onDrawCallback | undefined;
     set onDraw(cb: onDrawCallback | undefined);
     private _onResize?;
+    /**
+     * Callback on canvas resize.
+     * @example
+     * ```ts
+     * engine.onResize = () => {
+     *     console.log("Canvas resized:", engine.getSize());
+     * };
+     * ```
+     */
     get onResize(): (() => void) | undefined;
     set onResize(cb: (() => void) | undefined);
     private _onZoom?;
-    /** Callback: zoom level changes (wheel or pinch) */
+    /**
+     * Callback when zoom level changes (wheel or pinch).
+     * @param scale - The new scale value
+     * @example
+     * ```ts
+     * engine.onZoom = (scale) => {
+     *     console.log(`Zoom level: ${scale}`);
+     * };
+     * ```
+     */
     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. */
@@ -247,6 +589,7 @@ declare class CanvasTileEngine {
     /**
      * Set the canvas scale directly, clamped to min/max bounds.
      * @param newScale The desired scale value.
+     * @throws {ConfigValidationError} If scale is not a positive finite number.
      */
     setScale(newScale: number): void;
     /**
@@ -282,7 +625,11 @@ declare class CanvasTileEngine {
         minY: number;
         maxY: number;
     };
-    /** Set center coordinates from outside (adjusts the camera accordingly). */
+    /**
+     * Set center coordinates from outside (adjusts the camera accordingly).
+     * @param newCenter The new center coordinates.
+     * @throws {ConfigValidationError} If coordinates are not finite numbers.
+     */
     updateCoords(newCenter: Coords): void;
     /**
      * Smoothly move the camera center to target coordinates over the given duration.
@@ -290,6 +637,7 @@ declare class CanvasTileEngine {
      * @param y Target world y.
      * @param durationMs Animation duration in milliseconds (default: 500ms). Set to 0 for instant move.
      * @param onComplete Optional callback fired when animation completes.
+     * @throws {ConfigValidationError} If coordinates are not finite numbers.
      */
     goCoords(x: number, y: number, durationMs?: number, onComplete?: () => void): void;
     /**
@@ -331,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: DrawObject | Array<DrawObject>, 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).
@@ -352,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<DrawObject>, 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<DrawObject>, 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).
@@ -371,91 +713,91 @@ declare class CanvasTileEngine {
      * @param cacheKey Unique key for this cache (e.g., "terrain-cache").
      * @param layer Layer order (lower draws first).
      */
-    drawStaticImage(items: Array<Omit<DrawObject, "style"> & {
-        img: HTMLImageElement;
-    }>, 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.
      */
-    drawLine(items: Array<{
-        from: Coords;
-        to: Coords;
-    }> | {
-        from: Coords;
-        to: Coords;
-    }, style?: {
+    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: DrawObject | Array<DrawObject>, layer?: number): LayerHandle;
+    drawCircle(items: Circle | Array<Circle>, layer?: number): DrawHandle;
     /**
-     * Draw one or many texts at world positions (canvas renderer only).
-     * @param items Text definitions.
-     * @param style Text style overrides.
+     * Draw one or many texts at world positions.
+     * @param items Text definitions with position, text, size, and style.
      * @param layer Layer order.
+     * @example
+     * ```ts
+     * engine.drawText({
+     *     x: 0,
+     *     y: 0,
+     *     text: "Hello",
+     *     size: 1, // 1 tile height
+     *     style: { fillStyle: "black", fontFamily: "Arial" }
+     * });
+     *
+     * // Multiple texts
+     * engine.drawText([
+     *     { x: 0, y: 0, text: "A", size: 2 },
+     *     { x: 1, y: 0, text: "B", size: 2 }
+     * ]);
+     * ```
      */
-    drawText(items: Array<{
-        coords: Coords;
-        text: string;
-    }> | {
-        coords: Coords;
-        text: string;
-    }, style?: {
-        fillStyle?: string;
-        font?: string;
-        textAlign?: CanvasTextAlign;
-        textBaseline?: CanvasTextBaseline;
-    }, 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.
      */
-    drawPath(items: Array<Coords[]> | Coords[], style?: {
+    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<Omit<DrawObject, "style"> & {
-        img: HTMLImageElement;
-    }> | (Omit<DrawObject, "style"> & {
-        img: HTMLImageElement;
-    }), 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
@@ -467,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
@@ -476,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;
 }
 
@@ -573,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 };