Canvas Tile Engine API

Manages smooth animations for camera movements, zooming, and canvas resizing. Handles animation frame scheduling and cleanup.

class AnimationController {
    constructor(camera: ICamera, viewport: ViewportState, onAnimationFrame: () => void);
}

Core engine wiring camera, config, renderer, events, and draw helpers.

class CanvasTileEngine<TMount = HTMLDivElement, TImage = HTMLImageElement> {
    canvasWrapper: TMount;
    canvas: TMount extends HTMLElement ? HTMLCanvasElement : HTMLCanvasElement | undefined;
    get images(): IImageLoader<TImage>;
    constructor(canvasWrapper: TMount, config: CanvasTileEngineConfig, renderer: IRenderer<TMount, TImage>, center?: Coords);
}

Normalizes and stores grid engine configuration with safe defaults.

class Config {
    constructor(config: CanvasTileEngineConfig);
}

Transforms coordinates between world space and screen space using the active camera.

class CoordinateTransformer {
    constructor(camera: ICamera);
}

Handles gesture logic (click, hover, drag, zoom) independent of DOM/platform. Receives normalized input from renderer and performs calculations.

class GestureProcessor {
    constructor(camera: ICamera, config: Config, transformer: CoordinateTransformer, canvasBoundsGetter: () => CanvasBounds, onCameraChange: () => void);
    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;
}

No API description is included in the published TypeScript declaration for SpatialIndex.

class SpatialIndex<T extends SpatialItem> {
    constructor();
}

Plays a SpriteAnimation by invoking a callback whenever the current frame changes. The callback typically mutates an ImageItem's `sprite` field and triggers a render, which makes animation work identically across all renderers without renderer-specific code. The internal rAF loop only fires the callback when the frame index actually advances, so renders happen at the animation's fps, not at 60fps.

class SpriteAnimator {
    constructor(animation: SpriteAnimation);
}

const sheet = new SpriteSheet({ frameWidth: 32, frameHeight: 32 });
const item = { x: 5, y: 3, img, sprite: sheet.frame(0, 0) };
engine.drawImage(item);


const animator = new SpriteAnimator({ frames: sheet.framesInRow(0, 0, 4), fps: 8 });
animator.start((frame) => {
    item.sprite = frame;
    engine.render();
});

Grid-based spritesheet frame calculator. Maps (col, row) or linear frame indices to pixel source rectangles (SpriteRect) inside a sheet image. Pure calculation — holds no image reference, so it is platform-agnostic and works with every renderer.

class SpriteSheet {
    constructor(options: SpriteSheetOptions);
}

const sheet = new SpriteSheet({ frameWidth: 32, frameHeight: 32, columns: 5 });
engine.drawImage({ x: 5, y: 3, img, sprite: sheet.frame(3, 0) });

Holds mutable viewport size for runtime changes (resize, layout). Also tracks device pixel ratio for HiDPI/Retina display support.

class ViewportState {
    constructor(width: number, height: number);
    get dpr(): number;
}

Smoothly animate camera movement to target coordinates.

animateMoveTo(targetX: number, targetY: number, durationMs?: number, onComplete?: () => void): void

Returns void

Smoothly animate the camera scale to a target value, anchored at the viewport center (matching zoomIn/zoomOut).

animateZoomTo(targetScale: number, durationMs?: number, onZoomFrame?: (prevScale: number) => void, onComplete?: () => void): void

Returns void

Smoothly animate canvas size change while keeping view centered.

animateResize(targetWidth: number, targetHeight: number, durationMs: number | undefined, onApplySize: (width: number, height: number, center: Coords) => void, onComplete?: () => void): void

Returns void

Cancel the current move animation if running.

cancelMove(): void

Returns void

Cancel the current zoom animation if running.

cancelZoom(): void

Returns void

Cancel the current resize animation if running.

cancelResize(): void

Returns void

Cancel all running animations.

cancelAll(): void

Returns void

Check if any animation is currently running.

isAnimating(): boolean

Returns boolean

Tear down listeners and observers.

destroy(): void

Returns void

Render a frame using the active renderer.

render(): void

Returns void

Manually update canvas size (e.g., user-driven select). Keeps view centered.

resize(width: number, height: number, durationMs?: number, onComplete?: () => void): void

Returns void

Current canvas size.

