mudlet-map-renderer 0.33.0-konva → 0.34.1-konva

package/README.md

@@ -186,37 +186,97 @@ For large maps, spatial culling hides off-screen rooms for better performance:
 renderer.setCullingMode('indexed');
 ```
 
-### Export
+### Styles
+
+A `Style` is a target-agnostic visual transformer. One style drives the
+interactive canvas *and* every exporter — set it once and it applies to SVG,
+PNG, and anything else you export.
 
 ```ts
-// SVG export
-const svg = renderer.exportSvg();
-const svgCentered = renderer.exportSvg({ roomId: 1234, padding: 5 });
+import {
+  compose, identityStyle,
+  Parchment, Blueprint, Neon, Sketchy, Isometric,
+} from 'mudlet-map-renderer';
+
+// Single style
+renderer.setStyle(Parchment);
+
+// Compose a chain (left → right = inner → outer)
+renderer.setStyle(compose(
+  Parchment,
+  Sketchy({ jitter: 0.012, color: '#4a3728' }),
+  Isometric({ rotation: 30, depth: 0.18 }),
+));
+
+// Clear the current style
+renderer.setStyle(identityStyle);
+// or
+renderer.clearStyle();
+```
+
+Built-in styles:
+
+| Style | Effect |
+|---|---|
+| `Parchment` | Warm sepia / aged-paper palette |
+| `Blueprint` | White lines on deep blue |
+| `Neon` | Glowing neon outlines on dark background |
+| `Sketchy({ jitter, color })` | Hand-drawn pencil wobble |
+| `Isometric({ rotation?, depth? })` | 2:1 iso projection with optional cubes |
+
+Custom styles extend `BaseStyle<Inner>` and override only the draw calls they
+transform — see the built-ins for examples.
+
+### Export
 
-// SVG with explicit overlays
-const svgWithOverlays = renderer.exportSvg({
+Exporters are plug-ins: a new output format is a new `Exporter<T>` class,
+not a new `MapRenderer` method.
+
+```ts
+import {
+  SvgExporter, PngExporter, PngBlobExporter, CanvasExporter,
+} from 'mudlet-map-renderer';
+
+// SVG (string)
+const svg         = renderer.export(new SvgExporter());
+const svgCentered = renderer.export(new SvgExporter({ roomId: 1234, padding: 5 }));
+const svgTyped    = renderer.export(new SvgExporter({
   overlays: {
     position: { roomId: 1234 },
     highlights: [{ roomId: 100, color: '#ff0000' }],
     paths: [{ locations: [101, 102, 103], color: '#00ff00' }],
   },
-});
+}));
 
-// PNG export (data URL)
-const pngDataUrl = renderer.exportPng({ pixelRatio: 2 });
+// PNG data URL
+const pngUrl = renderer.export(new PngExporter({ pixelRatio: 2 }));
 
-// PNG export (Blob)
-const blob = await renderer.exportPngBlob({ pixelRatio: 2 });
+// PNG as Blob
+const blob = await renderer.export(new PngBlobExporter({ pixelRatio: 2 }));
 
-// Canvas export (specific region)
-const canvas = renderer.renderToCanvas({
+// Headless PNG bytes at a specific size (portable — works in browser + Node)
+const png = renderer.export(new PngBytesExporter({
   width: 1920,
   height: 1080,
   roomId: 1234,
   padding: 5,
-});
+}));
+// fs.writeFileSync('out.png', png!);            // Node
+// new Blob([png!], { type: 'image/png' });      // Browser
+
+// Canvas handle (if you need to draw more on it, attach to DOM, etc.)
+const canvas = renderer.export(new CanvasExporter({
+  width: 1920,
+  height: 1080,
+}));
 ```
 
+Style + export compose: the style currently applied with `setStyle` is passed
+to every exporter, so the SVG, the PNG, and the on-screen canvas stay in sync.
+
+Writing a new exporter — e.g. PDF — means shipping a class that implements
+`Exporter<Uint8Array>`. No changes to `MapRenderer`.
+
 ### Headless rendering (no DOM)
 
 For server-side or offscreen rendering, omit the container argument:
@@ -225,10 +285,45 @@ For server-side or offscreen rendering, omit the container argument:
 const renderer = new MapRenderer(mapReader, createSettings());
 
 renderer.drawArea(42, 0);
-renderer.setPosition(1234);
+renderer.state.positionRoomId = 1234;  // mark player position without auto-centering
 
-const svg = renderer.exportSvg({ padding: 5 });
-const canvas = renderer.renderToCanvas({ width: 1920, height: 1080 });
+const svg = renderer.export(new SvgExporter({ padding: 5 }));
+const png = renderer.export(new PngBytesExporter({ width: 1920, height: 1080 }));
+```
+
+### Overlays
+
+Two kinds, picked by what you need:
+
+- **`SceneOverlay`** — target-agnostic, appears in every output (interactive
+  canvas + every exporter). Use for static scene content (badges, annotations).
+- **`LiveEffect`** — interactive canvas only, receives a Konva layer and
+  viewport updates for animation. Skipped by exporters.
+
+```ts
+import type { SceneOverlay, LiveEffect } from 'mudlet-map-renderer';
+
+// Scene overlay — uses target-agnostic draw primitives
+class BadgeOverlay implements SceneOverlay {
+  render(target, state, bounds) {
+    const g = target.createGroup(0, 0);
+    target.addCircle(g, { cx: 5, cy: 5, radius: 0.4, fill: '#ff0' });
+    return g;
+  }
+}
+
+renderer.addSceneOverlay('badge', new BadgeOverlay());
+renderer.removeSceneOverlay('badge');
+
+// Live effect — gets a Konva layer, interactive only
+class Pulse implements LiveEffect {
+  attach(layer) { /* add Konva shapes */ }
+  updateViewport(bounds, scale) { /* react to pan/zoom */ }
+  destroy() { /* cleanup */ }
+}
+
+renderer.addLiveEffect('pulse', new Pulse());
+renderer.removeLiveEffect('pulse');
 ```
 
 ### Cleanup
