mudlet-map-renderer 1.0.0 → 1.1.0

package/dist/lens/ExplorationLens.d.ts

@@ -0,0 +1,29 @@
+import { RoomLens } from './RoomLens';
+/**
+ * Fog-of-war lens: rooms render only when their id is in the visited set.
+ *
+ * Default exit treatment is left to {@link RoomLens}'s built-in derivation
+ * (both visible → full, one visible → stub, neither → hidden), which produces
+ * the "explored frontier" look without any extra wiring.
+ *
+ * Mutations bump {@link getVersion} so a composing renderer can detect the
+ * change; the renderer still needs an explicit `refresh()` after mutation —
+ * the lens doesn't emit events.
+ */
+export declare class ExplorationLens implements RoomLens {
+    private readonly visited;
+    private version;
+    constructor(visited?: Iterable<number>);
+    isVisible(room: MapData.Room): boolean;
+    getVersion(): number;
+    hasVisited(roomId: number): boolean;
+    getVisitedRoomIds(): number[];
+    getVisitedCount(): number;
+    /** Returns true if the room was newly added. */
+    addVisited(roomId: number): boolean;
+    /** Returns the number of newly added rooms. */
+    addVisitedAll(roomIds: Iterable<number>): number;
+    /** Replace the visited set wholesale. */
+    setVisited(roomIds: Iterable<number>): void;
+    clear(): void;
+}

package/dist/lens/RoomLens.d.ts

@@ -0,0 +1,47 @@
+import { default as IExit } from '../reader/Exit';
+/**
+ * How the renderer should treat an exit whose endpoints are not both visible.
+ *
+ * - `"full"`   — draw the exit normally (both endpoints are visible, or the
+ *                lens overrides the default and wants the full line anyway).
+ * - `"stub"`   — draw only a short stub leaving the visible endpoint; the
+ *                far end isn't shown. This is the "explored frontier" look.
+ * - `"hidden"` — don't draw the exit at all.
+ *
+ * Cross-area exits (rooms in different `area` ids) are an orthogonal concept
+ * decided by raw room data, not by the lens. A lens that returns `"full"` for
+ * a cross-area exit still gets the cross-area arrow treatment.
+ */
+export type ExitTreatment = "full" | "stub" | "hidden";
+/**
+ * Visibility filter applied during scene build.
+ *
+ * `IArea` / `IPlane` / `IMapReader` are pure data — they return every room and
+ * every link exit the underlying map defines. The lens decides which of those
+ * actually paint, and (optionally) how partially-visible exits should be
+ * stubbed or hidden. Multiple concerns (exploration, guild scope, quest
+ * overlay, …) compose through {@link composeLenses}.
+ */
+export interface RoomLens {
+    isVisible(room: MapData.Room): boolean;
+    /**
+     * Decide how an exit between `a` and `b` should be drawn.
+     *
+     * Optional — when omitted, treatment is derived from endpoint visibility:
+     * both visible → `"full"`, one visible → `"stub"`, neither → `"hidden"`.
+     */
+    getExitTreatment?(exit: IExit, a: MapData.Room, b: MapData.Room): ExitTreatment;
+    /**
+     * Monotonically increasing version. The renderer caches the value from the
+     * last build and rebuilds when it changes. Mutations on a stateful lens
+     * (e.g. {@link ExplorationLens.addVisited}) bump this; callers that mutate
+     * the lens still call `renderer.refresh()` explicitly.
+     */
+    getVersion(): number;
+}
+export declare const ALL_VISIBLE: RoomLens;
+/**
+ * Default treatment when no lens supplies `getExitTreatment`: derive purely
+ * from endpoint visibility.
+ */
+export declare function defaultExitTreatment(lens: RoomLens, _exit: IExit, a: MapData.Room, b: MapData.Room): ExitTreatment;

package/dist/lens/composeLenses.d.ts

