mudlet-map-editor 0.18.0 → 0.20.0

package/dist-lib/components/Toolbar.d.ts

@@ -1,5 +1,14 @@
-export declare function Toolbar({ title, onHelpClick, onLoadFromUrl, onSave, onSearchClick, onSettingsClick }: {
+import { type ReactNode } from 'react';
+import type { ToolbarAction } from '../editor/plugin';
+/** `logo` is the plugin override slot. `undefined` means no plugin claimed it
+ *  (toolbar falls back to the built-in Mudlet logo); any other value — including
+ *  `null` — is rendered as-is, so a plugin can explicitly hide the slot.
+ *  `transformActions` is the composed plugin transform applied to the built-in
+ *  file-action list (see EditorPlugin#toolbarActions). */
+export declare function Toolbar({ title, logo, transformActions, onHelpClick, onLoadFromUrl, onSave, onSearchClick, onSettingsClick }: {
     title?: string;
+    logo?: ReactNode;
+    transformActions?: (actions: ToolbarAction[]) => ToolbarAction[];
     onHelpClick: () => void;
     onLoadFromUrl: () => void;
     onSave?: (bytes: Uint8Array) => void;

package/dist-lib/components/panels/RoutePanel.d.ts

@@ -0,0 +1,6 @@
+import type { SceneHandle } from '../../editor/scene';
+export declare function RoutePanel({ sceneRef }: {
+    sceneRef: {
+        current: SceneHandle | null;
+    };
+}): import("react/jsx-runtime").JSX.Element;

package/dist-lib/editor/effects/RouteEffect.d.ts

@@ -0,0 +1,37 @@
+import Konva from 'konva';
+import { type CoordinateTransform, type LiveEffect, type ViewportBounds } from 'mudlet-map-renderer';
+import type { SceneHandle } from '../scene';
+/**
+ * Draws the active route (store.route.summary.path) on top of the map: a glowing
+ * poly-line following the same geometry the renderer uses for paths (via
+ * computePathData), plus start/end rings and dots for up/down/in/out
+ * transitions. Only the portion of the path on the current area/z is drawn —
+ * computePathData filters by area/z and stubs cross-boundary hops, so a
+ * multi-area route still shows correctly as you switch areas.
+ */
+export declare class RouteEffect implements LiveEffect {
+    private readonly sceneRef;
+    private layer?;
+    private unsubscribe?;
+    private nodes;
+    /** Lines whose width must track zoom (node + width multiplier). */
+    private widthLines;
+    private rings;
+    private scale;
+    /** Last-drawn signature, so pointer-move store churn doesn't rebuild the path. */
+    private lastSummary;
+    private lastArea;
+    private lastZ;
+    private lastDataVersion;
+    constructor(sceneRef: {
+        current: SceneHandle | null;
+    });
+    attach(layer: Konva.Layer): void;
+    updateViewport(_bounds: ViewportBounds, scale: number, _transform: CoordinateTransform): void;
+    syncPositions(): void;
+    destroy(): void;
+    private clear;
+    private addLine;
+    private addRing;
+    private sync;
+}

package/dist-lib/editor/pathfinding.d.ts

@@ -0,0 +1,35 @@
+import { type PathFindingAlgorithm } from 'mudlet-map-renderer';
+import type { MudletMap } from '../mapIO';
+import type { EditorMapReader } from './reader/EditorMapReader';
+export type { PathFindingAlgorithm };
+export type RouteStep = {
+    /** Room you leave from. */
+    fromId: number;
+    /** Room you arrive at. */
+    toId: number;
+    /** Speedwalk command — short cardinal (n, ne, up…) or the special-exit name. */
+    token: string;
+    /** Whether this hop is a cardinal exit or a named special exit. */
+    kind: 'cardinal' | 'special';
+    /** Edge weight A* / Dijkstra paid for this hop. */
+    weight: number;
+};
+export type RouteSummary = {
+    /** Room-id sequence start→end (length = steps + 1). */
+    path: number[];
+    steps: RouteStep[];
+    /** Sum of edge weights along the path. */
+    totalWeight: number;
+    /** Semicolon-joined command string, e.g. "n;n;ne;up". */
+    speedwalk: string;
+};
+/**
+ * Find the lowest-cost route between two rooms using the renderer's pathfinder
+ * (respects exit/room weights, locked exits, and locked special exits) and
+ * summarise it into a speedwalk string + per-hop steps. Returns null when either
+ * endpoint is missing or no route exists.
+ *
+ * A fresh PathFinder is built per call: it snapshots the graph in its constructor,
+ * and the editor mutates the map constantly, so reusing one would go stale.
+ */
+export declare function findRoute(reader: EditorMapReader, map: MudletMap, fromId: number, toId: number, algorithm?: PathFindingAlgorithm): RouteSummary | null;

package/dist-lib/editor/plugin.d.ts

@@ -1,4 +1,4 @@
-import type { ReactNode } from 'react';
+import type { CSSProperties, ReactNode } from 'react';
 import type { MudletMap, MudletRoom } from '../mapIO';
 import type { SwatchSet } from './types';
 import type { SceneHandle } from './scene';
@@ -31,6 +31,38 @@ export interface RoomPanelSection {
     id: string;
     render(props: RoomSectionProps): ReactNode;
 }
+/** A button in the toolbar header row's file-action group. Plugins reshape the
+ *  list via `toolbarActions` — filter to hide built-ins, map to override
+ *  callbacks/labels, or push to add new entries. Built-in ids are 'new',
+ *  'load', 'loadUrl', and 'save'. */
+export interface ToolbarAction {
+    /** Stable id; plugins target a specific action by matching on this. */
+    id: string;
+    /** Tooltip text shown on hover. */
+    title?: string;
+    /** Button contents — typically an SVG icon, but any node works. */
+    icon?: ReactNode;
+    /** Click handler. Ignored when `filePicker` is set. */
+    onClick?: () => void;
+    /** When set, the action renders as a `<label>` wrapping a hidden `<input
+     *  type="file">`; clicking opens the OS file picker and the chosen file is
+     *  passed to `onFile`. Used by the built-in "load .dat" entry. */
+    filePicker?: {
+        accept: string;
+        onFile: (file: File) => void;
+    };
+    /** Disable the button (greys out + ignores clicks). */
+    disabled?: boolean;
+    /** Overlay node rendered on top of the button — used by the built-in
+     *  "save" entry to draw the dirty-marker asterisk. */
+    badge?: ReactNode;
+    /** Inline style for the button/label root. */
+    style?: CSSProperties;
+    /** Escape hatch: when set, every other field except `id` is ignored and
+     *  this node is rendered in place. Use for controls that aren't a single
+     *  button (e.g. a dropdown). */
+    render?: () => ReactNode;
+}
 export interface EditorPlugin {
     /** Stable identifier used to namespace plugin warning ack keys. Defaults to array index if omitted. */
     id?: string;
@@ -39,6 +71,22 @@ export interface EditorPlugin {
     onMapClosed?(): void;
     onMapSave?(bytes: Uint8Array): void;
     renderOverlay?(): ReactNode;
+    /** Replace the toolbar logo. The first plugin that defines this hook claims
+     *  the slot — its return value is rendered as-is (including `null`, which
+     *  hides the logo entirely). When no plugin defines it, the built-in Mudlet
+     *  logo appears. */
+    renderLogo?(): ReactNode;
+    /** Reshape the toolbar's file-action button list. The hook receives the
+     *  current list (built-ins first, then any earlier-plugin additions) and
+     *  returns a new list. Typical uses:
+     *    - **Hide** a built-in: `actions.filter(a => a.id !== 'loadUrl')`
+     *    - **Replace a callback**: `actions.map(a => a.id === 'save'
+     *        ? { ...a, onClick: mySave } : a)` (keeps the button visuals,
+     *        swaps the behaviour — onMapSave still fires when the editor
+     *        serialises the map elsewhere)
+     *    - **Add** a custom button: `[...actions, { id, title, icon, onClick }]`
+     *  Plugin transforms are applied in plugin order. */
+    toolbarActions?(actions: ToolbarAction[]): ToolbarAction[];
     sidebarTabs?(): SidebarTab[];
     swatchSets?(): SwatchSet[];
     /** Contribute additional sections rendered at the bottom of the room selection panel. */

package/dist-lib/editor/roomSearch.d.ts

@@ -0,0 +1,41 @@
+import type { MudletMap, MudletRoom } from '../mapIO';
+/**
+ * Structured room-search query language used by the Search panel.
+ *
+ * A query is a whitespace-separated list of tokens. Each token is either:
+ *   - a structured filter `key:value` (e.g. `env:3`, `weight:>5`, `stubs:>0`,
+ *     `exits:1`, `door:yes`, `locked:no`), optionally negated with a leading
+ *     `-` or `!` (e.g. `-door:yes`); or
+ *   - free text, matched against room name / id / userData (legacy behaviour).
+ *
+ * All structured filters are ANDed together; free-text tokens are joined with a
+ * space and matched as a single substring. A token is treated as a filter only
+ * when the part before the first colon is a recognised key — anything else
+ * (including URLs and colon-bearing free text) falls through to free text, so
+ * filters never produce surprising "unknown" errors for ordinary searches.
+ */
+export interface RoomMatchContext {
+    room: MudletRoom;
+    id: number;
+    map: MudletMap;
+}
+export type RoomPredicate = (ctx: RoomMatchContext) => boolean;
+export interface ParsedQuery {
+    /** Free-text portion, lowercased; '' when the query is filters-only. */
+    text: string;
+    /** Structured predicates; a room must satisfy all of them. */
+    predicates: RoomPredicate[];
+    /** Canonical keys of the active filters, in first-seen order (for result summaries). */
+    filterKeys: string[];
+    /** The original token of the first malformed filter, or null. */
+    error: string | null;
+}
+/** Count of real outgoing exits: cardinal/vertical exits plus special exits. */
+export declare function exitCount(room: MudletRoom): number;
+export declare function parseRoomQuery(input: string): ParsedQuery;
+/**
+ * Build a compact, human-readable summary of the room values relevant to the
+ * active filter keys — shown as the result row's reason when no free text
+ * supplied a match reason.
+ */
+export declare function describeRoom(ctx: RoomMatchContext, keys: string[]): string;

package/dist-lib/editor/store.d.ts

@@ -1,6 +1,7 @@
 import type { MudletMap, MudletRoom } from '../mapIO';
 import type { Command, HitItem, HoverTarget, LoadedMap, Pending, Selection, SwatchSet, ToolId } from './types';
 import type { MapWarning } from './warnings';
+import type { PathFindingAlgorithm, RouteSummary } from './pathfinding';
 export type RoomClipboard = {
     /** Rooms captured at copy time; origId preserved for internal-exit remap. */
     rooms: Array<{
@@ -26,6 +27,14 @@ export type SpreadShrinkState = {
     centerMode: 'centroid' | 'anchor';
     anchorRoomId: number | null;
 };
+/** Route-finder (speedwalk) panel state. `summary.path` is what RouteEffect draws. */
+export type RouteState = {
+    fromId: number | null;
+    toId: number | null;
+    algorithm: PathFindingAlgorithm;
+    summary: RouteSummary | null;
+    status: 'idle' | 'found' | 'noPath' | 'sameRoom' | 'missing';
+};
 export interface EditorState {
     map: MudletMap | null;
     loaded: LoadedMap | null;
@@ -90,6 +99,8 @@ export interface EditorState {
     swatchPaletteOpen: boolean;
     sessionId: string | null;
     spreadShrink: SpreadShrinkState | null;
+    /** Route-finder panel + the path RouteEffect renders. */
+    route: RouteState;
     warningAckVersion: number;
     /** Cached map warnings; recomputed in App after each command lands. */
     warnings: MapWarning[];

package/dist-lib/editor/tools.d.ts

@@ -19,6 +19,11 @@ export interface Tool {
 }
 type PickSpecialExitCb = (roomId: number) => void;
 export declare function registerSpecialExitPickCb(cb: PickSpecialExitCb | null): void;
+/** Generic room-pick callback for `pending.kind === 'pickRoom'`. Receives the
+ *  clicked room id; the registrant reads `pending.target` to know which slot
+ *  asked. Unlike the special-exit pick, this does NOT reset the selection. */
+type PickRoomCb = (roomId: number) => void;
+export declare function registerRoomPickCb(cb: PickRoomCb | null): void;
 /**
  * Combo tool: click a room to select it, drag to move it, click empty to clear selection.
  * Drag vs click is detected naturally — a drag only "moves" when the snapped cursor cell

package/dist-lib/editor/types.d.ts

@@ -199,6 +199,12 @@ export type PendingPickSpecialExit = {
     kind: 'pickSpecialExit';
     fromId: number;
 };
+/** Generic "click a room to fill a field" pick. `target` identifies which
+ *  field/slot requested the pick so the requester can route the result. */
+export type PendingPickRoom = {
+    kind: 'pickRoom';
+    target: string;
+};
 export type LabelResizeHandle = 'nw' | 'n' | 'ne' | 'e' | 'se' | 's' | 'sw' | 'w';
 export type PendingLabelDrag = {
     kind: 'labelDrag';
@@ -252,7 +258,7 @@ export type PendingPaint = {
 export type PendingPickSwatch = {
     kind: 'pickSwatch';
 };
-export type Pending = PendingDrag | PendingConnect | PendingCustomLine | PendingCustomLinePoint | PendingPickExit | PendingPickSpecialExit | PendingMarquee | PendingLabelDrag | PendingLabelRect | PendingLabelResize | PendingPaint | PendingPickSwatch | null;
+export type Pending = PendingDrag | PendingConnect | PendingCustomLine | PendingCustomLinePoint | PendingPickExit | PendingPickSpecialExit | PendingPickRoom | PendingMarquee | PendingLabelDrag | PendingLabelRect | PendingLabelResize | PendingPaint | PendingPickSwatch | null;
 export type RoomSnapshot = MudletRoom;
 export type CustomLineSnapshot = {
     points: [number, number][];

package/dist-lib/i18n/locales/panels.en.d.ts

@@ -8,6 +8,7 @@ export declare const panelsEn: {
         readonly historyShort: "Hist";
         readonly map: "Map";
         readonly script: "Script";
+        readonly route: "Route";
         readonly expandPanel: "Expand panel";
         readonly restorePanel: "Restore panel";
         readonly collapsePanel: "Collapse panel";
@@ -335,6 +336,34 @@ export declare const panelsEn: {
             readonly label: "Click a label to select and edit its properties.";
         };
     };
+    readonly route: {
+        readonly title: "Route / speedwalk";
+        readonly description: "Find the lowest-cost path between two rooms using room & exit weights, honouring locked exits and rooms.";
+        readonly from: "From";
+        readonly to: "To";
+        readonly pickFrom: "Pick start room from map";
+        readonly pickTo: "Pick destination room from map";
+        readonly pickCancel: "Click a room on the map (Esc to cancel)";
+        readonly swap: "Swap";
+        readonly algorithm: "Algorithm";
+        readonly astar: "A* (fast)";
+        readonly dijkstra: "Dijkstra";
+        readonly find: "Find route";
+        readonly clear: "Clear";
+        readonly rooms: "{{count}} rooms";
+        readonly steps: "{{count}} steps";
+        readonly cost: "Cost {{weight}}";
+        readonly speedwalk: "Speedwalk";
+        readonly copy: "Copy";
+        readonly copied: "Copied!";
+        readonly goStart: "Go to start";
+        readonly goEnd: "Go to end";
+        readonly noPath: "No route found between #{{from}} and #{{to}}.";
+        readonly sameRoom: "Start and destination are the same room.";
+        readonly missing: "Enter a valid start and destination room ID.";
+        readonly pickHint: "Tip: click “⊕” next to From or To, then click a room on the map.";
+        readonly stepList: "Steps";
+    };
 };
 export type PanelsLocale = {
     [K in keyof typeof panelsEn]: typeof panelsEn[K] extends string ? string : {

package/dist-lib/i18n/locales/search.en.d.ts

@@ -2,13 +2,30 @@ export declare const searchEn: {
     readonly tabRooms: "Rooms";
     readonly tabLabels: "Labels";
     readonly closeTitle: "Close (Esc)";
-    readonly placeholderRooms: "name, ID, or user data… (Tab to switch)";
+    readonly placeholderRooms: "name, ID, or filters like env:3 stubs:>0… (Tab to switch)";
     readonly placeholderLabels: "label text… (Tab to switch)";
     readonly clearTitle: "Clear";
     readonly noMatches: "No matches";
     readonly tooManyResults: "Showing first 100 results — refine your query";
     readonly unnamed: "unnamed";
     readonly emptyLabel: "empty label";
+    readonly filtersToggle: "Filters";
+    readonly filtersHelpTitle: "Filter syntax";
+    readonly filtersHelpHint: "Combine filters and free text. Use >, <, ranges (1-5), or yes/no. Prefix with - to negate.";
+    readonly invalidFilter: "Invalid filter: {{token}}";
+    readonly helpEnv: "environment id";
+    readonly helpWeight: "room weight above 5";
+    readonly helpExits: "exactly one exit";
+    readonly helpDeadend: "dead-ends (single exit)";
+    readonly helpStubs: "has exit stubs";
+    readonly helpDoor: "has a door";
+    readonly helpLocked: "not locked";
+    readonly helpSpecial: "has special exits";
+    readonly helpCustomLine: "has custom lines";
+    readonly helpSymbol: "has a symbol";
+    readonly helpArea: "area name contains";
+    readonly helpZ: "on z-level 0";
+    readonly helpNegate: "negate: no door";
 };
 export type SearchLocale = {
     [K in keyof typeof searchEn]: string;

package/dist-lib/index.d.ts

@@ -1,6 +1,6 @@
 import './styles.css';
 export { default as App } from './App';
-export type { EditorPlugin, SidebarTab, RoomPanelSection, RoomSectionProps, PluginCheckResult } from './editor/plugin';
+export type { EditorPlugin, SidebarTab, RoomPanelSection, RoomSectionProps, PluginCheckResult, ToolbarAction } from './editor/plugin';
 export type { MudletMap, MudletRoom, MudletColor } from './mapIO';
 export type { SwatchSet, Swatch } from './editor/types';
 export { loadUrlIntoStore } from './editor/loadFile';