mudlet-map-renderer 1.0.0 → 1.2.0

package/dist/rendering/KonvaRenderBackend.d.ts

@@ -0,0 +1,122 @@
+import { default as Konva } from 'konva';
+import { RendererEventMap } from '../types/Settings';
+import { DrawnExitEntry, DrawnSpecialExitEntry, DrawnStubEntry } from '../ScenePipeline';
+import { MapState } from '../MapState';
+import { Camera } from '../camera/Camera';
+import { CullingManager } from '../CullingManager';
+import { TypedEventEmitter } from '../TypedEventEmitter';
+import { InteractiveBackend } from './MapRenderer';
+import { CoordFn } from '../coord/CoordFn';
+import { LiveEffect } from '../overlay/LiveEffect';
+import { SceneOverlay } from '../overlay/SceneOverlay';
+import { ExportCanvas } from '../export/Exporter';
+import { HitTester } from '../hit/HitTester';
+import { Style } from '../style/Style';
+/**
+ * Konva rendering engine. Owns the full rendering pipeline:
+ * stage, layers, scene builder, culling, overlays.
+ *
+ * Camera is the source of truth for transform state.
+ * This backend subscribes to the camera's `change` event and applies state to the Konva stage.
+ *
+ * Works identically in both modes:
+ * - DOM container → stage attached to DOM, mouse/touch → camera
+ * - No container → headless stage, same camera/culling, no input
+ */
+export declare class KonvaRenderBackend implements InteractiveBackend {
+    readonly stage: Konva.Stage;
+    readonly gridLayer: Konva.Layer;
+    readonly linkLayer: Konva.Layer;
+    readonly roomLayer: Konva.Layer;
+    readonly topLabelLayer: Konva.Layer;
+    readonly overlayLayer: Konva.Layer;
+    readonly positionLayer: Konva.Layer;
+    readonly camera: Camera;
+    readonly culling: CullingManager;
+    readonly events: TypedEventEmitter<RendererEventMap>;
+    private readonly state;
+    private readonly container?;
+    private readonly positionLayerNode;
+    private readonly overlayLayerNode;
+    private gridLayerNode;
+    private topLabelLayerNode;
+    /** Snapped grid bounds last rendered onto gridLayerNode. */
+    private gridCachedBounds;
+    private sceneManager;
+    private currentStyle;
+    readonly hitTester: HitTester;
+    private lastHitShapes;
+    private shapeToDrawEntry;
+    private sceneNode;
+    /** Lookup from a pipeline-emitted shape to its recording node; rebuilt per buildScene. */
+    private shapeToGroup;
+    private positionMarker?;
+    private highlightShapes;
+    private pathShapes;
+    private currentRoomOverlay;
+    private areaExitHitZones;
+    private interactionHandler?;
+    private origSetSize?;
+    private cameraChangeHandler?;
+    private destroyed;
+    private _coordinateTransform;
+    private coordinateInverse;
+    get coordinateTransform(): CoordFn;
+    private liveEffects;
+    private sceneOverlays;
+    private sceneOverlayNodes;
+    private viewportSubscribers;
+    constructor(state: MapState, container?: HTMLDivElement);
+    setStyle(style: Style): void;
+    /** Pull forward/inverse coord transforms from the active shape Style. */
+    private applyStyleTransforms;
+    private styleContext;
+    private mapPoint;
+    get exitRenderer(): import('../ExitRenderer').default;
+    getDrawnExits(): readonly DrawnExitEntry[];
+    getDrawnSpecialExits(): readonly DrawnSpecialExitEntry[];
+    getDrawnStubs(): readonly DrawnStubEntry[];
+    destroy(): void;
+    updateBackground(): void;
+    exportCanvas(options?: {
+        pixelRatio?: number;
+    }): ExportCanvas | undefined;
+    private applyViewportToStage;
+    refresh(): void;
+    addLiveEffect(id: string, effect: LiveEffect): void;
+    removeLiveEffect(id: string): void;
+    addSceneOverlay(id: string, overlay: SceneOverlay): void;
+    removeSceneOverlay(id: string): void;
+    /** Iterable of scene overlays — used by exporters to apply them over static outputs. */
+    getSceneOverlays(): Iterable<SceneOverlay>;
+    private createOverlayContext;
+    private renderSceneOverlay;
+    private clearSceneOverlayNodes;
+    private subscribeToState;
+    private buildScene;
+    /** Wrap a non-group shape and walk to a recording node. */
+    private shapeToRecordingNode;
+    /**
+     * Run the active {@link Style} over `shape`, walk every result through
+     * {@link shapeToRecording}, and add it to `layerNode`. Returns the first
+     * emitted node (used as the cull-tracking / destroy handle).
+     */
+    private addStyledShape;
+    /**
+     * Recompute and re-publish the grid lines for the given viewport.
+     * Cached against snapped grid bounds so per-frame redraws are cheap when
+     * the viewport hasn't crossed a grid step.
+     */
+    private refreshGrid;
+    private onSceneBuilt;
+    private applyClipping;
+    private onPositionChanged;
+    private applyPositionMarker;
+    private clearCurrentRoomOverlay;
+    private updateCurrentRoomOverlay;
+    syncHighlight(roomId: number, color: string | undefined): void;
+    syncHighlights(): void;
+    syncPaths(): void;
+    private clearOverlayShapes;
+    private clearPathShapes;
+}