@@ -0,0 +1,31 @@
+import { RoomLens } from './RoomLens';
+/**
+ * How a composite lens reconciles disagreeing children when both expose
+ * `getExitTreatment`.
+ *
+ * - `"most-restrictive"` (default): `hidden` > `stub` > `full`. A single
+ *   child that says hide wins. Safe default for stacked visibility filters.
+ * - `"least-restrictive"`: `full` > `stub` > `hidden`. Useful when lenses are
+ *   additive scopes ("show guild rooms OR quest rooms").
+ * - `"first"`: the first child whose `getExitTreatment` returns non-undefined
+ *   decides. Lets the caller pick a dominant lens by ordering.
+ */
+export type ExitConflictStrategy = "most-restrictive" | "least-restrictive" | "first";
+export type ComposeOptions = {
+    /** Defaults to `"most-restrictive"`. */
+    exitStrategy?: ExitConflictStrategy;
+    /**
+     * AND (visibility must hold in every lens) vs OR (any lens may grant
+     * visibility). Defaults to `"and"` — restrictive intersection.
+     */
+    visibility?: "and" | "or";
+};
+/**
+ * Combine multiple lenses into one. Visibility uses AND by default (a room
+ * must pass every lens to render); exit treatment uses most-restrictive when
+ * children disagree. Both behaviours are configurable via {@link ComposeOptions}.
+ *
+ * Composing zero lenses returns a no-op equivalent to `ALL_VISIBLE`.
+ */
+export declare function composeLenses(...lenses: RoomLens[]): RoomLens;
+export declare function composeLenses(options: ComposeOptions, ...lenses: RoomLens[]): RoomLens;

package/dist/lens/index.d.ts

@@ -0,0 +1,5 @@
+export type { RoomLens, ExitTreatment } from './RoomLens';
+export { ALL_VISIBLE, defaultExitTreatment } from './RoomLens';
+export { composeLenses } from './composeLenses';
+export type { ComposeOptions, ExitConflictStrategy } from './composeLenses';
+export { ExplorationLens } from './ExplorationLens';

package/dist/overlay/AmbientLightOverlay.d.ts

@@ -0,0 +1,32 @@
+import { MapState } from '../MapState';
+import { ViewportBounds } from '../types/Settings';
+import { AmbientLightParams } from '../scene/AmbientLightStyle';
+import { Shape } from '../scene/Shape';
+import { SceneOverlay, SceneOverlayContext } from './SceneOverlay';
+export type AmbientLightOptions = Partial<AmbientLightParams>;
+/**
+ * Vignette centered on the player room. Re-renders on position changes and
+ * viewport changes (pan/zoom/resize). Registering the overlay turns the effect
+ * on; removing it turns it off — there is no global settings flag.
+ *
+ * ```ts
+ * const ambient = new AmbientLightOverlay({ color: '#ffcc44', radius: 12 });
+ * renderer.addSceneOverlay('ambient-light', ambient);
+ * // later:
+ * ambient.setOptions({ intensity: 0.9 });
+ * renderer.removeSceneOverlay('ambient-light');
+ * ```
+ */
+export declare class AmbientLightOverlay implements SceneOverlay {
+    private params;
+    private ctx?;
+    private viewportUnsub?;
+    private readonly onPosition;
+    constructor(options?: AmbientLightOptions);
+    /** Update tunables at runtime. Triggers a re-render. */
+    setOptions(options: AmbientLightOptions): void;
+    getOptions(): AmbientLightParams;
+    attach(ctx: SceneOverlayContext): void;
+    detach(): void;
+    render(state: MapState, bounds: ViewportBounds): Shape | void;
+}

package/dist/overlay/LiveEffect.d.ts

