mudlet-map-renderer 2.0.0 → 2.2.0

package/dist/rendering/offscreen/OffscreenCanvasBackend.d.ts

@@ -0,0 +1,109 @@
+import { InteractiveBackend } from '../MapRenderer';
+import { MapState } from '../../MapState';
+import { RendererEventMap } from '../../types/Settings';
+import { Camera } from '../../camera/Camera';
+import { CullingManager } from '../../CullingManager';
+import { HitTester } from '../../hit/HitTester';
+import { TypedEventEmitter } from '../../TypedEventEmitter';
+import { DrawnExitEntry, DrawnSpecialExitEntry, DrawnStubEntry } from '../../ScenePipeline';
+import { Style } from '../../style/Style';
+import { CoordFn } from '../../coord/CoordFn';
+import { SceneOverlay } from '../../overlay/SceneOverlay';
+import { LiveEffect } from '../../overlay/LiveEffect';
+import { ExportCanvas } from '../../export/Exporter';
+import { MainToWorkerMessage, WorkerToMainMessage } from './protocol';
+/** Transport the backend talks to. A real `Worker` satisfies this directly. */
+export interface WorkerTransport {
+    postMessage(message: MainToWorkerMessage, transfer?: Transferable[]): void;
+    addEventListener?(type: "message", handler: (ev: {
+        data: WorkerToMainMessage;
+    }) => void): void;
+    onmessage?: ((ev: {
+        data: WorkerToMainMessage;
+    }) => void) | null;
+    terminate?(): void;
+}
+export interface OffscreenBackendOptions {
+    /** Pre-created transport (used by the inline-worker factory and by tests). */
+    transport?: WorkerTransport;
+    /** Lazily create the transport. Ignored when {@link transport} is provided. */
+    createTransport?: () => WorkerTransport;
+    /** Override the device pixel ratio (tests / forcing 1x). */
+    devicePixelRatio?: number;
+}
+export declare class OffscreenCanvasBackend implements InteractiveBackend {
+    readonly camera: Camera;
+    readonly culling: CullingManager;
+    readonly events: TypedEventEmitter<RendererEventMap>;
+    readonly hitTester: HitTester;
+    private readonly state;
+    private readonly container?;
+    private readonly transport?;
+    private readonly pipeline;
+    private readonly dpr;
+    private currentStyle;
+    private _coordinateTransform;
+    private coordinateInverse;
+    private coordinateLayerOffset;
+    private lastResult?;
+    private lastHitShapes;
+    private boundsByShape;
+    private interactionHandler?;
+    private cameraChangeHandler?;
+    private readonly sceneOverlays;
+    private readonly viewportSubscribers;
+    private readonly liveEffects;
+    private liveEffectStage?;
+    private liveEffectLayer?;
+    private liveEffectHost?;
+    private readonly pendingExports;
+    private exportSeq;
+    private destroyed;
+    constructor(state: MapState, container?: HTMLDivElement, options?: OffscreenBackendOptions);
+    get coordinateTransform(): CoordFn;
+    private post;
+    private postSettings;
+    private postCamera;
+    private postScene;
+    private postOverlays;
+    private styleContext;
+    private styleOne;
+    private styleShapes;
+    /** Style a scene layer, carrying each shape's world-space cull bounds through. */
+    private styleLayer;
+    refresh(): void;
+    private buildBoundsMap;
+    /** Port of {@link KonvaRenderBackend.updateCurrentRoomOverlay} returning shapes. */
+    private buildCurrentRoomOverlayShapes;
+    setStyle(style: Style): void;
+    private applyStyleTransforms;
+    private onCameraChange;
+    private subscribeToState;
+    private onPositionChanged;
+    updateBackground(): void;
+    addSceneOverlay(id: string, overlay: SceneOverlay): void;
+    removeSceneOverlay(id: string): void;
+    getSceneOverlays(): Iterable<SceneOverlay>;
+    private createOverlayContext;
+    private ensureEffectStage;
+    /** Mirror the camera transform onto the effect stage so effects align with the map. */
+    private syncEffectStage;
+    addLiveEffect(id: string, effect: LiveEffect): void;
+    removeLiveEffect(id: string): void;
+    getDrawnExits(): readonly DrawnExitEntry[];
+    getDrawnSpecialExits(): readonly DrawnSpecialExitEntry[];
+    getDrawnStubs(): readonly DrawnStubEntry[];
+    /**
+     * Not supported with the worker backend — the live canvas is owned by the
+     * worker and cannot be read synchronously here. Use the headless
+     * `CanvasExporter` / `PngBytesExporter` (they rebuild from state), or the
+     * async {@link captureViewport} for a live snapshot.
+     */
+    exportCanvas(): ExportCanvas | undefined;
+    /** Async live-viewport snapshot via a worker round-trip. */
+    captureViewport(options?: {
+        pixelRatio?: number;
+    }): Promise<ImageBitmap>;
+    private handleWorkerMessage;
+    destroy(): void;
+}

