mudlet-map-renderer 0.43.0-konva → 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/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

@@ -1,35 +1,6 @@
 import { MapState } from '../MapState';
 import { ViewportBounds } from '../types/Settings';
 import { Shape } from '../scene/Shape';
-/**
- * State passed to {@link SceneOverlay.draw} on every repaint. Contains
- * everything needed to draw in world-space or screen-space without holding
- * any Konva references.
- */
-export interface CanvasDrawState {
-    /** Current viewport in world coordinates. */
-    bounds: ViewportBounds;
-    /** Current zoom scale (world units → canvas pixels). */
-    scale: number;
-    /** World → scene coordinate transform (identity for flat styles, isometric for IsometricBackend). */
-    coordinateTransform: (x: number, y: number) => {
-        x: number;
-        y: number;
-    };
-    /** Canvas element width in CSS pixels. */
-    canvasWidth: number;
-    /** Canvas element height in CSS pixels. */
-    canvasHeight: number;
-    /**
-     * Stage offset in CSS pixels. Together with `scale` this lets you convert
-     * a world point to screen coordinates:
-     *   screenX = worldX * scale + canvasOffset.x
-     */
-    canvasOffset: {
-        x: number;
-        y: number;
-    };
-}
 /**
  * Context handed to a {@link SceneOverlay} when it is registered. Gives the
  * overlay access to {@link MapState} events, viewport changes, and a way to
@@ -44,60 +15,31 @@ export interface SceneOverlayContext {
     onViewportChange(cb: () => void): () => void;
     /** Request a re-render of this overlay only. Cheap — no full scene rebuild. */
     invalidate(): void;