getSize(): {
    width: number;
    height: number;
}

Returns { width: number; height: number; } — Current `{ width, height }` in pixels.

Current canvas scale.

getScale(): number

Returns number — Current canvas scale.

Set the canvas scale directly, clamped to min/max bounds. The change is anchored at the viewport center, matching goScale/zoomIn/zoomOut.

setScale(newScale: number): void

Returns void

Smoothly animate the canvas scale to a target value over the given duration. The zoom is anchored at the viewport center, matching zoomIn/zoomOut.

goScale(targetScale: number, durationMs?: number, onComplete?: () => void): void

Returns void

Zoom in by a given factor, centered on the viewport.

zoomIn(factor?: number): void

Returns void

Zoom out by a given factor, centered on the viewport.

zoomOut(factor?: number): void

Returns void

Update the minimum and maximum scale limits at runtime. The current scale is clamped into the new range immediately.

setScaleLimits(minScale: number, maxScale: number): void

Returns void

// Allow zooming between 0.25x and 8x
engine.setScaleLimits(0.25, 8);

Snapshot of current normalized config.

getConfig(): Required<CanvasTileEngineConfig>

Returns Required<CanvasTileEngineConfig>

Current center of the view in world coordinates.

getCenter(): Coords

Returns Coords — Center coordinates `{ x, y }`.

Get the visible world coordinate bounds of the viewport. Returns floored/ceiled values representing which cells are visible.

getVisibleBounds(): {
    minX: number;
    maxX: number;
    minY: number;
    maxY: number;
}

Returns { minX: number; maxX: number; minY: number; maxY: number; } — Visible bounds with min/max coordinates.

const bounds = engine.getVisibleBounds();
// { minX: 0, maxX: 10, minY: 0, maxY: 10 }


// Use for random placement within visible area
const x = bounds.minX + Math.floor(Math.random() * (bounds.maxX - bounds.minX));

Move the view center to new world coordinates instantly.

setCenter(newCenter: Coords): void

Returns void

Smoothly animate the view center to target world coordinates over the given duration.

goCenter(x: number, y: number, durationMs?: number, onComplete?: () => void): void

Returns void

Fit a world-space rectangle into the viewport: centers the view on the rectangle and picks the largest scale that keeps the whole (padded) area visible, clamped to the scale limits. Animated by default; not related to setBounds, which restricts camera movement.

fitBounds(bounds: Bounds, options?: FitBoundsOptions): void

Returns void

// Show the whole board with one cell of margin
engine.fitBounds({ minX: 0, maxX: 32, minY: 0, maxY: 32 }, { padding: 1 });


// 24px of air around any selection, small or huge
engine.fitBounds(selectionBounds, { paddingPx: 24 });


// Jump to a selection instantly
engine.fitBounds(selectionBounds, { durationMs: 0 });

Update event handlers at runtime. This allows you to enable or disable specific interactions dynamically.

setEventHandlers(handlers: Partial<EventHandlers>): void

Returns void

// Disable drag temporarily
engine.setEventHandlers({ drag: false });


// Enable painting mode
engine.setEventHandlers({ drag: false, hover: true });


// Re-enable drag
engine.setEventHandlers({ drag: true });

Set or update map boundaries to restrict camera movement.

setBounds(bounds: {
    minX: number;
    maxX: number;
    minY: number;
    maxY: number;
}): void

Returns void

// Restrict map to -100 to 100 on both axes
engine.setBounds({ minX: -100, maxX: 100, minY: -100, maxY: 100 });


// Remove boundaries
engine.setBounds({ minX: -Infinity, maxX: Infinity, minY: -Infinity, maxY: Infinity });


// Only limit X axis
engine.setBounds({ minX: 0, maxX: 500, minY: -Infinity, maxY: Infinity });

Draw one or many rectangles in world space. Supports rotation via the `rotate` property (degrees, positive = clockwise).

drawRect<TData = unknown>(items: Rect<TData> | Array<Rect<TData>>, layer?: number, options?: RectDrawOptions<TData>): DrawHandle

Returns DrawHandle

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).

drawStaticRect(items: Array<Rect>, cacheKey: string, layer?: number, options?: StaticDrawOptions): DrawHandle

Returns DrawHandle

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.

drawStaticCircle(items: Array<Circle>, cacheKey: string, layer?: number, options?: StaticDrawOptions): DrawHandle

