mudlet-map-editor 0.1.0

package/README.md

@@ -0,0 +1,77 @@
+# Mudlet Map Editor
+
+A browser-based visual editor for [Mudlet](https://www.mudlet.org/) `.dat` binary map files. Load, edit, and save MUD maps directly in your browser — no installation required.
+
+## Features
+
+- **Visual editing** — add, move, and delete rooms on an interactive canvas
+- **Exit management** — create bidirectional or one-way exits between rooms in 14+ directions
+- **Labels** — place text labels with custom fonts, colors, and optional images
+- **Custom lines** — draw waypoint-based paths with configurable colors and arrowheads
+- **Area & environment management** — organize rooms into areas, customize terrain colors
+- **Swatches / Paint tool** — define symbol+environment presets and paint them onto rooms in one click
+- **Undo/redo** — full command history with descriptive labels
+- **Binary I/O** — load and save Mudlet `.dat` files directly in the browser; also load from URL
+- **Session persistence** — work is auto-saved to IndexedDB and restored on next visit
+
+## Tools
+
+| Key | Tool | Description |
+|-----|------|-------------|
+| `1` | Select | Click rooms to view/edit properties; nudge with arrow keys |
+| `2` | Connect | Click source then target to create an exit |
+| `3` | Unlink | Click an exit stub to remove that exit |
+| `4` | Add Room | Click an empty grid cell to create a room |
+| `5` | Add Label | Place a text label on the map |
+| `6` | Delete | Remove rooms, exits, or labels |
+| `7` | Pan | Drag to move the viewport |
+| `8` | Paint | Apply the active swatch (symbol + environment) to rooms |
+
+The **Custom Line** tool is activated from the side panel (on a selected exit), not the toolbar. Hold **Space** to temporarily pan from any tool.
+
+## Keyboard Shortcuts
+
+| Shortcut | Action |
+|----------|--------|
+| `Ctrl+Z` | Undo |
+| `Ctrl+Y` | Redo |
+| `G` | Toggle grid snap |
+| `F` | Fit area in view |
+| `Delete` | Remove selection |
+| `Ctrl+A` | Select all rooms in current area/z-level |
+| `Esc` | Cancel current operation |
+
+## Getting Started
+
+```bash
+npm install
+npm run dev
+```
+
+Then open the app, click **Load** in the toolbar to open a `.dat` file, or click **New** to start from scratch. Use **Download** to save your changes.
+
+## Commands
+
+```bash
+npm run dev       # Vite dev server with HMR
+npm run build     # Type-check and bundle for production
+npm run preview   # Preview the production build
+```
+
+## Tech Stack
+
+- **React 19** + **TypeScript**
+- **Vite** for bundling
+- **Konva** for canvas rendering (via [`mudlet-map-renderer`](https://github.com/Delwing/mudlet-map-renderer))
+- [`mudlet-map-binary-reader`](https://github.com/Delwing/mudlet-map-binary-reader) for parsing and serializing Mudlet `.dat` files
+
+## Architecture
+
+```
+Binary .dat file
+  → mudlet-map-binary-reader  →  MudletMap (in-memory model)
+  → EditorMapReader (adapter, Y-flip)
+  → MapRenderer (Konva canvas) + LiveEffect overlays
+```
+
+All map mutations go through a command system (`applyCommand`) that records operations for undo/redo. State is managed in a single centralized store.

package/dist-lib/App.d.ts

@@ -0,0 +1,5 @@
+import type { EditorPlugin } from './editor/plugin';
+export default function App({ plugins, title }: {
+    plugins?: EditorPlugin[];
+    title?: string;
+}): import("react/jsx-runtime").JSX.Element;

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

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

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

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

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

@@ -0,0 +1,15 @@
+export interface DropdownOption {
+    value: number;
+    label: string;
+}
+interface Props {
+    label: string;
+    value: number | null;
+    options: DropdownOption[];
+    onChange: (value: number) => void;
+    searchable?: boolean;
+    emptyText?: string;
+    width?: number;
+}
+export declare function DropdownSelect({ label, value, options, onChange, searchable, emptyText, width }: Props): import("react/jsx-runtime").JSX.Element;
+export {};

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

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

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

@@ -0,0 +1,13 @@
+import type { MudletMap } from '../mapIO';
+import type { SceneHandle } from '../editor/scene';
+interface EnvPickerProps {
+    map: MudletMap;
+    sceneRef: {
+        current: SceneHandle | null;
+    };
+    currentEnvId: number;
+    onSelect: (envId: number) => void;
+    onClose: () => void;
+}
+export declare function EnvPicker({ map, sceneRef, currentEnvId, onSelect, onClose }: EnvPickerProps): import("react/jsx-runtime").JSX.Element;
+export {};

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

@@ -0,0 +1,10 @@
+import type { ToolId } from '../editor/types';
+export declare const TOOL_BUTTONS: {
+    id: ToolId;
+    label: string;
+    hint: string;
+    key: string;
+}[];
+export declare function HelpModal({ onClose }: {
+    onClose: () => void;
+}): import("react/jsx-runtime").JSX.Element;

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

@@ -0,0 +1,15 @@
+import type { SceneHandle } from '../editor/scene';
+import type { MudletMap } from '../mapIO';
+interface RoomPanelProps {
+    selection: {
+        kind: 'room';
+        ids: number[];
+    };
+    room: NonNullable<MudletMap['rooms'][number]>;
+    map: MudletMap;
+    sceneRef: {
+        current: SceneHandle | null;
+    };
+}
+export declare function RoomPanel({ selection, room, map, sceneRef }: RoomPanelProps): import("react/jsx-runtime").JSX.Element;
+export {};

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

@@ -0,0 +1 @@
+export declare function SessionsPanel(): import("react/jsx-runtime").JSX.Element;

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

@@ -0,0 +1,10 @@
+import type { SceneHandle } from '../editor/scene';
+import type { SidebarTab } from '../editor/plugin';
+interface SidePanelProps {
+    sceneRef: {
+        current: SceneHandle | null;
+    };
+    extraTabs?: SidebarTab[];
+}
+export declare function SidePanel({ sceneRef, extraTabs }: SidePanelProps): import("react/jsx-runtime").JSX.Element;
+export {};

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

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

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

@@ -0,0 +1,6 @@
+export declare function Toolbar({ title, onHelpClick, onLoadFromUrl, onSave }: {
+    title?: string;
+    onHelpClick: () => void;
+    onLoadFromUrl: () => void;
+    onSave?: (bytes: Uint8Array) => void;
+}): import("react/jsx-runtime").JSX.Element;

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

@@ -0,0 +1,4 @@
+export declare function UrlLoadModal({ onClose, initialUrl }: {
+    onClose: () => void;
+    initialUrl?: string;
+}): import("react/jsx-runtime").JSX.Element;

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

@@ -0,0 +1,7 @@
+export declare function DoorIcon(): import("react/jsx-runtime").JSX.Element;
+export declare function LockIcon({ locked }: {
+    locked: boolean;
+}): import("react/jsx-runtime").JSX.Element;
+export declare function WeightIcon(): import("react/jsx-runtime").JSX.Element;
+export declare function CenterOnRoomIcon(): import("react/jsx-runtime").JSX.Element;
+export declare function CrosshairIcon(): import("react/jsx-runtime").JSX.Element;

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

@@ -0,0 +1,27 @@
+import type { MudletColor } from '../mapIO';
+export declare function RoomLink({ id, name, className }: {
+    id: number;
+    name?: string | null;
+    className?: string;
+}): import("react/jsx-runtime").JSX.Element;
+export declare function Field({ label, children, as: Tag }: {
+    label: string;
+    children: React.ReactNode;
+    as?: 'label' | 'div';
+}): import("react/jsx-runtime").JSX.Element;
+export declare function CheckboxField({ checked, onChange, description }: {
+    checked: boolean;
+    onChange: (checked: boolean) => void;
+    description: string;
+}): import("react/jsx-runtime").JSX.Element;
+export declare function ToolHint({ activeTool }: {
+    activeTool: string;
+}): import("react/jsx-runtime").JSX.Element;
+interface UserDataEditorProps {
+    data: Record<string, string> | undefined;
+    onCommit: (key: string, from: string | null, to: string | null) => void;
+}
+export declare function UserDataEditor({ data, onCommit }: UserDataEditorProps): import("react/jsx-runtime").JSX.Element;
+export declare function mudletColorToHex(c: MudletColor): string;
+export declare function hexToMudletColor(hex: string): MudletColor;
+export {};

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

@@ -0,0 +1,20 @@
+import type { PendingCustomLine } from '../../editor/types';
+import type { SceneHandle } from '../../editor/scene';
+import type { MudletMap } from '../../mapIO';
+export declare function CustomLineDrawPanel({ pending, sceneRef }: {
+    pending: PendingCustomLine;
+    sceneRef: {
+        current: SceneHandle | null;
+    };
+}): import("react/jsx-runtime").JSX.Element;
+export declare function CustomLineSelectPanel({ selection, map, sceneRef }: {
+    selection: {
+        kind: 'customLine';
+        roomId: number;
+        exitName: string;
+    };
+    map: MudletMap;
+    sceneRef: {
+        current: SceneHandle | null;
+    };
+}): import("react/jsx-runtime").JSX.Element;

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

@@ -0,0 +1,15 @@
+import type { Direction } from '../../editor/types';
+import type { SceneHandle } from '../../editor/scene';
+import type { MudletMap } from '../../mapIO';
+export declare function ExitPanel({ selection, map, sceneRef }: {
+    selection: {
+        kind: 'exit';
+        fromId: number;
+        toId: number;
+        dir: Direction;
+    };
+    map: MudletMap;
+    sceneRef: {
+        current: SceneHandle | null;
+    };
+}): import("react/jsx-runtime").JSX.Element;

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

@@ -0,0 +1,8 @@
+import type { Command } from '../../editor/types';
+import type { SceneHandle } from '../../editor/scene';
+export declare function commandLabel(cmd: Command): string;
+export declare function HistoryPanel({ sceneRef }: {
+    sceneRef: {
+        current: SceneHandle | null;
+    };
+}): import("react/jsx-runtime").JSX.Element;

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

@@ -0,0 +1,13 @@
+import type { SceneHandle } from '../../editor/scene';
+interface LabelPanelProps {
+    selection: {
+        kind: 'label';
+        id: number;
+        areaId: number;
+    };
+    sceneRef: {
+        current: SceneHandle | null;
+    };
+}
+export declare function LabelPanel({ selection, sceneRef }: LabelPanelProps): import("react/jsx-runtime").JSX.Element;
+export {};

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

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

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

@@ -0,0 +1,30 @@
+import type { MudletMap } from '../mapIO';
+import type { Command, NeighborEdit } from './types';
+import type { SceneHandle } from './scene';
+/**
+ * Apply a command. When a `scene` is provided, mutations go through
+ * `scene.reader` so the renderer stays in sync automatically. When it is
+ * omitted (tests, etc.) we mutate the raw map directly — the caller is
+ * responsible for triggering a rebuild.
+ */
+export declare function applyCommand(map: MudletMap, cmd: Command, scene?: SceneHandle | null): {
+    structural: boolean;
+};
+export declare function revertCommand(map: MudletMap, cmd: Command, scene?: SceneHandle | null): {
+    structural: boolean;
+};
+export declare function pushCommand(cmd: Command, scene?: SceneHandle | null): boolean;
+export declare function pushBatch(cmds: Command[], scene?: SceneHandle | null): boolean;
+export declare function undoOnce(scene?: SceneHandle | null): {
+    changed: boolean;
+    structural: boolean;
+};
+export declare function redoOnce(scene?: SceneHandle | null): {
+    changed: boolean;
+    structural: boolean;
+};
+/** Build setCustomLine commands that translate all waypoints of a room's custom lines by (dx, dy) in raw Mudlet space (y-up). */
+export declare function buildCustomLineMoveCommands(map: MudletMap, roomId: number, dx: number, dy: number): Command[];
+export declare function buildDeleteNeighborEdits(map: MudletMap, roomId: number): NeighborEdit[];
+/** O(n) version for batch deletion: one pass over all rooms, results for each deleted id. */
+export declare function buildDeleteNeighborEditsForMany(map: MudletMap, ids: number[]): Map<number, NeighborEdit[]>;

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

@@ -0,0 +1,6 @@
+import type { MapRenderer } from 'mudlet-map-renderer';
+export declare function snap(value: number, step: number): number;
+export declare function clientToMap(renderer: MapRenderer, container: HTMLElement, clientX: number, clientY: number): {
+    x: number;
+    y: number;
+};

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

@@ -0,0 +1,21 @@
+import Konva from 'konva';
+import type { CoordinateTransform, LiveEffect, ViewportBounds } from 'mudlet-map-renderer';
+import type { SceneHandle } from '../scene';
+export declare class ConnectHandlesEffect implements LiveEffect {
+    private readonly roomSize;
+    private readonly sceneRef;
+    private source?;
+    private target?;
+    private layer?;
+    private unsubscribe?;
+    constructor(roomSize: number, sceneRef: {
+        current: SceneHandle | null;
+    });
+    attach(layer: Konva.Layer): void;
+    updateViewport(_bounds: ViewportBounds, scale: number, _transform: CoordinateTransform): void;
+    destroy(): void;
+    private buildHandleSet;
+    private placeHandles;
+    private hide;
+    private sync;
+}

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

@@ -0,0 +1,19 @@
+import Konva from 'konva';
+import type { CoordinateTransform, LiveEffect, ViewportBounds } from 'mudlet-map-renderer';
+import type { SceneHandle } from '../scene';
+/** Draws waypoints + in-progress line while the custom line tool is active. */
+export declare class CustomLinePreviewEffect implements LiveEffect {
+    private readonly sceneRef;
+    private group?;
+    private layer?;
+    private unsubscribe?;
+    private currentScale;
+    constructor(sceneRef: {
+        current: SceneHandle | null;
+    });
+    attach(layer: Konva.Layer): void;
+    updateViewport(_bounds: ViewportBounds, scale: number, _transform: CoordinateTransform): void;
+    destroy(): void;
+    private sync;
+    private resolveTargetRoom;
+}

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

@@ -0,0 +1,27 @@
+import Konva from 'konva';
+import type { CoordinateTransform, LiveEffect, ViewportBounds } from 'mudlet-map-renderer';
+/**
+ * Fallback grid drawn on the LiveEffect layer for empty area/z levels where the
+ * renderer's own GridRenderer never fires (it returns early when there's no plane).
+ * Matches the renderer's grid color, line width, and cell size exactly.
+ * Draws subtle x=0 and y=0 axis lines plus a fixed-size (0,0) label at the origin.
+ */
+export declare class GridOverlayEffect implements LiveEffect {
+    private readonly gridColor;
+    private readonly gridLineWidth;
+    private readonly gridSize;
+    private readonly getIsEmpty;
+    private readonly getViewportBounds;
+    private gridShape?;
+    private axisShape?;
+    private labelShape?;
+    private layer?;
+    private bounds;
+    private scale;
+    private unsubscribe?;
+    constructor(gridColor: string, gridLineWidth: number, gridSize: number, getIsEmpty: () => boolean, getViewportBounds: () => ViewportBounds);
+    attach(layer: Konva.Layer): void;
+    updateViewport(bounds: ViewportBounds, scale: number, _transform: CoordinateTransform): void;
+    destroy(): void;
+    syncVisibility(): void;
+}

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

@@ -0,0 +1,19 @@
+import Konva from 'konva';
+import type { CoordinateTransform, LiveEffect, ViewportBounds } from 'mudlet-map-renderer';
+import type { SceneHandle } from '../scene';
+export declare class HoverHaloEffect implements LiveEffect {
+    private readonly roomSize;
+    private readonly sceneRef;
+    private roomRect?;
+    private linkGroup?;
+    private layer?;
+    private unsubscribe?;
+    private currentScale;
+    constructor(roomSize: number, sceneRef: {
+        current: SceneHandle | null;
+    });
+    attach(layer: Konva.Layer): void;
+    updateViewport(_bounds: ViewportBounds, scale: number, _transform: CoordinateTransform): void;
+    destroy(): void;
+    private sync;
+}

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

@@ -0,0 +1,25 @@
+import Konva from 'konva';
+import type { CoordinateTransform, LiveEffect, ViewportBounds } from 'mudlet-map-renderer';
+import type { SceneHandle } from '../scene';
+export declare class LabelHaloEffect implements LiveEffect {
+    private readonly sceneRef;
+    private selRect?;
+    private hoverRect?;
+    private previewRect?;
+    private handles;
+    private layer?;
+    private unsubscribe?;
+    private strokeWidth;
+    private handleSize;
+    constructor(sceneRef: {
+        current: SceneHandle | null;
+    });
+    attach(layer: Konva.Layer): void;
+    updateViewport(_bounds: ViewportBounds, scale: number, _transform: CoordinateTransform): void;
+    syncPositions(): void;
+    destroy(): void;
+    private getLabelBounds;
+    private applyBounds;
+    private updateHandles;
+    private sync;
+}

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

@@ -0,0 +1,11 @@
+import Konva from 'konva';
+import type { CoordinateTransform, LiveEffect, ViewportBounds } from 'mudlet-map-renderer';
+export declare class MarqueeEffect implements LiveEffect {
+    private rect?;
+    private layer?;
+    private unsubscribe?;
+    attach(layer: Konva.Layer): void;
+    updateViewport(_bounds: ViewportBounds, scale: number, _transform: CoordinateTransform): void;
+    destroy(): void;
+    private sync;
+}

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

@@ -0,0 +1,17 @@
+import Konva from 'konva';
+import type { CoordinateTransform, LiveEffect, ViewportBounds } from 'mudlet-map-renderer';
+import type { SceneHandle } from '../scene';
+export declare class RubberBandEffect implements LiveEffect {
+    private readonly sceneRef;
+    private line?;
+    private dirLabel?;
+    private layer?;
+    private unsubscribe?;
+    constructor(sceneRef: {
+        current: SceneHandle | null;
+    });
+    attach(layer: Konva.Layer): void;
+    updateViewport(_bounds: ViewportBounds, scale: number, _transform: CoordinateTransform): void;
+    destroy(): void;
+    private sync;
+}

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

@@ -0,0 +1,17 @@
+import Konva from 'konva';
+import type { CoordinateTransform, LiveEffect, ViewportBounds } from 'mudlet-map-renderer';
+import type { SceneHandle } from '../scene';
+/** Highlights the currently selected exit line or custom line. */
+export declare class SelectedLinkEffect implements LiveEffect {
+    private readonly sceneRef;
+    private group?;
+    private layer?;
+    private unsubscribe?;
+    constructor(sceneRef: {
+        current: SceneHandle | null;
+    }, _roomSize: number);
+    attach(layer: Konva.Layer): void;
+    updateViewport(_bounds: ViewportBounds, scale: number, _transform: CoordinateTransform): void;
+    destroy(): void;
+    private sync;
+}

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

@@ -0,0 +1,20 @@
+import Konva from 'konva';
+import type { CoordinateTransform, LiveEffect, ViewportBounds } from 'mudlet-map-renderer';
+import type { SceneHandle } from '../scene';
+export declare class SelectionHaloEffect implements LiveEffect {
+    private readonly roomSize;
+    private readonly sceneRef;
+    private rects;
+    private layer?;
+    private unsubscribe?;
+    private strokeWidth;
+    private dash;
+    constructor(roomSize: number, sceneRef: {
+        current: SceneHandle | null;
+    });
+    attach(layer: Konva.Layer): void;
+    updateViewport(_bounds: ViewportBounds, scale: number, _transform: CoordinateTransform): void;
+    syncPositions(): void;
+    destroy(): void;
+    private sync;
+}

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

@@ -0,0 +1,14 @@
+import Konva from 'konva';
+import type { CoordinateTransform, LiveEffect, ViewportBounds } from 'mudlet-map-renderer';
+/** Room silhouette preview at the snapped cell — used for Add Room. */
+export declare class SnapIndicatorEffect implements LiveEffect {
+    private readonly roomSize;
+    private rect?;
+    private layer?;
+    private unsubscribe?;
+    constructor(roomSize: number);
+    attach(layer: Konva.Layer): void;
+    updateViewport(_bounds: ViewportBounds, scale: number, _transform: CoordinateTransform): void;
+    destroy(): void;
+    private sync;
+}