@@ -360,16 +455,41 @@ MudletMapReader.exportJson(map, 'map.json');
 | `setZoom(zoom)` | Set zoom level |
 | `zoomToCenter(zoom)` | Zoom keeping center fixed |
 | `fitArea()` | Fit the full area in view |
-| `exportSvg(options?)` | Export as SVG string |
-| `exportPng(options?)` | Export as PNG data URL |
-| `exportPngBlob(options?)` | Export as PNG Blob |
-| `renderToCanvas(options)` | Export a region to canvas |
+| `setStyle(style)` | Apply a visual style (interactive + exporters) |
+| `clearStyle()` | Remove the current style |
+| `export(exporter)` | Run an `Exporter<T>` and return its output |
+| `addSceneOverlay(id, overlay)` | Add a target-agnostic overlay |
+| `removeSceneOverlay(id)` | Remove a scene overlay |
+| `addLiveEffect(id, effect)` | Add an interactive-only animated effect |
+| `removeLiveEffect(id)` | Remove a live effect |
 | `refresh()` | Force a full re-render |
 | `on(event, handler)` | Subscribe to an event |
 | `off(event, handler)` | Unsubscribe from an event |
 | `setCullingMode(mode)` | Set culling strategy |
 | `destroy()` | Release all resources |
 
+### Exporters
+
+| Exporter | Output |
+|---|---|
+| `SvgExporter({ roomId?, padding?, overlays? })` | `string` — SVG document |
+| `PngExporter({ pixelRatio? })` | `string` — PNG data URL (current viewport) |
+| `PngBlobExporter({ pixelRatio? })` | `Promise<Blob>` — PNG Blob (browser only) |
+| `PngBytesExporter({ width, height, roomId?, padding?, overlays?, mimeType?, quality? })` | `Uint8Array` — headless PNG/JPEG bytes; portable (browser + Node) |
+| `CanvasExporter({ width, height, roomId?, padding?, overlays? })` | `ExportCanvas` — canvas handle; reframes to fit |
+
+### Styles
+
+| Style | Constructor / Usage |
+|---|---|
+| `Parchment` | `setStyle(Parchment)` |
+| `Blueprint` | `setStyle(Blueprint)` |
+| `Neon` | `setStyle(Neon)` |
+| `Sketchy(opts)` | `setStyle(Sketchy({ jitter, color }))` |
+| `Isometric(opts)` | `setStyle(Isometric({ rotation?, depth? }))` |
+| `compose(...)` | Chain multiple styles into one |
+| `identityStyle` | Pass-through; equivalent to `clearStyle()` |
+
 ### `PathFinder`
 
 | Method | Description |

package/dist/ExitRenderer.d.ts

@@ -36,6 +36,18 @@ export type ExitDrawData = {
     };
     /** Set when this exit leads to a room in a different area (cross-area exit). */
     targetRoomId?: number;