Returns DrawHandle

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).

drawStaticImage(items: Array<ImageItem<TImage>>, cacheKey: string, layer?: number, options?: StaticDrawOptions): DrawHandle

Returns DrawHandle

Clear a static rendering cache.

clearStaticCache(cacheKey?: string): void

Returns void

Draw one or many lines between world points. Lines participate in hit testing: a point within half the stroke width of a segment (with a minimum tap width for hairlines) hits it.

drawLine<TData = unknown>(items: Array<Line<TData>> | Line<TData>, style?: LineStyle, layer?: number, options?: LineDrawOptions<TData>): DrawHandle

Returns DrawHandle

Draw one or many circles sized in world units.

drawCircle<TData = unknown>(items: Circle<TData> | Array<Circle<TData>>, layer?: number, options?: CircleDrawOptions<TData>): DrawHandle

Returns DrawHandle

Draw one or many texts at world positions.

drawText<TData = unknown>(items: Array<Text<TData>> | Text<TData>, layer?: number, options?: TextDrawOptions<TData>): DrawHandle

Returns DrawHandle

engine.drawText({
    x: 0,
    y: 0,
    text: "Hello",
    size: 1, // 1 tile height, scales with zoom
    style: { fillStyle: "black", fontFamily: "Arial" }
});


// Fixed-size label: always 14px on screen, regardless of zoom
engine.drawText({ x: 0, y: 0, text: "Ankara", fontPx: 14 });


// Multiple texts
engine.drawText([
    { x: 0, y: 0, text: "A", size: 2 },
    { x: 1, y: 0, text: "B", size: 2 }
]);

Draw one or many free-form paths through world points. Each `PathItem` owns its geometry and style: `points` traces the outline, `closed` joins it back to the start, `style.fillStyle` fills the interior (under `fillRule`), and stroke/dash/corner options follow the shared world-vs-`*Px` unit convention. Paths participate in hit testing: filled paths hit on their interior, unfilled paths on the stroke itself.

drawPath<TData = unknown>(items: PathItem<TData> | Array<PathItem<TData>>, layer?: number, options?: PathDrawOptions<TData>): DrawHandle

Returns DrawHandle

// Filled shape with a rounded outline
engine.drawPath({
    points: [{ x: 0, y: 0 }, { x: 4, y: 0 }, { x: 4, y: 3 }, { x: 0, y: 3 }],
    closed: true,
    style: { fillStyle: "#22c55e", strokeStyle: "#166534", lineWidthPx: 2, cornerRadius: 0.5 },
    data: { id: "zone-a" },
});


// Open route line
engine.drawPath({ points: route, style: { strokeStyle: "#3b82f6", lineWidthPx: 4 } });

Draw one or many images scaled in world units. Supports rotation via the `rotate` property (degrees, positive = clockwise).

drawImage<TData = unknown>(items: Array<ImageItem<TImage, TData>> | ImageItem<TImage, TData>, layer?: number, options?: ImageDrawOptions<TImage, TData>): DrawHandle

Returns DrawHandle

Draw grid lines at specified cell size.

drawGridLines(cellSize: number, lineWidth?: number, strokeStyle?: string, layer?: number, options?: DrawOptions): DrawHandle

Returns DrawHandle

engine.drawGridLines(50);

Register a custom draw function for complete rendering control. Useful for complex or one-off drawing operations.

addDrawFunction(fn: (ctx: unknown, coords: Coords, config: Required<CanvasTileEngineConfig>, transform: DrawTransform) => void, layer?: number, options?: DrawOptions): DrawHandle

Returns DrawHandle — DrawHandle for removal.

engine.addDrawFunction((ctx, coords, config, transform) => {
    const c = ctx as CanvasRenderingContext2D;
    const p = transform.worldToScreen(5, 3); // center of cell (5, 3)
    c.fillStyle = "red";
    c.fillRect(p.x - 4, p.y - 4, 8, 8);
}, 4);

Remove a specific draw callback by handle. Does not clear other callbacks on the same layer.

removeDrawHandle(handle: DrawHandle): void

Returns void

Clear all draw callbacks from a specific layer. Use this before redrawing dynamic content to prevent accumulation.

clearLayer(layer: number): void

Returns void

engine.clearLayer(1);
engine.drawRect(newRects, 1);
engine.render();