package/dist/rendering/MapRenderer.d.ts

@@ -0,0 +1,213 @@
+import { IMapReader } from '../reader/MapReader';
+import { IArea } from '../reader/Area';
+import { RoomLens } from '../lens/RoomLens';
+import { ViewportBounds, RendererEventMap, CullingMode, Settings } from '../types/Settings';
+import { MapState } from '../MapState';
+import { CoordFn } from '../coord/CoordFn';
+import { Style } from '../style';
+import { Camera } from '../camera/Camera';
+import { CullingManager } from '../CullingManager';
+import { TypedEventEmitter } from '../TypedEventEmitter';
+import { SceneOverlay } from '../overlay/SceneOverlay';
+import { LiveEffect } from '../overlay/LiveEffect';
+import { Exporter, ExportCanvas } from '../export/Exporter';
+import { DrawnExitEntry, DrawnSpecialExitEntry, DrawnStubEntry } from '../ScenePipeline';
+import { HitTester, HitResult } from '../hit/HitTester';
+/**
+ * Contract for interactive render backends.
+ *
+ * Engine-neutral surface — anything that requires a specific render engine
+ * (Konva layers for live effects, Konva.Stage for `toCanvas`) is intentionally
+ * not on this interface and lives only on the concrete backend.
+ */
+export interface InteractiveBackend {
+    readonly camera: Camera;
+    readonly culling: CullingManager;
+    readonly hitTester: HitTester;
+    readonly events: TypedEventEmitter<RendererEventMap>;
+    /** Forward map → render-space transform from the active style (identity for flat styles). */
+    readonly coordinateTransform: CoordFn;
+    /**
+     * Apply a target-agnostic {@link Style} to the live scene. The style
+     * transforms world-space shapes (paint, geometry, projection) before they
+     * are rasterized; the backend re-renders the current scene to reflect it.
+     */
+    setStyle(style: Style): void;
+    updateBackground(): void;
+    refresh(): void;
+    /** Capture the current camera as a canvas with background fill. */
+    exportCanvas(options?: {
+        pixelRatio?: number;
+    }): ExportCanvas | undefined;
+    addSceneOverlay(id: string, overlay: SceneOverlay): void;
+    removeSceneOverlay(id: string): void;
+    getSceneOverlays(): Iterable<SceneOverlay>;
+    /**
+     * Snapshot of inter-room exits as drawn in the last `buildScene` call
+     * (polyline segments, arrows, bounds, dashes — exactly what the user
+     * sees). Empty before the first draw. The list already reflects the
+     * renderer's suppression rules, so anything drawn appears here and
+     * anything not drawn does not.
+     */
+    getDrawnExits(): readonly DrawnExitEntry[];
+    /** Companion to {@link getDrawnExits} for custom-line special exits. */
+    getDrawnSpecialExits(): readonly DrawnSpecialExitEntry[];
+    /** Companion to {@link getDrawnExits} for one-way stub indicators. */
+    getDrawnStubs(): readonly DrawnStubEntry[];
+    destroy(): void;
+}
+/**
+ * Unified map renderer facade.
+ *
+ * Public surface is intentionally narrow:
+ * - **State mutations** (`drawArea`, `setPosition`, `renderHighlight`, …) emit
+ *   events through `MapState` that the interactive backend reacts to.
+ * - **{@link setStyle}** applies a target-agnostic visual transformation to the
+ *   interactive canvas and every exporter.
+ * - **{@link export}** runs an {@link Exporter} plug-in and returns its output
+ *   (SVG string, PNG data URL, canvas, PDF bytes, …). New formats are added by
+ *   shipping new `Exporter<T>` implementations — no new methods on this class.
+ * - **{@link addSceneOverlay}** is target-agnostic and appears in every output.
+ * - **{@link addLiveEffect}** registers interactive-only animated effects (Konva
+ *   canvas only; skipped by exporters).
+ */
+export declare class MapRenderer {
+    readonly state: MapState;
+    readonly backend: InteractiveBackend;
+    private currentStyle;
+    get settings(): Settings;
+    /** Camera owned by the active interactive backend. */
+    get camera(): Camera;
+    /** Culling manager owned by the active interactive backend. */
+    get culling(): CullingManager;
+    /** Hit-test index owned by the active interactive backend. */
+    get hitTester(): HitTester;
+    /** Renderer event emitter (room click, area exit click, zoom change, …). */
+    get events(): TypedEventEmitter<RendererEventMap>;
+    /**
+     * @param mapReader       Map data source.
+     * @param settings        Renderer settings. Defaults to `createSettings()`.
+     * @param container       DOM element for interactive rendering. Omit for headless.
+     * @param backendFactory  Optional factory that receives the `MapState` and returns
+     *   a custom `InteractiveBackend`. When omitted, a `KonvaRenderBackend` is created.
+     */
+    constructor(mapReader: IMapReader, settings?: Settings, container?: HTMLDivElement, backendFactory?: (state: MapState) => InteractiveBackend);
+    destroy(): void;
+    drawArea(id: number, zIndex: number): void;
+    getCurrentArea(): IArea | undefined;
+    setPosition(roomId: number, center?: boolean): void;
+    updatePositionMarker(roomId: number): void;
+    clearPosition(): void;
+    centerOn(roomId: number, instant?: boolean): void;
+    renderHighlight(roomId: number, color: string): void;
+    removeHighlight(roomId: number): void;
+    hasHighlight(roomId: number): boolean;
+    clearHighlights(): void;
+    renderPath(locations: number[], color?: string): void;
+    clearPaths(): void;
+    refreshCurrentRoomOverlay(): void;
+    /**
+     * Replace the active visibility lens. Lenses filter which rooms (and how
+     * partially-visible exits) the renderer draws — exploration / fog-of-war
+     * is one example, guild/quest scope overlays are others. Compose multiple
+     * concerns with `composeLenses(...)`.
+     *
+     * Triggers an immediate rebuild. For mutations on a stateful lens (e.g.
+     * `ExplorationLens.addVisited`), call {@link refresh} explicitly.
+     */
+    setLens(lens: RoomLens): void;
+    getLens(): RoomLens;
+    /**
+     * Apply a {@link Style} to the interactive canvas and every export path.
+     * The backend rebuilds the current scene under the new style — no explicit
+     * `refresh()` is needed.
+     *
+     * ```ts
+     * import {compose, Parchment, Sketchy} from 'mudlet-map-renderer';
+     * renderer.setStyle(compose(Parchment, Sketchy({jitter: 0.012, color: '#4a3728'})));
+     * ```
+     *
+     * Pass `identityStyle` (or call {@link clearStyle}) to remove the current style.
+     */
+    setStyle(style: Style): void;
+    /** Equivalent to `setStyle(identityStyle)`. */
+    clearStyle(): void;
+    /** Returns the style currently applied (defaults to identity). */
+    getStyle(): Style;
+    updateBackground(): void;
+    refresh(): void;
+    /** Target-agnostic overlay; appears in every output including exporters. */
+    addSceneOverlay(id: string, overlay: SceneOverlay): void;
+    removeSceneOverlay(id: string): void;
+    /**
+     * Register an interactive-only animated effect. No-ops when running with a
+     * non-Konva backend. Does not appear in SVG/PNG exports — use
+     * {@link addSceneOverlay} for overlays that must appear in exports.
+     *
+     * ```ts
+     * renderer.addLiveEffect('rain', new RainEffect());
+     * ```
+     */
+    addLiveEffect(id: string, effect: LiveEffect): void;
+    removeLiveEffect(id: string): void;
+    /**
+     * Hit-test a world-space map point against the current scene.
+     *
+     * Returns the nearest pickable shape at `(worldX, worldY)`, or `null`
+     * when no hittable shape is within range.  Coordinates must be in the
+     * same flat map space as room positions — the method applies the active
+     * style's world→scene projection internally, so callers never need to
+     * think about Isometric mode.
+     *
+     * ```ts
+     * const hit = renderer.hitTest(room.x, room.y);
+     * if (hit?.kind === 'room') console.log('room', hit.id);
+     * ```
+     */
+    hitTest(worldX: number, worldY: number): HitResult | null;
+    /**
+     * Polyline / arrow / bounds data for every inter-room exit the renderer
+     * drew on the last scene build. Intended for tools (e.g. editors) that
+     * need to hit-test against exactly what the user sees, including dash
+     * patterns, one-way arrows, and the renderer's suppression rules.
+     */
+    getDrawnExits(): readonly DrawnExitEntry[];
+    /** Companion to {@link getDrawnExits} for custom-line special exits. */
+    getDrawnSpecialExits(): readonly DrawnSpecialExitEntry[];
+    /**
+     * Polyline data for every one-way stub indicator the renderer drew
+     * (one entry per direction in `room.stubs`). Coordinates are in
+     * render space and match what's on screen.
+     */
+    getDrawnStubs(): readonly DrawnStubEntry[];
+    /**
+     * Run an {@link Exporter} against the current scene and return its output.
+     *
+     * ```ts
+     * const svg    = renderer.export(new SvgExporter({ padding: 5 }));
+     * const url    = renderer.export(new PngExporter({ pixelRatio: 2 }));
+     * const blob   = await renderer.export(new PngBlobExporter());
+     * const canvas = renderer.export(new CanvasExporter({ width, height }));
+     * ```
+     */
+    export<T>(exporter: Exporter<T>): T;
+    on<K extends keyof RendererEventMap>(event: K, handler: (detail: RendererEventMap[K]) => void): void;
+    off<K extends keyof RendererEventMap>(event: K, handler: (detail: RendererEventMap[K]) => void): void;
+    setZoom(zoom: number): boolean;
+    zoomToCenter(zoom: number): boolean;
+    getZoom(): number;
+    getViewportBounds(): ViewportBounds;
+    getAreaBounds(): ViewportBounds | null;
+    fitArea(insets?: {
+        top?: number;
+        right?: number;
+        bottom?: number;
+        left?: number;
+    }): void;
+    get centerOnResize(): boolean;
+    set centerOnResize(value: boolean);
+    get minZoom(): number;
+    set minZoom(value: number);
+    setCullingMode(mode: CullingMode): void;
+    getCullingMode(): CullingMode;
+}

