mudlet-map-renderer 1.0.0 → 1.2.0

package/dist/export/CanvasExporter.d.ts

@@ -0,0 +1,71 @@
+import { Exporter, ExportContext, ExportCanvas } from './Exporter';
+export interface 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;
+    /** Overlays to render over the scene (position marker, highlights, paths). */
+    overlays?: {
+        position?: {
+            roomId: number;
+        };
+        highlights?: Array<{
+            roomId: number;
+            color: string;
+        }>;
+        paths?: Array<{
+            locations: number[];
+            color: string;
+        }>;
+    };
+}
+/**
+ * Renders the current scene into a canvas at the requested width/height by
+ * driving {@link ScenePipeline} → {@link buildDrawCommands} →
+ * {@link renderToCanvas}.
+ *
+ * Decoupled from the live Konva stage: the pipeline is rebuilt against the
+ * export bounds, shapes are projected through a fitted camera transform, and
+ * the result is rasterized onto a fresh 2D canvas. Background colour is
+ * filled before any draw commands replay, so PNG / JPEG output looks identical
+ * to the on-screen map.
+ *
+ * Unlike {@link PngExporter} (which captures the on-screen viewport via the
+ * live Konva stage), `CanvasExporter` is fully headless and reproducible.
+ */
+export declare class CanvasExporter implements Exporter<ExportCanvas | undefined> {
+    private readonly options;
+    constructor(options: CanvasExportOptions);
+    render({ state, style, sceneOverlays }: ExportContext): ExportCanvas | undefined;
+}
+export interface PngBytesExportOptions extends CanvasExportOptions {
+    /** MIME type to encode. Defaults to `'image/png'`. */
+    mimeType?: string;
+    /** Encoder quality (0..1). Only used for lossy formats like `'image/jpeg'`. */
+    quality?: number;
+}
+/**
+ * Headless PNG/JPEG bytes at a specific width × height.
+ *
+ * Composes {@link CanvasExporter} with a portable `toDataURL` → `Uint8Array`
+ * decode, so callers get bytes directly without touching a canvas or casting
+ * to platform-specific types:
+ *
+ * ```ts
+ * const png = renderer.export(new PngBytesExporter({ width: 1920, height: 1080 }));
+ * fs.writeFileSync('out.png', png!);              // Node
+ * new Blob([png!], { type: 'image/png' });        // Browser
+ * ```
+ *
+ * For JPEG: `new PngBytesExporter({ width, height, mimeType: 'image/jpeg', quality: 0.9 })`.
+ */
+export declare class PngBytesExporter implements Exporter<Uint8Array | undefined> {
+    private readonly options;
+    private readonly canvasExporter;
+    constructor(options: PngBytesExportOptions);
+    render(context: ExportContext): Uint8Array | undefined;
+}

package/dist/export/Exporter.d.ts

@@ -0,0 +1,58 @@
+import { MapState } from '../MapState';
+import { Style } from '../style/Style';
+import { SceneOverlay } from '../overlay/SceneOverlay';
+import { InteractiveBackend } from '../rendering/MapRenderer';
+/**
+ * Context handed to every {@link Exporter} by {@link MapRenderer.export}.
+ * Exporters pull whatever they need — state + style for SVG, backend for
+ * canvas/PNG rasterization — so callers never have to wire `renderer.backend`
+ * (or any other internal) into an exporter themselves.
+ */
+export interface ExportContext {
+    readonly state: MapState;
+    readonly backend: InteractiveBackend;
+    readonly style: Style;
+    readonly sceneOverlays: Iterable<SceneOverlay>;
+}
+/**
+ * Pluggable output format. An {@link Exporter} consumes an {@link ExportContext}
+ * and returns an output of type `T` (a string, a Blob promise, a canvas, bytes…).
+ *
+ * Adding a new output format means implementing `Exporter<T>`. `MapRenderer`'s
+ * surface does not change — users just pass the new exporter to `renderer.export`.
+ *
+ * ```ts
+ * renderer.export(new SvgExporter({ padding: 5 }));         // string
+ * renderer.export(new PngExporter({ pixelRatio: 2 }));      // string (data URL)
+ * renderer.export(new CanvasExporter({ width, height }));   // ExportCanvas
+ * ```
+ */
+export interface Exporter<T> {
+    render(context: ExportContext): T;
+}
+/**
+ * Canvas returned by {@link CanvasExporter} and
+ * {@link InteractiveBackend.exportCanvas}. Describes the portable surface
+ * common to the browser `HTMLCanvasElement` and the `canvas` package's
+ * Node-side Canvas:
+ *
+ *   - Portable:  `width`, `height`, `getContext`, `toDataURL`.
+ *   - Browser:   `toBlob(cb)` (optional here; use when serializing to a Blob).
+ *
+ * Platform-specific serializers (e.g. node-canvas's `toBuffer`) are intentionally
+ * not part of this interface. Cast when you need them:
+ *
+ * ```ts
+ * import type { Canvas } from 'canvas';
+ * const canvas = renderer.export(new CanvasExporter({width, height})) as unknown as Canvas;
+ * const png = canvas.toBuffer('image/png');
+ * ```
+ */
+export interface ExportCanvas {
+    readonly width: number;
+    readonly height: number;
+    getContext(contextId: '2d', options?: any): CanvasRenderingContext2D | null;
+    toDataURL(type?: string, quality?: any): string;
+    /** Browser only; undefined in Node. */
+    toBlob?(callback: (blob: Blob | null) => void, type?: string, quality?: any): void;
+}