Clear all draw callbacks from all layers. Useful for complete scene reset.

clearAll(): void

Returns void

engine.clearAll();
// Redraw everything from scratch

All rect/circle/image/path/line items under a world point, highest visual priority first (higher layer, then later registration, then later item within a draw call). Pass the `coords.raw` value from event callbacks - origin anchoring, image aspect fit, and rotation are handled internally. Line, Path, and Text items are not hit-testable. Like rendering, results reflect item positions as of the draw call: mutating an item's position requires re-registration (style mutation is fine). `padding` (world units) and `paddingPx` (screen pixels, zoom independent) expand every item's hit geometry outward - generous touch targets around small markers without invisible helper items. `TData` types the `data` field of returned items — it is an assertion, not checked at runtime, so only pass it when every hit-testable item carries that data shape (or narrow per hit).

hitTest<TData = unknown>(point: Coords, opts?: HitTestOptions): HitResult<TImage, TData>[]

Returns HitResult<TImage, TData>[]

engine.onClick = (coords) => {
    // Accept clicks up to 0.6 world units around each station dot
    const hit = engine.hitTestFirst<Station>(coords.raw, { padding: 0.6 });
    if (hit?.item.data) openPanel(hit.item.data);
};

The topmost item under a world point, or `undefined`. See hitTest for semantics.

hitTestFirst<TData = unknown>(point: Coords, opts?: HitTestOptions): HitResult<TImage, TData> | undefined

Returns HitResult<TImage, TData> | undefined

All items whose geometry intersects (default) or lies fully inside a world rectangle — the marquee/box-selection query. Corners may be passed in any order (a drag can travel in any direction); build them from event `coords.raw` values, like `hitTest`. Region tests run on item GEOMETRY — stroke widths are not expanded — and filled paths count interior overlap with holes excluded.

hitTestRect<TData = unknown>(rect: Bounds, opts?: HitTestRectOptions): HitResult<TImage, TData>[]

Returns HitResult<TImage, TData>[]

// Marquee selection between drag start and end (raw coords)
const hits = engine.hitTestRect(
    { minX: start.x, minY: start.y, maxX: end.x, maxY: end.y },
    { layer: 2, mode: "contain" },
);
select(hits.map((h) => h.item.data));

Get the current configuration as an immutable snapshot. The returned object is deeply frozen and shared — do not mutate it. Runtime updates (`updateEventHandlers`, `updateBounds`) replace the snapshot with a new frozen object, so previously returned references keep their old values. Returning the frozen instance avoids the deep copy this method used to make on every call (it runs on every pointer event and every rendered frame).

get(): Readonly<Required<CanvasTileEngineConfig>>

Returns Readonly<Required<CanvasTileEngineConfig>> — Normalized configuration snapshot e.g. `{ scale: 1, size: { width: 800, height: 600 }, ... }`.

Update event handlers at runtime.

updateEventHandlers(handlers: Partial<EventHandlers>): void

Returns void

Update scale limits at runtime.

updateScaleLimits(minScale: number, maxScale: number): void

Returns void

Update map bounds at runtime.

updateBounds(bounds: {
    minX: number;
    maxX: number;
    minY: number;
    maxY: number;
}): void

Returns void

Convert a world grid coordinate to screen pixels, accounting for camera offset and scale.

worldToScreen(worldX: number, worldY: number): Coords

Returns Coords — Screen-space coordinates in pixels. e.g., (e.g. `{ x: 100.5, y: 200.5 }`).

Convert screen pixel coordinates back to world space grid coordinates.

screenToWorld(screenX: number, screenY: number): Coords

Returns Coords — World-space grid coordinates. (e.g. `{ x: 10, y: 20 }`).

Bulk load items into the R-Tree (much faster than individual inserts)

load(items: T[]): void

Returns void

Query all items within a rectangular range

query(minX: number, minY: number, maxX: number, maxY: number): T[]

Returns T[]

Clear all items

clear(): void

Returns void

Create SpatialIndex from array of items

static fromArray<T extends SpatialItem>(items: T[]): SpatialIndex<T>

Returns SpatialIndex<T>

Frame index for a given elapsed time since the animation started. Pure timing math; exposed for tests and manual stepping.

frameIndexAt(elapsedMs: number): number

Returns number

Frame source rect for a given elapsed time since the animation started.

