mudlet-map-renderer 0.24.0-konva → 0.26.0-konva

package/dist/AreaMapRenderer.d.ts

@@ -74,7 +74,7 @@ export declare class AreaMapRenderer {
     constructor(container: HTMLDivElement, mapReader: MapReader, settings?: AreaMapSettings);
     private initResize;
     private initScaling;
-    setZoom(zoom: number): void;
+    setZoom(zoom: number): boolean;
     getZoom(): number;
     setDomainInfo(domainInfo: Record<number, AreaDomainInfo>): void;
     setDomainFilter(filter: DomainFilter): void;

package/dist/CanvasExporter.d.ts

@@ -0,0 +1,76 @@
+import { default as MapReader } from './reader/MapReader';
+import { Settings } from './Renderer';
+export type CanvasExportOverlays = {
+    position?: {
+        roomId: number;
+    };
+    highlights?: Array<{
+        roomId: number;
+        color: string;
+    }>;
+    paths?: Array<{
+        locations: number[];
+        color: string;
+    }>;
+};
+export type CanvasExportOptions = {
+    /** Width of the output image in pixels. */
+    width: number;
+    /** Height of the output image in pixels. */
+    height: number;
+    /** Room ID to center the export on. If omitted, exports the full area. */
+    roomId?: number;
+    /** Padding in map units around the exported region. Default: 3 */
+    padding?: number;
+    /** Overlay data (position marker, highlights, paths). */
+    overlays?: CanvasExportOverlays;
+};
+/**
+ * Renders map data directly to a Canvas2D context.
+ * Works in both browser (OffscreenCanvas / regular Canvas) and Node.js (with the 'canvas' npm package).
+ *
+ * Usage (Node.js):
+ * ```
+ * import { createCanvas } from 'canvas';
+ * const canvas = createCanvas(width, height);
+ * const exporter = new CanvasExporter(mapReader, settings);
+ * exporter.render(canvas.getContext('2d'), areaId, zIndex, { width, height });
+ * const buffer = canvas.toBuffer('image/png');
+ * ```
+ *
+ * Usage (Browser):
+ * ```
+ * const canvas = new OffscreenCanvas(width, height);
+ * const exporter = new CanvasExporter(mapReader, settings);
+ * exporter.render(canvas.getContext('2d'), areaId, zIndex, { width, height });
+ * const blob = await canvas.convertToBlob({ type: 'image/png' });
+ * ```
+ */
+export declare class CanvasExporter {
+    private readonly mapReader;
+    private readonly settings;
+    private readonly exitRenderer;
+    constructor(mapReader: MapReader, settings: Settings);
+    private getSymbolColor;
+    /**
+     * Render the map area to a Canvas2D context.
+     * The caller creates the canvas and context; this method draws to it.
+     */
+    render(ctx: CanvasRenderingContext2D | OffscreenCanvasRenderingContext2D, areaId: number, zIndex: number, options: CanvasExportOptions): void;
+    private computeBounds;
+    private getEffectiveBounds;
+    private getRoomEdgePoint;
+    private renderGrid;
+    private renderLabels;
+    private renderLinkExits;
+    private drawExitData;
+    private renderStubs;
+    private renderSpecialExits;
+    private renderRooms;
+    private roundRect;
+    private renderInnerExits;
+    private drawTriangle;
+    private renderPathOverlay;
+    private renderHighlightOverlay;
+    private renderPositionMarker;
+}

package/dist/ExitRenderer.d.ts

@@ -34,12 +34,14 @@ export type ExitDrawData = {
         width: number;
         height: number;
     };
+    /** Set when this exit leads to a room in a different area (cross-area exit). */
+    targetRoomId?: number;
 };
 export default class ExitRenderer {
     private mapReader;
     private mapRenderer;
     private readonly settings;
-    constructor(mapReader: MapReader, mapRenderer: Renderer, settings: Settings);
+    constructor(mapReader: MapReader, mapRenderer: Renderer | null, settings: Settings);
     /**
      * Get the edge point of a room based on its shape
      */
@@ -54,6 +56,18 @@ export default class ExitRenderer {
     private renderOneWayExit;
     renderAreaExit(room: MapData.Room, dir: MapData.direction, color?: string): import('konva/lib/shapes/Arrow').Arrow;
     renderSpecialExits(room: MapData.Room, overrideColor?: string): (import('konva/lib/shapes/Arrow').Arrow | import('konva/lib/shapes/Rect').Rect | import('konva/lib/shapes/Line').Line<import('konva/lib/shapes/Line').LineConfig>)[];
+    /**
+     * Returns hit-zone bounds for special exits (custom lines) that lead to rooms in another area.
+     */
+    getSpecialExitAreaTargets(room: MapData.Room): {
+        bounds: {
+            x: number;
+            y: number;
+            width: number;
+            height: number;
+        };
+        targetRoomId: number;
+    }[];
     renderStubs(room: MapData.Room, color?: string): import('konva/lib/shapes/Line').Line<{
         points: number[];
         stroke: string;
@@ -61,6 +75,7 @@ export default class ExitRenderer {
         perfectDrawEnabled: false;
         listening: false;
     }>[];
+    private getSymbolColor;
     renderInnerExits(room: MapData.Room): import('konva/lib/Group').Group[];
     renderDoor(points: number[], type: 1 | 2 | 3): import('konva/lib/shapes/Rect').Rect;
 }

package/dist/HeadlessRenderer.d.ts

@@ -0,0 +1,63 @@
+import { default as MapReader } from './reader/MapReader';
+import { default as Area } from './reader/Area';
+import { Settings } from './Renderer';
+import { MapRenderer } from './MapRenderer';
+import { SvgExportOptions } from './SvgExporter';
+import { CanvasExportOptions, CanvasExportOverlays } from './CanvasExporter';
+/**
+ * A headless (no DOM / no Konva) renderer for server-side and backend use.
+ * Provides the same stateful API as the browser Renderer for area display,
+ * position tracking, path rendering, and highlights — then exports to SVG or
+ * renders to a caller-provided Canvas2D context for PNG output.
+ *
+ * Usage:
+ * ```
+ * const renderer = new HeadlessRenderer(mapReader, settings);
+ * renderer.drawArea(areaId, 0);
+ * renderer.setPosition(playerRoomId);
+ * renderer.renderPath([roomA, roomB, roomC], '#ff0000');
+ *
+ * // SVG export (always available)
+ * const svg = renderer.exportSvg({ padding: 5 });
+ *
+ * // PNG export (Node.js with 'canvas' package)
+ * import { createCanvas } from 'canvas';
+ * const canvas = createCanvas(1920, 1080);
+ * renderer.renderToCanvas(canvas.getContext('2d'), { width: 1920, height: 1080 });
+ * fs.writeFileSync('map.png', canvas.toBuffer('image/png'));
+ * ```
+ */
+export declare class HeadlessRenderer implements MapRenderer {
+    private readonly mapReader;
+    readonly settings: Settings;
+    private currentArea?;
+    private currentAreaInstance?;
+    private currentZIndex?;
+    private positionRoomId?;
+    private highlights;
+    private paths;
+    constructor(mapReader: MapReader, settings?: Settings);
+    drawArea(id: number, zIndex: number): void;
+    getCurrentArea(): Area | undefined;
+    setPosition(roomId: number): void;
+    clearPosition(): void;
+    renderPath(locations: number[], color?: string): void;
+    clearPaths(): void;
+    renderHighlight(roomId: number, color: string): void;
+    removeHighlight(roomId: number): void;
+    hasHighlight(roomId: number): boolean;
+    clearHighlights(): void;
+    /**
+     * Export the current area as an SVG string.
+     */
+    exportSvg(options?: SvgExportOptions): string | undefined;
+    /**
+     * Render the current area to a Canvas2D context (for PNG export).
+     * The caller provides the canvas and context — works with `canvas` npm package (Node.js)
+     * or OffscreenCanvas (browser).
+     */
+    renderToCanvas(ctx: CanvasRenderingContext2D | OffscreenCanvasRenderingContext2D, options: Omit<CanvasExportOptions, 'overlays'> & {
+        overlays?: CanvasExportOverlays;
+    }): void;
+    private buildOverlays;
+}

package/dist/MapRenderer.d.ts

@@ -0,0 +1,32 @@
+import { default as Area } from './reader/Area';
+import { Settings } from './Renderer';
+import { SvgExportOptions } from './SvgExporter';
+/**
+ * Environment-agnostic interface for map rendering.
+ *
+ * Both the browser {@link Renderer} (Konva.js, requires DOM) and
+ * {@link HeadlessRenderer} (no DOM, export-only) implement this interface.
+ *
+ * Use this type to write code that works in both environments:
+ * ```typescript
+ * function setupMap(renderer: MapRenderer) {
+ *     renderer.drawArea(1, 0);
+ *     renderer.setPosition(42);
+ *     renderer.renderHighlight(100, '#ff0000');
+ * }
+ * ```
+ */
+export interface MapRenderer {
+    readonly settings: Settings;
+    drawArea(id: number, zIndex: number): void;
+    getCurrentArea(): Area | undefined;
+    setPosition(roomId: number): void;
+    clearPosition(): void;
+    renderPath(locations: number[], color?: string): void;
+    clearPaths(): void;
+    renderHighlight(roomId: number, color: string): void;
+    removeHighlight(roomId: number): void;
+    hasHighlight(roomId: number): boolean;
+    clearHighlights(): void;
+    exportSvg(options?: SvgExportOptions): string | undefined;
+}

package/dist/PathData.d.ts

@@ -0,0 +1,18 @@
+import { default as MapReader } from './reader/MapReader';
+import { Settings } from './Renderer';
+export interface PathSegment {
+    points: number[];
+}
+export interface PathInnerMarker {
+    room: MapData.Room;
+    direction: MapData.direction;
+}
+export interface PathCustomLine {
+    points: number[];
+}
+export interface PathResult {
+    segments: PathSegment[];
+    innerMarkers: PathInnerMarker[];
+    customLines: PathCustomLine[];
+}
+export declare function computePathData(mapReader: MapReader, settings: Settings, locations: number[], currentArea: number, currentZIndex: number): PathResult;

package/dist/PathRenderer.d.ts

@@ -7,17 +7,8 @@ export default class PathRenderer {
     private readonly settings;
     private paths;
     constructor(mapReader: MapReader, overlayLayer: Konva.Layer, settings: Settings);
-    private getRoomEdgePoint;
-    private findConnection;
-    private findExitDirection;
     private createStrokedLine;
     private renderInnerExitMarker;
     renderPath(locations: number[], currentArea?: number, currentZIndex?: number, color?: string): import('konva/lib/Group').Group | import('konva/lib/Shape').Shape<import('konva/lib/Shape').ShapeConfig> | undefined;
-    private addRegularConnectionPoints;
-    private addSpecialConnectionPoints;
-    private renderInnerConnection;
     clearPaths(): void;
-    private isRoomVisible;
-    private getExitToRoom;
-    private getDirectionTowards;
 }

package/dist/Renderer.d.ts

@@ -1,5 +1,8 @@
 import { default as MapReader } from './reader/MapReader';
 import { default as Area } from './reader/Area';
+import { SvgExportOptions } from './SvgExporter';
+import { MapRenderer } from './MapRenderer';
+export declare function colorLightness(color: string): number;
 export type PerfSnapshot = {
     /** Total updateRoomCulling time in ms */
     cullingMs: number;
@@ -14,7 +17,7 @@ export type PerfSnapshot = {
     /** Estimated FPS based on time between culling calls */
     fps: number;
 };
-export type LabelRenderMode = "image" | "data";
+export type LabelRenderMode = "image" | "data" | "none";
 export type CullingMode = "none" | "basic" | "indexed";
 export type RoomShape = "rectangle" | "circle" | "roundedRectangle";
 export type RoomContextMenuEventDetail = {
@@ -34,6 +37,20 @@ export type RoomClickEventDetail = {
 export type ZoomChangeEventDetail = {
     zoom: number;
 };
+export type AreaExitClickEventDetail = {
+    targetRoomId: number;
+    position: {
+        x: number;
+        y: number;
+    };
+};
+export type ViewportBounds = {
+    minX: number;
+    maxX: number;
+    minY: number;
+    maxY: number;
+};
+export type PanEventDetail = ViewportBounds;
 /**
  * Style configuration for the player position marker.
  * The player marker is a circle that indicates the current player position on the map.
@@ -129,10 +146,22 @@ export type Settings = {
     gridLineWidth: number;
     /** Performance monitoring callback, or null to disable. */
     perfCallback: ((stats: PerfSnapshot) => void) | null;
+    /** Whether to draw borders (strokes) on rooms. Default: true */
+    borders: boolean;
+    /** When true, rooms use frame rendering: fill=backgroundColor, stroke=envColor. Default: false */
+    frameMode: boolean;
+    /** When true, rooms display a 3D emboss effect (rectangle/roundedRectangle only). Default: false */
+    emboss: boolean;
+    /** When true, displays the area name as a header text on the map. Default: false */
+    areaName: boolean;
+    /** Font family for the area name header. Default: 'sans-serif' */
+    fontFamily: string;
+    /** When true, uses bounds from all z-levels for viewport sizing, not just the current level. Default: false */
+    uniformLevelSize: boolean;
 };
 /** Creates a new Settings object with default values. */
 export declare function createSettings(): Settings;
-export declare class Renderer {
+export declare class Renderer implements MapRenderer {
     private readonly stage;
     private readonly gridLayer;
     private readonly roomLayer;
@@ -140,7 +169,7 @@ export declare class Renderer {
     private readonly overlayLayer;
     private readonly positionLayer;
     private mapReader;
-    private readonly settings;
+    readonly settings: Settings;
     private exitRenderer;
     private pathRenderer;
     private highlights;
@@ -156,6 +185,8 @@ export declare class Renderer {
     private roomNodes;
     /** When true, resizing the container will center on the current room. Set to false for static map views. */
     centerOnResize: boolean;
+    /** Minimum zoom level, updated by fitArea() to prevent zooming out beyond the full area view. */
+    minZoom: number;
     private standaloneExitNodes;
     private spatialBucketSize;
     private roomSpatialIndex;
@@ -170,6 +201,7 @@ export declare class Renderer {
     private cullingScheduled;
     private perfMonitor;
     private exitBatchShape?;
+    private areaExitHitZones;
     private visibleExitDrawData;
     private cachedGridBounds;
     constructor(container: HTMLDivElement, mapReader: MapReader, settings?: Settings);
@@ -179,6 +211,28 @@ export declare class Renderer {
     private onResize;
     private initScaling;
     drawArea(id: number, zIndex: number): void;
+    /**
+     * Export the currently displayed area as an SVG string.
+     * @param options - Optional room focus and padding
+     * @returns SVG string, or undefined if no area is displayed
+     */
+    exportSvg(options?: SvgExportOptions): string | undefined;
+    /**
+     * Export the currently displayed canvas as a PNG data URL.
+     * @param options - pixelRatio for resolution (default 1), mimeType override
+     * @returns data URL string, or undefined if no area is displayed
+     */
+    exportPng(options?: {
+        pixelRatio?: number;
+    }): string | undefined;
+    /**
+     * Export the currently displayed canvas as a PNG Blob.
+     * @param options - pixelRatio for resolution (default 1)
+     * @returns Promise resolving to a Blob, or undefined if no area is displayed
+     */
+    exportPngBlob(options?: {
+        pixelRatio?: number;
+    }): Promise<Blob> | undefined;
     private computeSpatialBucketSize;
     private getBucketKey;
     private forEachBucket;
@@ -189,7 +243,11 @@ export declare class Renderer {
     private refreshStandaloneExitBoundsIfNeeded;
     private emitRoomContextEvent;
     private emitRoomClickEvent;
+    private findAreaExitAtClientPoint;
+    private emitAreaExitClickEvent;
     private emitZoomChangeEvent;
+    private emitPanEvent;
+    private emitMapClickEvent;
     setZoom(zoom: number): boolean;
     /**
      * Zooms relative to the center of the viewport.
@@ -197,6 +255,21 @@ export declare class Renderer {
      */
     zoomToCenter(zoom: number): boolean;
     getZoom(): number;
+    /**
+     * Returns the current viewport bounds in map coordinates.
+     */
+    getViewportBounds(): ViewportBounds;
+    /**
+     * Returns the bounds of the current area in map coordinates.
+     * Accounts for area name overhead if enabled.
+     */
+    getAreaBounds(): ViewportBounds | null;
+    /**
+     * Fit the entire current area into the viewport.
+     * Calculates the zoom level needed to show all rooms (and labels) and centers the view.
+     * Call after drawArea() to show the whole area without needing a position room.
+     */
+    fitArea(): void;
     setCullingMode(mode: CullingMode): void;
     getCullingMode(): CullingMode;
     getCurrentArea(): Area | undefined;
@@ -221,7 +294,8 @@ export declare class Renderer {
      */
     updatePositionMarker(roomId: number): void;
     setPosition(roomId: number, center?: boolean): void;
-    centerOn(roomId: number): void;
+    clearPosition(): void;
+    centerOn(roomId: number, instant?: boolean): void;
     renderPath(locations: number[], color?: string): import('konva/lib/Group').Group | import('konva/lib/Shape').Shape<import('konva/lib/Shape').ShapeConfig> | undefined;
     clearPaths(): void;
     renderHighlight(roomId: number, color: string): import('konva/lib/Shape').Shape<import('konva/lib/Shape').ShapeConfig> | undefined;
@@ -232,6 +306,8 @@ export declare class Renderer {
     private createHighlightShape;
     private centerOnRoom;
     private centerOnRoomView;
+    private getEffectiveBounds;
+    private renderAreaName;
     private renderRooms;
     private scheduleRoomCulling;
     private updateRoomCulling;
@@ -241,6 +317,7 @@ export declare class Renderer {
     private clearCurrentRoomOverlay;
     private updateCurrentRoomOverlay;
     private createOverlayRoomGroup;
+    private getSymbolColor;
     private renderSymbol;
     private renderExits;
     private drawExitData;

package/dist/SvgExporter.d.ts

@@ -0,0 +1,51 @@
+import { default as MapReader } from './reader/MapReader';
+import { Settings } from './Renderer';
+export type SvgOverlays = {
+    position?: {
+        roomId: number;
+    };
+    highlights?: Array<{
+        roomId: number;
+        color: string;
+    }>;
+    paths?: Array<{
+        locations: number[];
+        color: string;
+    }>;
+};
+export type SvgExportOptions = {
+    /** Room ID to center the export on. If omitted, exports the full area. */
+    roomId?: number;
+    /** Padding in map units around the exported region. Default: 3 */
+    padding?: number;
+    /** Overlay data (position marker, highlights, paths) to include in the export. */
+    overlays?: SvgOverlays;
+};
+export declare class SvgExporter {
+    private readonly mapReader;
+    private readonly settings;
+    private readonly exitRenderer;
+    constructor(mapReader: MapReader, settings: Settings);
+    private getSymbolColor;
+    export(areaId: number, zIndex: number, options?: SvgExportOptions): string;
+    private computeBounds;
+    private getEffectiveBounds;
+    private getRoomEdgePoint;
+    private renderGrid;
+    private renderLabels;
+    private labelColor;
+    private renderLinkExits;
+    private renderExitData;
+    private renderSvgLine;
+    private renderSvgArrow;
+    private renderSvgDoor;
+    private renderStubs;
+    private renderSpecialExits;
+    private renderRooms;
+    private renderInnerExits;
+    private svgTriangle;
+    private renderPathOverlay;
+    private innerExitRotation;
+    private renderHighlightOverlay;
+    private renderPositionMarker;
+}