@@ -0,0 +1,33 @@
+import { default as Konva } from 'konva';
+import { ViewportBounds } from '../types/Settings';
+/** Map-space → render-space coordinate transform. */
+export type CoordinateTransform = (x: number, y: number) => {
+    x: number;
+    y: number;
+};
+/**
+ * Interactive-only animated effect. A {@link LiveEffect} receives a live Konva
+ * layer and viewport updates so it can react to pan/zoom and run its own
+ * animation loop.
+ *
+ * Exporters (SVG, PNG, PDF, …) skip `LiveEffect`s by design — use
+ * `SceneOverlay` when you need an overlay to appear in exports.
+ *
+ * ```ts
+ * class PulseEffect implements LiveEffect {
+ *     private shape?: Konva.Shape;
+ *     attach(layer: Konva.Layer) {
+ *         this.shape = new Konva.Shape({ sceneFunc: (ctx) => { ... } });
+ *         layer.add(this.shape);
+ *     }
+ *     updateViewport(bounds, scale) { ... }
+ *     destroy() { this.shape?.destroy(); }
+ * }
+ * renderer.konvaBackend?.addLiveEffect('pulse', new PulseEffect());
+ * ```
+ */
+export interface LiveEffect {
+    attach(layer: Konva.Layer): void;
+    updateViewport(bounds: ViewportBounds, scale: number, coordinateTransform: CoordinateTransform): void;
+    destroy(): void;
+}

package/dist/overlay/SceneOverlay.d.ts

@@ -0,0 +1,68 @@
+import { MapState } from '../MapState';
+import { ViewportBounds } from '../types/Settings';
+import { Shape } from '../scene/Shape';
+/**
+ * Context handed to a {@link SceneOverlay} when it is registered. Gives the
+ * overlay access to {@link MapState} events, viewport changes, and a way to
+ * request its own re-render.
+ */
+export interface SceneOverlayContext {
+    readonly state: MapState;
+    /**
+     * Subscribe to viewport changes (pan, zoom, resize). Returns an unsubscribe
+     * function — call it from {@link SceneOverlay.detach} to avoid leaks.
+     */
+    onViewportChange(cb: () => void): () => void;
+    /** Request a re-render of this overlay only. Cheap — no full scene rebuild. */
+    invalidate(): void;
+}
+/**
+ * Target-agnostic overlay. A {@link SceneOverlay} contributes static geometry
+ * to the scene by emitting one or more {@link Shape}s, so it renders in every
+ * output path: interactive canvas, SVG export, PNG export, and any future
+ * {@link Exporter}.
+ *
+ * Overlays may opt into reactivity via {@link attach}: subscribe to MapState or
+ * viewport events, then call `ctx.invalidate()` to re-render. Exporters skip
+ * `attach`/`detach` — they just call {@link render} once.
+ *
+ * ```ts
+ * class BadgeOverlay implements SceneOverlay {
+ *     render(state: MapState, bounds: ViewportBounds): Shape {
+ *         return {
+ *             type: 'circle',
+ *             cx: 5, cy: 5,
+ *             radius: 0.4,
+ *             paint: { fill: '#ff0' },
+ *             layer: 'overlay',
+ *         };
+ *     }
+ * }
+ *
+ * renderer.addSceneOverlay('badge', new BadgeOverlay());
+ * ```
+ */
+export interface SceneOverlay {
+    /**
+     * Optional. Called once when the overlay is registered with an interactive
+     * renderer. Subscribe to events here and call `ctx.invalidate()` when the
+     * overlay needs to re-render.
+     *
+     * Not called by exporters — they render statically via {@link render}.
+     */
+    attach?(ctx: SceneOverlayContext): void;
+    /**
+     * Optional. Called when the overlay is removed (or the renderer is
+     * destroyed). Unsubscribe from any events registered in {@link attach}.
+     */
+    detach?(): void;
+    /**
+     * Contribute geometry to the scene. Called on register, on invalidate, and
+     * by every exporter.
+     *
+     * @returns one or more world-space {@link Shape}s, or `void` to emit
+     *   nothing this frame. Shapes carry their own {@link Shape.layer} hint;
+     *   leaving it unset routes them to the overlay layer.
+     */
+    render(state: MapState, bounds: ViewportBounds): Shape | Shape[] | void;
+}

package/dist/reader/Area.d.ts