frameAt(elapsedMs: number): SpriteRect

Returns SpriteRect

Start playback. Restarts from the first frame if already running.

start(onFrame: (frame: SpriteRect, index: number) => void, onComplete?: () => void): void

Returns void

Stop playback. The last applied frame stays drawn.

stop(): void

Returns void

Whether the animation loop is currently scheduled.

isRunning(): boolean

Returns boolean

Source rectangle of the frame at grid position (col, row).

frame(col: number, row: number): SpriteRect

Returns SpriteRect

Source rectangle of a frame by linear index (left-to-right, top-to-bottom). Requires `columns` to be set.

frameByIndex(index: number): SpriteRect

Returns SpriteRect

Consecutive frames of a single row, from `startCol` to `endCol` inclusive. Useful as an animation frame list, e.g. `framesInRow(0, 0, 4)` for the frames (0,0) through (4,0).

framesInRow(row: number, startCol: number, endCol: number): SpriteRect[]

Returns SpriteRect[]

No API description is included in the published TypeScript declaration for ViewportState.getSize.

getSize(): {
    width: number;
    height: number;
}

Returns { width: number; height: number; }

No API description is included in the published TypeScript declaration for ViewportState.setSize.

setSize(width: number, height: number): void

Returns void

Update DPR (useful when window moves between displays).

updateDpr(): void

Returns void

Callback when center coordinates change (pan or zoom).

onCoordsChange?: (coords: Coords) => void

engine.onCoordsChange = (coords) => {
    console.log(`Center: ${coords.x}, ${coords.y}`);
};

Callback when a tile is clicked (mouse or touch tap).

get onClick(): onClickCallback | undefined
set onClick(cb: onClickCallback | undefined)

engine.onClick = (coords, mouse, client) => {
    console.log(`Clicked tile: ${coords.snapped.x}, ${coords.snapped.y}`);
};

Callback when a tile is right-clicked.

get onRightClick(): onRightClickCallback | undefined
set onRightClick(cb: onRightClickCallback | undefined)

engine.onRightClick = (coords) => {
    showContextMenu(coords.snapped.x, coords.snapped.y);
};

Callback when hovering over tiles.

get onHover(): onHoverCallback | undefined
set onHover(cb: onHoverCallback | undefined)

engine.onHover = (coords) => {
    setHoveredTile({ x: coords.snapped.x, y: coords.snapped.y });
};

Callback on mouse/touch down.

get onMouseDown(): onMouseDownCallback | undefined
set onMouseDown(cb: onMouseDownCallback | undefined)

engine.onMouseDown = (coords) => {
    startPainting(coords.snapped.x, coords.snapped.y);
};

Callback on mouse/touch up.

get onMouseUp(): onMouseUpCallback | undefined
set onMouseUp(cb: onMouseUpCallback | undefined)

engine.onMouseUp = (coords) => {
    stopPainting();
};

Callback when mouse/touch leaves the canvas.

get onMouseLeave(): onMouseLeaveCallback | undefined
set onMouseLeave(cb: onMouseLeaveCallback | undefined)

engine.onMouseLeave = () => {
    clearHoveredTile();
};

Callback after each draw frame, on top of all layers. Same signature as `addDrawFunction` callbacks: platform context, top-left world coords, live config, and coordinate transform helpers.

get onDraw(): onDrawCallback | undefined
set onDraw(cb: onDrawCallback | undefined)

engine.onDraw = (ctx, coords, config, transform) => {
    const c = ctx as CanvasRenderingContext2D;
    c.fillStyle = "red";
    c.fillText(`Scale: ${config.scale}`, 10, 20);
};

Callback on canvas resize.

get onResize(): (() => void) | undefined
set onResize(cb: (() => void) | undefined)

engine.onResize = () => {
    console.log("Canvas resized:", engine.getSize());
};

Callback when zoom level changes (wheel or pinch).

get onZoom(): ((scale: number) => void) | undefined
set onZoom(cb: ((scale: number) => void) | undefined)

engine.onZoom = (scale) => {
    console.log(`Zoom level: ${scale}`);
};

Callback for wheel (desktop) and pinch (touch) zoom gestures. Requires `eventHandlers.zoom`; fires even when the scale is clamped at a limit. Unlike `onZoom` (which reports the resulting scale, including programmatic changes), this reports the input gesture itself with its position. For pinch, the coordinates describe the pinch midpoint and `deltaY` is the wheel delta that would produce the same zoom factor.