package/dist/rendering/SceneManager.d.ts

@@ -0,0 +1,54 @@
+import { IArea } from '../reader/Area';
+import { IPlane } from '../reader/Plane';
+import { Settings } from '../types/Settings';
+import { SceneBuildResult, SceneShapesByLayer, AreaExitHitZone, DrawnExitEntry, DrawnSpecialExitEntry, DrawnStubEntry } from '../ScenePipeline';
+import { Camera } from '../camera/Camera';
+import { CoordFn } from '../coord/CoordFn';
+import { GroupShape, Shape } from '../scene/Shape';
+import { IMapReader } from '../reader/MapReader';
+import { RoomLens } from '../lens/RoomLens';
+import { ExitDrawData } from '../ExitRenderer';
+export interface CullStats {
+    visibleRooms: number;
+    totalRooms: number;
+    visibleExits: number;
+}
+export interface CullOutput {
+    shapes: SceneShapesByLayer;
+    stats: CullStats;
+}
+/**
+ * Encapsulates the scene build + cull pipeline for the interactive renderer.
+ *
+ * Owns {@link ScenePipeline} and the last {@link SceneBuildResult}. Backends
+ * call {@link rebuild} when the area/plane changes, then {@link cull} on each
+ * viewport update to get the currently-visible shapes. Neither the pipeline
+ * nor {@link clipSceneToViewport} need to be referenced outside this class.
+ */
+export declare class SceneManager {
+    private readonly camera;
+    private readonly settings;
+    private pipeline;
+    private lastBuildResult?;
+    private standaloneExitShapeSet;
+    constructor(camera: Camera, settings: Settings, mapReader: IMapReader);
+    get exitRenderer(): import('../ExitRenderer').default;
+    get lastResult(): SceneBuildResult | undefined;
+    get drawnExits(): readonly DrawnExitEntry[];
+    get drawnSpecialExits(): readonly DrawnSpecialExitEntry[];
+    get drawnStubs(): readonly DrawnStubEntry[];
+    get areaExitHitZones(): readonly AreaExitHitZone[];
+    get hitShapes(): readonly Shape[];
+    rebuild(area: IArea, plane: IPlane, zIndex: number, lens?: RoomLens): SceneBuildResult;
+    buildExitShape(data: ExitDrawData): GroupShape;
+    reset(): void;
+    resetPipeline(mapReader: IMapReader): void;
+    /**
+     * Lightweight cull for the interactive render path.  Returns a
+     * `Map<Shape, boolean>` where absent shapes are unmanaged pass-throughs
+     * (always visible).  Avoids the 12 Sets + 2 filtered arrays produced by
+     * the full {@link cull} path.
+     */
+    cullInteractive(coordinateTransform?: CoordFn): Map<Shape, boolean>;
+    cull(coordinateTransform?: CoordFn): CullOutput;
+}