@@ -0,0 +1,63 @@
+import { default as Plane, IPlane } from './Plane';
+import { default as IExit } from './Exit';
+/**
+ * Public, renderer-facing surface of an area. The renderer never inspects
+ * private state of {@link Area}; it talks to this interface only. Custom data
+ * models (e.g. an app that owns its own room store) can satisfy `IArea` and
+ * hand the result to {@link MapRenderer} without subclassing.
+ *
+ * Mutability lives on the concrete implementation: {@link Area.markDirty} is
+ * `protected`, kept off the public interface. Consumers signal "redraw me" by
+ * bumping {@link getVersion}; the renderer reads the version to decide
+ * whether to rebuild.
+ */
+export interface IArea {
+    getAreaName(): string;
+    getAreaId(): number;
+    /**
+     * Monotonically increasing version. The renderer compares the value it
+     * cached on the last build against the current value to decide whether
+     * the area needs a rebuild.
+     */
+    getVersion(): number;
+    getPlane(zIndex: number): IPlane;
+    getPlanes(): IPlane[];
+    getZLevels(): number[];
+    getRooms(): MapData.Room[];
+    getFullBounds(): {
+        minX: number;
+        maxX: number;
+        minY: number;
+        maxY: number;
+    };
+    /**
+     * Inter-room exits drawn on the given z-level. Each exit is bidirectional
+     * with optional one-way fallback; see {@link IExit}.
+     */
+    getLinkExits(zIndex: number): IExit[];
+}
+export default class Area implements IArea {
+    private readonly planes;
+    private readonly area;
+    private readonly exits;
+    private version;
+    constructor(area: MapData.Area);
+    getAreaName(): string;
+    getAreaId(): number;
+    getVersion(): number;
+    protected markDirty(): void;
+    getPlane(zIndex: number): Plane;
+    getPlanes(): Plane[];
+    getZLevels(): number[];
+    getRooms(): MapData.Room[];
+    getFullBounds(): {
+        minX: number;
+        maxX: number;
+        minY: number;
+        maxY: number;
+    };
+    getLinkExits(zIndex: number): IExit[];
+    private createPlanes;
+    private static readonly oppositeDir;
+    private createExits;
+}

package/dist/reader/Exit.d.ts

@@ -0,0 +1,15 @@
+export type Kind = "exit" | "specialExit";
+export default interface IExit {
+    a: number;
+    b: number;
+    aDir?: MapData.direction;
+    bDir?: MapData.direction;
+    kind?: Kind;
+    zIndex: number[];
+}
+export type { IExit };
+/** @deprecated Use {@link IExit}. Retained as a structural alias for backwards compatibility. */
+export type Exit = IExit;
+export declare const regularExits: MapData.direction[];
+export declare const shortTolong: Record<string, MapData.direction>;
+export declare const longToShort: Record<MapData.direction, string>;

package/dist/reader/MapReader.d.ts

@@ -0,0 +1,34 @@
+import { default as Area, IArea } from './Area';
+/**
+ * Public, renderer-facing surface for map data. Everything the renderer
+ * (and other library consumers) call on `MapReader` is on this interface —
+ * private state and internal helpers are not.
+ *
+ * Downstream apps with their own room/area store can implement `IMapReader`
+ * directly (no need to subclass {@link MapReader}) and hand the result to
+ * {@link MapRenderer}. Visibility filtering (exploration, scope overlays,
+ * etc.) lives on the renderer's lens — it is intentionally not on this
+ * interface.
+ */
+export interface IMapReader {
+    getArea(areaId: number): IArea;
+    getAreas(): IArea[];
+    getRooms(): MapData.Room[];
+    getRoom(roomId: number): MapData.Room;
+    /** Returns the env's `rgb(r,g,b)` string, or a default colour if the env id is unknown. */
+    getColorValue(envId: number): string;
+    /** Returns a contrasting symbol colour for the env, optionally with the given alpha. */
+    getSymbolColor(envId: number, opacity?: number): string;
+}
+export default class MapReader implements IMapReader {
+    private rooms;
+    private areas;
+    private colors;
+    constructor(map: MapData.Map, envs: MapData.Env[]);
+    getArea(areaId: number): Area;
+    getAreas(): Area[];
+    getRooms(): MapData.Room[];
+    getRoom(roomId: number): MapData.Room;
+    getColorValue(envId: number): string;
+    getSymbolColor(envId: number, opacity?: number): string;
+}