get onWheel(): onWheelCallback | undefined
set onWheel(cb: onWheelCallback | undefined)

engine.onWheel = (coords, mouse, client, wheel) => {
    console.log(`${wheel.source} zoom ${wheel.direction} at`, coords.snapped);
};

Event callback exposed by GestureProcessor.

onClick?: onClickCallback

Event callback exposed by GestureProcessor.

onRightClick?: onRightClickCallback

Event callback exposed by GestureProcessor.

onHover?: onHoverCallback

Event callback exposed by GestureProcessor.

onMouseDown?: onMouseDownCallback

Event callback exposed by GestureProcessor.

onMouseUp?: onMouseUpCallback

Event callback exposed by GestureProcessor.

onMouseLeave?: onMouseLeaveCallback

Event callback exposed by GestureProcessor.

onZoom?: onZoomCallback

Event callback exposed by GestureProcessor.

onWheel?: onWheelCallback

Top-left offset of a `w`x`h` box anchored at `pos`. - "cell": nudges the box from the cell center by `origin.x`/`origin.y` (0 to 1) across a `cellSize`-wide cell, independent of the box's own size. - "self": anchors within the box's own `w`/`h`; `cellSize` is unused. `pos`, `w`, `h`, and `cellSize` must share the same unit — screen pixels for renderers (`cellSize` = `camera.scale`), or world units for hit testing (`cellSize` = 1, a cell is exactly one world unit wide).

function computeOriginOffset(pos: Coords, w: number, h: number, origin: Origin, cellSize: number): Coords

Returns Coords

Compute the rounding arc for the corner `prev → v → next` with the desired `radiusPx`. The radius is clamped so the arc's tangent points never pass the midpoint of either adjacent segment (matching what `ctx.arcTo` would need to stay well-formed on short segments). Returns `null` for degenerate corners: zero-length segments, collinear continuation, or a fold-back.

function cornerArc(prev: Coords, v: Coords, next: Coords, radiusPx: number): CornerArc | null

Returns CornerArc | null

The scale (pixels per world unit) at which `bounds` exactly fits a `size`-pixel viewport — the math `fitBounds` uses to pick its target scale, exposed as a pure function for config-time use (the `gridToSize` of free-form content). Use it to derive scale limits from content instead of hand-tuning constants: the fit scale tracks the content automatically, and only `maxScale` — a content-resolution quality cap that no bounds can imply — stays a deliberate choice.

function fitScale(bounds: Bounds, size: {
    width: number;
    height: number;
}, options?: FitScaleOptions): number

Returns number — The fitting scale; unclamped — apply your own min/max policy.

const fit = fitScale(WORLD_BOUNDS, { width: 800, height: 600 }, { paddingPx: 24 });
const config = {
    size: { width: 800, height: 600 },
    scale: fit, // open showing everything
    minScale: fit * 0.8, // small overview slack — your policy
    maxScale: 64, // quality cap — intentionally hand-picked
};

Flattens a Canvas2D-style command list into polyline subpaths, following Canvas2D path semantics: each `moveTo` starts a new subpath; `lineTo`/ curves with no open subpath implicitly move first; `arc` draws a connecting line from the current point to the arc start; after `closePath` the current point is the closed subpath's start. All consumers of flattened geometry (hit testing, WebGL, culling) share this one implementation so they agree exactly. `maxSegment` is the max spacing between samples, in the same unit as the coordinates — callers flatten in world units with `ARC_SEGMENT_LENGTH / scale` to sample at the renderers' screen-pixel density.

function flattenPathCommands(commands: PathCommand[], maxSegment: number): Subpath[]

Returns Subpath[]

Convert grid-based dimensions to pixel-based config plus the board center. Integers are cell centers (cell k spans [k-0.5, k+0.5]), so a board of cells 0..N-1 is centered at (N-1)/2 on each axis. Pass the returned `center` to the engine so the board exactly fills the viewport.

function gridToSize(options: {
    columns: number;
    rows: number;
    cellSize: number;
}): Pick<CanvasTileEngineConfig, "size" | "scale"> & {
    center: Coords;
}