-    /**
-     * Register a per-frame callback driven by the backend's animation loop.
-     * `dt` is elapsed seconds since the last frame (capped at 0.1 s).
-     * The backend repaints the overlay layer after all registered callbacks
-     * fire each frame.
-     *
-     * Returns an unsubscribe function — call it from {@link SceneOverlay.detach}.
-     */
-    onFrame(cb: (dt: number) => void): () => void;
 }
 /**
- * Target-agnostic overlay. A {@link SceneOverlay} contributes geometry or
- * direct canvas drawing to the scene. Two rendering modes are available and
- * may be combined:
- *
- * - **{@link render}** — emits {@link Shape} descriptors. Shapes are converted to
- *   recording nodes and appear in every output path: interactive canvas, SVG
- *   export, PNG export, and any future {@link Exporter}.
+ * 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}.
  *
- * - **{@link draw}** — receives a raw `CanvasRenderingContext2D` and a
- *   {@link CanvasDrawState}. Used for effects that require gradients, compositing,
- *   or particle systems — anything that can't be expressed as a Shape. Exporters
- *   skip `draw()` overlays (same behaviour as the former `LiveEffect`).
- *
- * Overlays opt into reactivity via {@link attach}: subscribe to MapState or
- * viewport events, use {@link SceneOverlayContext.onFrame} for animation, then
- * call `ctx.invalidate()` for data-driven repaints.
+ * 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
- * // Shape-based (appears in exports)
  * class BadgeOverlay implements SceneOverlay {
- *     render(state, bounds) {
- *         return { type: 'circle', cx: 5, cy: 5, radius: 0.4, paint: { fill: '#ff0' } };
- *     }
- * }
- *
- * // Canvas-based with animation (interactive only)
- * class PulseOverlay implements SceneOverlay {
- *     private t = 0;
- *     attach(ctx) {
- *         this.unsub = ctx.onFrame((dt) => { this.t += dt; });
- *     }
- *     detach() { this.unsub?.(); }
- *     draw(ctx, state) {
- *         const alpha = 0.5 + 0.5 * Math.sin(this.t * 3);
- *         ctx.save(); ctx.setTransform(1, 0, 0, 1, 0, 0);
- *         ctx.globalAlpha = alpha;
- *         // ...
- *         ctx.restore();
+ *     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());
- * renderer.addSceneOverlay('pulse', new PulseOverlay());
  * ```
  */
 export interface SceneOverlay {
@@ -115,25 +57,12 @@ export interface SceneOverlay {
      */
     detach?(): void;
     /**
-     * Contribute {@link Shape} geometry to the scene. Called on register, on
-     * invalidate, and by every exporter.
+     * 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;
-    /**
-     * Draw directly onto the canvas using the provided `CanvasRenderingContext2D`.
-     * Called on every repaint of the overlay layer (including every animation
-     * frame when {@link SceneOverlayContext.onFrame} is in use).
-     *
-     * The context already has the stage transform applied (world-space drawing
-     * works at face value). Reset with `ctx.setTransform(1,0,0,1,0,0)` to
-     * draw in screen space.
-     *
-     * Exporters skip `draw()` overlays — use {@link render} for geometry that
-     * must appear in SVG/PNG exports.
-     */
-    draw?(ctx: CanvasRenderingContext2D, state: CanvasDrawState): void;
+    render(state: MapState, bounds: ViewportBounds): Shape | Shape[] | void;
 }

package/dist/reader/Area.d.ts

@@ -1,6 +1,42 @@
-import { default as Plane } from './Plane';
-import { default as Exit } from './Exit';
-export default class Area {
+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;
@@ -20,7 +56,7 @@ export default class Area {
         minY: number;
         maxY: number;
     };
-    getLinkExits(zIndex: number): Exit[];
+    getLinkExits(zIndex: number): IExit[];
     private createPlanes;
     private static readonly oppositeDir;
     private createExits;

package/dist/reader/Exit.d.ts

@@ -1,5 +1,5 @@
 export type Kind = "exit" | "specialExit";
-export default interface Exit {
+export default interface IExit {
     a: number;
     b: number;
     aDir?: MapData.direction;
@@ -7,6 +7,9 @@ export default interface Exit {
     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

@@ -1,28 +1,34 @@
-import { default as Area } from './Area';
-import { default as ExplorationArea } from './ExplorationArea';
-export default class MapReader {
+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 areaSources;
-    private visitedRooms?;
-    private explorationEnabled;
     private colors;
     constructor(map: MapData.Map, envs: MapData.Env[]);
     getArea(areaId: number): Area;
-    getExplorationArea(areaId: number): ExplorationArea | undefined;
     getAreas(): Area[];
     getRooms(): MapData.Room[];
     getRoom(roomId: number): MapData.Room;
-    private ensureVisitedRooms;
-    private applyExplorationDecoration;
-    decorateWithExploration(visitedRooms?: Iterable<number> | Set<number>): Set<number> | undefined;
-    getVisitedRooms(): Set<number> | undefined;
-    clearExplorationDecoration(): void;
-    isExplorationEnabled(): boolean;
-    setVisitedRooms(visitedRooms: Iterable<number> | Set<number>): Set<number>;
-    addVisitedRoom(roomId: number): boolean;
-    addVisitedRooms(roomIds: Iterable<number>): number;
-    hasVisitedRoom(roomId: number): boolean;
     getColorValue(envId: number): string;
     getSymbolColor(envId: number, opacity?: number): string;
 }

package/dist/reader/Plane.d.ts

@@ -1,4 +1,22 @@
-export default class Plane {
+/**
+ * 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;

package/dist/rendering/KonvaRenderBackend.d.ts

@@ -7,6 +7,7 @@ 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';
@@ -61,14 +62,10 @@ export declare class KonvaRenderBackend implements InteractiveBackend {
     private _coordinateTransform;
     private coordinateInverse;
     get coordinateTransform(): CoordFn;
+    private liveEffects;
     private sceneOverlays;
     private sceneOverlayNodes;
-    private drawOverlayShapes;
     private viewportSubscribers;
-    private frameCallbacks;
-    private rafHandle;
-    private lastFrameTime;
-    private frameSeq;
     constructor(state: MapState, container?: HTMLDivElement);
     setStyle(style: Style): void;
     /** Pull forward/inverse coord transforms from the active shape Style. */
@@ -86,14 +83,13 @@ export declare class KonvaRenderBackend implements InteractiveBackend {
     }): 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 startFrameLoop;
-    private stopFrameLoop;
-    private getCanvasDrawState;
     private renderSceneOverlay;
     private clearSceneOverlayNodes;
     private subscribeToState;

package/dist/rendering/MapRenderer.d.ts

@@ -1,5 +1,6 @@
-import { default as MapReader } from '../reader/MapReader';
-import { default as Area } from '../reader/Area';
+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';
@@ -8,6 +9,7 @@ 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';
@@ -16,7 +18,7 @@ import { HitTester, HitResult } from '../hit/HitTester';
  *
  * 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. Users who
+ * not on this interface and lives only on the concrete backend.
  */
 export interface InteractiveBackend {
     readonly camera: Camera;
@@ -66,8 +68,8 @@ export interface InteractiveBackend {
  *   (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.
- *   Overlays may implement `draw()` for direct canvas access (animated particles,
- *   compositing effects) or `render()` for Shape-based geometry that appears in exports.
+ * - **{@link addLiveEffect}** registers interactive-only animated effects (Konva
+ *   canvas only; skipped by exporters).
  */
 export declare class MapRenderer {
     readonly state: MapState;
@@ -89,10 +91,10 @@ export declare class MapRenderer {
      * @param backendFactory  Optional factory that receives the `MapState` and returns
      *   a custom `InteractiveBackend`. When omitted, a `KonvaRenderBackend` is created.
      */
-    constructor(mapReader: MapReader, settings?: Settings, container?: HTMLDivElement, backendFactory?: (state: MapState) => InteractiveBackend);
+    constructor(mapReader: IMapReader, settings?: Settings, container?: HTMLDivElement, backendFactory?: (state: MapState) => InteractiveBackend);
     destroy(): void;
     drawArea(id: number, zIndex: number): void;
-    getCurrentArea(): Area | undefined;
+    getCurrentArea(): IArea | undefined;
     setPosition(roomId: number, center?: boolean): void;
     updatePositionMarker(roomId: number): void;
     clearPosition(): void;
@@ -104,6 +106,17 @@ export declare class MapRenderer {
     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
@@ -126,6 +139,17 @@ export declare class MapRenderer {
     /** 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.
      *

package/dist/rendering/SceneManager.d.ts

@@ -1,11 +1,12 @@
-import { default as Area } from '../reader/Area';
-import { default as Plane } from '../reader/Plane';
+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 { default as MapReader } from '../reader/MapReader';
+import { IMapReader } from '../reader/MapReader';
+import { RoomLens } from '../lens/RoomLens';
 import { ExitDrawData } from '../ExitRenderer';
 export interface CullStats {
     visibleRooms: number;
@@ -30,7 +31,7 @@ export declare class SceneManager {
     private pipeline;
     private lastBuildResult?;
     private standaloneExitShapeSet;
-    constructor(camera: Camera, settings: Settings, mapReader: MapReader);
+    constructor(camera: Camera, settings: Settings, mapReader: IMapReader);
     get exitRenderer(): import('../ExitRenderer').default;
     get lastResult(): SceneBuildResult | undefined;
     get drawnExits(): readonly DrawnExitEntry[];
@@ -38,10 +39,10 @@ export declare class SceneManager {
     get drawnStubs(): readonly DrawnStubEntry[];
     get areaExitHitZones(): readonly AreaExitHitZone[];
     get hitShapes(): readonly Shape[];
-    rebuild(area: Area, plane: Plane, zIndex: number): SceneBuildResult;
+    rebuild(area: IArea, plane: IPlane, zIndex: number, lens?: RoomLens): SceneBuildResult;
     buildExitShape(data: ExitDrawData): GroupShape;
     reset(): void;
-    resetPipeline(mapReader: MapReader): void;
+    resetPipeline(mapReader: IMapReader): void;
     /**
      * Lightweight cull for the interactive render path.  Returns a
      * `Map<Shape, boolean>` where absent shapes are unmanaged pass-throughs

package/dist/scene/InnerExitStyle.d.ts

@@ -1,5 +1,5 @@
 import { Settings } from '../types/Settings';
-import { default as MapReader } from '../reader/MapReader';
+import { IMapReader } from '../reader/MapReader';
 export type TriangleData = {
     cx: number;
     cy: number;
@@ -17,7 +17,7 @@ declare function computeTriangleVertices(cx: number, cy: number, radius: 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: MapReader, settings: Settings): InnerExitData;
+export declare function computeInnerExits(room: MapData.Room, mapReader: IMapReader, settings: Settings): InnerExitData;
 /**
  * Compute triangle vertices for a standalone triangle (used by path overlay markers).
  */

package/dist/scene/OverlayStyle.d.ts

@@ -1,5 +1,5 @@
 import { Settings } from '../types/Settings';
-import { default as MapReader } from '../reader/MapReader';
+import { IMapReader } from '../reader/MapReader';
 export type HighlightData = {
     shape: 'circle' | 'rect';
     cx: number;
@@ -7,9 +7,13 @@ export type HighlightData = {
     /** For circle: radius. For rect: half-size. */
     size: number;
     cornerRadius: number;
-    stroke: string;
+    strokeColor: string;
+    strokeAlpha: number;
     strokeWidth: number;
-    dash: number[];
+    fillColor: string;
+    fillAlpha: number;
+    dash?: number[];
+    dashEnabled: boolean;
 };
 export declare function computeHighlight(room: MapData.Room, color: string, settings: Settings): HighlightData;
 export type PositionMarkerData = {
@@ -40,4 +44,4 @@ export type PathOverlayData = {
     outlineWidth: number;
     lineWidth: number;
 };
-export declare function computePathOverlay(mapReader: MapReader, settings: Settings, locations: number[], color: string, areaId: number, zIndex: number): PathOverlayData;
+export declare function computePathOverlay(mapReader: IMapReader, settings: Settings, locations: number[], color: string, areaId: number, zIndex: number): PathOverlayData;