package/dist/reader/Plane.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Public, renderer-facing surface of a z-level slice of an area.
+ *
+ * The renderer (and other library consumers) only depend on this interface;
+ * the concrete {@link Plane} class is one implementation of it. Downstream
+ * apps that want to drive the renderer from their own data model can hand it
+ * any `IPlane`-shaped object (typically returned from an {@link IArea}).
+ */
+export interface IPlane {
+    getRooms(): MapData.Room[];
+    getLabels(): MapData.Label[];
+    getBounds(): {
+        minX: number;
+        maxX: number;
+        minY: number;
+        maxY: number;
+    };
+}
+export default class Plane implements IPlane {
+    private readonly bounds;
+    private readonly rooms;
+    private readonly labels;
+    constructor(rooms: MapData.Room[], labels: MapData.Label[]);
+    getRooms(): MapData.Room[];
+    getLabels(): MapData.Label[];
+    getBounds(): {
+        minX: number;
+        maxX: number;
+        minY: number;
+        maxY: number;
+    };
+    private createBounds;
+}

package/dist/render/CanvasRenderer.d.ts

@@ -0,0 +1,17 @@
+import { DrawCommandBatch } from '../draw/DrawCommand';
+/**
+ * Image loader hook. Canvas2D's `drawImage` needs an `HTMLImageElement` (or
+ * compatible). Browsers create one via `new Image()`; Node-canvas provides
+ * its own `Image` constructor. The default tries both — callers can override
+ * for tests or unusual targets.
+ */
+export type ImageFactory = (src: string) => unknown;
+export interface CanvasRenderOptions {
+    imageFactory?: ImageFactory;
+}
+/**
+ * Replay every batch onto `ctx`, in order. Each batch's commands are flushed
+ * sequentially; transform / clip stacks are independent per batch so a stray
+ * push in one layer cannot leak into the next.
+ */
+export declare function renderToCanvas(ctx: CanvasRenderingContext2D, batches: DrawCommandBatch[], options?: CanvasRenderOptions): void;

package/dist/render/RecordingLayer.d.ts