Returns Pick<CanvasTileEngineConfig, "size" | "scale"> & { center: Coords; } — Config `size`/`scale` plus the `center` of a 0-based board.

const { center, ...board } = gridToSize({ columns: 8, rows: 8, cellSize: 60 });
// board.size = { width: 480, height: 480 }, board.scale = 60
// center = { x: 3.5, y: 3.5 }


const engine = new CanvasTileEngine(
    wrapper,
    { ...board, gridAligned: true },
    new RendererCanvas(),
    center,
);

Overlay one line style on another, unit-pair by unit-pair. A plain field-by-field spread breaks the world/px precedence rule across layers: a base `lineWidthPx` would survive the merge and shadow an overlay that only sets the world `lineWidth`. Instead, a layer that sets either field of a pair (`lineWidth`/`lineWidthPx`, `lineDash`/`lineDashPx`) replaces the whole pair — the `*Px`-wins rule applies within one layer, never across layers. Used for `Line.style` over the call-level style, and for `styleOf` decorations over both.

function overlayLineStyle<T extends OverlayableLineStyle>(base: T | undefined, over: Partial<T> | undefined): T

Returns T

Conservative world-space bounds of a command list from its control-point hull: every endpoint and control point, and each arc's full center±radius box. Curves never leave their control hull, so this over-approximates — cheap, camera-independent, and safe for culling. Returns null for an empty list.

function pathCommandsBounds(commands: PathCommand[]): {
    minX: number;
    minY: number;
    maxX: number;
    maxY: number;
} | null

Returns { minX: number; minY: number; maxX: number; maxY: number; } | null

Effective Path corner-rounding radius in screen pixels; 0 disables rounding. `cornerRadiusPx` wins; `cornerRadius` is world units.

function resolveCornerRadiusPx(style: CornerRadiusStyle | undefined, scale: number): number

Returns number

Effective dash pattern in screen pixels, or `undefined` for a solid line. Follows Canvas2D `setLineDash` semantics: an odd-length pattern is repeated (doubled), and a pattern that is empty, contains a negative or non-finite value, or sums to zero yields a solid line.

function resolveLineDashPx(style: LineDashStyle | undefined, scale: number): number[] | undefined

Returns number[] | undefined

Effective stroke width in screen pixels. `lineWidthPx` wins; `lineWidth` is world units (multiplied by `scale`); neither given falls back to a 1px hairline.

function resolveLineWidthPx(style: StrokeWidthStyle | undefined, scale: number): number

Returns number

Fills in the "cell"/0.5/0.5 defaults for an item's `origin` field.

function resolveOrigin(origin?: RawOrigin): Origin

Returns Origin

Border radius in screen pixels. `radius` is world units; single values and per-corner arrays are both supported.

function resolveRadiusPx(radius: number | number[] | undefined, scale: number): number | number[] | undefined

Returns number | number[] | undefined

Effective drawn size in screen pixels. `sizePx` wins; else `size * scale`; default 1 world unit.

function resolveSizePx(item: SizedItem, scale: number): number

Returns number

Effective size in world units at the current scale. Note that a `sizePx` item's world extent GROWS as the camera zooms out — culling and hit queries must re-evaluate this per frame instead of caching it.

function resolveSizeWorld(item: SizedItem, scale: number): number

Returns number

Replace each interior vertex of a polyline with its rounding arc, flattened into short segments. Uses cornerArc for the exact same clamped geometry the Canvas2D/Skia renderers feed to their native tangent-arc APIs, so flattened consumers (WebGL, hit testing) agree with them. Because the result is a plain (denser) polyline, dash tessellation and distance tests run over it unchanged. Radius, points, and `maxSegment` share one unit (pixels or world).

function roundedPolyline(points: Coords[], radius: number, maxSegment?: number): Coords[]

Returns Coords[]

Closed-ring variant of roundedPolyline: every vertex is a corner with cyclic neighbors, including the joins of the closing segment. The result is still an implicit ring — consumers connect the last sample back to the first.

function roundedRing(points: Coords[], radius: number, maxSegment?: number): Coords[]

Returns Coords[]

Replays a PathCommand list into a Canvas2D-style sink, converting world coordinates to screen pixels and degrees to radians at this one boundary so every renderer traces identical geometry. The world→screen transform is uniform (one scale for both axes), so curves and arcs map exactly.

