mudlet-map-renderer 2.2.0 → 2.3.1

package/dist/labelPlacement.d.ts

@@ -0,0 +1,132 @@
+/**
+ * Point-feature label placement.
+ *
+ * Given a set of anchored labels (e.g. waypoints on rooms) and obstacles
+ * (rooms, exits, already-placed labels), choose for each label the candidate
+ * slot around its anchor that best avoids collisions. Pure and deterministic —
+ * the same inputs always produce the same layout — so it's reusable beyond
+ * waypoints and easy to test.
+ *
+ * For each slot the label is scanned outward (up to {@link extend}); the spot
+ * with the most CLEARANCE — distance to the nearest room, exit line, or other
+ * placed label — wins, lightly penalised by how far it had to push. This puts
+ * labels in open space, off every line, and only as far out as openness needs.
+ * Positions overlapping a room/label are skipped; sitting on an exit just reads
+ * as zero clearance. Cardinal-over-diagonal and an optional preferred direction
+ * break ties between equally-open slots.
+ *
+ * Placement is greedy: items are processed in input order and each placed label
+ * becomes an obstacle for the ones after it.
+ */
+export type Direction8 = "n" | "s" | "e" | "w" | "ne" | "nw" | "se" | "sw";
+export interface Rect {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+/** An obstacle the placement should avoid. `kind` weights how hard to avoid it. */
+export interface Obstacle extends Rect {
+    kind?: "room" | "label" | "exit" | string;
+}
+export interface LabelPlacementItem {
+    /** Anchor point (e.g. room centre), world coords. */
+    x: number;
+    y: number;
+    /** Label box size, world units. */
+    width: number;
+    height: number;
+    /** Optional preferred direction — nudges the choice, never forces overlap. */
+    preferred?: Direction8;
+    /** Optional stable id, echoed back on the result. */
+    id?: string | number;
+}
+export interface PlacedLabel {
+    id?: string | number;
+    /** Top-left of the placed label box, world coords. */
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    /** Chosen slot. */
+    direction: Direction8;
+    /** Leader endpoint on the box edge nearest the anchor (for drawing a connector). */
+    leader: {
+        x: number;
+        y: number;
+    };
+}
+/** Per-slot diagnostic from {@link PlaceLabelsOptions.onScored}. */
+export interface SlotScore {
+    dir: Direction8;
+    /** False when no non-overlapping position exists in this slot. */
+    valid: boolean;
+    /** Clearance (distance to nearest obstacle) at the best position found. */
+    clearance: number;
+    /** Outward offset of the best position. */
+    off: number;
+    /** Final cost (lower = better; Infinity when invalid). */
+    cost: number;
+    /** The label box at the best position. */
+    box: Rect;
+}
+export interface PlaceLabelsOptions {
+    /** Gap between the anchor and the near edge of the label box, world units. Default 0.6. */
+    offset?: number;
+    /** Use only N/S/E/W (4) or all 8 slots. Default 8. */
+    slots?: 4 | 8;
+    /**
+     * How far (world units) a label may be pushed outward along a slot, beyond
+     * the base {@link offset}, while searching for the most open spot. 0 keeps
+     * labels at the base offset; larger lets them float into open pockets away
+     * from rooms/exit lines.
+     */
+    extend?: number;
+    /**
+     * Clearance is only rewarded up to this many world units — past it a spot is
+     * "open enough" and extra distance isn't worth pushing further for. Defaults
+     * to the label's larger side.
+     */
+    clearCap?: number;
+    /**
+     * When the best slot's clearance is below this (world units), the room is
+     * treated as "surrounded": instead of floating out for a marginal gain, the
+     * label sits close at the base offset on an exit, preferring north. Default 0
+     * (disabled — always go for max clearance).
+     */
+    minClearance?: number;
+    /**
+     * Debug hook — called once per item with the score of every candidate slot
+     * and the chosen direction. For visualising/diagnosing placement decisions.
+     */
+    onScored?: (item: LabelPlacementItem, slots: SlotScore[], chosen: Direction8) => void;
+    /** Cost weights (sane defaults; overlap dominates, then openness, then direction). */
+    weights?: Partial<typeof DEFAULT_WEIGHTS>;
+}
+declare const DEFAULT_WEIGHTS: {
+    /**
+     * Reward per world unit of clearance (distance from the label box to the
+     * nearest room/exit/label), capped at {@link PlaceLabelsOptions.clearCap}.
+     * The dominant term — pushes labels into open space, off every line.
+     */
+    clear: number;
+    /**
+     * Cardinal-over-diagonal preference — a TRUE tie-break only. Kept tiny so
+     * any real clearance advantage (≳0.03 units) overrides it: a clearly more
+     * open diagonal always beats an on-a-line cardinal.
+     */
+    diagonal: number;
+    /** Bonus (subtracted from cost) when a slot matches the item's preferred direction. */
+    preferred: number;
+    /**
+     * Penalty per world unit the label is pushed out — keeps it close, but small
+     * enough not to cancel the clearance gained by pushing into open space.
+     */
+    distance: number;
+};
+/**
+ * Place each item at its best-scoring slot. Returns one {@link PlacedLabel} per
+ * input item, in the same order.
+ */
+export declare function placeLabels(items: LabelPlacementItem[], obstacles: Obstacle[], options?: PlaceLabelsOptions): PlacedLabel[];
+export {};

package/dist/overlay/RippleEffect.d.ts

@@ -0,0 +1,48 @@
+import { default as Konva } from 'konva';
+import { CoordinateTransform, LiveEffect } from './LiveEffect';
+import { ViewportBounds } from '../types/Settings';
+export interface RippleOptions {
+    /** Animation length in milliseconds. Default 400. */
+    duration?: number;
+    /** Ring colour (any CSS colour). Default "#00e5b2". */
+    color?: string;
+    /** Starting ring radius in world units. Default 0.3. */
+    startRadius?: number;
+    /** Final ring radius in world units. Default 1.2. */
+    endRadius?: number;
+    /** Ring stroke width in world units. Default 0.08. */
+    strokeWidth?: number;
+    /**
+     * Invoked once when the animation finishes. The host should use this to
+     * remove the (now spent) effect, e.g. `removeLiveEffect(id)`.
+     */
+    onComplete?: () => void;
+}
+/**
+ * One-shot expanding, fading ring centred on a world-space point — used to
+ * pulse the player marker when it moves. Implements {@link LiveEffect}, so it
+ * works on both the Konva and OffscreenCanvas backends (the latter composites
+ * it on its main-thread effect stage).
+ *
+ * The ring lives in scene space (the host layer carries the camera transform),
+ * so it tracks the map as the user pans/zooms. It self-animates and calls
+ * {@link RippleOptions.onComplete} when done.
+ */
+export declare class RippleEffect implements LiveEffect {
+    private readonly worldX;
+    private readonly worldY;
+    private ring?;
+    private rafId?;
+    private cancelled;
+    private transform;
+    private readonly duration;
+    private readonly color;
+    private readonly startRadius;
+    private readonly endRadius;
+    private readonly strokeWidth;
+    private readonly onComplete?;
+    constructor(worldX: number, worldY: number, options?: RippleOptions);
+    attach(layer: Konva.Layer): void;
+    updateViewport(_bounds: ViewportBounds, _scale: number, coordinateTransform: CoordinateTransform): void;
+    destroy(): void;
+}

package/dist/overlay/WaypointOverlay.d.ts

@@ -0,0 +1,70 @@
+import { MapState } from '../MapState';
+import { ViewportBounds } from '../types/Settings';
+import { Shape } from '../scene/Shape';
+import { Direction8 } from '../labelPlacement';
+import { SceneOverlay, SceneOverlayContext } from './SceneOverlay';
+export interface Waypoint {
+    roomId: number;
+    /** Label text. An array renders as stacked lines in one bubble. */
+    label: string | string[];
+    /** Marker / accent colour (hex). Default amber. */
+    color?: string;
+    /** Optional preferred label direction (nudge only). */
+    preferred?: Direction8;
+    /**
+     * Optional click handler. Fired when the waypoint's bubble is clicked.
+     * Wire pointer hits to it via {@link WaypointOverlay.hitTest} (see below).
+     * Waypoints without a handler are inert.
+     */
+    onClick?: (waypoint: Waypoint) => void;
+}
+/**
+ * Persistent named markers anchored to rooms (shops, banks, quest givers …),
+ * with auto-placed labels that dodge neighbouring rooms, exits, and each other
+ * via {@link placeLabels}. A {@link SceneOverlay}, so it renders on the
+ * interactive canvas and in every export.
+ *
+ * A room may carry more than one waypoint (e.g. a transport stop served by two
+ * routes): the list is flat, so push several entries with the same `roomId` and
+ * each gets its own auto-placed bubble. Alternatively give one waypoint a
+ * multi-line `label` to list them in a single bubble.
+ *
+ * Waypoints can be clickable. Bubbles are overlay-layer shapes, so they are not
+ * part of the renderer's {@link HitTester}; the overlay instead records the
+ * rects it places and resolves them via {@link hitTest}. Wire pointer clicks to
+ * it by converting the cursor to world space:
+ *
+ * ```ts
+ * const waypoints = new WaypointOverlay();
+ * waypoints.add({ roomId: 42, label: 'Bank', onClick: wp => console.log(wp.roomId) });
+ * renderer.addSceneOverlay('waypoints', waypoints);
+ *
+ * container.addEventListener('click', e => {
+ *     const p = renderer.camera.clientToMapPoint(e.clientX, e.clientY, container.getBoundingClientRect());
+ *     if (!p) return;
+ *     const wp = waypoints.hitTest(p.x, p.y);
+ *     wp?.onClick?.(wp);
+ * });
+ * ```
+ */
+export declare class WaypointOverlay implements SceneOverlay {
+    private waypoints;
+    private ctx?;
+    /** Bubble rects from the last render, for click hit-testing (world space). */
+    private placed;
+    set(list: Waypoint[]): void;
+    add(waypoint: Waypoint): void;
+    /** Remove every waypoint anchored to this room. */
+    remove(roomId: number): void;
+    has(roomId: number): boolean;
+    /**
+     * Topmost waypoint whose bubble contains the given **world-space** point, or
+     * `undefined`. Hit-tests the bubbles placed by the last {@link render} (in
+     * reverse, so later-drawn bubbles win). Convert a pointer position to world
+     * space with `renderer.camera.clientToMapPoint(...)` before calling.
+     */
+    hitTest(worldX: number, worldY: number): Waypoint | undefined;
+    attach(ctx: SceneOverlayContext): void;
+    detach(): void;
+    render(state: MapState, _bounds: ViewportBounds): Shape[];
+}

package/dist/style/index.d.ts

@@ -3,6 +3,7 @@ import { SketchyOptions } from './shape/SketchyStyle';
 import { IsometricOptions, IsometricRotation } from './shape/IsometricStyle';
 import { GradientRoomsOptions } from './shape/GradientRoomsStyle';
 import { WatercolorOptions } from './shape/WatercolorStyle';
+import { treasureMapDecorations } from './shape/TreasureMapStyle';
 export { compose, identityStyle } from './Style';
 export type { Style, StyleContext } from './Style';
 export { applyStyleToShapes } from './applyStyle';
@@ -34,4 +35,17 @@ export declare const GraphPaper: Style;
 export declare const Topographic: Style;
 /** Hand-painted watercolour — translucent edge-bled washes that pool on overlap. */
 export declare function Watercolor(options?: WatercolorOptions): Style;
+/** Flat dark "modern UI" theme — muted dark rooms with subtle elevation shadows. */
+export declare const DarkModern: Style;
+/**
+ * Aged treasure-map palette — weathered-paper rooms inked in faded brown.
+ * Pair with {@link treasureMapDecorations} (a scene overlay) for the compass
+ * rose and double border frame:
+ * ```ts
+ * renderer.setStyle(TreasureMap);
+ * renderer.addSceneOverlay('treasure-decor', treasureMapDecorations());
+ * ```
+ */
+export declare const TreasureMap: Style;
+export { treasureMapDecorations };
 export type { SketchyOptions, IsometricOptions, IsometricRotation, GradientRoomsOptions, WatercolorOptions };

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

@@ -0,0 +1,15 @@
+import { Style } from '../Style';
+/**
+ * Flat dark "modern UI" aesthetic as a {@link Style}.
+ *
+ * - Room fills are flattened into a muted dark palette (hue kept, saturation
+ *   capped, lightness compressed) so the map reads as a calm dark dashboard.
+ * - Room outlines become a subtle translucent light border.
+ * - Each room body casts a soft offset drop-shadow (emitted **before** the
+ *   body, like Neon's glow, so it renders underneath) for a sense of
+ *   elevation.
+ * - Exit lines become a muted grey-blue; text is off-white.
+ * - Images and groups pass through unchanged (the caller walks group
+ *   children separately).
+ */
+export declare const darkModernShapeStyle: Style;

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

@@ -0,0 +1,23 @@
+import { Style } from '../Style';
+import { SceneOverlay } from '../../overlay/SceneOverlay';
+/**
+ * Aged treasure-map palette as a {@link Style}.
+ *
+ * Recolours rooms onto a warm weathered-paper ramp and inks every line in
+ * faded brown. For the decorative compass rose and double border frame, add
+ * {@link treasureMapDecorations} as a scene overlay alongside this style.
+ *
+ * ```ts
+ * renderer.setStyle(TreasureMap);
+ * renderer.addSceneOverlay('treasure-decor', treasureMapDecorations());
+ * ```
+ */
+export declare const treasureMapShapeStyle: Style;
+/**
+ * Decorative scene overlay for the treasure-map look: a double-line border
+ * frame inset from the viewport and a compass rose in the top-right corner.
+ *
+ * Emitted in world space and pinned to the current viewport, so it tracks the
+ * visible region as the user pans/zooms and appears in every export path.
+ */
+export declare function treasureMapDecorations(): SceneOverlay;

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

@@ -30,3 +30,5 @@ export { graphPaperShapeStyle } from './GraphPaperStyle';
 export { topographicShapeStyle } from './TopographicStyle';
 export { watercolorShapeStyle } from './WatercolorStyle';
 export type { WatercolorOptions } from './WatercolorStyle';
+export { darkModernShapeStyle } from './DarkModernStyle';
+export { treasureMapShapeStyle, treasureMapDecorations } from './TreasureMapStyle';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mudlet-map-renderer",
-  "version": "2.2.0",
+  "version": "2.3.1",
   "license": "MIT",
   "repository": {
     "url": "https://github.com/Delwing/mudlet-map-renderer"