package/dist/export/PngExporter.d.ts

@@ -0,0 +1,23 @@
+import { Exporter, ExportContext } from './Exporter';
+export interface PngExportOptions {
+    pixelRatio?: number;
+}
+/**
+ * Exports the current interactive canvas as a PNG data URL. Rasterizes the
+ * live Konva stage — whatever style the renderer currently has applied is
+ * what gets captured.
+ *
+ * For re-framing with an explicit width/height (e.g. server-side rendering),
+ * use {@link CanvasExporter} and serialize its output yourself.
+ */
+export declare class PngExporter implements Exporter<string | undefined> {
+    private readonly options;
+    constructor(options?: PngExportOptions);
+    render({ backend }: ExportContext): string | undefined;
+}
+/** Companion to {@link PngExporter} that returns a Blob instead of a data URL. */
+export declare class PngBlobExporter implements Exporter<Promise<Blob> | undefined> {
+    private readonly options;
+    constructor(options?: PngExportOptions);
+    render({ backend }: ExportContext): Promise<Blob> | undefined;
+}

package/dist/export/SvgExporter.d.ts

@@ -0,0 +1,19 @@
+import { SvgExportOptions } from '../SvgTypes';
+import { Exporter, ExportContext } from './Exporter';
+/**
+ * Renders the current scene as an SVG string by driving
+ * {@link ScenePipeline} → {@link buildDrawCommands} → {@link svgFromBatches}.
+ *
+ * The pipeline is rebuilt with bounded viewport bounds (so the grid layout
+ * matches the export region), then `sceneShapes` is flushed through the
+ * draw-command pipeline at scale 1 — coordinates land inside the SVG
+ * viewBox in world space, identical to the legacy SvgBackend output. Active
+ * {@link SceneOverlay}s are still rendered against an {@link SvgBackend}
+ * so user code that builds custom overlays via the DrawingBackend keeps
+ * working until the overlay API is migrated to shapes.
+ */
+export declare class SvgExporter implements Exporter<string | undefined> {
+    private readonly options;
+    constructor(options?: SvgExportOptions);
+    render({ state, style, sceneOverlays }: ExportContext): string | undefined;
+}

package/dist/export/canvasToBytes.d.ts

@@ -0,0 +1,19 @@
+import { ExportCanvas } from './Exporter';
+/**
+ * Serialize an {@link ExportCanvas} to raw bytes, synchronously, using the
+ * portable `toDataURL` API. Works identically in the browser and in Node.
+ *
+ * ```ts
+ * const canvas = renderer.export(new CanvasExporter({ width, height }));
+ * const png = canvasToBytes(canvas);     // Uint8Array
+ * fs.writeFileSync('out.png', png);       // Node
+ * // or: new Blob([png], { type: 'image/png' })   — browser
+ * ```
+ *
+ * @param canvas    Canvas produced by {@link CanvasExporter} or the
+ *                  interactive backend's `exportCanvas`.
+ * @param mimeType  Output format. Defaults to `'image/png'`. Pass `'image/jpeg'`
+ *                  + `quality` (0..1) for JPEG.
+ * @param quality   JPEG quality (ignored for PNG).
+ */
+export declare function canvasToBytes(canvas: ExportCanvas, mimeType?: string, quality?: number): Uint8Array;

package/dist/export/clipSceneToViewport.d.ts