@@ -0,0 +1,158 @@
+import { default as Konva } from 'konva';
+type RectCommand = {
+    type: 'rect';
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+    fill?: string;
+    stroke?: string;
+    sw: number;
+    cr: number;
+    dash?: number[];
+};
+type CircleCommand = {
+    type: 'circle';
+    cx: number;
+    cy: number;
+    r: number;
+    fill?: string;
+    stroke?: string;
+    sw: number;
+    dash?: number[];
+};
+type LineCommand = {
+    type: 'line';
+    points: number[];
+    stroke?: string;
+    sw: number;
+    dash?: number[];
+    lineCap?: string;
+    lineJoin?: string;
+    alpha?: number;
+};
+type PolygonCommand = {
+    type: 'polygon';
+    vertices: number[];
+    fill?: string;
+    stroke?: string;
+    sw: number;
+};
+type TextCommand = {
+    type: 'text';
+    x: number;
+    y: number;
+    text: string;
+    fontSize: number;
+    fontFamily: string;
+    fontStyle: string;
+    fill: string;
+    stroke?: string;
+    sw: number;
+    align: string;
+    vAlign: string;
+    w: number;
+    h: number;
+    baselineRatio?: number;
+    transform?: [number, number, number, number, number, number];
+};
+type ImageCommand = {
+    type: 'image';
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+    image: HTMLImageElement | any;
+    transform?: [number, number, number, number, number, number];
+};
+export type RecordingDrawCommand = RectCommand | CircleCommand | LineCommand | PolygonCommand | TextCommand | ImageCommand;
+/**
+ * One positional group of recorded draw commands. Used as both the unit a
+ * shape walker emits and the cull-tracking handle inside
+ * {@link DrawCommandLayerNode}. Lazily materializes into a `Konva.Group` /
+ * `Konva.Shape` pair when added directly to a Konva layer.
+ */
+export declare class RecordingGroupNode {
+    x: number;
+    y: number;
+    _visible: boolean;
+    noScaling: boolean;
+    readonly commands: RecordingDrawCommand[];
+    /** Lazily created when this group is materialized for a Konva.Layer. */
+    _konvaGroup?: Konva.Group;
+    constructor(x: number, y: number);
+    setVisible(visible: boolean): void;
+    isVisible(): boolean;
+    destroy(): void;
+    setPosition(x: number, y: number): void;
+    getPosition(): {
+        x: number;
+        y: number;
+    };
+    moveToTop(): void;
+    /**
+     * Materialize this recording as a Konva.Group + Konva.Shape. Used by
+     * {@link MaterializingLayerNode} for layers that want individual nodes
+     * (overlay, position) rather than a single bulk replay.
+     */
+    materialize(): Konva.Group;
+}
+/**
+ * Lightweight record extracted from a {@link RecordingGroupNode} when added
+ * to a {@link DrawCommandLayerNode}. Contains only plain data so culling
+ * callbacks can toggle visibility without a Konva node reference.
+ */
+export type DrawEntry = {
+    x: number;
+    y: number;
+    noScaling: boolean;
+    readonly commands: RecordingDrawCommand[];
+    visible: boolean;
+};
+/**
+ * LayerNode backed by a single Konva.Shape whose sceneFunc replays
+ * {@link DrawEntry} objects. Used for the main scene layer where individual
+ * shapes need cull toggling.
+ */
+export declare class DrawCommandLayerNode {
+    private readonly entries;
+    private readonly nodeToEntry;
+    private readonly konvaLayer;
+    private konvaShape;
+    constructor(konvaLayer: Konva.Layer);
+    addNode(node: RecordingGroupNode): void;
+    /** Return the DrawEntry created when `node` was added, or undefined if not found. */
+    getEntry(node: RecordingGroupNode): DrawEntry | undefined;
+    destroyChildren(): void;
+    batchDraw(): void;
+    private ensureShape;
+}
+/**
+ * Layer backed by a single Konva.Shape whose sceneFunc replays every added
+ * {@link RecordingGroupNode} in order. Used for layers that don't need
+ * per-shape cull toggling (grid, top-label).
+ */
+export declare class RecordingLayerNode {
+    private groups;
+    private readonly konvaLayer;
+    private konvaShape;
+    constructor(konvaLayer: Konva.Layer);
+    addNode(node: RecordingGroupNode): void;
+    destroyChildren(): void;
+    batchDraw(): void;
+    private ensureShape;
+}
+/**
+ * Layer that materializes each added {@link RecordingGroupNode} as its own
+ * `Konva.Group`. Used for layers where the renderer keeps a reference to
+ * each node (overlay highlights, position marker) so it can destroy them
+ * individually.
+ */
+export declare class MaterializingLayerNode {
+    private readonly konvaLayer;
+    constructor(konvaLayer: Konva.Layer);
+    addNode(node: RecordingGroupNode): void;
+    destroyChildren(): void;
+    batchDraw(): void;
+}
+export {};

package/dist/render/SvgRenderer.d.ts

@@ -0,0 +1,7 @@
+import { DrawCommandBatch } from '../draw/DrawCommand';
+/**
+ * Convert one or more {@link DrawCommandBatch}es into SVG element strings, in
+ * the order they appear. Caller wraps the result in `<svg viewBox=…>` /
+ * `</svg>` and inserts a background rect.
+ */
+export declare function svgFromBatches(batches: DrawCommandBatch[]): string[];

package/dist/render/shapeToRecording.d.ts

@@ -0,0 +1,3 @@
+import { RecordingGroupNode } from './RecordingLayer';
+import { GroupShape } from '../scene/Shape';
+export declare function shapeToRecording(group: GroupShape): RecordingGroupNode;