+    /** Source room center in map coords — used to compute label direction. */
+    from?: {
+        x: number;
+        y: number;
+    };
+    /** Arrow tip / far endpoint in map coords — anchor for placed labels. */
+    tip?: {
+        x: number;
+        y: number;
+    };
+    /** Stroke colour of the rendered arrow — used to colour area-exit labels. */
+    arrowColor?: string;
 };
 export default class ExitRenderer {
     private mapReader;
@@ -53,6 +65,29 @@ export default class ExitRenderer {
     /**
      * Returns hit-zone bounds for special exits (custom lines) that lead to rooms in another area.
      */
+    /**
+     * Hit zones for cross-area inner exits (up/down/in/out). These are drawn as
+     * triangles inside the room, not through the exit pipeline, so they need
+     * their own plumbing for area-exit labelling and clickability.
+     */
+    getInnerExitAreaTargets(room: MapData.Room): {
+        bounds: {
+            x: number;
+            y: number;
+            width: number;
+            height: number;
+        };
+        targetRoomId: number;
+        from: {
+            x: number;
+            y: number;
+        };
+        tip: {
+            x: number;
+            y: number;
+        };
+        arrowColor: string;
+    }[];
     getSpecialExitAreaTargets(room: MapData.Room): {
         bounds: {
             x: number;
@@ -61,5 +96,14 @@ export default class ExitRenderer {
             height: number;
         };
         targetRoomId: number;
+        from: {
+            x: number;
+            y: number;
+        };
+        tip: {
+            x: number;
+            y: number;
+        };
+        arrowColor: string;
     }[];
 }

package/dist/ScenePipeline.d.ts

@@ -24,6 +24,18 @@ export type StandaloneExitEntry = {
 export type AreaExitHitZone = {
     bounds: Bounds;
     targetRoomId: number;
+    /** Source room center — used to compute arrow direction for labels. Optional for back-compat. */
+    from?: {
+        x: number;
+        y: number;
+    };
+    /** Arrow tip / far endpoint — anchor for placed labels. Optional for back-compat. */
+    tip?: {
+        x: number;
+        y: number;
+    };
+    /** Stroke colour of the rendered arrow — used to colour area-exit labels. */
+    arrowColor?: string;
 };
 export type SceneBuildResult = {
     roomNodes: Map<number, RoomNodeEntry>;
@@ -34,8 +46,8 @@ export type SceneBuildResult = {
  * Backend-agnostic scene composition pipeline.
  * Drives a DrawingBackend + LayerNode to render the full map scene.
  *
- * Both KonvaRenderBackend and SvgRenderBackend use this same pipeline
- * with their respective DrawingBackend implementations.
+ * Both the interactive KonvaRenderBackend and exporters (SvgExporter,
+ * CanvasExporter, …) drive this pipeline with their respective DrawingBackend.
  */
 export declare class ScenePipeline {
     private readonly mapReader;
@@ -70,6 +82,7 @@ export declare class ScenePipeline {
     renderExitData(data: ExitDrawData): GroupNode;
     private renderArrow;
     private renderLabels;
+    private renderAreaExitLabels;
     private renderAreaName;
 }
 export {};

package/dist/Viewport.d.ts

@@ -52,6 +52,18 @@ export declare class Viewport {
      * Center on a map coordinate, with optional animation.
      */
     panToMapPointAnimated(x: number, y: number, instant: boolean): void;
+    /**
+     * Compute the zoom level that would fit the given map bounds in the current
+     * viewport (with the same padding/insets as {@link fitToMapBounds}). Useful
+     * for updating `minZoom` to lock zoom-out to an area without changing the
+     * current zoom or position.
+     */
+    computeFitZoom(minX: number, maxX: number, minY: number, maxY: number, insets?: {
+        top?: number;
+        right?: number;
+        bottom?: number;
+        left?: number;
+    }): number;
     /**
      * Fit the viewport to show the given map bounds with padding.
      * Optional `insets` (screen pixels) reserve space at each edge — content

package/dist/backend/DrawingBackend.d.ts

@@ -1,9 +1,12 @@
 /**
- * Abstract interface for creating visual nodes.
- * Implement this to swap the rendering engine (Konva, PixiJS, raw Canvas2D, etc.).
+ * Low-level drawing primitives. A {@link DrawingBackend} is a thin abstraction
+ * over per-node draw calls. Leaf implementations target a specific rendering
+ * engine (Konva, raw Canvas2D, SVG strings, …); decorator implementations
+ * ({@link BaseStyle}) wrap another backend and transform the calls.
  *
- * GroupNode is the opaque handle returned by createGroup(). The culling system
- * and renderer use it for visibility toggling, positioning, and cleanup.
+ * End users should rarely touch this directly — prefer {@link Style} factories
+ * (Parchment, Sketchy(…), …) with {@link MapRenderer.setStyle}, and
+ * {@link Exporter} implementations with {@link MapRenderer.export}.
  */
 export interface GroupNode {
     setVisible(visible: boolean): void;
@@ -119,11 +122,51 @@ export interface DrawingBackend {
     };
     /**
      * Map-space → render-space transform. Identity for flat backends; non-identity
-     * for backends that warp coordinates (e.g. {@link IsometricBackend}).
+     * for styles that warp coordinates (e.g. `IsometricStyle`).
      * Decorators delegate to their inner backend.
-     * MapRenderer auto-applies this to culling and grid rendering when the backend is set.
      */
     getTransform(): CoordFn;
     /** Inverse of {@link getTransform}. */
     getInverseTransform(): CoordFn;
 }
+/**
+ * Abstract base for style (decorator) backends. Forwards every
+ * {@link DrawingBackend} method to `this.inner` by default; subclasses override
+ * only the methods they transform. Generic over the wrapped inner type so
+ * tooling preserves specific types through chains where useful.
+ */
+export declare abstract class BaseStyle<Inner extends DrawingBackend = DrawingBackend> implements DrawingBackend {
+    protected readonly inner: Inner;
+    constructor(inner: Inner);
+    createGroup(x: number, y: number): GroupNode;
+    addRect(parent: GroupNode, config: RectConfig): void;
+    addCircle(parent: GroupNode, config: CircleConfig): void;
+    addLine(parent: GroupNode, config: LineConfig): void;
+    addPolygon(parent: GroupNode, config: PolygonConfig): void;
+    addText(parent: GroupNode, config: TextConfig): void;
+    addImage(parent: GroupNode, config: ImageConfig): void;
+    supportsBatchExitRendering(): boolean;
+    getExitDepthOffset(): {
+        x: number;
+        y: number;
+    };
+    getTransform(): CoordFn;
+    getInverseTransform(): CoordFn;
+}
+/**
+ * A {@link Style} is a target-agnostic transformer: given a {@link DrawingBackend}
+ * it returns a decorated one. The same style drives interactive canvas, SVG
+ * export, and any future target.
+ *
+ * Compose via {@link compose}; built-in styles live in `src/style`.
+ */
+export type Style = (target: DrawingBackend) => DrawingBackend;
+/** Identity style — passes the target through unchanged. Useful as a default. */
+export declare const identityStyle: Style;
+/**
+ * Compose a chain of {@link Style}s into a single Style.
+ *
+ * `compose(Parchment, Sketchy)` wraps with Parchment first, then Sketchy —
+ * Sketchy is the outermost decorator, i.e. its methods run first during rendering.
+ */
+export declare function compose(...styles: Style[]): Style;

package/dist/export/CanvasExporter.d.ts

@@ -0,0 +1,67 @@
+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,
+ * reframing the viewport to fit the area (or a specific room) with padding.
+ *
+ * The returned {@link ExportCanvas} is the node-canvas-compatible object
+ * produced by Konva. Serialize with `.toBuffer('image/png')` in Node or
+ * `.toDataURL('image/png')` / `.toBlob(cb)` in the browser.
+ *
+ * Unlike {@link PngExporter} (which rasterizes the current on-screen viewport),
+ * `CanvasExporter` is the headless/programmatic path.
+ */
+export declare class CanvasExporter implements Exporter<ExportCanvas | undefined> {
+    private readonly options;
+    constructor(options: CanvasExportOptions);
+    render({ backend }: 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;
+    constructor(options: PngBytesExportOptions);
+    render(context: ExportContext): Uint8Array | undefined;
+}

package/dist/export/Exporter.d.ts

@@ -0,0 +1,57 @@
+import { MapState } from '../MapState';
+import { Style } from '../backend/DrawingBackend';
+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 InteractiveBackend.toCanvas} and
+ * {@link CanvasExporter}. 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,15 @@
+import { SvgExportOptions } from '../SvgTypes';
+import { Exporter, ExportContext } from './Exporter';
+/**
+ * Renders the current scene as an SVG string through the shared
+ * {@link ScenePipeline}. The context's style is applied so styled exports
+ * match the on-screen canvas; {@link SceneOverlay}s from the context are
+ * rendered into the SVG alongside the scene. `LiveEffect`s are intentionally
+ * ignored by design.
+ */
+export declare class SvgExporter implements Exporter<string | undefined> {
+    private readonly options;
+    constructor(options?: SvgExportOptions);
+    render({ state, style, sceneOverlays }: ExportContext): string | undefined;
+    private renderBuiltInOverlays;
+}

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;