package/dist/scene/AmbientLightStyle.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Ambient light data: a single image containing a smooth radial vignette,
+ * positioned centered on the player.
+ */
+export type AmbientLightData = {
+    cx: number;
+    cy: number;
+    displaySize: number;
+    src: string;
+};
+/** Tunable parameters for the ambient light vignette. */
+export type AmbientLightParams = {
+    color: string;
+    radius: number;
+    intensity: number;
+};
+/**
+ * Compute ambient light vignette for the given player position and viewport.
+ *
+ * Produces a single image overlay containing a smooth radial gradient:
+ * clear at center → full darkness at edges. The image is sized to always
+ * cover the entire visible viewport with margin.
+ */
+export declare function computeAmbientLight(cx: number, cy: number, viewportBounds: {
+    minX: number;
+    maxX: number;
+    minY: number;
+    maxY: number;
+}, params: AmbientLightParams): AmbientLightData;

package/dist/scene/GridStyle.d.ts

@@ -0,0 +1,21 @@
+import { Settings } from '../types/Settings';
+export type GridLineData = {
+    x1: number;
+    y1: number;
+    x2: number;
+    y2: number;
+};
+export type GridData = {
+    lines: GridLineData[];
+    stroke: string;
+    strokeWidth: number;
+};
+/**
+ * Compute grid lines for a given viewport bounds.
+ */
+export declare function computeGrid(settings: Settings, bounds: {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+}): GridData;