@@ -0,0 +1,48 @@
+import { SceneBuildResult, SceneShapesByLayer } from '../ScenePipeline';
+import { ViewportBounds, Settings } from '../types/Settings';
+import { Shape } from '../scene/Shape';
+/**
+ * Interactive-path optimised alternative to {@link clipSceneToViewport}.
+ *
+ * Returns a single `Map<Shape, boolean>` where `true` means the shape is
+ * inside the viewport and `false` means it should be hidden.  Shapes absent
+ * from the map are "unmanaged" pass-throughs (noScaling labels, overlays) and
+ * should be treated as visible.
+ *
+ * Allocation budget per frame: 1 Map instead of the 12 Sets + 2 filtered
+ * arrays that {@link clipSceneToViewport} produces.
+ */
+export declare function buildCullingVisibilityMap(result: SceneBuildResult, viewportBounds: ViewportBounds, settings: Settings, transforms?: SceneTransforms): Map<Shape, boolean>;
+type TransformFn = (x: number, y: number) => {
+    x: number;
+    y: number;
+};
+/** Forward and inverse coordinate transforms for styles that warp space (e.g. Isometric). */
+export type SceneTransforms = {
+    /** World → scene (for culling bounding-box projection). */
+    forward?: TransformFn;
+    /** Scene → world (for grid-line Cartesian-bounds computation). */
+    inverse?: TransformFn;
+};
+/**
+ * Filter scene shapes to only those that intersect the given viewport, and
+ * generate the grid for that viewport — the shared cull step used by export
+ * paths (SVG, PNG).
+ *
+ * Uses {@link buildCullingVisibilityMap} for the predicate so culling logic
+ * lives in one place.  Shapes absent from the map are unmanaged pass-throughs
+ * (noScaling labels, overlays) and are always included.
+ *
+ * Interactive path uses {@link buildCullingVisibilityMap} directly and skips
+ * building these filtered arrays.
+ *
+ * When `settings.cullingEnabled` is false the original {@link SceneShapesByLayer}
+ * is returned (with grid appended).
+ *
+ * `transforms.forward` projects world → rendered space for styles like
+ * Isometric that warp coordinates (pass `style.worldToScene` when available).
+ * `transforms.inverse` projects rendered → world space (pass `style.sceneToWorld`)
+ * for correct grid-line Cartesian-bounds computation under warped styles.
+ */
+export declare function clipSceneToViewport(result: SceneBuildResult, viewportBounds: ViewportBounds, settings: Settings, transforms?: SceneTransforms): SceneShapesByLayer;
+export {};

package/dist/export/flushSceneShapes.d.ts

@@ -0,0 +1,21 @@
+import { SceneShapesByLayer } from '../ScenePipeline';
+import { Shape } from '../scene/Shape';
+import { MapState } from '../MapState';
+import { SceneOverlay } from '../overlay/SceneOverlay';
+import { ViewportBounds } from '../types/Settings';
+import { SvgOverlays } from '../SvgTypes';
+export interface SceneFlushContext {
+    state: MapState;
+    viewportBounds: ViewportBounds;
+    sceneOverlays: Iterable<SceneOverlay>;
+    overlays?: SvgOverlays;
+}
+/**
+ * Walk the canonical scene-layer order, calling `flush` once per layer.
+ * Order: grid → link → room → built-in overlays → scene overlays → topLabel.
+ *
+ * Single source of truth for what static exporters must render — adding a new
+ * exporter no longer means re-typing the sequence and risking a silent omission.
+ */
+export declare function flushSceneShapes(sceneShapes: SceneShapesByLayer, context: SceneFlushContext, flush: (shapes: Shape[]) => void): void;
+export declare function buildBuiltInOverlayShapes(state: MapState, overlaysInput?: SvgOverlays): Shape[];

package/dist/export/sceneBounds.d.ts

@@ -0,0 +1,24 @@
+import { Style } from '../style/Style';
+export interface ExportBounds {
+    readonly x: number;
+    readonly y: number;
+    readonly w: number;
+    readonly h: number;
+}
+/**
+ * Convert world-space export bounds into the scene-space AABB an exporter
+ * (SVG, canvas) should target.
+ *
+ * Coordinate-warping styles (e.g. Isometric) project world coords into a
+ * different render space, so the SVG viewBox / canvas fit must be sized to
+ * the projected region — otherwise the rendered scene drifts outside the
+ * background rect and is partially clipped.
+ *
+ * For non-warping styles (identity, parchment, sketchy, …) `worldToScene`
+ * is undefined and the bounds pass through unchanged.
+ *
+ * `scenePad` adds a uniform buffer in scene space — used to absorb
+ * decorations the projection itself doesn't account for (cube depth in
+ * Isometric, neon glow, …).
+ */
+export declare function projectExportBoundsToScene(bounds: ExportBounds, style: Style, scenePad?: number): ExportBounds;