function traceCommands(ctx: CommandTraceTarget, commands: PathCommand[], worldToScreen: (x: number, y: number) => Coords, scale: number): void

Returns void

Traces one path item's outline (screen-pixel points) into a Canvas2D-style sink, applying corner rounding via cornerArc so every renderer produces identical geometry. Open paths round interior vertices only; closed paths round every vertex, including the joins of the closing segment. Degenerate corners (collinear, fold-back, zero radius) fall back to straight joins.

function traceRoundedPath(ctx: PathTraceTarget, pts: Coords[], closed: boolean, radiusPx: number): void

Returns void

No API description is included in the published TypeScript declaration for Bounds.

interface Bounds {
    minX: number;
    maxX: number;
    minY: number;
    maxY: number;
}

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

Options for CanvasTileEngine.drawCircle.

interface CircleDrawOptions<TData = unknown> extends DrawOptions {
    /** Paint-time decoration; see {@link StyleOf}. */
    styleOf?: StyleOf<Circle<TData>, ShapeDecorationStyle>;
    /** Per-item visibility; see {@link VisibleOf}. */
    visibleOf?: VisibleOf<Circle<TData>>;
    /** Per-item hit-test opt-out; see {@link InteractiveOf}. */
    interactiveOf?: InteractiveOf<Circle<TData>>;
}

Full Canvas2D-shaped sink for command replay: PathTraceTarget plus the curve methods. DOM and

interface CommandTraceTarget extends PathTraceTarget {
    quadraticCurveTo(cpx: number, cpy: number, x: number, y: number): void;
    bezierCurveTo(cp1x: number, cp1y: number, cp2x: number, cp2y: number, x: number, y: number): void;
}

Geometry of one rounded polyline corner, in screen pixels. All renderers derive their corner arcs from this single computation so the rounding is identical everywhere: Canvas2D/Skia feed `radius` to their native tangent arc APIs, WebGL flattens the arc from `center`/angles.

interface CornerArc {
    /** Arc radius after per-corner clamping. */
    radius: number;
    /** Tangent point on the incoming segment (arc start). */
    t1: Coords;
    /** Tangent point on the outgoing segment (arc end). */
    t2: Coords;
    /** Arc center. */
    center: Coords;
    /** Angle of `t1` around the center, radians. */
    startAngle: number;
    /** Angle of `t2` around the center, radians. */
    endAngle: number;
    /** Sweep from start to end, radians; negative = counterclockwise. */
    sweep: number;
}

No API description is included in the published TypeScript declaration for DrawHandle.

interface DrawHandle {
    readonly id: symbol;
    readonly layer: number;
}

Options accepted by the engine draw helpers (`drawRect`, `drawCircle`, ...).

interface DrawOptions {
    /**
     * Stable identity for this registration. Calling any draw method again
     * with the same id atomically replaces the previous registration: the old
     * draw callback and its hit-test entries are removed (and, for static
     * draws, the offscreen cache is invalidated) before the new one is added.
     * Ids share a single namespace across draw kinds and layers; static draw
     * helpers use their `cacheKey` as the id. Without an id, every call adds
     * a new registration (remove with the returned handle or `clearLayer`).
     */
    id?: string;
    /**
     * Set to `false` to keep this registration out of hit testing — the
     * `pointer-events: none` of the draw API. Decorative content (floor
     * tiles, background images, zone overlays) declared once at registration
     * stops leaking into every `hitTest`/`hitTestFirst`/`hitTestRect` query,
     * and large decorative sets skip hit-registry bookkeeping entirely.
     * Default `true`. Text and custom draw functions never enter hit testing
     * regardless of this flag.
     */
    hitTest?: boolean;
}

Coordinate transform helpers handed to custom draw callbacks (`addDrawFunction` / `onDraw`), so user code never re-derives the `(world - topLeft) * scale` formula or the cell-center offset.

interface DrawTransform {
    /**
     * Item-space world coordinate → canvas pixel position. Integers are cell
     * centers (the same space item `x`/`y` live in), so `worldToScreen(k, k)`
     * is the pixel at the center of cell `k`.
     */
    worldToScreen(x: number, y: number): Coords;
    /**
     * Canvas pixel position → raw (corner-space) world coordinate — the same
     * space event payloads report as `coords.raw`.
     */
    screenToWorld(x: number, y: number): Coords;
}