package/dist/scene/InnerExitStyle.d.ts

@@ -0,0 +1,24 @@
+import { Settings } from '../types/Settings';
+import { IMapReader } from '../reader/MapReader';
+export type TriangleData = {
+    cx: number;
+    cy: number;
+    /** Pre-computed polygon vertices (3 pairs of x,y) */
+    vertices: number[];
+    fill: string;
+    stroke: string;
+    strokeWidth: number;
+};
+export type InnerExitData = {
+    triangles: TriangleData[];
+};
+declare function computeTriangleVertices(cx: number, cy: number, radius: number, rotationDeg: number): number[];
+/**
+ * Compute inner exit triangle data for a room.
+ * Returns pre-computed vertex positions so each backend just draws polygons.
+ */
+export declare function computeInnerExits(room: MapData.Room, mapReader: IMapReader, settings: Settings): InnerExitData;
+/**
+ * Compute triangle vertices for a standalone triangle (used by path overlay markers).
+ */
+export { computeTriangleVertices };

package/dist/scene/OverlayStyle.d.ts

@@ -0,0 +1,47 @@
+import { Settings } from '../types/Settings';
+import { IMapReader } from '../reader/MapReader';
+export type HighlightData = {
+    shape: 'circle' | 'rect';
+    cx: number;
+    cy: number;
+    /** For circle: radius. For rect: half-size. */
+    size: number;
+    cornerRadius: number;
+    strokeColor: string;
+    strokeAlpha: number;
+    strokeWidth: number;
+    fillColor: string;
+    fillAlpha: number;
+    dash?: number[];
+    dashEnabled: boolean;
+};
+export declare function computeHighlight(room: MapData.Room, color: string, settings: Settings): HighlightData;
+export type PositionMarkerData = {
+    shape: 'circle' | 'rect';
+    cx: number;
+    cy: number;
+    size: number;
+    cornerRadius: number;
+    strokeColor: string;
+    strokeWidth: number;
+    strokeAlpha: number;
+    fillColor: string;
+    fillAlpha: number;
+    dash?: number[];
+    dashEnabled: boolean;
+};
+export declare function computePositionMarker(room: MapData.Room, settings: Settings): PositionMarkerData;
+export type PathOverlaySegment = {
+    points: number[];
+};
+export type PathOverlayTriangle = {
+    vertices: number[];
+};
+export type PathOverlayData = {
+    segments: PathOverlaySegment[];
+    triangles: PathOverlayTriangle[];
+    color: string;
+    outlineWidth: number;
+    lineWidth: number;
+};
+export declare function computePathOverlay(mapReader: IMapReader, settings: Settings, locations: number[], color: string, areaId: number, zIndex: number): PathOverlayData;