package/dist/hit/HitTester.d.ts

@@ -0,0 +1,101 @@
+import { Shape, Bbox } from '../scene/Shape';
+export type CoordTransform = (x: number, y: number) => {
+    x: number;
+    y: number;
+};
+/** Result returned by {@link HitTester.pick} et al. */
+export interface HitResult {
+    kind: string;
+    id?: number | string;
+    payload?: unknown;
+    /** Distance from the query point to the shape (rendered space units). */
+    distance: number;
+    /** Effective priority used when ranking (per-kind default unless overridden). */
+    priority: number;
+    /** Center of the shape's rendered bbox — useful for hover effects. */
+    centerX: number;
+    centerY: number;
+}
+/** One entry returned by {@link HitTester.debugEntries} for visualisation. */
+export interface HitDebugEntry {
+    kind: string;
+    geoms: ReadonlyArray<HitGeom>;
+    /** Max distance from shape edge that still registers as a hit (rendered-space units). */
+    marginRadius: number;
+    /** Rendered-space bbox of the hit geometry. */
+    minX: number;
+    maxX: number;
+    minY: number;
+    maxY: number;
+}
+export type HitGeom = {
+    type: "polyline";
+    pts: number[];
+    closed: boolean;
+} | {
+    type: "circle";
+    cx: number;
+    cy: number;
+    r: number;
+};
+/**
+ * Spatial index for hittable shapes. Rebuilt cheaply after each scene build.
+ */
+export declare class HitTester {
+    private entries;
+    private bucketSize;
+    private roomSize;
+    private spatialIndex;
+    private transform;
+    /**
+     * Rebuild from a fresh set of world-space shapes.
+     *
+     * @param shapes         Top-level shape list from {@link ScenePipeline}.
+     * @param roomSize       Current room size (world units) — used as base pick margin.
+     * @param coordTransform World→rendered projection; omit for flat (identity).
+     */
+    build(shapes: Shape[], roomSize: number, coordTransform?: CoordTransform): void;
+    clear(): void;
+    /**
+     * Find the best-matching hittable shape at a rendered-space point.
+     * Best = highest priority, then closest. Returns `null` when no shape
+     * is within its margin of the point.
+     */
+    pick(x: number, y: number): HitResult | null;
+    /**
+     * Return every hittable shape at a rendered-space point, sorted by
+     * priority desc then distance asc. Used for Alt+click cycling and
+     * disambiguation menus.
+     */
+    pickAll(x: number, y: number): HitResult[];
+    /**
+     * Return every hittable shape whose rendered-space center falls inside
+     * the rect, optionally filtered by kind. Used for marquee selection.
+     */
+    pickInRect(minX: number, minY: number, maxX: number, maxY: number, kinds?: string[]): HitResult[];
+    /**
+     * Convenience wrapper: return the room whose hit shape is nearest to
+     * the given rendered-space point, or `null` when none is within range.
+     */
+    findRoomAtPoint(x: number, y: number): MapData.Room | null;
+    /**
+     * Returns hit geometry for every entry, for debug visualisation.
+     * Coordinates are in **rendered space** (world space for flat styles).
+     */
+    debugEntries(): HitDebugEntry[];
+    /** Walk the 9 buckets around the point and emit candidates within margin. */
+    private forEachCandidate;
+    private toResult;
+    private collectHitShapes;
+    private indexEntry;
+}
+/**
+ * Compute the axis-aligned bounding box of a shape in world space.
+ * `offsetX/Y` is the cumulative parent group origin.
+ *
+ * Note: this does NOT apply the HitTester's coord transform. Callers that
+ * need rendered-space extents should transform the four corners themselves.
+ * Kept exported for backends that need a quick world-space AABB (e.g. cull
+ * entry construction, scene bounds), and for tests.
+ */
+export declare function computeShapeBbox(shape: Shape, offsetX: number, offsetY: number): Bbox;

package/dist/index.d.ts

