mudlet-map-renderer 2.2.0 → 2.3.0

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/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.0",
   "license": "MIT",
   "repository": {
     "url": "https://github.com/Delwing/mudlet-map-renderer"