package/dist/scene/RoomStyle.d.ts

@@ -0,0 +1,32 @@
+import { Settings } from '../types/Settings';
+import { IMapReader } from '../reader/MapReader';
+export type RoomColors = {
+    fillColor: string;
+    strokeColor: string;
+    borderWidth: number;
+    symbolColor: string;
+    envColor: string;
+};
+export type EmbossEdge = {
+    points: number[];
+    stroke: string;
+    strokeWidth: number;
+    lineCap?: string;
+    lineJoin?: string;
+};
+export type EmbossStyle = {
+    highlight: EmbossEdge;
+    shadow: EmbossEdge;
+} | null;
+/**
+ * Compute the fill/stroke/border colors for a room based on env color and settings.
+ * This is the single source of truth — used by Konva renderer, SVG exporter, and Canvas exporter.
+ */
+export declare function computeRoomColors(room: MapData.Room, mapReader: IMapReader, settings: Settings, strokeOverride?: string): RoomColors;
+/**
+ * Compute the emboss bevel for a room.
+ * Returns highlight (top+left) and shadow (bottom+right) edges using
+ * lightened/darkened versions of the fill color for a raised 3D look.
+ * Works for all room shapes: rectangle, roundedRectangle, and circle.
+ */
+export declare function computeEmboss(fillColor: string, settings: Settings): EmbossStyle;