@@ -0,0 +1,61 @@
+export { createSettings } from './types/Settings';
+export type { Settings, ViewportBounds, RendererEventMap, CullingMode, RoomShape, LabelRenderMode, PlayerMarkerStyle, RoomClickEventDetail, RoomContextMenuEventDetail, ZoomChangeEventDetail, AreaExitClickEventDetail, PanEventDetail, } from './types/Settings';
+export { darkenColor, colorLightness, hexToRgba } from './utils/color';
+export { MapRenderer } from './rendering/MapRenderer';
+export type { InteractiveBackend } from './rendering/MapRenderer';
+export type { DrawnExitEntry, DrawnSpecialExitEntry, DrawnStubEntry } from './ScenePipeline';
+export type { ExitDrawData, ExitDrawLine, ExitDrawArrow, ExitDrawDoor } from './ExitRenderer';
+export { MapState } from './MapState';
+export type { MapStateEventMap, HighlightEntry, PathEntry } from './MapState';
+export { Camera } from './camera/Camera';
+export type { CameraEventMap } from './camera/Camera';
+export { HitTester } from './hit/HitTester';
+export type { HitResult } from './hit/HitTester';
+export { CullingManager } from './CullingManager';
+export type { CoordFn } from './coord/CoordFn';
+export { IDENTITY_TRANSFORM } from './coord/CoordFn';
+export { DrawCommandLayerNode, MaterializingLayerNode, RecordingLayerNode, RecordingGroupNode, } from './render/RecordingLayer';
+export type { DrawEntry, RecordingDrawCommand } from './render/RecordingLayer';
+export { shapeToRecording } from './render/shapeToRecording';
+export type { Shape, ShapeBase, RectShape, CircleShape, LineShape, PolygonShape, TextShape, ImageShape, GroupShape, Paint, HitInfo, LayerId, Bbox, SceneIR, } from './scene/Shape';
+export type { DrawCommand, DrawCommandBatch, RectCommand, CircleCommand, LineCommand, PolygonCommand, TextCommand, ImageCommand, PrimitiveDrawCommand, StackDrawCommand, PushTransformCommand, PopTransformCommand, PushClipCommand, PopClipCommand, } from './draw/DrawCommand';
+export { buildDrawCommands } from './draw/DrawCommandBuilder';
+export type { CameraTransform } from './draw/DrawCommandBuilder';
+export { svgFromBatches } from './render/SvgRenderer';
+export { renderToCanvas } from './render/CanvasRenderer';
+export type { ImageFactory, CanvasRenderOptions } from './render/CanvasRenderer';
+export { Parchment, Blueprint, Neon, Sketchy, Isometric, Construction, SciFi, compose, identityStyle, applyStyleToShapes, } from './style';
+export type { Style, StyleContext, SketchyOptions, IsometricOptions, IsometricRotation, } from './style';
+export type { Exporter, ExportContext, ExportCanvas } from './export/Exporter';
+export { SvgExporter } from './export/SvgExporter';
+export { PngExporter, PngBlobExporter } from './export/PngExporter';
+export type { PngExportOptions } from './export/PngExporter';
+export { CanvasExporter, PngBytesExporter } from './export/CanvasExporter';
+export type { CanvasExportOptions, PngBytesExportOptions } from './export/CanvasExporter';
+export { canvasToBytes } from './export/canvasToBytes';
+export type { SceneOverlay, SceneOverlayContext } from './overlay/SceneOverlay';
+export type { LiveEffect, CoordinateTransform } from './overlay/LiveEffect';
+export { AmbientLightOverlay } from './overlay/AmbientLightOverlay';
+export type { AmbientLightOptions } from './overlay/AmbientLightOverlay';
+export { default as MapReader } from './reader/MapReader';
+export type { IMapReader } from './reader/MapReader';
+export { default as PathFinder } from './PathFinder';
+export type { PathFindingAlgorithm } from './PathFinder';
+export { MapGraph } from './MapGraph';
+export type { Edge, GraphData } from './MapGraph';
+export { default as Area } from './reader/Area';
+export type { IArea } from './reader/Area';
+export { default as Plane } from './reader/Plane';
+export type { IPlane } from './reader/Plane';
+export type { IExit, Kind as ExitKind } from './reader/Exit';
+export type { RoomLens, ExitTreatment } from './lens/RoomLens';
+export { ALL_VISIBLE, defaultExitTreatment } from './lens/RoomLens';
+export { composeLenses } from './lens/composeLenses';
+export type { ComposeOptions, ExitConflictStrategy } from './lens/composeLenses';
+export { ExplorationLens } from './lens/ExplorationLens';
+export { AreaMapRenderer, createAreaMapSettings } from './AreaMapRenderer';
+export type { AreaMapSettings } from './AreaMapRenderer';
+export type { AreaDomainInfo, DomainFilter } from './AreaMapRenderer';
+export type { SvgExportOptions, SvgOverlays } from './SvgTypes';
+export { computePathData } from './PathData';
+export type { PathResult, PathSegment, PathInnerMarker } from './PathData';