package/dist/rendering/offscreen/index.d.ts

@@ -0,0 +1,11 @@
+import { MapState } from '../../MapState';
+import { InteractiveBackend } from '../MapRenderer';
+import { OffscreenBackendOptions } from './OffscreenCanvasBackend';
+export { OffscreenCanvasBackend } from './OffscreenCanvasBackend';
+export type { OffscreenBackendOptions, WorkerTransport } from './OffscreenCanvasBackend';
+export type { MainToWorkerMessage, WorkerToMainMessage, SerializableTransform } from './protocol';
+/**
+ * Build a backend factory for {@link MapRenderer}'s `backendFactory` parameter.
+ * Pass the same `container` you give `MapRenderer`.
+ */
+export declare function createOffscreenBackend(container?: HTMLDivElement, options?: OffscreenBackendOptions): (state: MapState) => InteractiveBackend;

package/dist/rendering/offscreen/protocol.d.ts

@@ -0,0 +1,100 @@
+import { Shape } from '../../scene/Shape';
+import { Settings, ViewportBounds } from '../../types/Settings';
+/** World-space axis-aligned bounds used for culling. */
+export interface Bounds {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+/**
+ * Flattened coordinate transform. `Style.worldToScene` / `sceneToWorld` are
+ * closures and cannot cross `postMessage`; we sample them into affine matrices
+ * on the main thread. `'identity'` is the fast path for every flat style.
+ *
+ * Affine matrices follow the DOM/Canvas convention `[a, b, c, d, e, f]`:
+ * `x' = a·x + c·y + e`, `y' = b·x + d·y + f`.
+ */
+export type SerializableTransform = {
+    kind: "identity";
+} | {
+    kind: "affine";
+    /** World → scene (for culling-bounds projection). */
+    forward: AffineMatrix;
+    /** Scene → world (for grid Cartesian-bounds computation). */
+    inverse: AffineMatrix;
+};
+export type AffineMatrix = [number, number, number, number, number, number];
+/** Camera transform needed to project world coordinates into render space. */
+export interface RenderCamera {
+    scale: number;
+    offsetX: number;
+    offsetY: number;
+}
+/** One scene layer: styled shapes plus per-shape world-space cull bounds. */
+export interface LayerPayload {
+    /** Already-styled, scene-space shapes (identity style → world-space). */
+    shapes: Shape[];
+    /**
+     * Per-shape world-space cull bounds, index-aligned with {@link shapes}.
+     * `null` marks an unmanaged pass-through (area name, noScaling label) that
+     * is always drawn. Shapes fanned out by a style share their parent bounds.
+     */
+    bounds: Array<Bounds | null>;
+}
+export interface InitMessage {
+    type: "init";
+    canvas: OffscreenCanvas;
+    width: number;
+    height: number;
+    /** Device pixel ratio for crisp rendering on HiDPI displays. */
+    dpr: number;
+    settings: Settings;
+}
+export interface SettingsMessage {
+    type: "settings";
+    settings: Settings;
+}
+export interface SceneMessage {
+    type: "scene";
+    link: LayerPayload;
+    room: LayerPayload;
+    topLabel: Shape[];
+    transform: SerializableTransform;
+}
+export interface OverlaysMessage {
+    type: "overlays";
+    /** Already-styled overlay shapes (current-room overlay + built-in overlays). */
+    shapes: Shape[];
+}
+export interface CameraMessage {
+    type: "camera";
+    camera: RenderCamera;
+    viewport: ViewportBounds;
+    width: number;
+    height: number;
+}
+export interface ResizeMessage {
+    type: "resize";
+    width: number;
+    height: number;
+    dpr: number;
+}
+export interface ExportMessage {
+    type: "export";
+    requestId: number;
+    pixelRatio: number;
+}
+export interface DestroyMessage {
+    type: "destroy";
+}
+export type MainToWorkerMessage = InitMessage | SettingsMessage | SceneMessage | OverlaysMessage | CameraMessage | ResizeMessage | ExportMessage | DestroyMessage;
+export interface ReadyMessage {
+    type: "ready";
+}
+export interface ExportResultMessage {
+    type: "export";
+    requestId: number;
+    bitmap: ImageBitmap;
+}
+export type WorkerToMainMessage = ReadyMessage | ExportResultMessage;

package/dist/rendering/offscreen/renderFrame.d.ts

@@ -0,0 +1,28 @@
+import { Settings, ViewportBounds } from '../../types/Settings';
+import { Shape } from '../../scene/Shape';
+import { ImageFactory } from '../../render/CanvasRenderer';
+import { LayerPayload, RenderCamera, SerializableTransform } from './protocol';
+export interface FrameScene {
+    link: LayerPayload;
+    room: LayerPayload;
+    topLabel: Shape[];
+    transform: SerializableTransform;
+}
+export interface FrameInput {
+    scene: FrameScene | null;
+    overlays: Shape[];
+    camera: RenderCamera;
+    viewport: ViewportBounds;
+    settings: Settings;
+    /** Logical (CSS) pixel dimensions; HiDPI scaling is applied by the caller. */
+    width: number;
+    height: number;
+    /**
+     * Resolves an image shape's `src` to a drawable source. In the worker this
+     * returns a cached {@link ImageBitmap} (or `null` while it decodes), so
+     * data-URL labels and the ambient-light vignette render off-thread.
+     */
+    imageFactory?: ImageFactory;
+}
+/** Render one frame of the scene + overlays onto `ctx`. */
+export declare function renderFrame(ctx: CanvasRenderingContext2D, input: FrameInput): void;

package/dist/rendering/offscreen/serializeTransform.d.ts

@@ -0,0 +1,20 @@
+import { Style } from '../../style/Style';
+import { SerializableTransform } from './protocol';
+type TransformFn = (x: number, y: number) => {
+    x: number;
+    y: number;
+};
+/** Build the flattened transform for a style. Identity styles short-circuit. */
+export declare function serializeTransform(style: Style): SerializableTransform;
+/**
+ * World → scene projector for the worker's cull-bounds test. Returns
+ * `undefined` for the identity transform so callers can skip projection.
+ */
+export declare function forwardFn(transform: SerializableTransform): TransformFn | undefined;
+/**
+ * Scene → world projector for the worker's grid Cartesian-bounds computation.
+ * Returns `undefined` for the identity transform (grid layout treats absent
+ * inverse as identity).
+ */
+export declare function inverseFn(transform: SerializableTransform): TransformFn | undefined;
+export {};

package/dist/rendering/offscreen/worker.d.ts

@@ -0,0 +1,15 @@
+/**
+ * OffscreenCanvas worker entry.
+ *
+ * Thin dispatcher around {@link renderFrame}: owns the transferred
+ * `OffscreenCanvas`, stores the latest scene / overlays / camera / settings,
+ * and coalesces redraws onto one animation frame (only the latest camera
+ * matters, so queued messages are harmless). Resizing a transferred canvas can
+ * only happen here, so size/DPR changes are applied worker-side.
+ *
+ * This module is bundled standalone (see vite.config.ts). It must import ONLY
+ * worker-safe code — never Konva, `textMeasure`, or anything touching
+ * `document`. A stray such import would surface as a runtime error in the
+ * worker and a Konva chunk in the build.
+ */
+export {};

package/dist/scene/OverlayStyle.d.ts

@@ -7,15 +7,19 @@ export type HighlightData = {
     /** For circle: radius. For rect: half-size. */
     size: number;
     cornerRadius: number;
-    strokeColor: string;
+    /**
+     * One or more colours. A single colour draws the classic ring/marker; two
+     * or more split the highlight into that many equal pie wedges (one colour
+     * each).
+     */
+    colors: string[];
     strokeAlpha: number;
     strokeWidth: number;
-    fillColor: string;
     fillAlpha: number;
     dash?: number[];
     dashEnabled: boolean;
 };
-export declare function computeHighlight(room: MapData.Room, color: string, settings: Settings): HighlightData;
+export declare function computeHighlight(room: MapData.Room, color: string | string[], settings: Settings): HighlightData;
 export type PositionMarkerData = {
     shape: 'circle' | 'rect';
     cx: number;

package/dist/scene/Shape.d.ts

@@ -62,6 +62,13 @@ export interface Paint {
 }
 /** True when `fill` is a gradient object rather than a colour string. */
 export declare function isGradientFill(fill: FillStyle | undefined): fill is LinearGradient | RadialGradient;
+/**
+ * Resolve a paint's effective dash pattern. Returns the dash only when it is
+ * present AND not explicitly disabled (`dashEnabled === false` blanks it).
+ * Renderers call this so every shape kind — rect, circle, line — honours
+ * `dashEnabled` identically.
+ */
+export declare function resolveDash(dash: number[] | undefined, dashEnabled: boolean | undefined): number[] | undefined;
 /**
  * Apply a camera-style affine (translate by world origin, scale uniformly,
  * translate by render offset) to a fill. Strings pass through unchanged.

package/dist/scene/elements/OverlayLayout.d.ts

@@ -6,6 +6,9 @@ import { Shape } from '../Shape';
  * a group) so the corner dashes line up cleanly — each side's dash pattern
  * starts fresh at the corner instead of wrapping continuously around the
  * perimeter (same approach as the backend renderer).
+ *
+ * When the highlight carries more than one colour the ring is split into that
+ * many equal pie wedges via {@link highlightWedgesToShape}.
  */
 export declare function highlightToShape(data: HighlightData): Shape;
 /** Build the player-position marker. */

package/dist/style/Style.d.ts

@@ -28,6 +28,18 @@ export interface Style {
         x: number;
         y: number;
     };
+    /**
+     * Optional extra scene-space offset that {@link transform} applies to a
+     * given layer's groups but {@link worldToScene} does not capture. Isometric
+     * lowers the `link` layer by the cube depth so connectors meet the cube
+     * base; without mirroring that here, {@link HitTester} would place exit hit
+     * zones a cube-height above the drawn connectors. Returns `{x:0, y:0}` for
+     * layers it does not shift.
+     */
+    sceneLayerOffset?(layer: Shape["layer"]): {
+        x: number;
+        y: number;
+    };
 }
 /** Identity style — passes shapes through unchanged. */
 export declare const identityStyle: Style;

package/dist/style/index.d.ts

@@ -2,6 +2,7 @@ import { Style } from './Style';
 import { SketchyOptions } from './shape/SketchyStyle';
 import { IsometricOptions, IsometricRotation } from './shape/IsometricStyle';
 import { GradientRoomsOptions } from './shape/GradientRoomsStyle';
+import { WatercolorOptions } from './shape/WatercolorStyle';
 export { compose, identityStyle } from './Style';
 export type { Style, StyleContext } from './Style';
 export { applyStyleToShapes } from './applyStyle';
@@ -25,4 +26,12 @@ export declare const SciFi: Style;
  * gradient stops are recoloured per stop.
  */
 export declare function GradientRooms(options?: GradientRoomsOptions): Style;
-export type { SketchyOptions, IsometricOptions, IsometricRotation, GradientRoomsOptions };
+/** Stained-glass aesthetic — saturated panes framed by fat near-black leading. */
+export declare const StainedGlass: Style;
+/** Old-school graph-paper dungeon — pale rooms inked in navy over blue grid. */
+export declare const GraphPaper: Style;
+/** Topographic relief — earthy rooms with concentric contour rings. */
+export declare const Topographic: Style;
+/** Hand-painted watercolour — translucent edge-bled washes that pool on overlap. */
+export declare function Watercolor(options?: WatercolorOptions): Style;
+export type { SketchyOptions, IsometricOptions, IsometricRotation, GradientRoomsOptions, WatercolorOptions };

package/dist/style/shape/GraphPaperStyle.d.ts

@@ -0,0 +1,16 @@
+import { Style } from '../Style';
+/**
+ * Old-school graph-paper dungeon aesthetic as a {@link Style} — the classic
+ * hand-drawn D&D look: pale rooms inked in navy over blue grid paper.
+ *
+ * - Fills map to a pale slate-blue → near-white range by luminance, so rooms
+ *   stay light and the blue grid reads through. Gradient stops recolour per stop.
+ * - Strokes become fattened navy ink.
+ * - Exit lines become navy ink (kept thin where the source was thin).
+ * - Text uses navy ink.
+ * - Images and groups pass through unchanged.
+ *
+ * Pair with a cream/white background and a light-blue grid in settings for the
+ * full graph-paper effect.
+ */
+export declare const graphPaperShapeStyle: Style;

package/dist/style/shape/StainedGlassStyle.d.ts

@@ -0,0 +1,15 @@
+import { Style } from '../Style';
+/**
+ * Stained-glass aesthetic as a {@link Style} — jewel-toned panes separated by
+ * thick near-black leading, glowing on a dark backdrop.
+ *
+ * - Fills are pushed to high saturation in a mid-lightness window so rooms read
+ *   as coloured glass; grey rooms stay neutral (frosted panes). Gradient fills
+ *   recolour per stop.
+ * - Strokes become fat near-black leading; filled panes gain leading even when
+ *   the source had none.
+ * - Exit lines become slim leading too, tying the panes together.
+ * - Text uses pale glass-white for legibility over the dark cames.
+ * - Images and groups pass through unchanged.
+ */
+export declare const stainedGlassShapeStyle: Style;

package/dist/style/shape/TopographicStyle.d.ts

@@ -0,0 +1,14 @@
+import { Style } from '../Style';
+/**
+ * Topographic / contour-map aesthetic as a {@link Style}. Rooms get an earthy
+ * elevation palette and a set of concentric inset "contour" rings, so each room
+ * reads like a hill on a shaded relief map.
+ *
+ * - Rect / circle / polygon: emit the earth-toned base shape, then up to
+ *   {@link RINGS} stroke-only rings inset toward the centre. Rings collapse and
+ *   are skipped for rooms too small to hold them.
+ * - Exit lines become muted brown paths.
+ * - Text uses dark sepia.
+ * - Images and groups pass through unchanged.
+ */
+export declare const topographicShapeStyle: Style;

package/dist/style/shape/WatercolorStyle.d.ts

@@ -0,0 +1,32 @@
+import { Style } from '../Style';
+export interface WatercolorOptions {
+    /**
+     * Edge-bleed amount in map units (perpendicular wobble of pane edges).
+     * Default 0.05.
+     */
+    bleed?: number;
+    /**
+     * Translucent washes stacked per filled shape. More layers = deeper, more
+     * uneven colour where they overlap. Default 2 (clamped to 1..4).
+     */
+    layers?: number;
+    /** Per-wash alpha multiplier so stacked washes build up colour. Default 0.4. */
+    alpha?: number;
+}
+/**
+ * Hand-painted watercolour as a {@link Style}. Each filled shape becomes a
+ * stack of translucent, edge-wobbled washes that bleed and deepen where they
+ * overlap — soft and organic, with no crisp ink outline.
+ *
+ * - Rect / circle / polygon fills → N wobbly low-alpha polygon washes (seeded,
+ *   so re-renders are identical). Hard strokes are dropped; the soft edges come
+ *   from the overlapping washes.
+ * - Lines (exits) keep their colour but lose alpha so they read as a thin wet
+ *   brushstroke under the rooms.
+ * - Text is repainted in muted ink.
+ * - Images and groups pass through unchanged.
+ *
+ * Unfilled stroked shapes (e.g. exit arrowheads) fall back to a single faint
+ * wobbled outline rather than vanishing.
+ */
+export declare function watercolorShapeStyle(options?: WatercolorOptions): Style;

package/dist/style/shape/index.d.ts

@@ -25,3 +25,8 @@ export { constructionShapeStyle } from './ConstructionStyle';
 export { scifiShapeStyle } from './SciFiStyle';
 export { gradientRoomsStyle } from './GradientRoomsStyle';
 export type { GradientRoomsOptions } from './GradientRoomsStyle';
+export { stainedGlassShapeStyle } from './StainedGlassStyle';
+export { graphPaperShapeStyle } from './GraphPaperStyle';
+export { topographicShapeStyle } from './TopographicStyle';
+export { watercolorShapeStyle } from './WatercolorStyle';
+export type { WatercolorOptions } from './WatercolorStyle';

package/dist/style/shape/paintMap.d.ts

@@ -23,3 +23,11 @@ export declare function parseRgb(color: string): ParsedRgb | null;
 export declare function formatRgb(r: number, g: number, b: number, a?: number): string;
 /** Perceived luminance in [0, 1] using ITU-R BT.601 weights. */
 export declare function luminance(c: ParsedRgb): number;
+/**
+ * Convert 0..255 RGB to HSL with hue in degrees and saturation/lightness in
+ * [0, 1]. Achromatic colours report hue 0. Shared by the newer styles
+ * (StainedGlass, …); Neon and SciFi keep their own local copies.
+ */
+export declare function rgbToHsl(r: number, g: number, b: number): [number, number, number];
+/** Build an `rgb(...)` / `rgba(...)` string from HSL (hue degrees, s/l in [0,1]). */
+export declare function hslToRgbString(h: number, s: number, l: number, a?: number): string;

package/dist/types/Settings.d.ts

@@ -129,10 +129,18 @@ export type HighlightStyle = {
      */
     dashEnabled: boolean;
     /**
-     * When true, the highlight shape matches the current roomShape setting
-     * (rectangle, circle, or roundedRectangle). When false, the highlight is always a circle.
+     * @deprecated Use {@link shape} instead. Only consulted when `shape` is
+     * `'match'` (or omitted): when true (the default) the highlight follows the
+     * current roomShape (rectangle / roundedRectangle / circle); when false it
+     * is always a circle.
      */
-    matchRoomShape: boolean;
+    matchRoomShape?: boolean;
+    /**
+     * Outline shape of the highlight. `'match'` (the default when omitted)
+     * follows the current roomShape; the other values force that specific shape
+     * regardless of the room's shape.
+     */
+    shape?: 'match' | 'rectangle' | 'roundedRectangle' | 'circle';
 };
 /**
  * Settings for map rendering.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mudlet-map-renderer",
-  "version": "2.0.0",
+  "version": "2.2.0",
   "license": "MIT",
   "repository": {
     "url": "https://github.com/Delwing/mudlet-map-renderer"
@@ -17,6 +17,10 @@
     "./binary": {
       "types": "./dist/binary/index.d.ts",
       "import": "./dist/binary.mjs"
+    },
+    "./offscreen": {
+      "types": "./dist/rendering/offscreen/index.d.ts",
+      "import": "./dist/offscreen.mjs"
     }
   },
   "sideEffects": false,
@@ -25,6 +29,7 @@
     "build": "tsc -p tsconfig.json && vite build",
     "preview": "vite preview",
     "demo:dev": "vite --config vite.demo.config.ts",
+    "bench": "vite --config vite.bench.config.ts",
     "demo:build": "vite build --config vite.demo.config.ts",
     "demo:preview": "vite preview --config vite.demo.config.ts",
     "demo:headless": "tsx --tsconfig demo/tsconfig.json demo/headless.ts",